Compare commits
3
Commits
refa
...
fix-docker-build
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
38a6e6f0fc | ||
|
|
0a601931e5 | ||
|
|
a70b97a871 |
+20
-18
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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" },
|
||||
|
||||
Reference in New Issue
Block a user