Menu ▾ ▴

Configuration

Robert Trenaman

Configuration Guide

This guide explains how to configure the Cognitive Engine for different use cases.

Environment Variables

The Cognitive Engine can be configured using environment variables or a .env file.

Required Variables

LLM Provider Configuration

OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
DEFAULT_LLM_PROVIDER=openai

OPENAI_API_KEY: Your OpenAI API key. Get it from https://platform.openai.com/api-keys

ANTHROPIC_API_KEY: Your Anthropic API key. Get it from https://console.anthropic.com/

DEFAULT_LLM_PROVIDER: Which LLM provider to use by default. Options: openai or anthropic

Note: You need at least one API key configured. The system will use the available provider.

Optional Variables

Engine Configuration

MIN_ITERATIONS=3
MAX_ITERATIONS=50
EARLY_STOP_CONFIDENCE=0.95
CONFIDENCE_THRESHOLD=0.7

MIN_ITERATIONS: Minimum number of cognitive iterations before considering early stop. Default: 3

MAX_ITERATIONS: Maximum number of cognitive iterations to prevent infinite loops. Default: 50

EARLY_STOP_CONFIDENCE: Confidence threshold for early stopping. If the best thought exceeds this confidence, the engine stops early. Default: 0.95

CONFIDENCE_THRESHOLD: Minimum confidence required for acceptable output. If no thought meets this threshold after MAX_ITERATIONS, the best available thought is used. Default: 0.7

Dashboard Configuration

ENABLE_DASHBOARD=true
DASHBOARD_PORT=8000
DASHBOARD_HOST=0.0.0.0

ENABLE_DASHBOARD: Enable or disable the real-time cognitive telemetry dashboard. Default: true

DASHBOARD_PORT: Port for the dashboard WebSocket server. Default: 8000

DASHBOARD_HOST: Host address for the dashboard server. Default: 0.0.0.0 (all interfaces)

Memory Configuration

MEMORY_DB_PATH=cognitive_engine.db
MAX_MEMORY_SIZE=10000
MEMORY_RETENTION_DAYS=365

MEMORY_DB_PATH: Path to the SQLite database file for memory persistence. Default: cognitive_engine.db

MAX_MEMORY_SIZE: Maximum number of entries to store in memory. Default: 10000

MEMORY_RETENTION_DAYS: Number of days to retain episodic memory entries. Default: 365

Logging Configuration

LOG_LEVEL=INFO
LOG_FILE=cognitive_engine.log
LOG_FORMAT=%(asctime)s - %(name)s - %(levelname)s - %(message)s
LOG_TO_CONSOLE=true
LOG_TO_FILE=true

LOG_LEVEL: Logging level. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL. Default: INFO

LOG_FILE: Path to the log file. Default: cognitive_engine.log

LOG_FORMAT: Log message format. Default: %(asctime)s - %(name)s - %(levelname)s - %(message)s

LOG_TO_CONSOLE: Enable console logging. Default: true

LOG_TO_FILE: Enable file logging. Default: true

Learning Configuration

ENABLE_LEARNING=true
LEARNING_INTERVAL=100
PATTERN_THRESHOLD=5
RULE_EFFECTIVENESS_THRESHOLD=0.7

ENABLE_LEARNING: Enable the learning system. Default: true

LEARNING_INTERVAL: Number of processing cycles between learning operations. Default: 100

PATTERN_THRESHOLD: Minimum frequency for a pattern to be considered significant. Default: 5

RULE_EFFECTIVENESS_THRESHOLD: Minimum effectiveness score for a rule to be retained. Default: 0.7

Prompt Evolution Configuration

ENABLE_PROMPT_EVOLUTION=false
PROMPT_EVOLUTION_INTERVAL=1000
MUTATION_RATE=0.1
PERFORMANCE_BASELINE_LOCK=true

ENABLE_PROMPT_EVOLUTION: Enable prompt evolution system. Default: false (experimental)

PROMPT_EVOLUTION_INTERVAL: Number of processing cycles between prompt evolution attempts. Default: 1000

MUTATION_RATE: Maximum rate of prompt change per evolution cycle (0-1). Default: 0.1

PERFORMANCE_BASELINE_LOCK: Prevent performance regression below original baseline. Default: true

Agent Configuration

ENABLE_AGENT=true
AGENT_STEP_LIMIT=100
AGENT_GOAL_VALIDATION=true
AGENT_MEMORY_CONTROL=true

ENABLE_AGENT: Enable autonomous agent mode. Default: true

AGENT_STEP_LIMIT: Maximum number of steps an agent can take. Default: 100

AGENT_GOAL_VALIDATION: Enable goal validation for safety. Default: true

AGENT_MEMORY_CONTROL: Enable memory control for agents. Default: true

Configuration File

.env File

Create a .env file in the project root:

cp .env.example .env

Edit the .env file with your configuration:

# LLM Provider
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DEFAULT_LLM_PROVIDER=openai

# Engine
MIN_ITERATIONS=3
MAX_ITERATIONS=50
EARLY_STOP_CONFIDENCE=0.95
CONFIDENCE_THRESHOLD=0.7

# Dashboard
ENABLE_DASHBOARD=true
DASHBOARD_PORT=8000

# Memory
MEMORY_DB_PATH=cognitive_engine.db
MAX_MEMORY_SIZE=10000

# Logging
LOG_LEVEL=INFO
LOG_FILE=cognitive_engine.log

# Learning
ENABLE_LEARNING=true
LEARNING_INTERVAL=100

