ouroboros-ai 0.1.0__py3-none-any.whl

ouroboros/core/errors.py

@@ -0,0 +1,246 @@
+"""Error hierarchy for Ouroboros.
+
+This module defines the exception hierarchy for Ouroboros. These exceptions
+are used for unexpected errors (programming bugs) and as error types in
+Result for expected failures.
+
+Exception Hierarchy:
+    OuroborosError (base)
+    ├── ProviderError     - LLM provider failures (rate limits, API errors)
+    ├── ConfigError       - Configuration and credentials issues
+    ├── PersistenceError  - Database and storage issues
+    └── ValidationError   - Schema and data validation failures
+"""
+
+from typing import Any
+
+
+class OuroborosError(Exception):
+    """Base exception for all Ouroboros errors.
+
+    All Ouroboros-specific exceptions inherit from this class.
+    This allows catching all Ouroboros errors with a single except clause.
+
+    Attributes:
+        message: Human-readable error description.
+        details: Optional dict with additional context.
+    """
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
+        """Initialize the error.
+
+        Args:
+            message: Human-readable error description.
+            details: Optional dict with additional context about the error.
+        """
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        """Return string representation of the error."""
+        if self.details:
+            return f"{self.message} (details: {self.details})"
+        return self.message
+
+
+class ProviderError(OuroborosError):
+    """Error from LLM provider operations.
+
+    Raised when LLM provider calls fail (rate limits, API errors, timeouts).
+    Can be converted from provider-specific exceptions.
+
+    Attributes:
+        provider: Name of the provider (e.g., "openai", "anthropic").
+        status_code: HTTP status code if applicable.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        provider: str | None = None,
+        status_code: int | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize provider error.
+
+        Args:
+            message: Human-readable error description.
+            provider: Name of the LLM provider.
+            status_code: HTTP status code if applicable.
+            details: Optional dict with additional context.
+        """
+        super().__init__(message, details)
+        self.provider = provider
+        self.status_code = status_code
+
+    @classmethod
+    def from_exception(
+        cls, exc: Exception, *, provider: str | None = None
+    ) -> ProviderError:
+        """Create ProviderError from a provider exception.
+
+        Args:
+            exc: The original exception from the provider.
+            provider: Name of the LLM provider.
+
+        Returns:
+            A ProviderError wrapping the original exception with __cause__ set
+            for proper traceback preservation.
+        """
+        status_code = getattr(exc, "status_code", None)
+        error = cls(
+            str(exc),
+            provider=provider,
+            status_code=status_code,
+            details={"original_exception": type(exc).__name__},
+        )
+        error.__cause__ = exc  # Preserve original traceback
+        return error
+
+
+class ConfigError(OuroborosError):
+    """Error from configuration operations.
+
+    Raised when configuration loading, parsing, or validation fails.
+
+    Attributes:
+        config_key: The configuration key that caused the error.
+        config_file: Path to the config file if applicable.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        config_key: str | None = None,
+        config_file: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize config error.
+
+        Args:
+            message: Human-readable error description.
+            config_key: The configuration key that caused the error.
+            config_file: Path to the config file if applicable.
+            details: Optional dict with additional context.
+        """
+        super().__init__(message, details)
+        self.config_key = config_key
+        self.config_file = config_file
+
+
+class PersistenceError(OuroborosError):
+    """Error from database and storage operations.
+
+    Raised when database queries, event storage, or checkpoint operations fail.
+
+    Attributes:
+        operation: The operation that failed (e.g., "insert", "query").
+        table: The database table involved if applicable.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        operation: str | None = None,
+        table: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize persistence error.
+
+        Args:
+            message: Human-readable error description.
+            operation: The operation that failed.
+            table: The database table involved.
+            details: Optional dict with additional context.
+        """
+        super().__init__(message, details)
+        self.operation = operation
+        self.table = table
+
+
+class ValidationError(OuroborosError):
+    """Error from data validation operations.
+
+    Raised when input data fails schema validation or business rule checks.
+
+    Attributes:
+        field: The field that failed validation.
+        value: The invalid value if safe to include.
+
+    Security Note:
+        Use safe_value property instead of value when logging to avoid
+        exposing sensitive data like API keys or credentials.
+    """
+
+    # Fields that should never have their values exposed
+    _SENSITIVE_FIELDS = frozenset({
+        "password", "api_key", "secret", "token", "credential",
+        "auth", "key", "private", "apikey", "api-key",
+    })
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        field: str | None = None,
+        value: Any | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize validation error.
+
+        Args:
+            message: Human-readable error description.
+            field: The field that failed validation.
+            value: The invalid value (only include if safe).
+            details: Optional dict with additional context.
+        """
+        super().__init__(message, details)
+        self.field = field
+        self.value = value
+
+    @property
+    def safe_value(self) -> str:
+        """Return a safe representation of the value for logging.
+
+        Masks potentially sensitive values based on field name or value type.
+        Always use this instead of value when logging or displaying errors.
+
+        Returns:
+            A safe string representation: masked for sensitive fields,
+            truncated for long values, or type info for complex objects.
+        """
+        if self.value is None:
+            return "<None>"
+
+        # Check if field name suggests sensitive data
+        if self.field:
+            field_lower = self.field.lower()
+            if any(sensitive in field_lower for sensitive in self._SENSITIVE_FIELDS):
+                return "<REDACTED>"
+
+        # Check if value looks like a secret (starts with common prefixes)
+        if isinstance(self.value, str):
+            value_str = self.value
+            secret_prefixes = ("sk-", "pk-", "api-", "bearer ", "token ", "secret_")
+            if any(value_str.lower().startswith(p) for p in secret_prefixes):
+                return "<REDACTED>"
+            # Truncate long strings
+            if len(value_str) > 50:
+                return f"{value_str[:20]}...({len(value_str)} chars)"
+            return repr(value_str)
+
+        # For other types, show type info
+        return f"<{type(self.value).__name__}>"
+
+    def __str__(self) -> str:
+        """Return string representation using safe_value."""
+        base = self.message
+        if self.field:
+            base = f"{base} (field: {self.field}, value: {self.safe_value})"
+        if self.details:
+            base = f"{base} (details: {self.details})"
+        return base

ouroboros/core/seed.py

@@ -0,0 +1,212 @@
+"""Immutable Seed schema for workflow execution.
+
+The Seed is the "constitution" of a workflow - an immutable specification
+generated from the Big Bang interview phase when ambiguity score <= 0.2.
+
+Key properties:
+- Seed.direction (goal, constraints, acceptance_criteria) is IMMUTABLE
+- Effective ontology can evolve with consensus during iterations
+- Contains all information needed to execute and evaluate the workflow
+
+This module defines:
+- Seed: The immutable Pydantic model with frozen=True
+- SeedMetadata: Version and creation metadata
+- Supporting types for seed components
+"""
+
+from datetime import UTC, datetime
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class ExitCondition(BaseModel, frozen=True):
+    """Defines when the workflow should terminate.
+
+    Attributes:
+        name: Short identifier for the condition.
+        description: Detailed explanation of the exit condition.
+        evaluation_criteria: How to determine if condition is met.
+    """
+
+    name: str = Field(..., min_length=1)
+    description: str = Field(..., min_length=1)
+    evaluation_criteria: str = Field(..., min_length=1)
+
+
+class EvaluationPrinciple(BaseModel, frozen=True):
+    """A principle for evaluating workflow outputs.
+
+    Attributes:
+        name: Short identifier for the principle.
+        description: What this principle evaluates.
+        weight: Relative importance (0.0 to 1.0).
+    """
+
+    name: str = Field(..., min_length=1)
+    description: str = Field(..., min_length=1)
+    weight: float = Field(default=1.0, ge=0.0, le=1.0)
+
+
+class OntologyField(BaseModel, frozen=True):
+    """A field in the ontology schema.
+
+    Attributes:
+        name: Field identifier.
+        field_type: Type of the field (string, number, boolean, array, object).
+        description: Purpose of this field.
+        required: Whether this field is required.
+    """
+
+    name: str = Field(..., min_length=1)
+    field_type: str = Field(..., min_length=1)
+    description: str = Field(..., min_length=1)
+    required: bool = Field(default=True)
+
+
+class OntologySchema(BaseModel, frozen=True):
+    """Schema defining the structure of workflow outputs.
+
+    The ontology schema defines what data structure the workflow should
+    produce and maintain throughout iterations.
+
+    Attributes:
+        name: Name of the ontology.
+        description: Purpose and scope of this ontology.
+        fields: List of fields in the ontology.
+    """
+
+    name: str = Field(..., min_length=1)
+    description: str = Field(..., min_length=1)
+    fields: tuple[OntologyField, ...] = Field(default_factory=tuple)
+
+
+class SeedMetadata(BaseModel, frozen=True):
+    """Metadata about the Seed generation.
+
+    Attributes:
+        seed_id: Unique identifier for this seed.
+        version: Schema version for forward compatibility.
+        created_at: When this seed was generated.
+        ambiguity_score: The ambiguity score at generation time.
+        interview_id: Reference to the source interview.
+    """
+
+    seed_id: str = Field(default_factory=lambda: f"seed_{uuid4().hex[:12]}")
+    version: str = Field(default="1.0.0")
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    ambiguity_score: float = Field(..., ge=0.0, le=1.0)
+    interview_id: str | None = Field(default=None)
+
+
+class Seed(BaseModel, frozen=True):
+    """Immutable specification for workflow execution.
+
+    The Seed is the "constitution" of the workflow - once generated, it cannot
+    be modified. This ensures consistency throughout the workflow lifecycle.
+
+    Direction (goal, constraints, acceptance_criteria) is IMMUTABLE:
+    - These define WHAT the workflow should achieve
+    - Cannot be changed after generation
+    - Serves as the ground truth for evaluation
+
+    Attributes:
+        goal: The primary objective of the workflow.
+        constraints: Hard constraints that must be satisfied.
+        acceptance_criteria: Specific criteria for success.
+        ontology_schema: Schema for workflow output structure.
+        evaluation_principles: Principles for evaluating outputs.
+        exit_conditions: Conditions for terminating the workflow.
+        metadata: Generation metadata (version, timestamp, etc.).
+
+    Example:
+        seed = Seed(
+            goal="Build a CLI task management tool",
+            constraints=("Python 3.14+", "No external database"),
+            acceptance_criteria=("Tasks can be created", "Tasks can be listed"),
+            ontology_schema=OntologySchema(
+                name="TaskManager",
+                description="Task management ontology",
+                fields=(
+                    OntologyField(
+                        name="tasks",
+                        field_type="array",
+                        description="List of tasks",
+                    ),
+                ),
+            ),
+            evaluation_principles=(
+                EvaluationPrinciple(
+                    name="completeness",
+                    description="All requirements are met",
+                ),
+            ),
+            exit_conditions=(
+                ExitCondition(
+                    name="all_criteria_met",
+                    description="All acceptance criteria satisfied",
+                    evaluation_criteria="100% criteria pass",
+                ),
+            ),
+            metadata=SeedMetadata(ambiguity_score=0.15),
+        )
+
+        # Attempting to modify raises an error:
+        seed.goal = "New goal"  # Raises ValidationError (frozen)
+    """
+
+    # Direction - IMMUTABLE
+    goal: str = Field(..., min_length=1, description="Primary objective of the workflow")
+    constraints: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Hard constraints that must be satisfied",
+    )
+    acceptance_criteria: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Specific criteria for success evaluation",
+    )
+
+    # Structure
+    ontology_schema: OntologySchema = Field(
+        ...,
+        description="Schema defining the structure of workflow outputs",
+    )
+
+    # Evaluation
+    evaluation_principles: tuple[EvaluationPrinciple, ...] = Field(
+        default_factory=tuple,
+        description="Principles for evaluating workflow outputs",
+    )
+
+    # Termination
+    exit_conditions: tuple[ExitCondition, ...] = Field(
+        default_factory=tuple,
+        description="Conditions for terminating the workflow",
+    )
+
+    # Metadata
+    metadata: SeedMetadata = Field(
+        ...,
+        description="Generation metadata (version, timestamp, etc.)",
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert seed to dictionary for serialization.
+
+        Returns:
+            Dictionary representation of the seed.
+        """
+        return self.model_dump(mode="json")
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Seed":
+        """Create seed from dictionary.
+
+        Args:
+            data: Dictionary representation of the seed.
+
+        Returns:
+            Seed instance.
+        """
+        return cls.model_validate(data)

