ouroboros-ai 0.1.0__py3-none-any.whl

ouroboros/config/loader.py

@@ -0,0 +1,292 @@
+"""Configuration loading and management for Ouroboros.
+
+This module provides functions for loading, creating, and validating
+Ouroboros configuration files.
+
+Functions:
+    load_config: Load configuration from ~/.ouroboros/config.yaml
+    load_credentials: Load credentials from ~/.ouroboros/credentials.yaml
+    create_default_config: Create default configuration files
+    ensure_config_dir: Ensure ~/.ouroboros/ directory exists
+"""
+
+import os
+from pathlib import Path
+import stat
+from typing import Any
+
+from pydantic import ValidationError as PydanticValidationError
+import yaml
+
+from ouroboros.config.models import (
+    CredentialsConfig,
+    OuroborosConfig,
+    get_config_dir,
+    get_default_config,
+    get_default_credentials,
+)
+from ouroboros.core.errors import ConfigError
+
+
+def ensure_config_dir() -> Path:
+    """Ensure the configuration directory exists.
+
+    Creates ~/.ouroboros/ directory and subdirectories if they don't exist.
+
+    Returns:
+        Path to the configuration directory.
+    """
+    config_dir = get_config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create subdirectories
+    (config_dir / "data").mkdir(exist_ok=True)
+    (config_dir / "logs").mkdir(exist_ok=True)
+
+    return config_dir
+
+
+def _set_secure_permissions(file_path: Path) -> None:
+    """Set secure permissions (chmod 600) on a file.
+
+    Args:
+        file_path: Path to the file to secure.
+    """
+    # Set permissions to owner read/write only (0o600)
+    os.chmod(file_path, stat.S_IRUSR | stat.S_IWUSR)
+
+
+def _model_to_yaml_dict(model: OuroborosConfig | CredentialsConfig) -> dict[str, Any]:
+    """Convert a Pydantic model to a YAML-serializable dict.
+
+    Args:
+        model: The Pydantic model to convert.
+
+    Returns:
+        A dict suitable for YAML serialization.
+    """
+    return model.model_dump(mode="json")
+
+
+def create_default_config(
+    config_dir: Path | None = None,
+    *,
+    overwrite: bool = False,
+) -> tuple[Path, Path]:
+    """Create default configuration files.
+
+    Creates config.yaml and credentials.yaml with default templates
+    in the specified directory. credentials.yaml is created with
+    chmod 600 permissions for security.
+
+    Args:
+        config_dir: Directory to create files in. Defaults to ~/.ouroboros/
+        overwrite: If True, overwrite existing files. Defaults to False.
+
+    Returns:
+        Tuple of (config_path, credentials_path).
+
+    Raises:
+        ConfigError: If files exist and overwrite=False.
+    """
+    if config_dir is None:
+        config_dir = ensure_config_dir()
+    else:
+        config_dir.mkdir(parents=True, exist_ok=True)
+        (config_dir / "data").mkdir(exist_ok=True)
+        (config_dir / "logs").mkdir(exist_ok=True)
+
+    config_path = config_dir / "config.yaml"
+    credentials_path = config_dir / "credentials.yaml"
+
+    # Check if files exist
+    if not overwrite:
+        if config_path.exists():
+            raise ConfigError(
+                f"Configuration file already exists: {config_path}",
+                config_file=str(config_path),
+            )
+        if credentials_path.exists():
+            raise ConfigError(
+                f"Credentials file already exists: {credentials_path}",
+                config_file=str(credentials_path),
+            )
+
+    # Create config.yaml
+    default_config = get_default_config()
+    config_dict = _model_to_yaml_dict(default_config)
+    with config_path.open("w") as f:
+        yaml.dump(
+            config_dict,
+            f,
+            default_flow_style=False,
+            sort_keys=False,
+            allow_unicode=True,
+        )
+
+    # Create credentials.yaml with secure permissions
+    default_credentials = get_default_credentials()
+    credentials_dict = _model_to_yaml_dict(default_credentials)
+    with credentials_path.open("w") as f:
+        yaml.dump(
+            credentials_dict,
+            f,
+            default_flow_style=False,
+            sort_keys=False,
+            allow_unicode=True,
+        )
+
+    # Set chmod 600 on credentials file
+    _set_secure_permissions(credentials_path)
+
+    return config_path, credentials_path
+
+
+def load_config(config_path: Path | None = None) -> OuroborosConfig:
+    """Load configuration from YAML file.
+
+    Loads and validates configuration from the specified path or
+    the default ~/.ouroboros/config.yaml.
+
+    Args:
+        config_path: Path to config file. Defaults to ~/.ouroboros/config.yaml.
+
+    Returns:
+        Validated OuroborosConfig instance.
+
+    Raises:
+        ConfigError: If file doesn't exist, is malformed, or fails validation.
+    """
+    if config_path is None:
+        config_path = get_config_dir() / "config.yaml"
+
+    if not config_path.exists():
+        raise ConfigError(
+            f"Configuration file not found: {config_path}. "
+            "Run `ouroboros config init` to create default configuration.",
+            config_file=str(config_path),
+        )
+
+    try:
+        with config_path.open() as f:
+            config_dict = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ConfigError(
+            f"Failed to parse configuration file: {e}",
+            config_file=str(config_path),
+            details={"yaml_error": str(e)},
+        ) from e
+
+    if config_dict is None:
+        config_dict = {}
+
+    try:
+        return OuroborosConfig.model_validate(config_dict)
+    except PydanticValidationError as e:
+        # Format validation errors for clarity
+        error_messages = []
+        for error in e.errors():
+            loc = ".".join(str(x) for x in error["loc"])
+            msg = error["msg"]
+            error_messages.append(f"  - {loc}: {msg}")
+
+        raise ConfigError(
+            "Configuration validation failed:\n" + "\n".join(error_messages),
+            config_file=str(config_path),
+            details={"validation_errors": e.errors()},
+        ) from e
+
+
+def load_credentials(credentials_path: Path | None = None) -> CredentialsConfig:
+    """Load credentials from YAML file.
+
+    Loads and validates credentials from the specified path or
+    the default ~/.ouroboros/credentials.yaml.
+
+    Args:
+        credentials_path: Path to credentials file.
+            Defaults to ~/.ouroboros/credentials.yaml.
+
+    Returns:
+        Validated CredentialsConfig instance.
+
+    Raises:
+        ConfigError: If file doesn't exist, is malformed, or fails validation.
+    """
+    if credentials_path is None:
+        credentials_path = get_config_dir() / "credentials.yaml"
+
+    if not credentials_path.exists():
+        raise ConfigError(
+            f"Credentials file not found: {credentials_path}. "
+            "Run `ouroboros config init` to create default configuration.",
+            config_file=str(credentials_path),
+        )
+
+    # Check file permissions (warn if too permissive)
+    file_mode = credentials_path.stat().st_mode
+    if file_mode & (stat.S_IRGRP | stat.S_IROTH):
+        # File is readable by group or others - this is a security warning
+        # We don't raise an error, but this could be logged
+        pass
+
+    try:
+        with credentials_path.open() as f:
+            credentials_dict = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ConfigError(
+            f"Failed to parse credentials file: {e}",
+            config_file=str(credentials_path),
+            details={"yaml_error": str(e)},
+        ) from e
+
+    if credentials_dict is None:
+        credentials_dict = {}
+
+    try:
+        return CredentialsConfig.model_validate(credentials_dict)
+    except PydanticValidationError as e:
+        error_messages = []
+        for error in e.errors():
+            loc = ".".join(str(x) for x in error["loc"])
+            msg = error["msg"]
+            error_messages.append(f"  - {loc}: {msg}")
+
+        raise ConfigError(
+            "Credentials validation failed:\n" + "\n".join(error_messages),
+            config_file=str(credentials_path),
+            details={"validation_errors": e.errors()},
+        ) from e
+
+
+def config_exists() -> bool:
+    """Check if configuration files exist.
+
+    Returns:
+        True if both config.yaml and credentials.yaml exist.
+    """
+    config_dir = get_config_dir()
+    return (config_dir / "config.yaml").exists() and (
+        config_dir / "credentials.yaml"
+    ).exists()
+
+
+def credentials_file_secure(credentials_path: Path | None = None) -> bool:
+    """Check if credentials file has secure permissions.
+
+    Args:
+        credentials_path: Path to credentials file.
+            Defaults to ~/.ouroboros/credentials.yaml.
+
+    Returns:
+        True if file has chmod 600 (owner read/write only).
+    """
+    if credentials_path is None:
+        credentials_path = get_config_dir() / "credentials.yaml"
+
+    if not credentials_path.exists():
+        return False
+
+    file_mode = credentials_path.stat().st_mode
+    # Check that only owner has read/write permissions
+    return (file_mode & 0o777) == 0o600

