fix docker cp image build on ci (#10)
* fix docker cp image build on ci * fix docker * fix docker again
This commit is contained in:
parent
a14024775b
commit
58592d4abc
11 changed files with 179 additions and 333 deletions
38
.github/workflows/test.yml
vendored
38
.github/workflows/test.yml
vendored
|
|
@ -53,6 +53,25 @@ jobs:
|
||||||
working-directory: ./hindsight-clients/typescript
|
working-directory: ./hindsight-clients/typescript
|
||||||
run: npm run build
|
run: npm run build
|
||||||
|
|
||||||
|
build-docs:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Set up Node.js
|
||||||
|
uses: actions/setup-node@v4
|
||||||
|
with:
|
||||||
|
node-version: '20'
|
||||||
|
|
||||||
|
- name: Install dependencies
|
||||||
|
working-directory: ./hindsight-docs
|
||||||
|
run: npm ci
|
||||||
|
|
||||||
|
- name: Build docs
|
||||||
|
working-directory: ./hindsight-docs
|
||||||
|
run: npm run build
|
||||||
|
|
||||||
build-rust-cli:
|
build-rust-cli:
|
||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
|
|
||||||
|
|
@ -129,24 +148,7 @@ jobs:
|
||||||
test-api:
|
test-api:
|
||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
needs: [build-python-packages]
|
needs: [build-python-packages]
|
||||||
|
|
||||||
services:
|
|
||||||
postgres:
|
|
||||||
image: pgvector/pgvector:pg16
|
|
||||||
env:
|
env:
|
||||||
POSTGRES_USER: postgres
|
|
||||||
POSTGRES_PASSWORD: postgres
|
|
||||||
POSTGRES_DB: hindsight_test
|
|
||||||
options: >-
|
|
||||||
--health-cmd pg_isready
|
|
||||||
--health-interval 10s
|
|
||||||
--health-timeout 5s
|
|
||||||
--health-retries 5
|
|
||||||
ports:
|
|
||||||
- 5432:5432
|
|
||||||
|
|
||||||
env:
|
|
||||||
HINDSIGHT_API_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/hindsight_test
|
|
||||||
HINDSIGHT_API_LLM_PROVIDER: groq
|
HINDSIGHT_API_LLM_PROVIDER: groq
|
||||||
HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
|
HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
|
||||||
HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
|
HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
|
||||||
|
|
@ -170,4 +172,4 @@ jobs:
|
||||||
|
|
||||||
- name: Run tests
|
- name: Run tests
|
||||||
working-directory: ./hindsight-api
|
working-directory: ./hindsight-api
|
||||||
run: uv run pytest tests -v --ignore=tests/test_fact_extraction_quality.py
|
run: uv run pytest tests -v
|
||||||
|
|
|
||||||
|
|
@ -74,11 +74,15 @@ WORKDIR /app
|
||||||
COPY --from=sdk-builder /app/sdk /app/sdk
|
COPY --from=sdk-builder /app/sdk /app/sdk
|
||||||
|
|
||||||
# Install Control Plane dependencies
|
# Install Control Plane dependencies
|
||||||
COPY hindsight-control-plane/package*.json ./
|
# Only copy package.json (not package-lock.json) to ensure npm installs
|
||||||
RUN npm ci
|
# correct platform-specific native bindings for lightningcss/tailwindcss
|
||||||
|
COPY hindsight-control-plane/package.json ./
|
||||||
|
RUN npm install
|
||||||
|
|
||||||
# Copy Control Plane source
|
# Copy Control Plane source (excluding node_modules via .dockerignore)
|
||||||
COPY hindsight-control-plane/ ./
|
COPY hindsight-control-plane/ ./
|
||||||
|
# Remove package-lock.json to avoid conflicts with installed native bindings
|
||||||
|
RUN rm -f package-lock.json
|
||||||
|
|
||||||
# Link SDK (temporary for build)
|
# Link SDK (temporary for build)
|
||||||
RUN cd /app/sdk && npm link && cd /app && npm link @vectorize-io/hindsight-client
|
RUN cd /app/sdk && npm link && cd /app && npm link @vectorize-io/hindsight-client
|
||||||
|
|
|
||||||
|
|
@ -16,6 +16,24 @@ from pydantic import BaseModel, Field, field_validator, ConfigDict
|
||||||
from ..llm_wrapper import OutputTooLongError, LLMConfig
|
from ..llm_wrapper import OutputTooLongError, LLMConfig
|
||||||
|
|
||||||
|
|
||||||
|
def _sanitize_text(text: str) -> str:
|
||||||
|
"""
|
||||||
|
Sanitize text by removing invalid Unicode surrogate characters.
|
||||||
|
|
||||||
|
Surrogate characters (U+D800 to U+DFFF) are used in UTF-16 encoding
|
||||||
|
but cannot be encoded in UTF-8. They can appear in Python strings
|
||||||
|
from improperly decoded data (e.g., from JavaScript or broken files).
|
||||||
|
|
||||||
|
This function removes unpaired surrogates to prevent UnicodeEncodeError
|
||||||
|
when the text is sent to the LLM API.
|
||||||
|
"""
|
||||||
|
if not text:
|
||||||
|
return text
|
||||||
|
# Remove surrogate characters (U+D800 to U+DFFF) using regex
|
||||||
|
# These are invalid in UTF-8 and cause encoding errors
|
||||||
|
return re.sub(r'[\ud800-\udfff]', '', text)
|
||||||
|
|
||||||
|
|
||||||
class Entity(BaseModel):
|
class Entity(BaseModel):
|
||||||
"""An entity extracted from text."""
|
"""An entity extracted from text."""
|
||||||
text: str = Field(
|
text: str = Field(
|
||||||
|
|
@ -470,6 +488,10 @@ WHAT TO EXTRACT vs SKIP
|
||||||
max_retries = 2
|
max_retries = 2
|
||||||
last_error = None
|
last_error = None
|
||||||
|
|
||||||
|
# Sanitize input text to prevent Unicode encoding errors (e.g., unpaired surrogates)
|
||||||
|
sanitized_chunk = _sanitize_text(chunk)
|
||||||
|
sanitized_context = _sanitize_text(context) if context else 'none'
|
||||||
|
|
||||||
# Build user message with metadata and chunk content in a clear format
|
# Build user message with metadata and chunk content in a clear format
|
||||||
# Format event_date with day of week for better temporal reasoning
|
# Format event_date with day of week for better temporal reasoning
|
||||||
event_date_formatted = event_date.strftime('%A, %B %d, %Y') # e.g., "Monday, June 10, 2024"
|
event_date_formatted = event_date.strftime('%A, %B %d, %Y') # e.g., "Monday, June 10, 2024"
|
||||||
|
|
@ -477,10 +499,10 @@ WHAT TO EXTRACT vs SKIP
|
||||||
|
|
||||||
Chunk: {chunk_index + 1}/{total_chunks}
|
Chunk: {chunk_index + 1}/{total_chunks}
|
||||||
Event Date: {event_date_formatted} ({event_date.isoformat()})
|
Event Date: {event_date_formatted} ({event_date.isoformat()})
|
||||||
Context: {context if context else 'none'}
|
Context: {sanitized_context}
|
||||||
|
|
||||||
Text:
|
Text:
|
||||||
{chunk}"""
|
{sanitized_chunk}"""
|
||||||
|
|
||||||
for attempt in range(max_retries):
|
for attempt in range(max_retries):
|
||||||
try:
|
try:
|
||||||
|
|
|
||||||
|
|
@ -36,4 +36,4 @@ response = client.reflect(
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
For full documentation, visit [hindsight.dev](https://hindsight.dev).
|
For full documentation, visit [hindsight](https://github.com/vectorize-io/hindsight).
|
||||||
|
|
|
||||||
|
|
@ -1,57 +1,89 @@
|
||||||
# @hindsight/client
|
# Hindsight TypeScript Client
|
||||||
|
|
||||||
TypeScript client for Hindsight - Semantic memory system with personality-driven thinking.
|
TypeScript client library for the Hindsight API.
|
||||||
|
|
||||||
**Auto-generated from OpenAPI spec** - provides type-safe access to all Hindsight API endpoints.
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install @hindsight/client
|
npm install @vectorize-io/hindsight-client
|
||||||
# or
|
# or
|
||||||
yarn add @hindsight/client
|
yarn add @vectorize-io/hindsight-client
|
||||||
```
|
```
|
||||||
|
|
||||||
## Quick Start
|
## Usage
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import { OpenAPI, MemoryStorageService, ReasoningService } from '@hindsight/client';
|
import { HindsightClient } from '@vectorize-io/hindsight-client';
|
||||||
|
|
||||||
// Configure API base URL
|
const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });
|
||||||
OpenAPI.BASE = 'http://localhost:8888';
|
|
||||||
|
|
||||||
// Store memory
|
// Retain information
|
||||||
await MemoryStorageService.putApiPutPost({
|
await client.retain('my-bank', 'Alice works at Google in Mountain View.');
|
||||||
agent_id: 'user123',
|
|
||||||
content: 'Alice loves machine learning'
|
// Recall memories
|
||||||
|
const results = await client.recall('my-bank', 'Where does Alice work?');
|
||||||
|
|
||||||
|
// Reflect and get an opinion
|
||||||
|
const response = await client.reflect('my-bank', 'What do you think about Alice\'s career?');
|
||||||
|
```
|
||||||
|
|
||||||
|
## API Reference
|
||||||
|
|
||||||
|
### `retain(bankId, content, options?)`
|
||||||
|
|
||||||
|
Store a single memory.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
await client.retain('my-bank', 'User prefers dark mode', {
|
||||||
|
timestamp: new Date(),
|
||||||
|
context: 'Settings conversation',
|
||||||
|
metadata: { source: 'chat' }
|
||||||
});
|
});
|
||||||
|
```
|
||||||
|
|
||||||
// Think (generate answer with personality)
|
### `retainBatch(bankId, items, options?)`
|
||||||
const response = await ReasoningService.thinkApiThinkPost({
|
|
||||||
agent_id: 'user123',
|
Store multiple memories in batch.
|
||||||
query: 'What does Alice think about AI?',
|
|
||||||
thinking_budget: 50
|
```typescript
|
||||||
|
await client.retainBatch('my-bank', [
|
||||||
|
{ content: 'Alice loves hiking' },
|
||||||
|
{ content: 'Alice visited Paris last summer' }
|
||||||
|
], { async: true });
|
||||||
|
```
|
||||||
|
|
||||||
|
### `recall(bankId, query, options?)`
|
||||||
|
|
||||||
|
Recall memories matching a query.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const results = await client.recall('my-bank', 'What are Alice\'s hobbies?', {
|
||||||
|
budget: 'mid'
|
||||||
});
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### `reflect(bankId, query, options?)`
|
||||||
|
|
||||||
|
Generate a contextual answer using the bank's identity and memories.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const response = await client.reflect('my-bank', 'What should I do this weekend?', {
|
||||||
|
budget: 'low'
|
||||||
|
});
|
||||||
console.log(response.text);
|
console.log(response.text);
|
||||||
```
|
```
|
||||||
|
|
||||||
## Available Services
|
### `createBank(bankId, options)`
|
||||||
|
|
||||||
- `MemoryStorageService` - Store and retrieve facts
|
Create or update a memory bank with personality.
|
||||||
- `SearchService` - Semantic and temporal search
|
|
||||||
- `ReasoningService` - Personality-driven thinking
|
|
||||||
- `VisualizationService` - Memory graphs and statistics
|
|
||||||
- `ManagementService` - Agent profiles and configuration
|
|
||||||
- `DocumentsService` - Document tracking
|
|
||||||
|
|
||||||
All services are fully typed with TypeScript interfaces.
|
```typescript
|
||||||
|
await client.createBank('my-bank', {
|
||||||
|
name: 'My Assistant',
|
||||||
|
background: 'A helpful assistant that remembers everything.'
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
## Development
|
## Documentation
|
||||||
|
|
||||||
Auto-generated from `openapi.json`. See [RELEASE.md](../../RELEASE.md) for regeneration instructions.
|
For full documentation, visit [hindsight](https://github.com/vectorize-io/hindsight).
|
||||||
|
|
||||||
## Links
|
|
||||||
|
|
||||||
- [GitHub Repository](https://github.com/vectorize-io/hindsight)
|
|
||||||
- [Full Documentation](https://github.com/vectorize-io/hindsight/blob/main/README.md)
|
|
||||||
|
|
|
||||||
|
|
@ -39,7 +39,7 @@ pip install hindsight-client
|
||||||
npm install @hindsight/client
|
npm install @hindsight/client
|
||||||
```
|
```
|
||||||
|
|
||||||
**Requires:** A running Hindsight server (see [Server Deployment](/developer/server) for setup).
|
**Requires:** A running Hindsight server (see [Server Deployment](/developer/installation) for setup).
|
||||||
|
|
||||||
</TabItem>
|
</TabItem>
|
||||||
<TabItem value="cli" label="CLI">
|
<TabItem value="cli" label="CLI">
|
||||||
|
|
@ -120,4 +120,4 @@ hindsight --version
|
||||||
## Next Steps
|
## Next Steps
|
||||||
|
|
||||||
- [**Quick Start**](./quickstart) — Get running in 60 seconds
|
- [**Quick Start**](./quickstart) — Get running in 60 seconds
|
||||||
- [**Server Deployment**](/developer/server) — Production setup options
|
- [**Server Deployment**](/developer/installation) — Production setup options
|
||||||
|
|
|
||||||
|
|
@ -123,4 +123,4 @@ hindsight reflect my-bank "Tell me about Alice"
|
||||||
- [**Recall**](./recall) — Search and retrieval strategies
|
- [**Recall**](./recall) — Search and retrieval strategies
|
||||||
- [**Reflect**](./reflect) — Personality-aware reasoning
|
- [**Reflect**](./reflect) — Personality-aware reasoning
|
||||||
- [**Memory Banks**](./memory-banks) — Configure personality and background
|
- [**Memory Banks**](./memory-banks) — Configure personality and background
|
||||||
- [**Server Options**](/developer/server) — Production deployment
|
- [**Server Options**](/developer/installation) — Production deployment
|
||||||
|
|
|
||||||
|
|
@ -121,4 +121,4 @@ The `bias_strength` parameter (0-1) controls how much personality influences opi
|
||||||
- [**Operations**](/developer/api/operations) — Monitor async tasks
|
- [**Operations**](/developer/api/operations) — Monitor async tasks
|
||||||
|
|
||||||
### Deployment
|
### Deployment
|
||||||
- [**Server Setup**](/developer/server) — Deploy with Docker Compose, Helm, or pip
|
- [**Server Setup**](/developer/installation) — Deploy with Docker Compose, Helm, or pip
|
||||||
|
|
|
||||||
|
|
@ -1,56 +1,33 @@
|
||||||
# Installation
|
# Installation
|
||||||
|
|
||||||
Hindsight can be deployed in multiple ways depending on your infrastructure and requirements. This guide covers all installation methods and explains the core dependencies.
|
Hindsight can be deployed in three ways depending on your infrastructure and requirements.
|
||||||
|
|
||||||
## Dependencies
|
## Prerequisites
|
||||||
|
|
||||||
Hindsight has two core dependencies that you need to provide:
|
### PostgreSQL with pgvector
|
||||||
|
|
||||||
### 1. PostgreSQL Database
|
Hindsight requires PostgreSQL with the **pgvector** extension for vector similarity search:
|
||||||
|
|
||||||
**Why PostgreSQL?**
|
|
||||||
|
|
||||||
Hindsight uses PostgreSQL with the **pgvector** extension to store and query semantic memories efficiently:
|
|
||||||
|
|
||||||
- **Vector search**: pgvector enables fast approximate nearest neighbor (ANN) search using HNSW indexes
|
|
||||||
- **Full-text search**: PostgreSQL's GIN indexes provide BM25-ranked text search
|
|
||||||
- **Graph storage**: Entity relationships are stored using relational tables
|
|
||||||
- **ACID compliance**: Ensures data consistency for memory operations
|
|
||||||
- **Temporal queries**: Native date/time support for temporal reasoning
|
|
||||||
|
|
||||||
**Requirements**:
|
|
||||||
- PostgreSQL 14+ (recommended: 16+)
|
- PostgreSQL 14+ (recommended: 16+)
|
||||||
- pgvector extension installed
|
- pgvector extension installed
|
||||||
- ~2GB+ RAM for small deployments, 4GB+ for production
|
- ~2GB+ RAM for small deployments
|
||||||
|
|
||||||
### 2. LLM Provider
|
### LLM Provider
|
||||||
|
|
||||||
**Why an LLM?**
|
You need an LLM API key for fact extraction, entity resolution, and answer generation:
|
||||||
|
|
||||||
Hindsight uses Large Language Models for several critical operations:
|
- **Groq** (recommended): Fast inference, high throughput
|
||||||
|
|
||||||
- **Fact extraction**: Converting raw text into structured semantic facts during retention
|
|
||||||
- **Entity resolution**: Identifying and linking entities across memories
|
|
||||||
- **Temporal parsing**: Understanding time references in natural language
|
|
||||||
- **Opinion generation**: Creating personality-based opinions during reflection
|
|
||||||
- **Answer generation**: Synthesizing responses from retrieved memories
|
|
||||||
|
|
||||||
**Performance Impact**: The LLM is the primary bottleneck for **write operations (retention)**. See [Performance](./performance.md) for details on optimizing throughput.
|
|
||||||
|
|
||||||
**Supported Providers**:
|
|
||||||
- **Groq**: Fast inference, high throughput (recommended for production)
|
|
||||||
- **OpenAI**: GPT-4, GPT-4o, GPT-4 Mini
|
- **OpenAI**: GPT-4, GPT-4o, GPT-4 Mini
|
||||||
- **Anthropic**: Claude 3.5 Sonnet, Haiku
|
- **Anthropic**: Claude 3.5 Sonnet, Haiku
|
||||||
- **Ollama**: Run models locally (llama3.1, mixtral, etc.)
|
- **Ollama**: Run models locally
|
||||||
- **Any OpenAI-compatible API**: Custom endpoints
|
|
||||||
|
|
||||||
## Installation Methods
|
---
|
||||||
|
|
||||||
### Docker Compose (Recommended)
|
## Docker
|
||||||
|
|
||||||
**Best for**: Quick start, development, small deployments
|
**Best for**: Quick start, development, small deployments
|
||||||
|
|
||||||
**Why use this?**: Bundles all dependencies (PostgreSQL with pgvector, API server, optional Control Plane) in a single command.
|
Docker Compose bundles all dependencies (PostgreSQL with pgvector, API server, Control Plane) in a single command.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone the repository
|
# Clone the repository
|
||||||
|
|
@ -68,43 +45,35 @@ cd docker
|
||||||
./start.sh
|
./start.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
**What you get**:
|
**Services started**:
|
||||||
- **API Server**: http://localhost:8888
|
- **API Server**: http://localhost:8888
|
||||||
- **Control Plane** (Web UI): http://localhost:3000
|
- **Control Plane** (Web UI): http://localhost:3000
|
||||||
- **Swagger UI**: http://localhost:8888/docs
|
- **Swagger UI**: http://localhost:8888/docs
|
||||||
- **PostgreSQL**: Runs in container with pgvector extension
|
|
||||||
|
|
||||||
**Management**:
|
**Management**:
|
||||||
```bash
|
```bash
|
||||||
# Stop services
|
./stop.sh # Stop services
|
||||||
cd docker && ./stop.sh
|
./clean.sh # Delete all data
|
||||||
|
|
||||||
# Clean all data (WARNING: deletes all memories)
|
|
||||||
cd docker && ./clean.sh
|
|
||||||
|
|
||||||
# View logs
|
|
||||||
docker-compose logs -f api
|
|
||||||
docker-compose logs -f postgres
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Helm Chart (Kubernetes)
|
---
|
||||||
|
|
||||||
|
## Helm / Kubernetes
|
||||||
|
|
||||||
**Best for**: Production deployments, auto-scaling, cloud environments
|
**Best for**: Production deployments, auto-scaling, cloud environments
|
||||||
|
|
||||||
**Why use this?**: Kubernetes-native deployment with proper resource management, health checks, and auto-scaling capabilities.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Add Hindsight Helm repository
|
# Add Hindsight Helm repository
|
||||||
helm repo add hindsight https://vectorize-io.github.io/hindsight
|
helm repo add hindsight https://vectorize-io.github.io/hindsight
|
||||||
helm repo update
|
helm repo update
|
||||||
|
|
||||||
# Install with basic configuration
|
# Install with built-in PostgreSQL
|
||||||
helm install hindsight hindsight/hindsight \
|
helm install hindsight hindsight/hindsight \
|
||||||
--set api.llm.provider=groq \
|
--set api.llm.provider=groq \
|
||||||
--set api.llm.apiKey=gsk_xxxxxxxxxxxx \
|
--set api.llm.apiKey=gsk_xxxxxxxxxxxx \
|
||||||
--set postgresql.enabled=true
|
--set postgresql.enabled=true
|
||||||
|
|
||||||
# Or use your own PostgreSQL
|
# Or use external PostgreSQL
|
||||||
helm install hindsight hindsight/hindsight \
|
helm install hindsight hindsight/hindsight \
|
||||||
--set api.llm.provider=groq \
|
--set api.llm.provider=groq \
|
||||||
--set api.llm.apiKey=gsk_xxxxxxxxxxxx \
|
--set api.llm.apiKey=gsk_xxxxxxxxxxxx \
|
||||||
|
|
@ -112,248 +81,65 @@ helm install hindsight hindsight/hindsight \
|
||||||
--set api.database.url=postgresql://user:pass@postgres.example.com:5432/hindsight
|
--set api.database.url=postgresql://user:pass@postgres.example.com:5432/hindsight
|
||||||
```
|
```
|
||||||
|
|
||||||
**What you need**:
|
|
||||||
- Kubernetes cluster (GKE, EKS, AKS, or self-hosted)
|
|
||||||
- kubectl configured
|
|
||||||
- Helm 3+
|
|
||||||
- External PostgreSQL with pgvector (recommended) or use built-in PostgreSQL
|
|
||||||
|
|
||||||
See the [Helm chart documentation](https://github.com/vectorize-io/hindsight/tree/main/deploy/helm) for advanced configuration.
|
|
||||||
|
|
||||||
### pip install (Python Package)
|
|
||||||
|
|
||||||
**Best for**: Custom deployments, development, integration into existing Python applications
|
|
||||||
|
|
||||||
**Why use this?**: Maximum flexibility. Runs as a Python application with embedded PostgreSQL (pg0) by default, or connects to your own database.
|
|
||||||
|
|
||||||
#### Install
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Install the all-in-one package
|
|
||||||
pip install hindsight-all
|
|
||||||
|
|
||||||
# Verify installation
|
|
||||||
hindsight-api --version
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Run with Embedded Database (pg0)
|
|
||||||
|
|
||||||
**Best for**: Development, testing, single-machine deployments
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Configure LLM provider
|
|
||||||
export HINDSIGHT_API_LLM_PROVIDER=groq
|
|
||||||
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
|
|
||||||
|
|
||||||
# Start the server - uses embedded pg0
|
|
||||||
hindsight-api
|
|
||||||
```
|
|
||||||
|
|
||||||
**What happens**:
|
|
||||||
- Creates `~/.hindsight/data/` directory for database storage
|
|
||||||
- Downloads ML models on first run (~500MB)
|
|
||||||
- Starts API server on http://localhost:8888
|
|
||||||
- Ready to use - no external dependencies needed!
|
|
||||||
|
|
||||||
**Limitations**:
|
|
||||||
- Single process only (no horizontal scaling)
|
|
||||||
- Lower performance than dedicated PostgreSQL
|
|
||||||
- Not recommended for production
|
|
||||||
|
|
||||||
#### Run with External PostgreSQL
|
|
||||||
|
|
||||||
**Best for**: Production, high-performance deployments
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Configure database
|
|
||||||
export HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@localhost:5432/hindsight
|
|
||||||
|
|
||||||
# Configure LLM
|
|
||||||
export HINDSIGHT_API_LLM_PROVIDER=groq
|
|
||||||
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
|
|
||||||
|
|
||||||
# Start the server
|
|
||||||
hindsight-api
|
|
||||||
```
|
|
||||||
|
|
||||||
**Requirements**:
|
**Requirements**:
|
||||||
- PostgreSQL 14+ with pgvector extension
|
- Kubernetes cluster (GKE, EKS, AKS, or self-hosted)
|
||||||
- Database must already exist
|
- Helm 3+
|
||||||
- pgvector extension must be enabled: `CREATE EXTENSION vector;`
|
|
||||||
|
|
||||||
#### CLI Options
|
See the [Helm chart documentation](https://github.com/vectorize-io/hindsight/tree/main/helm) for advanced configuration.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Bare Metal (pip)
|
||||||
|
|
||||||
|
**Best for**: Custom deployments, integration into existing Python applications
|
||||||
|
|
||||||
|
### Install
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
hindsight-api --help
|
pip install hindsight-all
|
||||||
|
```
|
||||||
|
|
||||||
# Common options
|
### Run with Embedded Database
|
||||||
|
|
||||||
|
For development and testing, Hindsight can run with an embedded PostgreSQL (pg0):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export HINDSIGHT_API_LLM_PROVIDER=groq
|
||||||
|
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
|
||||||
|
|
||||||
|
hindsight-api
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates a database in `~/.hindsight/data/` and starts the API on http://localhost:8888.
|
||||||
|
|
||||||
|
### Run with External PostgreSQL
|
||||||
|
|
||||||
|
For production, connect to your own PostgreSQL instance:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@localhost:5432/hindsight
|
||||||
|
export HINDSIGHT_API_LLM_PROVIDER=groq
|
||||||
|
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
|
||||||
|
|
||||||
|
hindsight-api
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note**: The database must exist and have pgvector enabled (`CREATE EXTENSION vector;`).
|
||||||
|
|
||||||
|
### CLI Options
|
||||||
|
|
||||||
|
```bash
|
||||||
hindsight-api --port 9000 # Custom port (default: 8888)
|
hindsight-api --port 9000 # Custom port (default: 8888)
|
||||||
hindsight-api --host 127.0.0.1 # Bind to localhost only
|
hindsight-api --host 127.0.0.1 # Bind to localhost only
|
||||||
hindsight-api --workers 4 # Multiple worker processes
|
hindsight-api --workers 4 # Multiple worker processes
|
||||||
hindsight-api --mcp # Enable MCP server
|
hindsight-api --mcp # Enable MCP server
|
||||||
hindsight-api --log-level debug # Verbose logging
|
hindsight-api --log-level debug # Verbose logging
|
||||||
hindsight-api --reload # Auto-reload on code changes (dev)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Cloud Managed Services
|
|
||||||
|
|
||||||
**Best for**: Production with minimal ops overhead
|
|
||||||
|
|
||||||
You can deploy Hindsight to cloud platforms using their managed services:
|
|
||||||
|
|
||||||
#### AWS
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Use RDS PostgreSQL with pgvector
|
|
||||||
# Deploy via ECS, EKS, or EC2
|
|
||||||
# Example: ECS with Fargate
|
|
||||||
docker build -t hindsight-api .
|
|
||||||
aws ecr get-login-password | docker login --username AWS
|
|
||||||
docker push your-ecr-repo/hindsight-api
|
|
||||||
# Deploy via ECS task definition
|
|
||||||
```
|
|
||||||
|
|
||||||
**Required AWS Services**:
|
|
||||||
- **RDS PostgreSQL** with pgvector extension
|
|
||||||
- **ECS/EKS** for container orchestration
|
|
||||||
- **Secrets Manager** for API keys
|
|
||||||
- **ALB** for load balancing (optional)
|
|
||||||
|
|
||||||
#### Google Cloud
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Use Cloud SQL PostgreSQL with pgvector
|
|
||||||
# Deploy via Cloud Run or GKE
|
|
||||||
gcloud run deploy hindsight \
|
|
||||||
--image gcr.io/your-project/hindsight-api \
|
|
||||||
--set-env-vars HINDSIGHT_API_DATABASE_URL=... \
|
|
||||||
--set-secrets HINDSIGHT_API_LLM_API_KEY=...
|
|
||||||
```
|
|
||||||
|
|
||||||
**Required GCP Services**:
|
|
||||||
- **Cloud SQL PostgreSQL** with pgvector
|
|
||||||
- **Cloud Run** or **GKE** for deployment
|
|
||||||
- **Secret Manager** for API keys
|
|
||||||
|
|
||||||
#### Supabase
|
|
||||||
|
|
||||||
**Simplest cloud deployment** - Supabase provides PostgreSQL with pgvector built-in:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Create a Supabase project at supabase.com
|
|
||||||
# 2. Get your database URL from Settings > Database
|
|
||||||
# 3. Deploy API server with DATABASE_URL
|
|
||||||
|
|
||||||
export HINDSIGHT_API_DATABASE_URL=postgresql://postgres:password@db.xxxxxxxxxxxx.supabase.co:5432/postgres
|
|
||||||
export HINDSIGHT_API_LLM_PROVIDER=groq
|
|
||||||
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
|
|
||||||
|
|
||||||
hindsight-api
|
|
||||||
```
|
|
||||||
|
|
||||||
## Choosing an Installation Method
|
|
||||||
|
|
||||||
| Method | Best For | Pros | Cons |
|
|
||||||
|--------|----------|------|------|
|
|
||||||
| **Docker Compose** | Development, small deployments | Easy setup, all dependencies included | Not scalable, single host |
|
|
||||||
| **Helm/Kubernetes** | Production, auto-scaling | Scalable, cloud-native, resilient | Complex setup, K8s knowledge required |
|
|
||||||
| **pip install** | Development, custom integration | Flexible, Python-native, embedded DB option | Manual dependency management |
|
|
||||||
| **Cloud Services** | Production with managed infrastructure | Minimal ops, auto-scaling, managed DB | Higher cost, cloud lock-in |
|
|
||||||
|
|
||||||
## Post-Installation
|
|
||||||
|
|
||||||
### Verify Installation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Check API server health
|
|
||||||
curl http://localhost:8888/health
|
|
||||||
|
|
||||||
# List banks (should return empty array initially)
|
|
||||||
curl http://localhost:8888/api/v1/banks
|
|
||||||
|
|
||||||
# View API documentation
|
|
||||||
open http://localhost:8888/docs
|
|
||||||
```
|
|
||||||
|
|
||||||
### First Steps
|
|
||||||
|
|
||||||
1. **Create your first bank**:
|
|
||||||
```bash
|
|
||||||
curl -X POST http://localhost:8888/api/v1/banks/my-first-bank \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{"name": "My First Bank"}'
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Retain your first memory**:
|
|
||||||
```bash
|
|
||||||
curl -X POST http://localhost:8888/api/v1/banks/my-first-bank/retain \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{"items": [{"content": "The Eiffel Tower is in Paris."}]}'
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Recall the memory**:
|
|
||||||
```bash
|
|
||||||
curl -X POST http://localhost:8888/api/v1/banks/my-first-bank/recall \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{"query": "Where is the Eiffel Tower?"}'
|
|
||||||
```
|
|
||||||
|
|
||||||
### Next Steps
|
|
||||||
|
|
||||||
- **Configure** your deployment: [Configuration](./configuration.md)
|
|
||||||
- **Understand ML models**: [Models](./models.md)
|
|
||||||
- **Monitor performance**: [Metrics](./metrics.md)
|
|
||||||
- **Optimize for production**: [Performance](./performance.md)
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
### PostgreSQL Connection Issues
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Test database connection
|
|
||||||
psql "$HINDSIGHT_API_DATABASE_URL"
|
|
||||||
|
|
||||||
# Verify pgvector extension
|
|
||||||
psql -c "SELECT * FROM pg_extension WHERE extname = 'vector';"
|
|
||||||
|
|
||||||
# Enable pgvector if missing
|
|
||||||
psql -c "CREATE EXTENSION IF NOT EXISTS vector;"
|
|
||||||
```
|
|
||||||
|
|
||||||
### LLM Provider Issues
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Test Groq API key
|
|
||||||
curl https://api.groq.com/openai/v1/models \
|
|
||||||
-H "Authorization: Bearer $HINDSIGHT_API_LLM_API_KEY"
|
|
||||||
|
|
||||||
# Test OpenAI API key
|
|
||||||
curl https://api.openai.com/v1/models \
|
|
||||||
-H "Authorization: Bearer $HINDSIGHT_API_LLM_API_KEY"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Port Already in Use
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Find process using port 8888
|
|
||||||
lsof -i :8888
|
|
||||||
|
|
||||||
# Kill the process
|
|
||||||
kill -9 <PID>
|
|
||||||
|
|
||||||
# Or use a different port
|
|
||||||
hindsight-api --port 9000
|
|
||||||
```
|
|
||||||
|
|
||||||
### Model Download Issues
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Models are downloaded to ~/.cache/huggingface/
|
|
||||||
# Clear cache and retry
|
|
||||||
rm -rf ~/.cache/huggingface/
|
|
||||||
hindsight-api # Will re-download models
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
For installation issues not covered here, please [open an issue](https://github.com/your-repo/hindsight/issues) on GitHub.
|
## Next Steps
|
||||||
|
|
||||||
|
- [Configuration](./configuration.md) — Environment variables and settings
|
||||||
|
- [Models](./models.md) — ML models and providers
|
||||||
|
- [Metrics](./metrics.md) — Monitoring and observability
|
||||||
|
|
|
||||||
|
|
@ -309,7 +309,7 @@ Hindsight has been evaluated on the LoComo (Long Context Memory) benchmark:
|
||||||
- **Average recall latency**: 400-600ms (mid budget)
|
- **Average recall latency**: 400-600ms (mid budget)
|
||||||
- **Average reflect latency**: 1500-2500ms (end-to-end)
|
- **Average reflect latency**: 1500-2500ms (end-to-end)
|
||||||
|
|
||||||
See [benchmarks README](../../benchmarks/README.md) for detailed results.
|
See the [GitHub repository](https://github.com/vectorize-io/hindsight/tree/main/hindsight-dev/benchmarks) for detailed benchmark results.
|
||||||
|
|
||||||
### Performance Metrics
|
### Performance Metrics
|
||||||
|
|
||||||
|
|
|
||||||
6
uv.lock
6
uv.lock
|
|
@ -1141,7 +1141,7 @@ provides-extras = ["test"]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "hindsight-api"
|
name = "hindsight-api"
|
||||||
version = "0.0.12"
|
version = "0.0.14"
|
||||||
source = { editable = "hindsight-api" }
|
source = { editable = "hindsight-api" }
|
||||||
dependencies = [
|
dependencies = [
|
||||||
{ name = "alembic" },
|
{ name = "alembic" },
|
||||||
|
|
@ -1243,7 +1243,7 @@ dev = [
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "hindsight-client"
|
name = "hindsight-client"
|
||||||
version = "0.0.12"
|
version = "0.0.14"
|
||||||
source = { editable = "hindsight-clients/python" }
|
source = { editable = "hindsight-clients/python" }
|
||||||
dependencies = [
|
dependencies = [
|
||||||
{ name = "aiohttp" },
|
{ name = "aiohttp" },
|
||||||
|
|
@ -1275,7 +1275,7 @@ provides-extras = ["test"]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "hindsight-dev"
|
name = "hindsight-dev"
|
||||||
version = "0.0.12"
|
version = "0.0.14"
|
||||||
source = { editable = "hindsight-dev" }
|
source = { editable = "hindsight-dev" }
|
||||||
dependencies = [
|
dependencies = [
|
||||||
{ name = "hindsight-api" },
|
{ name = "hindsight-api" },
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue