Skip to main content

Development Guide

Guide to setting up a local development environment for contributing to Hindsight.

Prerequisites​

  • Python 3.11+
  • uv - Fast Python package manager
  • Docker and Docker Compose
  • An LLM API key (OpenAI, Groq, or Ollama)

Local Development Setup​

1. Clone the Repository​

git clone https://github.com/vectorize-io/hindsight.git
cd hindsight

2. Install Dependencies​

uv sync

3. Start PostgreSQL​

Start only the database via Docker:

cd docker && docker-compose up -d postgres

4. Configure Environment​

cp .env.example .env

Edit .env with your LLM API key:

# Database (connects to Docker postgres)
HINDSIGHT_API_DATABASE_URL=postgresql://hindsight:hindsight_dev@localhost:5432/hindsight

# LLM Provider (choose one)
HINDSIGHT_API_LLM_PROVIDER=groq
HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
HINDSIGHT_API_LLM_MODEL=llama-3.1-70b-versatile

5. Start the API Server​

./scripts/start-server.sh --env local

The server will be available at http://localhost:8888.

Running Tests​

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_retrieval.py

# Run with verbose output
uv run pytest -v

Code Generation​

Regenerate API Clients​

When you modify the OpenAPI spec, regenerate the clients:

./scripts/generate-clients.sh

This generates:

  • Python client in hindsight-clients/python/
  • TypeScript client in hindsight-clients/typescript/

Export OpenAPI Schema​

./scripts/export-openapi.sh

Project Structure​

hindsight/
├── hindsight-api/          # Main API server
│   ├── hindsight_api/
│   │   ├── api/           # HTTP endpoints
│   │   ├── engine/        # Memory engine, retrieval, reasoning
│   │   └── web/           # Server entry point
│   └── tests/
├── hindsight-clients/      # Generated SDK clients
│   ├── python/
│   └── typescript/
├── hindsight-control-plane/ # Admin UI (Next.js)
├── docker/                 # Docker Compose setup
└── scripts/               # Development scripts

Contributing​

  1. Create a feature branch from main
  2. Make your changes
  3. Run tests: uv run pytest
  4. Submit a pull request

Troubleshooting​

Database Connection Issues​

Ensure PostgreSQL is running:

docker-compose ps

Check database connectivity:

psql postgresql://hindsight:hindsight_dev@localhost:5432/hindsight

ML Model Download​

On first run, Hindsight downloads embedding and reranking models. This may take a few minutes. Models are cached in ~/.cache/huggingface/.

Port Conflicts​

If port 8888 is in use:

HINDSIGHT_API_PORT=8889 ./scripts/start-server.sh --env local