ouroboros/config/models.py

@@ -0,0 +1,332 @@
+"""Pydantic models for Ouroboros configuration.
+
+This module defines the configuration schema using Pydantic v2.
+All configuration validation happens through these models.
+
+Classes:
+    ModelConfig: Single LLM model configuration
+    TierConfig: Tier configuration with cost factor and models
+    ProviderCredentials: API credentials for a single provider
+    CredentialsConfig: All provider credentials
+    EconomicsConfig: Economic model with tier definitions
+    ClarificationConfig: Phase 0 configuration
+    ExecutionConfig: Phase 2 configuration
+    ResilienceConfig: Phase 3 configuration
+    EvaluationConfig: Phase 4 configuration
+    ConsensusConfig: Phase 5 configuration
+    PersistenceConfig: Storage configuration
+    LoggingConfig: Logging configuration
+    OuroborosConfig: Top-level configuration combining all sections
+"""
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ModelConfig(BaseModel, frozen=True):
+    """Configuration for a single LLM model.
+
+    Attributes:
+        provider: Provider name (openai, anthropic, google, openrouter)
+        model: Model identifier string
+    """
+
+    provider: str
+    model: str
+
+
+class TierConfig(BaseModel, frozen=True):
+    """Configuration for a cost tier.
+
+    Attributes:
+        cost_factor: Relative cost multiplier (1 for frugal, 10 for standard, etc.)
+        intelligence_range: Tuple of min/max intelligence score
+        models: List of models available in this tier
+        use_cases: List of use cases this tier is suited for
+    """
+
+    cost_factor: int = Field(ge=1)
+    intelligence_range: tuple[int, int] = Field(default=(1, 20))
+    models: list[ModelConfig] = Field(default_factory=list)
+    use_cases: list[str] = Field(default_factory=list)
+
+    @field_validator("intelligence_range")
+    @classmethod
+    def validate_intelligence_range(cls, v: tuple[int, int]) -> tuple[int, int]:
+        """Validate that min <= max in intelligence range."""
+        if v[0] > v[1]:
+            msg = f"Intelligence range min ({v[0]}) must be <= max ({v[1]})"
+            raise ValueError(msg)
+        return v
+
+
+class ProviderCredentials(BaseModel, frozen=True):
+    """API credentials for a single provider.
+
+    Attributes:
+        api_key: The API key for the provider
+        base_url: Optional custom base URL for the provider
+    """
+
+    api_key: str = Field(min_length=1)
+    base_url: str | None = None
+
+
+class CredentialsConfig(BaseModel, frozen=True):
+    """Configuration for all provider credentials.
+
+    Attributes:
+        providers: Dict mapping provider name to credentials
+    """
+
+    providers: dict[str, ProviderCredentials] = Field(default_factory=dict)
+
+
+class EconomicsConfig(BaseModel, frozen=True):
+    """Economic model configuration.
+
+    Attributes:
+        default_tier: Default tier to use for tasks
+        tiers: Dict mapping tier name to tier configuration
+        escalation_threshold: Number of failures before upgrading tier
+        downgrade_success_streak: Successes needed to downgrade tier
+    """
+
+    default_tier: Literal["frugal", "standard", "frontier"] = "frugal"
+    tiers: dict[str, TierConfig] = Field(default_factory=dict)
+    escalation_threshold: int = Field(default=2, ge=1)
+    downgrade_success_streak: int = Field(default=5, ge=1)
+
+
+class ClarificationConfig(BaseModel, frozen=True):
+    """Phase 0 (Big Bang) configuration.
+
+    Attributes:
+        ambiguity_threshold: Maximum ambiguity score to proceed
+        max_interview_rounds: Maximum number of clarification rounds
+        model_tier: Tier to use for clarification
+        default_model: Default LLM model for interview and seed generation
+    """
+
+    ambiguity_threshold: float = Field(default=0.2, ge=0.0, le=1.0)
+    max_interview_rounds: int = Field(default=10, ge=1)
+    model_tier: Literal["frugal", "standard", "frontier"] = "standard"
+    default_model: str = "openrouter/google/gemini-2.0-flash-001"
+
+
+class ExecutionConfig(BaseModel, frozen=True):
+    """Phase 2 (Execution) configuration.
+
+    Attributes:
+        max_iterations_per_ac: Maximum iterations per acceptance criteria
+        retrospective_interval: Iterations between retrospectives
+    """
+
+    max_iterations_per_ac: int = Field(default=10, ge=1)
+    retrospective_interval: int = Field(default=3, ge=1)
+
+
+class ResilienceConfig(BaseModel, frozen=True):
+    """Phase 3 (Resilience) configuration.
+
+    Attributes:
+        stagnation_enabled: Whether stagnation detection is enabled
+        lateral_thinking_enabled: Whether lateral thinking is enabled
+        lateral_model_tier: Tier for lateral thinking
+        lateral_temperature: Temperature for lateral thinking LLM calls
+    """
+
+    stagnation_enabled: bool = True
+    lateral_thinking_enabled: bool = True
+    lateral_model_tier: Literal["frugal", "standard", "frontier"] = "frontier"
+    lateral_temperature: float = Field(default=0.8, ge=0.0, le=2.0)
+
+
+class EvaluationConfig(BaseModel, frozen=True):
+    """Phase 4 (Evaluation) configuration.
+
+    Attributes:
+        stage1_enabled: Whether mechanical checks are enabled
+        stage2_enabled: Whether semantic evaluation is enabled
+        stage3_enabled: Whether consensus evaluation is enabled
+        satisfaction_threshold: Minimum satisfaction score
+        uncertainty_threshold: Threshold above which to trigger consensus
+    """
+
+    stage1_enabled: bool = True
+    stage2_enabled: bool = True
+    stage3_enabled: bool = True
+    satisfaction_threshold: float = Field(default=0.8, ge=0.0, le=1.0)
+    uncertainty_threshold: float = Field(default=0.3, ge=0.0, le=1.0)
+
+
+class ConsensusConfig(BaseModel, frozen=True):
+    """Phase 5 (Consensus) configuration.
+
+    Attributes:
+        min_models: Minimum number of models for consensus
+        threshold: Agreement threshold for consensus
+        diversity_required: Whether different providers are required
+    """
+
+    min_models: int = Field(default=3, ge=2)
+    threshold: float = Field(default=0.67, ge=0.0, le=1.0)
+    diversity_required: bool = True
+
+
+class PersistenceConfig(BaseModel, frozen=True):
+    """Persistence configuration.
+
+    Attributes:
+        enabled: Whether persistence is enabled
+        database_path: Path to SQLite database (relative to config dir)
+    """
+
+    enabled: bool = True
+    database_path: str = "data/ouroboros.db"
+
+
+class DriftConfig(BaseModel, frozen=True):
+    """Drift monitoring configuration.
+
+    Attributes:
+        warning_threshold: Drift score threshold for warnings
+        critical_threshold: Drift score threshold for intervention
+    """
+
+    warning_threshold: float = Field(default=0.3, ge=0.0, le=1.0)
+    critical_threshold: float = Field(default=0.5, ge=0.0, le=1.0)
+
+    @field_validator("critical_threshold")
+    @classmethod
+    def validate_critical_threshold(cls, v: float, info: object) -> float:
+        """Validate that critical threshold >= warning threshold."""
+        data = getattr(info, "data", {})
+        warning = data.get("warning_threshold", 0.3)
+        if v < warning:
+            msg = f"critical_threshold ({v}) must be >= warning_threshold ({warning})"
+            raise ValueError(msg)
+        return v
+
+
+class LoggingConfig(BaseModel, frozen=True):
+    """Logging configuration.
+
+    Attributes:
+        level: Log level (debug, info, warning, error)
+        log_path: Path to log file (relative to config dir)
+        include_reasoning: Whether to log LLM reasoning
+    """
+
+    level: Literal["debug", "info", "warning", "error"] = "info"
+    log_path: str = "logs/ouroboros.log"
+    include_reasoning: bool = True
+
+
+class OuroborosConfig(BaseModel, frozen=True):
+    """Top-level Ouroboros configuration.
+
+    This is the main configuration model that combines all section configs.
+    It validates against config.yaml in ~/.ouroboros/.
+
+    Attributes:
+        economics: Economic model and tier configuration
+        clarification: Phase 0 (Big Bang) configuration
+        execution: Phase 2 configuration
+        resilience: Phase 3 configuration
+        evaluation: Phase 4 configuration
+        consensus: Phase 5 configuration
+        persistence: Storage configuration
+        drift: Drift monitoring configuration
+        logging: Logging configuration
+    """
+
+    economics: EconomicsConfig = Field(default_factory=EconomicsConfig)
+    clarification: ClarificationConfig = Field(default_factory=ClarificationConfig)
+    execution: ExecutionConfig = Field(default_factory=ExecutionConfig)
+    resilience: ResilienceConfig = Field(default_factory=ResilienceConfig)
+    evaluation: EvaluationConfig = Field(default_factory=EvaluationConfig)
+    consensus: ConsensusConfig = Field(default_factory=ConsensusConfig)
+    persistence: PersistenceConfig = Field(default_factory=PersistenceConfig)
+    drift: DriftConfig = Field(default_factory=DriftConfig)
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+
+
+def get_default_config() -> OuroborosConfig:
+    """Get the default Ouroboros configuration.
+
+    Returns:
+        OuroborosConfig with all default values populated.
+    """
+    return OuroborosConfig(
+        economics=EconomicsConfig(
+            default_tier="frugal",
+            tiers={
+                "frugal": TierConfig(
+                    cost_factor=1,
+                    intelligence_range=(9, 11),
+                    models=[
+                        ModelConfig(provider="openai", model="gpt-4o-mini"),
+                        ModelConfig(provider="google", model="gemini-2.0-flash"),
+                        ModelConfig(provider="anthropic", model="claude-3-5-haiku"),
+                    ],
+                    use_cases=["routine_coding", "log_analysis", "stage1_fix"],
+                ),
+                "standard": TierConfig(
+                    cost_factor=10,
+                    intelligence_range=(14, 16),
+                    models=[
+                        ModelConfig(provider="openai", model="gpt-4o"),
+                        ModelConfig(provider="anthropic", model="claude-sonnet-4-20250514"),
+                        ModelConfig(provider="google", model="gemini-2.5-pro"),
+                    ],
+                    use_cases=["logic_design", "stage2_evaluation", "refactoring"],
+                ),
+                "frontier": TierConfig(
+                    cost_factor=30,
+                    intelligence_range=(18, 20),
+                    models=[
+                        ModelConfig(provider="openai", model="o3"),
+                        ModelConfig(provider="anthropic", model="claude-opus-4-5-20251101"),
+                    ],
+                    use_cases=["consensus", "lateral_thinking", "big_bang"],
+                ),
+            },
+            escalation_threshold=2,
+            downgrade_success_streak=5,
+        ),
+    )
+
+
+def get_default_credentials() -> CredentialsConfig:
+    """Get the default credentials configuration template.
+
+    Returns:
+        CredentialsConfig with placeholder providers.
+
+    Note:
+        The returned credentials have empty API keys and should be
+        filled in by the user.
+    """
+    return CredentialsConfig(
+        providers={
+            "openrouter": ProviderCredentials(
+                api_key="YOUR_OPENROUTER_API_KEY",
+                base_url="https://openrouter.ai/api/v1",
+            ),
+            "openai": ProviderCredentials(api_key="YOUR_OPENAI_API_KEY"),
+            "anthropic": ProviderCredentials(api_key="YOUR_ANTHROPIC_API_KEY"),
+            "google": ProviderCredentials(api_key="YOUR_GOOGLE_API_KEY"),
+        }
+    )
+
+
+def get_config_dir() -> Path:
+    """Get the Ouroboros configuration directory path.
+
+    Returns:
+        Path to ~/.ouroboros/
+    """
+    return Path.home() / ".ouroboros"

