Configuration Reference¶

This document provides a comprehensive reference for all configuration options in the Maricusco trading system.

Configuration Sources¶

Configuration is loaded from multiple sources in the following priority order (highest to lowest):

Environment Variables (highest priority)
Configuration File (maricusco/config/settings.py)
Runtime Parameters (lowest priority)

Environment variables override configuration file settings, and runtime parameters override both.

Core Configuration¶

Execution Settings¶

`max_debate_rounds`¶

Type: int Default: 1 Environment Variable: MARICUSCO_MAX_DEBATE_ROUNDS

Number of debate rounds between bull and bear researchers. More rounds = more thorough analysis but higher cost and longer execution time.

config["max_debate_rounds"] = 1  # Quick (default)
config["max_debate_rounds"] = 2  # Standard
config["max_debate_rounds"] = 3  # Deep

`max_risk_discuss_rounds`¶

Type: int Default: 1 Environment Variable: MARICUSCO_MAX_RISK_DISCUSS_ROUNDS

Number of debate rounds for risk management discussion between aggressive, conservative, and neutral debators.

config["max_risk_discuss_rounds"] = 1  # Quick (default)
config["max_risk_discuss_rounds"] = 2  # Standard

Selected Analysts¶

`selected_analysts`¶

Type: List[str] Default: ["technical", "fundamentals", "sentiment", "news"] Environment Variable: MARICUSCO_SELECTED_ANALYSTS (comma-separated)

Which analysts to run in the analysis workflow.

Valid Values: - technical: Technical analysis (price patterns, indicators) - fundamentals: Fundamental analysis (financials, ratios) - sentiment: Sentiment analysis (social media, forums) - news: News analysis (headlines, macroeconomic events)

# All analysts (default)
config["selected_analysts"] = ["technical", "fundamentals", "sentiment", "news"]

# Technical and fundamentals only
config["selected_analysts"] = ["technical", "fundamentals"]

# Technical only
config["selected_analysts"] = ["technical"]

# Environment variable
export MARICUSCO_SELECTED_ANALYSTS="technical,fundamentals"

LLM Configuration¶

Provider Settings¶

`llm_provider`¶

Type: str Default: "openai" Environment Variable: MARICUSCO_LLM_PROVIDER

LLM provider to use for agent reasoning.

Valid Values: - openai: OpenAI (GPT-4, GPT-3.5-turbo) - anthropic: Anthropic (Claude models) - google: Google (Gemini models) - ollama: Ollama (local models) - openrouter: OpenRouter (multiple providers)

config["llm_provider"] = "openai"
config["llm_provider"] = "anthropic"
config["llm_provider"] = "google"

`llm_model`¶

Type: str Default: "gpt-4" Environment Variable: MARICUSCO_LLM_MODEL

Specific LLM model to use. Available models depend on the provider.

OpenAI Models: - gpt-4: Best quality, higher cost - gpt-4-turbo-preview: Faster, lower cost - gpt-3.5-turbo: Good balance, lowest cost

Anthropic Models: - claude-3-opus-20240229: Best quality - claude-3-sonnet-20240229: Balanced - claude-3-haiku-20240307: Fastest, lowest cost

Google Models: - gemini-pro: Flagship model - gemini-pro-vision: With vision capabilities

config["llm_model"] = "gpt-4"
config["llm_model"] = "claude-3-opus-20240229"
config["llm_model"] = "gemini-pro"

`llm_temperature`¶

Type: float Default: 0.7 Environment Variable: MARICUSCO_LLM_TEMPERATURE

Temperature parameter for LLM sampling. Higher values = more creative/random, lower values = more deterministic.

Range: 0.0 to 1.0

config["llm_temperature"] = 0.0  # Deterministic
config["llm_temperature"] = 0.5  # Balanced
config["llm_temperature"] = 0.7  # Default (recommended)
config["llm_temperature"] = 1.0  # Creative

`llm_max_tokens`¶

Type: int Default: 2000 Environment Variable: MARICUSCO_LLM_MAX_TOKENS

Maximum number of tokens in LLM responses.

config["llm_max_tokens"] = 1000  # Short responses
config["llm_max_tokens"] = 2000  # Default
config["llm_max_tokens"] = 4000  # Long responses

`deep_think_llm`¶

Type: str Default: "o4-mini" Environment Variable: MARICUSCO_DEEP_THINK_LLM

LLM model used for deep thinking agents (researchers, managers). Used for complex reasoning tasks requiring thorough analysis.

config["deep_think_llm"] = "o4-mini"  # Default
config["deep_think_llm"] = "gpt-4"    # Higher quality
config["deep_think_llm"] = "claude-3-opus-20240229"  # Alternative

`quick_think_llm`¶

Type: str Default: "gpt-4o-mini" Environment Variable: MARICUSCO_QUICK_THINK_LLM

LLM model used for quick thinking agents (analysts). Used for faster, less complex analysis tasks.

config["quick_think_llm"] = "gpt-4o-mini"  # Default
config["quick_think_llm"] = "gpt-3.5-turbo"  # Faster alternative
config["quick_think_llm"] = "claude-3-haiku-20240307"  # Alternative

`backend_url`¶

Type: str Default: "https://api.openai.com/v1" Environment Variable: MARICUSCO_BACKEND_URL

Base URL for the LLM API backend. Used for custom API endpoints or proxy configurations.

config["backend_url"] = "https://api.openai.com/v1"  # Default OpenAI
config["backend_url"] = "https://api.anthropic.com/v1"  # Anthropic
config["backend_url"] = "https://openrouter.ai/api/v1"  # OpenRouter

API Keys¶

API keys are configured via environment variables only (never in code or configuration files).

# OpenAI
export OPENAI_API_KEY=sk-...

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# Google
export GOOGLE_API_KEY=...

# OpenRouter
export OPENROUTER_API_KEY=sk-or-...

Data Vendor Configuration¶

Vendor Selection¶

`stock_data_vendor`¶

Type: str Default: "yfinance" Environment Variable: MARICUSCO_STOCK_DATA_VENDOR

Data vendor for stock price data.

Valid Values: - yfinance: Yahoo Finance (free, no API key) - alpha_vantage: Alpha Vantage (requires API key) - local: Local CSV files

config["stock_data_vendor"] = "yfinance"

`technical_indicators_vendor`¶

Type: str Default: "yfinance" Environment Variable: MARICUSCO_TECHNICAL_INDICATORS_VENDOR

Data vendor for technical indicators (MACD, RSI, moving averages).

Valid Values: - yfinance: Yahoo Finance (free) - alpha_vantage: Alpha Vantage (requires API key) - local: Local calculations

config["technical_indicators_vendor"] = "yfinance"

`fundamental_data_vendor`¶

Type: str Default: "alpha_vantage" Environment Variable: MARICUSCO_FUNDAMENTAL_DATA_VENDOR

Data vendor for fundamental data (financials, ratios).

Valid Values: - alpha_vantage: Alpha Vantage (requires API key) - openai: OpenAI (web search via tools) - local: Local data files

config["fundamental_data_vendor"] = "alpha_vantage"

`news_data_vendor`¶

Type: str Default: "alpha_vantage" Environment Variable: MARICUSCO_NEWS_DATA_VENDOR

Data vendor for news articles and headlines.

Valid Values: - google: Google News (free, no API key) - alpha_vantage: Alpha Vantage (requires API key, default) - openai: OpenAI (web search via tools) - local: Local news files

config["news_data_vendor"] = "alpha_vantage"  # Default
config["news_data_vendor"] = "google"  # Free alternative

Data Vendor API Keys¶

# Alpha Vantage (required for fundamentals)
export ALPHA_VANTAGE_API_KEY=...

# Reddit (optional, for sentiment analysis)
export REDDIT_CLIENT_ID=...
export REDDIT_CLIENT_SECRET=...
export REDDIT_USER_AGENT=...

Directory Configuration¶

Data Directories¶

`data_cache_dir`¶

Type: str Default: "maricusco/data/data_cache" Environment Variable: MARICUSCO_DATA_CACHE_DIR

