Nicolò Boschi f7cf33c610 fix regressions and bunch of issues

2025-12-01 18:44:49 +01:00

10 KiB

Raw Blame History

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.

Dependencies

Hindsight has two core dependencies that you need to provide:

1. PostgreSQL Database

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

2. LLM Provider

Why an LLM?

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 for details on optimizing throughput.

Supported Providers:

Groq: Fast inference, high throughput (recommended for production)
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

Installation Methods

Docker Compose (Recommended)

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.

# Clone the repository
git clone https://github.com/vectorize-io/hindsight.git
cd hindsight

# Create environment file
cp .env.example .env
# Edit .env with your LLM API key:
# HINDSIGHT_API_LLM_PROVIDER=groq
# HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx

# Start all services
cd docker
./start.sh

What you get:

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:

# 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

Helm Chart (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.

# Add Hindsight Helm repository
helm repo add hindsight https://vectorize-io.github.io/hindsight
helm repo update

# Install with basic configuration
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
helm install hindsight hindsight/hindsight \
  --set api.llm.provider=groq \
  --set api.llm.apiKey=gsk_xxxxxxxxxxxx \
  --set postgresql.enabled=false \
  --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 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

# 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

# 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

# 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;

CLI Options

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)

Cloud Managed Services

Best for: Production with minimal ops overhead

You can deploy Hindsight to cloud platforms using their managed services:

AWS

# 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

# 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:

# 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

# 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

Create your first bank:

curl -X POST http://localhost:8888/api/v1/banks/my-first-bank \
  -H "Content-Type: application/json" \
  -d '{"name": "My First Bank"}'

Retain your first memory:

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."}]}'

Recall the memory:

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
Understand ML models: Models
Monitor performance: Metrics
Optimize for production: Performance

Troubleshooting

PostgreSQL Connection Issues

# 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

# 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

# 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

# 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 on GitHub.

10 KiB Raw Blame History