1501 04 Configuration Directory 990487d5

Configuration Module (src/tunacode/configuration)

Where

src/tunacode/configuration/ - Application configuration and settings management.

What

Manages all aspects of TunaCode configuration:

• User Settings: settings.py - Application preferences and defaults
• Model Registry: models.py + models_registry.json - Available AI models
• Pricing Data: pricing.py - Cost tracking and token pricing
• Defaults: defaults.py - Factory default configuration

Directory Structure

configuration/
├── __init__.py              # Package exports
├── settings.py              # User settings management
├── models.py                # Model definitions and metadata
├── models_registry.json     # Model database (provider, capabilities, pricing)
├── pricing.py               # Token pricing and cost calculation
└── defaults.py              # Default configuration values

How

The configuration module implements a layered configuration system:

Configuration Layers

Configuration is loaded in priority order:

1. Code Defaults: Hardcoded in defaults.py
2. User Config: ~/.tunacode/tunacode.json
3. Environment Variables: .env file or shell environment
4. Command-Line Args: Runtime overrides

Settings System (settings.py)

Manages user preferences:

class Settings:
    # Model Configuration
    model: str

    # Behavior
    timeout: float
    max_retries: int
    auto_confirm: bool

    # UI Preferences
    theme: str

    # Provider-Specific Settings
    providers: {
        "<provider_name>": {
            "base_url": str | None  # Per-provider base URL override
        }
    }

Base URL Resolution (in agent_config.py):

1. Per-provider config: settings.providers.<provider>.base_url
2. Registry default: models_registry.json → provider api field
3. OpenAI escape hatch: OPENAI_BASE_URL env var (non-Anthropic only)

Settings Features:

• Schema Validation: Pydantic models validate settings
• Migration: Versioned settings support schema changes
• Defaults: Automatic fallback to factory defaults
• Hot Reload: Settings can be reloaded without restart

Model Registry (models.py + models_registry.json)

Database of available AI models:

Model Metadata:

{
  "model_id": {
    "provider": "anthropic",
    "name": "Claude 3 Opus",
    "context_window": 200000,
    "supports_vision": true,
    "supports_tools": true,
    "input_price": 0.015,
    "output_price": 0.075,
    "capabilities": ["tool_use", "vision", "streaming"]
  }
}

Registry Features:

• Provider Support: Anthropic, OpenAI, Google, local models
• Capability Detection: Tool use, vision, streaming support
• Version Tracking: Model aliases and versioning
• Lazy Loading: Models loaded on-demand to reduce startup time

Pricing System (pricing.py)

Tracks token usage and costs:

class ModelPricing:
    input_price_per_1k: float  # Cost per 1K input tokens
    output_price_per_1k: float # Cost per 1K output tokens
    currency: str = "USD"

    def calculate_cost(input_tokens: int, output_tokens: int) -> float:
        """Calculate total cost in currency."""

Pricing Features:

• Real-Time Tracking: Cost updates during streaming
• Session Totals: Cumulative cost across all requests
• Budget Alerts: Warnings when approaching spending limits
• Multi-Currency: Extensible currency support (default USD)

Defaults System (defaults.py)

Factory default configuration:

DEFAULT_SETTINGS = {
    "model": "claude-opus-4-5-20251101",
    "timeout": 120.0,
    "max_retries": 3,
    "theme": "tunacode",
    "auto_confirm": False,
    # ... more defaults
}

Default Strategy:

• Sensible Defaults: Work out-of-the-box for most users
• Documentation: Each default includes explanatory comment
• Override Points: Clear path to override any default
• Versioning: Defaults can evolve with application versions

Why

Configuration Centralization: All settings managed in one place:

• Maintainability: Single source of truth for configuration
• Consistency: All parts of app use same config values
• Testability: Default config enables reproducible tests
• Documentation: Settings are self-documenting via Pydantic models

User Experience:

• Zero Config: Works immediately with sensible defaults
• Progressive Enhancement: Advanced users can customize deeply
• Clear Errors: Validation errors explain exactly what's wrong
• Migration: Settings upgrades preserve user preferences

Design Principles:

1. Explicit Over Implicit: Config values are visible and obvious
2. Fail Fast: Invalid config caught at startup, not runtime
3. Backward Compatible: Old config files work with new versions
4. Documented: Every setting has clear documentation
5. Secure: API keys never logged or displayed

Integration Points

• Core Agents: tunacode.core reads model settings for API initialization
• Token Usage: tunacode.core.token_usage uses pricing data for cost calculation
• UI: tunacode.ui displays settings and runs setup wizard
• CLI: Command-line args override config file values

Code Quality Notes

• Type Safety: Pydantic models enforce type checking
• Validation: Complex validation rules for config values
• Documentation: Docstrings explain each setting's purpose
• Testing: Config validation tested with edge cases
• Performance: Lazy loading of model registry for fast startup

Configuration Files

• User Config: ~/.tunacode/tunacode.json
• Environment: .env file in project root
• Session Data: ~/.tunacode/sessions/<session_id>/