Directory for caching market data (CSV files, API responses).

config["data_cache_dir"] = "maricusco/data/data_cache"

`results_dir`¶

Type: str Default: "data/results" Environment Variable: MARICUSCO_RESULTS_DIR

Directory for saving analysis reports and trading decisions.

config["results_dir"] = "data/results"

Reports are saved to: {results_dir}/{ticker}/{date}/reports/

`data_dir`¶

Type: str Default: "data" Environment Variable: MARICUSCO_DATA_DIR

Base data directory for all data-related files.

config["data_dir"] = "data"

Mock Mode Configuration¶

Mock Mode Settings¶

`mock_mode`¶

Type: bool Default: False Environment Variable: MARICUSCO_MOCK_MODE

Enable mock mode for cost-free development and testing. When enabled, all LLM calls and embeddings are replaced with predefined responses.

config["mock_mode"] = True  # Enable mock mode
config["mock_mode"] = False  # Use real APIs

# Environment variable
export MARICUSCO_MOCK_MODE=true

`mock_llm_responses_file`¶

Type: Optional[str] Default: None Environment Variable: MARICUSCO_MOCK_RESPONSES

Path to custom mock responses JSON file. If not specified, uses default responses.

config["mock_llm_responses_file"] = "/path/to/custom-responses.json"

export MARICUSCO_MOCK_RESPONSES=/path/to/custom-responses.json

`mock_memory_preloaded`¶

Type: bool Default: True Environment Variable: MARICUSCO_MOCK_MEMORY_PRELOADED

Whether to preload example memories in mock mode.

config["mock_memory_preloaded"] = True  # Include example scenarios
config["mock_memory_preloaded"] = False  # Empty memory

`mock_agent_delays_ms`¶

Type: Dict[str, int] Default: {} Environment Variable: MARICUSCO_MOCK_AGENT_DELAYS_MS

Per-agent execution delays in milliseconds for latency simulation in mock mode.

config["mock_agent_delays_ms"] = {
    "technical": 800,
    "sentiment": 400,
    "news": 200,
    "fundamentals": 600,
}

export MARICUSCO_MOCK_AGENT_DELAYS_MS="technical:800,sentiment:400,news:200,fundamentals:600"

See Mock Mode documentation for complete details.

Logging Configuration¶

Log Settings¶

`MARICUSCO_LOG_LEVEL`¶

Type: str Default: "INFO" Environment Variable: MARICUSCO_LOG_LEVEL

Logging level for application logs.

Valid Values: - DEBUG: Detailed debugging information - INFO: General informational messages - WARNING: Warning messages - ERROR: Error messages - CRITICAL: Critical errors

export MARICUSCO_LOG_LEVEL=DEBUG
export MARICUSCO_LOG_LEVEL=INFO
export MARICUSCO_LOG_LEVEL=WARNING

`MARICUSCO_LOG_FORMAT`¶

Type: str Default: "json" Environment Variable: MARICUSCO_LOG_FORMAT

Log output format.

Valid Values: - json: Machine-readable JSON format (production) - human-readable: Colored console format (development)

export MARICUSCO_LOG_FORMAT=json
export MARICUSCO_LOG_FORMAT=human-readable

`MARICUSCO_LOG_CONSOLE`¶

Type: bool Default: True Environment Variable: MARICUSCO_LOG_CONSOLE

Enable console logging output.

export MARICUSCO_LOG_CONSOLE=true
export MARICUSCO_LOG_CONSOLE=false

`MARICUSCO_LOG_FILE_ENABLED`¶

Type: bool Default: False Environment Variable: MARICUSCO_LOG_FILE_ENABLED

Enable file logging output.

export MARICUSCO_LOG_FILE_ENABLED=true
export MARICUSCO_LOG_FILE_ENABLED=false

`MARICUSCO_LOG_FILE`¶

Type: str Default: "maricusco/logs/maricusco.log" Environment Variable: MARICUSCO_LOG_FILE

Path to log file (when file logging is enabled).

export MARICUSCO_LOG_FILE=maricusco/logs/maricusco.log

