Configure Cogitator with YAML files, environment variables, and provider settings.

Configuration File

Create a cogitator.yml in your project root:

llm:
  defaultProvider: ollama
  defaultModel: llama3.2
  providers:
    ollama:
      baseUrl: http://localhost:11434
    openai:
      apiKey: sk-xxx
      baseUrl: https://api.openai.com/v1
    anthropic:
      apiKey: sk-ant-xxx
    google:
      apiKey: xxx

memory:
  adapter: redis
  redis:
    url: redis://localhost:6379
  embedding:
    provider: ollama
    model: nomic-embed-text

logging:
  level: info
  format: pretty

Load it with @cogitator-ai/config:

import { Cogitator } from '@cogitator-ai/core';
import { loadConfig } from '@cogitator-ai/config';

const config = loadConfig();
const cogitator = new Cogitator(config);

loadConfig() automatically:

Reads cogitator.yml (or .cogitator.yml) from the current directory
Merges with environment variables (see below)
Validates the config against Zod schemas
Applies programmatic overrides

Environment Variables

Cogitator reads environment variables with the COGITATOR_ prefix:

COGITATOR_LLM_DEFAULT_PROVIDER=openai
COGITATOR_LLM_DEFAULT_MODEL=gpt-4o
COGITATOR_OLLAMA_BASE_URL=http://localhost:11434
COGITATOR_OPENAI_API_KEY=sk-xxx
COGITATOR_ANTHROPIC_API_KEY=sk-ant-xxx
COGITATOR_GOOGLE_API_KEY=xxx
COGITATOR_AZURE_DEPLOYMENT=gpt-4o
COGITATOR_MISTRAL_API_KEY=xxx
COGITATOR_GROQ_API_KEY=xxx
COGITATOR_TOGETHER_API_KEY=xxx
COGITATOR_DEEPSEEK_API_KEY=xxx

Standard provider env vars are also supported:

OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
GOOGLE_API_KEY=xxx
OLLAMA_HOST=http://localhost:11434
MISTRAL_API_KEY=xxx
GROQ_API_KEY=xxx
TOGETHER_API_KEY=xxx
DEEPSEEK_API_KEY=xxx

Programmatic Configuration

You can skip the YAML file and configure directly:

import { defineConfig } from '@cogitator-ai/config';

const config = defineConfig({
  llm: {
    defaultProvider: 'openai',
    defaultModel: 'gpt-4o',
    providers: {
      openai: {
        apiKey: process.env.OPENAI_API_KEY!,
      },
    },
  },
  memory: {
    adapter: 'postgres',
    postgres: {
      connectionString: process.env.DATABASE_URL!,
    },
    embedding: {
      provider: 'openai',
      apiKey: process.env.OPENAI_API_KEY!,
      model: 'text-embedding-3-small',
    },
  },
});

const cogitator = new Cogitator(config);

Or use loadConfig with overrides:

const config = loadConfig({
  configPath: './cogitator.yml',
  overrides: {
    logging: { level: 'debug' },
  },
});

Provider Configuration

Ollama (Local)

llm:
  providers:
    ollama:
      baseUrl: http://localhost:11434

OpenAI

llm:
  providers:
    openai:
      apiKey: sk-xxx
      baseUrl: https://api.openai.com/v1 # optional, for proxies

Anthropic

llm:
  providers:
    anthropic:
      apiKey: sk-ant-xxx

Google Gemini

llm:
  providers:
    google:
      apiKey: xxx

Azure OpenAI

llm:
  providers:
    azure:
      apiKey: xxx
      endpoint: https://your-resource.openai.azure.com
      apiVersion: '2024-02-15-preview' # optional
      deployment: gpt-4o # optional

AWS Bedrock

llm:
  providers:
    bedrock:
      region: us-east-1 # optional, can use AWS config chain
      accessKeyId: xxx # optional, uses AWS credentials chain
      secretAccessKey: xxx # optional

OpenAI-Compatible Providers

llm:
  providers:
    mistral:
      apiKey: xxx
    groq:
      apiKey: xxx
    together:
      apiKey: xxx
    deepseek:
      apiKey: xxx

Config Merging

Configs are merged with this priority (highest wins):

Programmatic overrides passed to loadConfig({ overrides })
Environment variables (COGITATOR_* and standard provider vars)
YAML config file values
Built-in defaults

Configuration

On this page