ouroboros/core/types.py

@@ -0,0 +1,205 @@
+"""Core types for Ouroboros - Result type and type aliases.
+
+This module provides:
+- Result[T, E]: A generic type for handling expected failures without exceptions
+- Type aliases for common domain types
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, cast
+
+
+@dataclass(frozen=True, slots=True)
+class Result[T, E]:
+    """A type that represents either success (Ok) or failure (Err).
+
+    Result is used for expected failures (rate limits, API errors, validation failures)
+    instead of exceptions. Exceptions are reserved for programming errors (bugs).
+
+    Usage:
+        # Construction
+        ok_result: Result[int, str] = Result.ok(42)
+        err_result: Result[int, str] = Result.err("something went wrong")
+
+        # Pattern matching
+        if result.is_ok:
+            process(result.value)
+        else:
+            handle_error(result.error)
+
+        # Transform values
+        mapped = result.map(lambda x: x * 2)
+        mapped_err = result.map_err(lambda e: CustomError(e))
+
+        # Extract values
+        value = result.unwrap()  # Raises if Err
+        value = result.unwrap_or(default)  # Returns default if Err
+    """
+
+    _value: T | None
+    _error: E | None
+    _is_ok: bool
+
+    @classmethod
+    def ok(cls, value: T) -> Result[T, E]:
+        """Create a successful Result containing the given value.
+
+        Args:
+            value: The success value to wrap.
+
+        Returns:
+            A Result in the Ok state.
+        """
+        return cls(_value=value, _error=None, _is_ok=True)
+
+    @classmethod
+    def err(cls, error: E) -> Result[T, E]:
+        """Create a failed Result containing the given error.
+
+        Args:
+            error: The error value to wrap.
+
+        Returns:
+            A Result in the Err state.
+        """
+        return cls(_value=None, _error=error, _is_ok=False)
+
+    @property
+    def is_ok(self) -> bool:
+        """Return True if this Result is Ok (success)."""
+        return self._is_ok
+
+    @property
+    def is_err(self) -> bool:
+        """Return True if this Result is Err (failure)."""
+        return not self._is_ok
+
+    def __repr__(self) -> str:
+        """Return a semantic string representation of the Result.
+
+        Returns:
+            'Ok(value)' for success, 'Err(error)' for failure.
+        """
+        if self._is_ok:
+            return f"Ok({self._value!r})"
+        return f"Err({self._error!r})"
+
+    @property
+    def value(self) -> T:
+        """Return the Ok value.
+
+        Note: Only access this when is_ok is True.
+        For safe access, use unwrap() or unwrap_or().
+        """
+        if not self._is_ok:
+            msg = "Cannot access value on Err result"
+            raise ValueError(msg)
+        return cast(T, self._value)
+
+    @property
+    def error(self) -> E:
+        """Return the Err value.
+
+        Note: Only access this when is_err is True.
+        """
+        if self._is_ok:
+            msg = "Cannot access error on Ok result"
+            raise ValueError(msg)
+        return cast(E, self._error)
+
+    def unwrap(self) -> T:
+        """Return the Ok value or raise ValueError if Err.
+
+        Raises:
+            ValueError: If this Result is Err, with the error as the message.
+
+        Returns:
+            The success value.
+        """
+        if self._is_ok:
+            return cast(T, self._value)
+        raise ValueError(str(self._error))
+
+    def unwrap_or(self, default: T) -> T:
+        """Return the Ok value or the provided default if Err.
+
+        Args:
+            default: Value to return if this Result is Err.
+
+        Returns:
+            The success value if Ok, otherwise the default.
+        """
+        if self._is_ok:
+            return cast(T, self._value)
+        return default
+
+    def map[U](self, fn: Callable[[T], U]) -> Result[U, E]:
+        """Transform the Ok value using the given function.
+
+        If this Result is Ok, apply fn to the value and return Ok(fn(value)).
+        If this Result is Err, return Err unchanged.
+
+        Args:
+            fn: Function to apply to the Ok value.
+
+        Returns:
+            A new Result with the transformed value or the original error.
+        """
+        if self._is_ok:
+            return Result.ok(fn(cast(T, self._value)))
+        return Result.err(cast(E, self._error))
+
+    def map_err[F](self, fn: Callable[[E], F]) -> Result[T, F]:
+        """Transform the Err value using the given function.
+
+        If this Result is Err, apply fn to the error and return Err(fn(error)).
+        If this Result is Ok, return Ok unchanged.
+
+        Args:
+            fn: Function to apply to the Err value.
+
+        Returns:
+            A new Result with the original value or the transformed error.
+        """
+        if self._is_ok:
+            return Result.ok(cast(T, self._value))
+        return Result.err(fn(cast(E, self._error)))
+
+    def and_then[U](self, fn: Callable[[T], "Result[U, E]"]) -> "Result[U, E]":
+        """Chain Result-producing operations (flatMap/bind).
+
+        If this Result is Ok, apply fn to the value and return the result.
+        If this Result is Err, return Err unchanged.
+
+        This is useful for chaining operations that may fail.
+
+        Args:
+            fn: Function that takes the Ok value and returns a new Result.
+
+        Returns:
+            The result of fn if Ok, or the original Err.
+
+        Example:
+            def divide(a: int, b: int) -> Result[int, str]:
+                if b == 0:
+                    return Result.err("division by zero")
+                return Result.ok(a // b)
+
+            result = Result.ok(10).and_then(lambda x: divide(x, 2))
+            # Returns Ok(5)
+        """
+        if self._is_ok:
+            return fn(cast(T, self._value))
+        return Result.err(cast(E, self._error))
+
+
+# Type aliases for common domain types
+EventPayload = dict[str, Any]
+"""Type alias for event payload data - arbitrary JSON-serializable dict."""
+
+CostUnits = int
+"""Type alias for cost tracking - integer units (e.g., token counts)."""
+
+DriftScore = float
+"""Type alias for drift measurement - float between 0.0 and 1.0."""