449 lines
11 KiB
Plaintext
449 lines
11 KiB
Plaintext
---
|
|
title: "Configuration Guide"
|
|
description: "Complete guide to configuring Honcho for development and production"
|
|
icon: "gear"
|
|
---
|
|
|
|
Honcho uses a flexible configuration system that supports both TOML files and environment variables. Configuration values are loaded in the following priority order (highest to lowest):
|
|
|
|
1. Environment variables (always take precedence)
|
|
2. `.env` file (for local development)
|
|
3. `config.toml` file (base configuration)
|
|
4. Default values
|
|
|
|
## Recommended Configuration Approaches
|
|
|
|
### Option 1: Environment Variables Only (Production)
|
|
- Use environment variables for all configuration
|
|
- No config files needed
|
|
- Ideal for containerized deployments (Docker, Kubernetes)
|
|
- Secrets managed by your deployment platform
|
|
|
|
### Option 2: config.toml (Development/Simple Deployments)
|
|
- Use config.toml for base configuration
|
|
- Override sensitive values with environment variables
|
|
- Good for development and simple deployments
|
|
|
|
### Option 3: Hybrid Approach
|
|
- Use config.toml for non-sensitive base settings
|
|
- Use .env file for sensitive values (API keys, secrets)
|
|
- Good for development teams
|
|
|
|
### Option 4: .env Only (Local Development)
|
|
- Use .env file for all configuration
|
|
- Simple for local development
|
|
- Never commit .env files to version control
|
|
|
|
## Configuration Methods
|
|
|
|
### Using config.toml
|
|
|
|
Copy the example configuration file to get started:
|
|
|
|
```bash
|
|
cp config.toml.example config.toml
|
|
```
|
|
|
|
Then modify the values as needed. The TOML file is organized into sections:
|
|
|
|
- `[app]` - Application-level settings (log level, host, port, embedding settings)
|
|
- `[db]` - Database connection and pool settings
|
|
- `[auth]` - Authentication configuration
|
|
- `[llm]` - LLM provider API keys and general settings
|
|
- `[dialectic]` - Dialectic API configuration (provider, model, search settings)
|
|
- `[deriver]` - Background worker settings and theory of mind configuration
|
|
- `[summary]` - Session summarization settings
|
|
- `[sentry]` - Error tracking and monitoring settings
|
|
|
|
### Using Environment Variables
|
|
|
|
All configuration values can be overridden using environment variables. The environment variable names follow this pattern:
|
|
|
|
- `{SECTION}_{KEY}` for nested settings
|
|
- Just `{KEY}` for app-level settings
|
|
|
|
Examples:
|
|
|
|
- `DB_CONNECTION_URI` → `[db].CONNECTION_URI`
|
|
- `DB_POOL_SIZE` → `[db].POOL_SIZE`
|
|
- `AUTH_JWT_SECRET` → `[auth].JWT_SECRET`
|
|
- `DIALECTIC_MODEL` → `[dialectic].MODEL`
|
|
- `LOG_LEVEL` (no section) → `[app].LOG_LEVEL`
|
|
|
|
### Configuration Priority
|
|
|
|
When a configuration value is set in multiple places, Honcho uses this priority:
|
|
|
|
1. **Environment variables** - Always take precedence
|
|
2. **.env file** - Loaded for local development
|
|
3. **config.toml** - Base configuration
|
|
4. **Default values** - Built-in defaults
|
|
|
|
This allows you to:
|
|
|
|
- Use `config.toml` for base configuration
|
|
- Override specific values with environment variables in production
|
|
- Use `.env` files for local development without modifying config.toml
|
|
|
|
### Example
|
|
|
|
If you have this in `config.toml`:
|
|
|
|
```toml
|
|
[db]
|
|
CONNECTION_URI = "postgresql://localhost/honcho_dev"
|
|
POOL_SIZE = 10
|
|
```
|
|
|
|
You can override just the connection URI in production:
|
|
|
|
```bash
|
|
export DB_CONNECTION_URI="postgresql://prod-server/honcho_prod"
|
|
```
|
|
|
|
The application will use the production connection URI while keeping the pool size from config.toml.
|
|
|
|
## Core Configuration
|
|
|
|
### Application Settings
|
|
|
|
**Basic Application Configuration:**
|
|
```bash
|
|
# Logging and server settings
|
|
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR
|
|
SESSION_PEERS_LIMIT=10
|
|
GET_CONTEXT_MAX_TOKENS=100000
|
|
|
|
# Embedding settings (optional)
|
|
EMBED_MESSAGES=false
|
|
MAX_EMBEDDING_TOKENS=8192
|
|
MAX_EMBEDDING_TOKENS_PER_REQUEST=300000
|
|
```
|
|
|
|
**Environment-specific settings:**
|
|
```bash
|
|
# Development
|
|
LOG_LEVEL=DEBUG
|
|
FASTAPI_HOST=127.0.0.1
|
|
|
|
# Production
|
|
LOG_LEVEL=WARNING
|
|
FASTAPI_HOST=0.0.0.0
|
|
```
|
|
|
|
### Database Configuration
|
|
|
|
**Required Database Settings:**
|
|
```bash
|
|
# PostgreSQL connection string (required)
|
|
DB_CONNECTION_URI=postgresql+psycopg://username:password@host:port/database
|
|
|
|
# Example for local development
|
|
DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/honcho
|
|
|
|
# Example for production
|
|
DB_CONNECTION_URI=postgresql+psycopg://honcho_user:secure_password@db.example.com:5432/honcho_prod
|
|
```
|
|
|
|
**Database Pool Settings:**
|
|
```bash
|
|
# Connection pool configuration
|
|
DB_SCHEMA=public
|
|
DB_POOL_SIZE=10
|
|
DB_MAX_OVERFLOW=20
|
|
DB_POOL_TIMEOUT=30
|
|
DB_POOL_RECYCLE=300
|
|
DB_POOL_PRE_PING=true
|
|
DB_SQL_DEBUG=false
|
|
DB_TRACING=false
|
|
```
|
|
|
|
**Docker Compose for PostgreSQL:**
|
|
```yaml
|
|
# docker-compose.yml
|
|
version: '3.8'
|
|
services:
|
|
database:
|
|
image: pgvector/pgvector:pg15
|
|
environment:
|
|
POSTGRES_USER: postgres
|
|
POSTGRES_PASSWORD: postgres
|
|
POSTGRES_DB: honcho
|
|
ports:
|
|
- "5432:5432"
|
|
volumes:
|
|
- postgres_data:/var/lib/postgresql/data
|
|
- ./init.sql:/docker-entrypoint-initdb.d/init.sql
|
|
|
|
volumes:
|
|
postgres_data:
|
|
```
|
|
|
|
### Authentication Configuration
|
|
|
|
**JWT Authentication:**
|
|
```bash
|
|
# Enable/disable authentication
|
|
AUTH_USE_AUTH=false # Set to true for production
|
|
|
|
# JWT settings (required if AUTH_USE_AUTH is true)
|
|
AUTH_JWT_SECRET=your-super-secret-jwt-key
|
|
```
|
|
|
|
**Generate JWT Secret:**
|
|
```bash
|
|
# Generate a secure JWT secret
|
|
python scripts/generate_jwt_secret.py
|
|
```
|
|
|
|
## LLM Provider Configuration
|
|
|
|
Honcho supports multiple LLM providers for different tasks. API keys are configured in the `[llm]` section, while specific features use their own configuration sections.
|
|
|
|
### API Keys
|
|
|
|
All provider API keys use the `LLM_` prefix:
|
|
|
|
```bash
|
|
# Provider API Keys
|
|
LLM_ANTHROPIC_API_KEY=your-anthropic-api-key
|
|
LLM_OPENAI_API_KEY=your-openai-api-key
|
|
LLM_GEMINI_API_KEY=your-gemini-api-key
|
|
LLM_GROQ_API_KEY=your-groq-api-key
|
|
|
|
# OpenAI-compatible endpoints
|
|
LLM_OPENAI_COMPATIBLE_API_KEY=your-api-key
|
|
LLM_OPENAI_COMPATIBLE_BASE_URL=https://your-openai-compatible-endpoint.com
|
|
```
|
|
|
|
### General LLM Settings
|
|
|
|
```bash
|
|
# Default settings for all LLM calls
|
|
LLM_DEFAULT_MAX_TOKENS=2500
|
|
```
|
|
|
|
### Feature-Specific Model Configuration
|
|
|
|
Different features can use different providers and models:
|
|
|
|
**Dialectic API:**
|
|
```bash
|
|
# Main dialectic model (default: Anthropic)
|
|
DIALECTIC_PROVIDER=anthropic
|
|
DIALECTIC_MODEL=claude-sonnet-4-20250514
|
|
DIALECTIC_MAX_OUTPUT_TOKENS=2500
|
|
DIALECTIC_THINKING_BUDGET_TOKENS=1024
|
|
|
|
# Query generation for dialectic (default: Groq)
|
|
DIALECTIC_QUERY_GENERATION_PROVIDER=groq
|
|
DIALECTIC_QUERY_GENERATION_MODEL=llama-3.1-8b-instant
|
|
|
|
# Semantic search settings
|
|
DIALECTIC_SEMANTIC_SEARCH_TOP_K=10
|
|
DIALECTIC_SEMANTIC_SEARCH_MAX_DISTANCE=0.85
|
|
```
|
|
|
|
**Deriver:**
|
|
```bash
|
|
# Deriver model (default: Google)
|
|
DERIVER_PROVIDER=google
|
|
DERIVER_MODEL=gemini-2.0-flash-lite
|
|
|
|
# Worker settings
|
|
DERIVER_WORKERS=1
|
|
DERIVER_STALE_SESSION_TIMEOUT_MINUTES=5
|
|
DERIVER_POLLING_SLEEP_INTERVAL_SECONDS=1.0
|
|
|
|
# Peer card settings
|
|
DERIVER_PEER_CARD_PROVIDER=openai
|
|
DERIVER_PEER_CARD_MODEL=gpt-5-nano-2025-08-07
|
|
DERIVER_PEER_CARD_MAX_OUTPUT_TOKENS=2000
|
|
|
|
# Maximum number of observations to store in working representation
|
|
# This is applied to both explicit and deductive observations
|
|
DERIVER_WORKING_REPRESENTATION_MAX_OBSERVATIONS=100
|
|
```
|
|
|
|
**Summary Generation:**
|
|
```bash
|
|
# Summary model (default: Google)
|
|
SUMMARY_PROVIDER=google
|
|
SUMMARY_MODEL=gemini-1.5-flash-latest
|
|
SUMMARY_MAX_TOKENS_SHORT=1000
|
|
SUMMARY_MAX_TOKENS_LONG=2000
|
|
SUMMARY_THINKING_BUDGET_TOKENS=512
|
|
|
|
# Summary frequency
|
|
SUMMARY_MESSAGES_PER_SHORT_SUMMARY=20
|
|
SUMMARY_MESSAGES_PER_LONG_SUMMARY=60
|
|
```
|
|
|
|
### Default Provider Usage
|
|
|
|
By default, Honcho uses:
|
|
- **Anthropic** for dialectic API responses
|
|
- **Groq** for query generation
|
|
- **Google** for deriving theory of mind and summarization
|
|
- **OpenAI** for embeddings (if `EMBED_MESSAGES=true`)
|
|
|
|
You only need to set the API keys for the providers you plan to use.
|
|
|
|
|
|
## Monitoring Configuration
|
|
|
|
### Sentry Error Tracking
|
|
|
|
**Sentry Settings:**
|
|
```bash
|
|
# Enable/disable Sentry
|
|
SENTRY_ENABLED=false
|
|
|
|
# Sentry configuration
|
|
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
|
|
SENTRY_TRACES_SAMPLE_RATE=0.1
|
|
SENTRY_PROFILES_SAMPLE_RATE=0.1
|
|
```
|
|
|
|
## Environment-Specific Examples
|
|
|
|
### Development Configuration
|
|
|
|
**config.toml for development:**
|
|
```toml
|
|
[app]
|
|
LOG_LEVEL = "DEBUG"
|
|
SESSION_PEERS_LIMIT = 10
|
|
EMBED_MESSAGES = false
|
|
|
|
[db]
|
|
CONNECTION_URI = "postgresql+psycopg://postgres:postgres@localhost:5432/honcho_dev"
|
|
POOL_SIZE = 5
|
|
|
|
[auth]
|
|
USE_AUTH = false
|
|
|
|
[dialectic]
|
|
PROVIDER = "anthropic"
|
|
MODEL = "claude-sonnet-4-20250514"
|
|
QUERY_GENERATION_PROVIDER = "groq"
|
|
QUERY_GENERATION_MODEL = "llama-3.1-8b-instant"
|
|
MAX_OUTPUT_TOKENS = 2500
|
|
|
|
[summary]
|
|
PROVIDER = "google"
|
|
MODEL = "gemini-1.5-flash-latest"
|
|
MAX_TOKENS_SHORT = 1000
|
|
MAX_TOKENS_LONG = 2000
|
|
|
|
[deriver]
|
|
WORKERS = 1
|
|
|
|
[sentry]
|
|
ENABLED = false
|
|
```
|
|
|
|
**Environment variables for development:**
|
|
```bash
|
|
# .env.development
|
|
LOG_LEVEL=DEBUG
|
|
DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/honcho_dev
|
|
AUTH_USE_AUTH=false
|
|
ANTHROPIC_API_KEY=your-dev-anthropic-key
|
|
```
|
|
|
|
### Production Configuration
|
|
|
|
**config.toml for production:**
|
|
```toml
|
|
[app]
|
|
LOG_LEVEL = "WARNING"
|
|
SESSION_PEERS_LIMIT = 10
|
|
EMBED_MESSAGES = true
|
|
|
|
[db]
|
|
CONNECTION_URI = "postgresql+psycopg://honcho_user:secure_password@prod-db:5432/honcho_prod"
|
|
POOL_SIZE = 20
|
|
MAX_OVERFLOW = 40
|
|
|
|
[auth]
|
|
USE_AUTH = true
|
|
|
|
[dialectic]
|
|
PROVIDER = "anthropic"
|
|
MODEL = "claude-sonnet-4-20250514"
|
|
QUERY_GENERATION_PROVIDER = "groq"
|
|
QUERY_GENERATION_MODEL = "llama-3.1-8b-instant"
|
|
MAX_OUTPUT_TOKENS = 2500
|
|
|
|
[summary]
|
|
PROVIDER = "google"
|
|
MODEL = "gemini-1.5-flash-latest"
|
|
MAX_TOKENS_SHORT = 1000
|
|
MAX_TOKENS_LONG = 2000
|
|
|
|
[deriver]
|
|
WORKERS = 4
|
|
PROVIDER = "google"
|
|
MODEL = "gemini-2.0-flash-lite"
|
|
|
|
[sentry]
|
|
ENABLED = true
|
|
TRACES_SAMPLE_RATE = 0.1
|
|
```
|
|
|
|
**Environment variables for production:**
|
|
```bash
|
|
# .env.production
|
|
LOG_LEVEL=WARNING
|
|
DB_CONNECTION_URI=postgresql+psycopg://honcho_user:secure_password@prod-db:5432/honcho_prod
|
|
AUTH_USE_AUTH=true
|
|
AUTH_JWT_SECRET=your-super-secret-jwt-key
|
|
ANTHROPIC_API_KEY=your-prod-anthropic-key
|
|
GEMINI_API_KEY=your-prod-gemini-key
|
|
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
|
|
```
|
|
|
|
## Migration Management
|
|
|
|
**Running Database Migrations:**
|
|
```bash
|
|
# Check current migration status
|
|
uv run alembic current
|
|
|
|
# Upgrade to latest
|
|
uv run alembic upgrade head
|
|
|
|
# Downgrade to specific revision
|
|
uv run alembic downgrade revision_id
|
|
|
|
# Create new migration
|
|
uv run alembic revision --autogenerate -m "Description of changes"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
**Common Configuration Issues:**
|
|
|
|
1. **Database Connection Errors**
|
|
- Ensure `DB_CONNECTION_URI` uses `postgresql+psycopg://` prefix
|
|
- Verify database is running and accessible
|
|
- Check pgvector extension is installed
|
|
|
|
2. **Authentication Issues**
|
|
- Set `AUTH_USE_AUTH=true` for production
|
|
- Generate and set `AUTH_JWT_SECRET` if authentication is enabled
|
|
- Use `python scripts/generate_jwt_secret.py` to create a secure secret
|
|
|
|
3. **LLM Provider Issues**
|
|
- Verify API keys are set correctly
|
|
- Check model names match provider specifications
|
|
- Ensure provider is enabled in configuration
|
|
|
|
4. **Deriver Issues**
|
|
- Increase `DERIVER_WORKERS` for better performance
|
|
- Check `DERIVER_STALE_SESSION_TIMEOUT_MINUTES` for session cleanup
|
|
- Monitor background processing logs
|
|
|
|
This configuration guide covers all the settings available in Honcho. Always use environment-specific configuration files and never commit sensitive values like API keys or JWT secrets to version control.
|