ouroboros/core/__init__.py

@@ -0,0 +1,62 @@
+"""Ouroboros core module - shared types, errors, and protocols."""
+
+from ouroboros.core.context import (
+    CompressionResult,
+    ContextMetrics,
+    FilteredContext,
+    WorkflowContext,
+    compress_context,
+    compress_context_with_llm,
+    count_context_tokens,
+    count_tokens,
+    create_filtered_context,
+    get_context_metrics,
+)
+from ouroboros.core.errors import (
+    ConfigError,
+    OuroborosError,
+    PersistenceError,
+    ProviderError,
+    ValidationError,
+)
+from ouroboros.core.seed import (
+    EvaluationPrinciple,
+    ExitCondition,
+    OntologyField,
+    OntologySchema,
+    Seed,
+    SeedMetadata,
+)
+from ouroboros.core.types import CostUnits, DriftScore, EventPayload, Result
+
+__all__ = [
+    # Types
+    "Result",
+    "EventPayload",
+    "CostUnits",
+    "DriftScore",
+    # Errors
+    "OuroborosError",
+    "ProviderError",
+    "ConfigError",
+    "PersistenceError",
+    "ValidationError",
+    # Seed (Immutable Specification)
+    "Seed",
+    "SeedMetadata",
+    "OntologySchema",
+    "OntologyField",
+    "EvaluationPrinciple",
+    "ExitCondition",
+    # Context Management
+    "WorkflowContext",
+    "ContextMetrics",
+    "CompressionResult",
+    "FilteredContext",
+    "count_tokens",
+    "count_context_tokens",
+    "get_context_metrics",
+    "compress_context",
+    "compress_context_with_llm",
+    "create_filtered_context",
+]