# Prompt Evolution (experimental)
ENABLE_PROMPT_EVOLUTION=false

# Agent
ENABLE_AGENT=true
AGENT_STEP_LIMIT=100

Programmatic Configuration

You can also configure the engine programmatically:

from core.config import Config

config = Config(
    min_iterations=5,
    max_iterations=30,
    early_stop_confidence=0.9,
    confidence_threshold=0.75,
    enable_dashboard=True,
    dashboard_port=8080,
    default_llm_provider="anthropic"
)

from core.engine import CognitiveEngine
engine = CognitiveEngine(config)

Configuration Scenarios

Fast Response (Low Latency)

For scenarios where speed is more important than depth of reasoning:

MIN_ITERATIONS=1
MAX_ITERATIONS=5
EARLY_STOP_CONFIDENCE=0.8
CONFIDENCE_THRESHOLD=0.6
ENABLE_LEARNING=false
ENABLE_DASHBOARD=false

Deep Reasoning (High Quality)

For scenarios where quality is more important than speed:

MIN_ITERATIONS=5
MAX_ITERATIONS=100
EARLY_STOP_CONFIDENCE=0.98
CONFIDENCE_THRESHOLD=0.8
ENABLE_LEARNING=true
ENABLE_DASHBOARD=true

Development/Debugging

For development and debugging:

LOG_LEVEL=DEBUG
LOG_TO_CONSOLE=true
LOG_TO_FILE=true
ENABLE_DASHBOARD=true
MIN_ITERATIONS=2
MAX_ITERATIONS=10

Production

For production deployment:

LOG_LEVEL=INFO
LOG_TO_CONSOLE=false
LOG_TO_FILE=true
ENABLE_DASHBOARD=false
MIN_ITERATIONS=3
MAX_ITERATIONS=50
ENABLE_PROMPT_EVOLUTION=false

Research/Experimentation

For research and experimentation with prompt evolution:

ENABLE_PROMPT_EVOLUTION=true
PROMPT_EVOLUTION_INTERVAL=500
MUTATION_RATE=0.2
PERFORMANCE_BASELINE_LOCK=true
ENABLE_LEARNING=true
ENABLE_DASHBOARD=true
LOG_LEVEL=DEBUG

Configuration Validation

The system validates configuration at startup. Common validation errors:

Missing API Keys

Error: No LLM API key configured

Solution: Set either OPENAI_API_KEY or ANTHROPIC_API_KEY

Invalid Iteration Settings

Error: MIN_ITERATIONS must be less than MAX_ITERATIONS

Solution: Ensure MIN_ITERATIONS < MAX_ITERATIONS

Invalid Confidence Values

Error: Confidence values must be between 0 and 1

Solution: Ensure all confidence values are in range [0, 1]

Port Already in Use

Error: Dashboard port already in use

Solution: Change DASHBOARD_PORT to a different port

Advanced Configuration

Custom LLM Provider

You can add custom LLM providers by extending the LLM client:

from llm.client import LLMClient

class CustomLLMClient(LLMClient):
    def __init__(self):
        super().__init__(provider="custom")
        # Custom initialization

Custom Memory Backend

You can use a different memory backend by implementing the memory interface:

from core.memory import MemoryBackend

class CustomMemoryBackend(MemoryBackend):
    def store(self, event):
        # Custom storage logic
        pass

    def retrieve(self, query):
        # Custom retrieval logic
        pass

Custom Scoring Functions

You can implement custom thought scoring:

from utils.scoring import ThoughtScorer

class CustomScorer(ThoughtScorer):
    def score_thought(self, thought):
        # Custom scoring logic
        score = super().score_thought(thought)
        # Add custom factors
        return score

Configuration Best Practices

  1. Security: Never commit .env files with real API keys to version control
  2. Environment-Specific: Use different configurations for development, staging, and production
  3. Documentation: Document custom configurations for your team
  4. Validation: Test configuration changes in a development environment first
  5. Monitoring: Monitor the impact of configuration changes on system performance
  6. Backups: Backup configuration files and database before major changes
  7. Version Control: Keep .env.example in version control with placeholder values

Troubleshooting Configuration Issues

Configuration Not Loading

If configuration variables aren't being loaded:

  1. Check that .env file exists in project root
  2. Verify variable names are correct (no typos)
  3. Ensure no extra spaces around =
  4. Check file encoding (should be UTF-8)
  5. Verify python-dotenv is installed

Dashboard Not Starting

If the dashboard won't start:

  1. Check that ENABLE_DASHBOARD=true
  2. Verify DASHBOARD_PORT is not in use
  3. Check firewall settings
  4. Verify FastAPI and Uvicorn are installed
  5. Check logs for specific error messages

Memory Database Issues

If memory database has issues:

  1. Check MEMORY_DB_PATH is writable
  2. Verify SQLite is installed
  3. Check disk space
  4. Try deleting the database file and letting it recreate
  5. Check file permissions

LLM API Errors

If LLM API calls fail:

  1. Verify API keys are correct
  2. Check API quota/limits
  3. Verify internet connectivity
  4. Check API service status
  5. Try switching to alternate provider

Configuration Migration

When upgrading versions, configuration may change:

  1. Check release notes for configuration changes
  2. Backup current .env file
  3. Update .env.example with new variables
  4. Test new configuration in development
  5. Deploy to production after validation

Support

For configuration issues:

  • Check logs in cognitive_engine.log for detailed error information
  • Review this documentation for common issues
  • Contact: autobotsolution@gmail.com
auth0 logo