Pensieve Docs

Global Configuration

configurationreference

Global Configuration

The global config.yaml is Pensieve’s primary configuration file. It defines LLM providers, the search provider, server settings, and the workspaces root directory.

Default location: config.yaml in the application root (repository root for local setup, /app/config.yaml inside Docker containers).

Override: Set the PENSIEVE_CONFIG environment variable to point to a different file path.

Full Example

# config.yaml — Global Pensieve configuration

# =============================================================================
# LLM Providers
# =============================================================================
llm_providers:
  default:
    type: openai
    base_url: "https://api.openai.com/v1"
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4o"
    temperature: 0.7
    max_tokens: 4096

  fast:
    type: openai
    base_url: "https://api.openai.com/v1"
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4o-mini"
    temperature: 0.7
    max_tokens: 4096

  strong:
    type: openai
    base_url: "https://api.openai.com/v1"
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4o"
    temperature: 0.4
    max_tokens: 8192

# =============================================================================
# Search Provider
# =============================================================================
search:
  provider: "tavily"
  api_key: "${SEARCH_API_KEY}"
  max_results_per_query: 5

# =============================================================================
# Server Settings
# =============================================================================
server:
  host: "0.0.0.0"
  port: 8000
  websocket_path: "/ws"
  cors_origins:
    - "http://localhost:3000"
    - "http://localhost:5173"

# =============================================================================
# Authentication (optional)
# =============================================================================
# auth:
#   secret: "${PENSIEVE_AUTH_SECRET}"
#   password_hash: "${PENSIEVE_PASSWORD_HASH}"

# =============================================================================
# Workspaces Root
# =============================================================================
workspaces_root: "./workspaces"

LLM Providers

The llm_providers section defines named LLM configurations. Workspace configs reference these by name (e.g., provider: fast), allowing you to reuse a single provider across multiple pipeline stages or easily swap models.

llm_providers:
  <name>:
    type: openai
    base_url: "https://api.openai.com/v1"
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4o"
    temperature: 0.7
    max_tokens: 4096

Provider Fields

Field Required Description
type Yes Provider type. Currently only openai is supported.
base_url Yes API endpoint URL. Use https://api.openai.com/v1 for OpenAI, or a custom URL for compatible APIs.
api_key Yes API key. Supports environment variable interpolation (${VAR_NAME}).
model Yes Model name (e.g., gpt-4o, gpt-4o-mini).
temperature No Sampling temperature (0.0–2.0). Default depends on the model.
max_tokens No Maximum tokens in the response.

Using OpenAI-compatible APIs

Any API that implements the OpenAI chat completions interface works with type: openai. This includes local model servers like LM Studio, Ollama (with OpenAI compatibility mode), and vLLM:

llm_providers:
  local:
    type: openai
    base_url: "http://localhost:1234/v1"
    api_key: "not-needed"
    model: "local-model"
    temperature: 0.7
Provider name Model Use case
default gpt-4o General-purpose — most pipeline stages
fast gpt-4o-mini Lightweight tasks — topic refinement, consistency check
strong gpt-4o (low temperature) High-stakes tasks — first draft, revision

The workspace configuration assigns providers to individual pipeline stages.

Search Provider

The search section configures web search for agents that use the web_search tool (Researcher and Fact Checker).

search:
  provider: "tavily"
  api_key: "${SEARCH_API_KEY}"
  max_results_per_query: 5
Field Required Description
provider Yes Search provider: tavily, serpapi, or brave.
api_key Yes API key for the search provider. Supports environment variable interpolation.
max_results_per_query No Number of results per search query. Default: 5.

Note: Web search is optional. If no search provider is configured, agents that use web_search will skip search-dependent operations.

Server Settings

The server section controls the FastAPI server.

server:
  host: "0.0.0.0"
  port: 8000
  websocket_path: "/ws"
  cors_origins:
    - "http://localhost:3000"
    - "http://localhost:5173"
Field Default Description
host 0.0.0.0 Bind address. Use 127.0.0.1 for local-only access.
port 8000 HTTP port.
websocket_path /ws WebSocket endpoint path.
cors_origins ["http://localhost:3000", "http://localhost:5173"] Allowed CORS origins. Add your frontend URL if it differs from the defaults.

Important: If you serve the frontend on a custom URL or port, add it to cors_origins to avoid CORS errors. For example, when using Docker Compose on a non-standard port.

The host and port values can also be overridden via PENSIEVE_HOST and PENSIEVE_PORT environment variables. Environment variables take precedence over config file values.

Authentication

The optional auth section enables password-based authentication. When present, all API routes and the WebSocket endpoint require a valid session. When omitted, Pensieve runs in open-access mode.

auth:
  secret: "${PENSIEVE_AUTH_SECRET}"
  password_hash: "${PENSIEVE_PASSWORD_HASH}"
Field Required Description
secret Yes Secret key for signing JWTs. Must be at least 32 characters. Store in an environment variable.
password_hash Yes bcrypt hash of the login password. Generate with python -m pensieve.auth hash-password.

See Authentication for a complete guide including password hash generation, security details, and troubleshooting.

Workspaces Root

workspaces_root: "./workspaces"

The directory where all workspace data is stored. Each workspace gets a subdirectory containing its own configuration, identity memory, topics, and projects.

Field Default Description
workspaces_root ./workspaces Path to the workspaces directory. Relative paths are resolved from the application root.

The directory is created automatically if it doesn’t exist. It must be writable by the application.

In Docker, this is typically mounted as a volume at /app/workspaces to persist data across container restarts.

Environment Variable Interpolation

Any value in config.yaml that contains ${VAR_NAME} is replaced with the corresponding environment variable at startup. This keeps secrets out of the configuration file.

api_key: "${OPENAI_API_KEY}"
# → replaced with the value of the OPENAI_API_KEY environment variable

A .env file in the application root is loaded automatically via python-dotenv. See Environment Variables for details.

If an interpolated variable is missing or empty, the server will report a configuration error at startup.

Validation

At startup, the global configuration is validated:

  • All required fields must be present
  • API keys must be non-empty after environment variable interpolation
  • The workspaces_root directory must be writable
  • LLM provider type must be a recognized value

Invalid configuration causes a clear error message and prevents the server from starting.

Next Steps