`MARICUSCO_LOG_MAX_BYTES`¶

Type: int Default: 10485760 (10MB) Environment Variable: MARICUSCO_LOG_MAX_BYTES

Maximum log file size before rotation (size-based rotation).

export MARICUSCO_LOG_MAX_BYTES=10485760  # 10MB

`MARICUSCO_LOG_BACKUP_COUNT`¶

Type: int Default: 5 Environment Variable: MARICUSCO_LOG_BACKUP_COUNT

Number of rotated log files to keep.

export MARICUSCO_LOG_BACKUP_COUNT=5

`MARICUSCO_LOG_RETENTION_DAYS`¶

Type: int Default: 30 Environment Variable: MARICUSCO_LOG_RETENTION_DAYS

Number of days to retain rotated log files before deletion.

export MARICUSCO_LOG_RETENTION_DAYS=30

`MARICUSCO_LOG_ROTATION`¶

Type: str Default: "size" Environment Variable: MARICUSCO_LOG_ROTATION

Log rotation strategy.

Valid Values: - size: Rotate when file reaches max size - time: Rotate daily

export MARICUSCO_LOG_ROTATION=size
export MARICUSCO_LOG_ROTATION=time

Metrics Configuration¶

Metrics Settings¶

`MARICUSCO_METRICS_ENABLED`¶

Type: bool Default: False Environment Variable: MARICUSCO_METRICS_ENABLED

Enable Prometheus metrics exposition.

export MARICUSCO_METRICS_ENABLED=true
export MARICUSCO_METRICS_ENABLED=false

`MARICUSCO_METRICS_PATH`¶

Type: str Default: "/metrics" Environment Variable: MARICUSCO_METRICS_PATH

HTTP path for metrics endpoint.

export MARICUSCO_METRICS_PATH=/metrics

`MARICUSCO_METRICS_PORT`¶

Type: int Default: 8000 Environment Variable: MARICUSCO_METRICS_PORT

Port for metrics endpoint.

export MARICUSCO_METRICS_PORT=8000

`MARICUSCO_METRICS_SAMPLING_RATE`¶

Type: float Default: 1.0 Environment Variable: MARICUSCO_METRICS_SAMPLING_RATE

Sampling rate for metrics collection (0.0 to 1.0). Use lower values to reduce overhead.

export MARICUSCO_METRICS_SAMPLING_RATE=1.0  # 100% sampling
export MARICUSCO_METRICS_SAMPLING_RATE=0.1  # 10% sampling

`MARICUSCO_METRICS_LABELS`¶

Type: str Default: "" Environment Variable: MARICUSCO_METRICS_LABELS

Constant labels to add to all metrics (comma-separated key=value pairs).

export MARICUSCO_METRICS_LABELS="environment=production,region=us-east-1"

Health Check Configuration¶

Health Check Settings¶

`MARICUSCO_HEALTHCHECK_ENABLED`¶

Type: bool Default: True Environment Variable: MARICUSCO_HEALTHCHECK_ENABLED

Enable health check endpoint.

export MARICUSCO_HEALTHCHECK_ENABLED=true
export MARICUSCO_HEALTHCHECK_ENABLED=false

`MARICUSCO_HEALTHCHECK_PATH`¶

Type: str Default: "/health" Environment Variable: MARICUSCO_HEALTHCHECK_PATH

HTTP path for health check endpoint.

export MARICUSCO_HEALTHCHECK_PATH=/health

`MARICUSCO_HEALTHCHECK_CACHE_TTL_SECONDS`¶

Type: float Default: 0.0 Environment Variable: MARICUSCO_HEALTHCHECK_CACHE_TTL_SECONDS

Cache TTL for health check results in seconds. Set to 0 to disable caching.

export MARICUSCO_HEALTHCHECK_CACHE_TTL_SECONDS=5.0  # 5 seconds
export MARICUSCO_HEALTHCHECK_CACHE_TTL_SECONDS=0.0  # No caching

`MARICUSCO_HEALTHCHECK_TIMEOUT_DEFAULT`¶

Type: float Default: 1.0 Environment Variable: MARICUSCO_HEALTHCHECK_TIMEOUT_DEFAULT

