Compare commits

...
3 Commits
Author SHA1 Message Date
Nicolò Boschi 38a6e6f0fc fix docker again 2025-12-03 18:35:42 +01:00
Nicolò Boschi 0a601931e5 fix docker 2025-12-03 18:20:57 +01:00
Nicolò Boschi a70b97a871 fix docker cp image build on ci 2025-12-03 17:09:31 +01:00
11 changed files with 179 additions and 333 deletions
+20 -18
View File
@@ -53,6 +53,25 @@ jobs:
working-directory: ./hindsight-clients/typescript
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:
runs-on: ubuntu-latest
@@ -129,24 +148,7 @@ jobs:
test-api:
runs-on: ubuntu-latest
needs: [build-python-packages]
services:
postgres:
image: pgvector/pgvector:pg16
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_API_KEY: ${{ secrets.GROQ_API_KEY }}
HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
@@ -170,4 +172,4 @@ jobs:
- name: Run tests
working-directory: ./hindsight-api
run: uv run pytest tests -v --ignore=tests/test_fact_extraction_quality.py
run: uv run pytest tests -v
+7 -3
View File
@@ -74,11 +74,15 @@ WORKDIR /app
COPY --from=sdk-builder /app/sdk /app/sdk
# Install Control Plane dependencies
COPY hindsight-control-plane/package*.json ./
RUN npm ci
# Only copy package.json (not package-lock.json) to ensure npm installs
# 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/ ./
# Remove package-lock.json to avoid conflicts with installed native bindings
RUN rm -f package-lock.json
# Link SDK (temporary for build)
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
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):
"""An entity extracted from text."""
text: str = Field(
@@ -470,6 +488,10 @@ WHAT TO EXTRACT vs SKIP
max_retries = 2
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
# 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"
@@ -477,10 +499,10 @@ WHAT TO EXTRACT vs SKIP
Chunk: {chunk_index + 1}/{total_chunks}
Event Date: {event_date_formatted} ({event_date.isoformat()})
Context: {context if context else 'none'}
Context: {sanitized_context}
Text:
{chunk}"""
{sanitized_chunk}"""
for attempt in range(max_retries):
try:
+1 -1
View File
@@ -36,4 +36,4 @@ response = client.reflect(
## Documentation
For full documentation, visit [hindsight.dev](https://hindsight.dev).
For full documentation, visit [hindsight](https://github.com/vectorize-io/hindsight).
+66 -34
View File
@@ -1,57 +1,89 @@
# @hindsight/client
# Hindsight TypeScript Client
TypeScript client for Hindsight - Semantic memory system with personality-driven thinking.
**Auto-generated from OpenAPI spec** - provides type-safe access to all Hindsight API endpoints.
TypeScript client library for the Hindsight API.
## Installation
```bash
npm install @hindsight/client
npm install @vectorize-io/hindsight-client
# or
yarn add @hindsight/client
yarn add @vectorize-io/hindsight-client
```
## Quick Start
## Usage
```typescript
import { OpenAPI, MemoryStorageService, ReasoningService } from '@hindsight/client';
import { HindsightClient } from '@vectorize-io/hindsight-client';
// Configure API base URL
OpenAPI.BASE = 'http://localhost:8888';
const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });
// Store memory
await MemoryStorageService.putApiPutPost({
agent_id: 'user123',
content: 'Alice loves machine learning'
// Retain information
await client.retain('my-bank', 'Alice works at Google in Mountain View.');
// 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)
const response = await ReasoningService.thinkApiThinkPost({
agent_id: 'user123',
query: 'What does Alice think about AI?',
thinking_budget: 50
### `retainBatch(bankId, items, options?)`
Store multiple memories in batch.
```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);
```
## Available Services
### `createBank(bankId, options)`
- `MemoryStorageService` - Store and retrieve facts
- `SearchService` - Semantic and temporal search
- `ReasoningService` - Personality-driven thinking
- `VisualizationService` - Memory graphs and statistics
- `ManagementService` - Agent profiles and configuration
- `DocumentsService` - Document tracking
Create or update a memory bank with personality.
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.
## Links
- [GitHub Repository](https://github.com/vectorize-io/hindsight)
- [Full Documentation](https://github.com/vectorize-io/hindsight/blob/main/README.md)
For full documentation, visit [hindsight](https://github.com/vectorize-io/hindsight).
@@ -39,7 +39,7 @@ pip 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 value="cli" label="CLI">
@@ -120,4 +120,4 @@ hindsight --version
## Next Steps
- [**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
- [**Reflect**](./reflect) — Personality-aware reasoning
- [**Memory Banks**](./memory-banks) — Configure personality and background
- [**Server Options**](/developer/server) — Production deployment
- [**Server Options**](/developer/installation) — Production deployment
+1 -1
View File
@@ -121,4 +121,4 @@ The `bias_strength` parameter (0-1) controls how much personality influences opi
- [**Operations**](/developer/api/operations) — Monitor async tasks
### Deployment
- [**Server Setup**](/developer/server) — Deploy with Docker Compose, Helm, or pip
- [**Server Setup**](/developer/installation) — Deploy with Docker Compose, Helm, or pip
+53 -267
View File
@@ -1,56 +1,33 @@
# 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+)
- 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:
- **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)
- **Groq** (recommended): Fast inference, high throughput
- **OpenAI**: GPT-4, GPT-4o, GPT-4 Mini
- **Anthropic**: Claude 3.5 Sonnet, Haiku
- **Ollama**: Run models locally (llama3.1, mixtral, etc.)
- **Any OpenAI-compatible API**: Custom endpoints
- **Ollama**: Run models locally
## Installation Methods
---
### Docker Compose (Recommended)
## Docker
**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
# Clone the repository
@@ -68,43 +45,35 @@ cd docker
./start.sh
```
**What you get**:
**Services started**:
- **API Server**: http://localhost:8888
- **Control Plane** (Web UI): http://localhost:3000
- **Swagger UI**: http://localhost:8888/docs
- **PostgreSQL**: Runs in container with pgvector extension
**Management**:
```bash
# Stop services
cd docker && ./stop.sh
# Clean all data (WARNING: deletes all memories)
cd docker && ./clean.sh
# View logs
docker-compose logs -f api
docker-compose logs -f postgres
./stop.sh # Stop services
./clean.sh # Delete all data
```
### Helm Chart (Kubernetes)
---
## Helm / Kubernetes
**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
# Add Hindsight Helm repository
helm repo add hindsight https://vectorize-io.github.io/hindsight
helm repo update
# Install with basic configuration
# Install with built-in PostgreSQL
helm install hindsight hindsight/hindsight \
--set api.llm.provider=groq \
--set api.llm.apiKey=gsk_xxxxxxxxxxxx \
--set postgresql.enabled=true
# Or use your own PostgreSQL
# Or use external PostgreSQL
helm install hindsight hindsight/hindsight \
--set api.llm.provider=groq \
--set api.llm.apiKey=gsk_xxxxxxxxxxxx \
@@ -112,248 +81,65 @@ helm install hindsight hindsight/hindsight \
--set api.database.url=postgresql://user:[email protected]: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**:
- PostgreSQL 14+ with pgvector extension
- Database must already exist
- pgvector extension must be enabled: `CREATE EXTENSION vector;`
- Kubernetes cluster (GKE, EKS, AKS, or self-hosted)
- Helm 3+
#### 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
hindsight-api --help
# Common options
hindsight-api --port 9000 # Custom port (default: 8888)
hindsight-api --host 127.0.0.1 # Bind to localhost only
hindsight-api --workers 4 # Multiple worker processes
hindsight-api --mcp # Enable MCP server
hindsight-api --log-level debug # Verbose logging
hindsight-api --reload # Auto-reload on code changes (dev)
pip install hindsight-all
```
### Cloud Managed Services
### Run with Embedded Database
**Best for**: Production with minimal ops overhead
You can deploy Hindsight to cloud platforms using their managed services:
#### AWS
For development and testing, Hindsight can run with an embedded PostgreSQL (pg0):
```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:[email protected]:5432/postgres
export HINDSIGHT_API_LLM_PROVIDER=groq
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
hindsight-api
```
## Choosing an Installation Method
This creates a database in `~/.hindsight/data/` and starts the API on http://localhost:8888.
| 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 |
### Run with External PostgreSQL
## Post-Installation
### Verify Installation
For production, connect to your own PostgreSQL instance:
```bash
# Check API server health
curl http://localhost:8888/health
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
# List banks (should return empty array initially)
curl http://localhost:8888/api/v1/banks
# View API documentation
open http://localhost:8888/docs
hindsight-api
```
### First Steps
**Note**: The database must exist and have pgvector enabled (`CREATE EXTENSION vector;`).
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
### CLI Options
```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
hindsight-api --port 9000 # Custom port (default: 8888)
hindsight-api --host 127.0.0.1 # Bind to localhost only
hindsight-api --workers 4 # Multiple worker processes
hindsight-api --mcp # Enable MCP server
hindsight-api --log-level debug # Verbose logging
```
---
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
+1 -1
View File
@@ -309,7 +309,7 @@ Hindsight has been evaluated on the LoComo (Long Context Memory) benchmark:
- **Average recall latency**: 400-600ms (mid budget)
- **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
Generated
+3 -3
View File
@@ -1141,7 +1141,7 @@ provides-extras = ["test"]
[[package]]
name = "hindsight-api"
version = "0.0.12"
version = "0.0.14"
source = { editable = "hindsight-api" }
dependencies = [
{ name = "alembic" },
@@ -1243,7 +1243,7 @@ dev = [
[[package]]
name = "hindsight-client"
version = "0.0.12"
version = "0.0.14"
source = { editable = "hindsight-clients/python" }
dependencies = [
{ name = "aiohttp" },
@@ -1275,7 +1275,7 @@ provides-extras = ["test"]
[[package]]
name = "hindsight-dev"
version = "0.0.12"
version = "0.0.14"
source = { editable = "hindsight-dev" }
dependencies = [
{ name = "hindsight-api" },