Default timeout for health checks in seconds.

export MARICUSCO_HEALTHCHECK_TIMEOUT_DEFAULT=1.0

`MARICUSCO_HEALTHCHECK_TIMEOUT_DATABASE`¶

Type: float Default: 1.0 Environment Variable: MARICUSCO_HEALTHCHECK_TIMEOUT_DATABASE

Timeout for database health check in seconds.

export MARICUSCO_HEALTHCHECK_TIMEOUT_DATABASE=2.0

`MARICUSCO_HEALTHCHECK_TIMEOUT_REDIS`¶

Type: float Default: 1.0 Environment Variable: MARICUSCO_HEALTHCHECK_TIMEOUT_REDIS

Timeout for Redis health check in seconds.

export MARICUSCO_HEALTHCHECK_TIMEOUT_REDIS=1.0

`MARICUSCO_HEALTHCHECK_TIMEOUT_VENDORS`¶

Type: float Default: 1.0 Environment Variable: MARICUSCO_HEALTHCHECK_TIMEOUT_VENDORS

Timeout for data vendor health checks in seconds.

export MARICUSCO_HEALTHCHECK_TIMEOUT_VENDORS=5.0

`MARICUSCO_HEALTHCHECK_REQUIRED_DEPENDENCIES`¶

Type: str Default: "database,redis" Environment Variable: MARICUSCO_HEALTHCHECK_REQUIRED_DEPENDENCIES

Comma-separated list of required dependencies. Health check returns 503 if any required dependency is unhealthy. Set to empty string to disable required dependencies.

export MARICUSCO_HEALTHCHECK_REQUIRED_DEPENDENCIES="database,redis"
export MARICUSCO_HEALTHCHECK_REQUIRED_DEPENDENCIES=""  # No required deps

`MARICUSCO_HEALTHCHECK_OPTIONAL_DEPENDENCIES`¶

Type: str Default: "" Environment Variable: MARICUSCO_HEALTHCHECK_OPTIONAL_DEPENDENCIES

Comma-separated list of optional dependencies to check (won't affect health status).

export MARICUSCO_HEALTHCHECK_OPTIONAL_DEPENDENCIES="chromadb,prometheus"

`MARICUSCO_HEALTHCHECK_VENDORS_ENABLED`¶

Type: bool Default: False Environment Variable: MARICUSCO_HEALTHCHECK_VENDORS_ENABLED

Enable health checks for data vendors (Alpha Vantage, yfinance, etc.).

export MARICUSCO_HEALTHCHECK_VENDORS_ENABLED=true
export MARICUSCO_HEALTHCHECK_VENDORS_ENABLED=false

Database Configuration¶

PostgreSQL Settings¶

# Database connection
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DB=maricusco
export POSTGRES_USER=maricusco
export POSTGRES_PASSWORD=maricusco_password

# Connection pool
export POSTGRES_POOL_SIZE=10
export POSTGRES_MAX_OVERFLOW=20

Redis Settings¶

# Redis connection
export REDIS_HOST=localhost
export REDIS_PORT=6379
export REDIS_DB=0
export REDIS_PASSWORD=  # Optional

# Cache TTL (seconds)
export REDIS_CACHE_TTL=300  # 5 minutes

ChromaDB Settings¶

# ChromaDB connection
export CHROMA_HOST=localhost
export CHROMA_PORT=8000
export CHROMA_SERVER_AUTHN_CREDENTIALS=test-token

Docker Configuration¶

Docker Compose Environment¶

# Application
export APP_MODULE=maricusco.api.app:app
export APP_HOST=0.0.0.0
export APP_PORT=8000
export UVICORN_WORKERS=1
export UVICORN_RELOAD=false

# Grafana
export GRAFANA_PORT=3000
export GF_SECURITY_ADMIN_USER=admin
export GF_SECURITY_ADMIN_PASSWORD=admin  # Change for production!

# Prometheus
export PROMETHEUS_PORT=9090

Configuration Examples¶

Development Configuration¶

# .env file for development
MARICUSCO_MOCK_MODE=true
MARICUSCO_LOG_LEVEL=DEBUG
MARICUSCO_LOG_FORMAT=human-readable
MARICUSCO_LOG_CONSOLE=true
MARICUSCO_LOG_FILE_ENABLED=false
MARICUSCO_METRICS_ENABLED=false
MARICUSCO_HEALTHCHECK_REQUIRED_DEPENDENCIES=""

Production Configuration¶

# .env file for production
MARICUSCO_MOCK_MODE=false
MARICUSCO_LOG_LEVEL=INFO
MARICUSCO_LOG_FORMAT=json
MARICUSCO_LOG_CONSOLE=true
MARICUSCO_LOG_FILE_ENABLED=true
MARICUSCO_METRICS_ENABLED=true
MARICUSCO_HEALTHCHECK_REQUIRED_DEPENDENCIES="database,redis"

# API Keys (use secrets manager in production)
OPENAI_API_KEY=sk-...
ALPHA_VANTAGE_API_KEY=...

# Database (use managed service in production)
POSTGRES_HOST=prod-db.example.com
POSTGRES_PASSWORD=<secure-password>

# Grafana (secure credentials)
GF_SECURITY_ADMIN_PASSWORD=<secure-password>

Testing Configuration¶

# .env.test file for testing
MARICUSCO_MOCK_MODE=true
MARICUSCO_LOG_LEVEL=WARNING
MARICUSCO_LOG_CONSOLE=false
MARICUSCO_METRICS_ENABLED=false
MARICUSCO_HEALTHCHECK_ENABLED=false
MARICUSCO_MOCK_AGENT_DELAYS_MS="technical:100,sentiment:100,news:100,fundamentals:100"

Configuration Validation¶

Validate Configuration¶

from maricusco.config.settings import DEFAULT_CONFIG

# Validate configuration
def validate_config(config: dict) -> bool:
    required_keys = [
        "parallel_execution",
        "max_debate_rounds",
        "llm_provider",
        "llm_model",
    ]

    for key in required_keys:
        if key not in config:
            raise ValueError(f"Missing required config key: {key}")

    if config["max_debate_rounds"] < 1:
        raise ValueError("max_debate_rounds must be >= 1")

    if config["llm_provider"] not in ["openai", "anthropic", "google", "ollama", "openrouter"]:
        raise ValueError(f"Invalid llm_provider: {config['llm_provider']}")

    return True

# Usage
config = DEFAULT_CONFIG.copy()
validate_config(config)

Quick Reference¶

Key environment variables:

Variable	Default	Description
`MARICUSCO_MOCK_MODE`	`false`	Enable mock mode
`MARICUSCO_MAX_DEBATE_ROUNDS`	`2`	Debate rounds
`MARICUSCO_LLM_PROVIDER`	`openai`	LLM provider
`MARICUSCO_LOG_LEVEL`	`INFO`	Logging level
`MARICUSCO_METRICS_ENABLED`	`false`	Enable metrics
`OPENAI_API_KEY`	-	OpenAI API key
`ALPHA_VANTAGE_API_KEY`	-	Alpha Vantage API key

See sections above for complete configuration options.

Next Steps¶

Read CLI Usage for command-line interface details
Read Mock Mode for development without API costs
Read Monitoring & Metrics for observability configuration
Read Developer Onboarding for development setup

Configuration Reference¶

Configuration Sources¶

Core Configuration¶

Execution Settings¶

max_debate_rounds¶

max_risk_discuss_rounds¶

Selected Analysts¶

selected_analysts¶

LLM Configuration¶

Provider Settings¶

llm_provider¶

llm_model¶

llm_temperature¶

llm_max_tokens¶

deep_think_llm¶

quick_think_llm¶

backend_url¶

API Keys¶

Data Vendor Configuration¶

Vendor Selection¶

stock_data_vendor¶

technical_indicators_vendor¶

fundamental_data_vendor¶

news_data_vendor¶

Data Vendor API Keys¶

Directory Configuration¶

Data Directories¶

data_cache_dir¶

results_dir¶

data_dir¶