ouroboros-ai 0.1.0__py3-none-any.whl

ouroboros/persistence/migrations/runner.py

@@ -0,0 +1,100 @@
+"""Simple migration runner for SQLite.
+
+This module provides a basic migration system for applying SQL scripts
+to the database in order. Tracks applied migrations to avoid re-running.
+"""
+
+import asyncio
+from pathlib import Path
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+MIGRATIONS_DIR = Path(__file__).parent / "scripts"
+
+# SQL for migration tracking table
+CREATE_MIGRATIONS_TABLE = """
+CREATE TABLE IF NOT EXISTS _migrations (
+    name TEXT PRIMARY KEY,
+    applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+)
+"""
+
+
+async def _get_applied_migrations(engine: AsyncEngine) -> set[str]:
+    """Get set of already applied migration names.
+
+    Args:
+        engine: SQLAlchemy async engine.
+
+    Returns:
+        Set of applied migration names.
+    """
+    async with engine.begin() as conn:
+        # Ensure migrations table exists
+        await conn.execute(text(CREATE_MIGRATIONS_TABLE))
+
+        # Get applied migrations
+        result = await conn.execute(text("SELECT name FROM _migrations"))
+        return {row[0] for row in result.fetchall()}
+
+
+async def _read_migration_file(migration_file: Path) -> str:
+    """Read migration file content using asyncio.to_thread to avoid blocking.
+
+    Args:
+        migration_file: Path to the migration SQL file.
+
+    Returns:
+        Content of the migration file.
+    """
+    return await asyncio.to_thread(migration_file.read_text)
+
+
+async def run_migrations(engine: AsyncEngine) -> list[str]:
+    """Run all pending migrations.
+
+    Migrations are SQL files in the scripts/ directory, named with a
+    numeric prefix (e.g., 001_initial.sql). They are executed in order.
+    Already applied migrations are tracked and skipped.
+
+    Note: This is a simple migration system. For production, consider
+    using Alembic.
+
+    Args:
+        engine: SQLAlchemy async engine.
+
+    Returns:
+        List of newly applied migration names.
+    """
+    applied: list[str] = []
+
+    # Get already applied migrations
+    already_applied = await _get_applied_migrations(engine)
+
+    # Get all .sql files sorted by name
+    migration_files = sorted(MIGRATIONS_DIR.glob("*.sql"))
+
+    for migration_file in migration_files:
+        if migration_file.name in already_applied:
+            continue
+
+        # Read file content using asyncio.to_thread to avoid blocking
+        sql_content = await _read_migration_file(migration_file)
+
+        async with engine.begin() as conn:
+            # Split by semicolon and execute each statement
+            for statement in sql_content.split(";"):
+                statement = statement.strip()
+                if statement and not statement.startswith("--"):
+                    await conn.execute(text(statement))
+
+            # Record this migration as applied
+            await conn.execute(
+                text("INSERT INTO _migrations (name) VALUES (:name)"),
+                {"name": migration_file.name},
+            )
+
+        applied.append(migration_file.name)
+
+    return applied

ouroboros/persistence/migrations/scripts/001_initial.sql

@@ -0,0 +1,20 @@
+-- Migration: 001_initial
+-- Description: Create initial events table for event sourcing
+-- Created: 2026-01-16
+
+CREATE TABLE IF NOT EXISTS events (
+    id VARCHAR(36) PRIMARY KEY,
+    aggregate_type VARCHAR(100) NOT NULL,
+    aggregate_id VARCHAR(36) NOT NULL,
+    event_type VARCHAR(200) NOT NULL,
+    payload JSON NOT NULL,
+    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    consensus_id VARCHAR(36)
+);
+
+-- Indexes for efficient queries
+CREATE INDEX IF NOT EXISTS ix_events_aggregate_type ON events (aggregate_type);
+CREATE INDEX IF NOT EXISTS ix_events_aggregate_id ON events (aggregate_id);
+CREATE INDEX IF NOT EXISTS ix_events_aggregate_type_id ON events (aggregate_type, aggregate_id);
+CREATE INDEX IF NOT EXISTS ix_events_event_type ON events (event_type);
+CREATE INDEX IF NOT EXISTS ix_events_timestamp ON events (timestamp);

ouroboros/persistence/schema.py

@@ -0,0 +1,56 @@
+"""Database schema definitions using SQLAlchemy Core.
+
+This module defines the events table schema for event sourcing.
+SQLAlchemy Core is used (not ORM) for flexibility and explicit control.
+
+Table: events
+    Single unified table for all event types following event sourcing pattern.
+"""
+
+from datetime import UTC, datetime
+
+from sqlalchemy import (
+    JSON,
+    Column,
+    DateTime,
+    Index,
+    MetaData,
+    String,
+    Table,
+    text,
+)
+
+# Global metadata instance for all tables
+metadata = MetaData()
+
+# Events table - single unified table for event sourcing
+events_table = Table(
+    "events",
+    metadata,
+    # Primary key - UUID as string
+    Column("id", String(36), primary_key=True),
+    # Aggregate identification for event replay
+    Column("aggregate_type", String(100), nullable=False),
+    Column("aggregate_id", String(36), nullable=False),
+    # Event type following dot.notation.past_tense convention
+    # e.g., "ontology.concept.added", "execution.ac.completed"
+    Column("event_type", String(200), nullable=False),
+    # Event payload as JSON
+    Column("payload", JSON, nullable=False),
+    # Timestamp with timezone, defaults to UTC now
+    Column(
+        "timestamp",
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(UTC),
+        server_default=text("CURRENT_TIMESTAMP"),
+    ),
+    # Optional consensus ID for multi-model consensus events
+    Column("consensus_id", String(36), nullable=True),
+    # Indexes for efficient queries
+    Index("ix_events_aggregate_type", "aggregate_type"),
+    Index("ix_events_aggregate_id", "aggregate_id"),
+    Index("ix_events_aggregate_type_id", "aggregate_type", "aggregate_id"),
+    Index("ix_events_event_type", "event_type"),
+    Index("ix_events_timestamp", "timestamp"),
+)

ouroboros/persistence/uow.py

@@ -0,0 +1,230 @@
+"""Unit of Work pattern for phase-based persistence.
+
+This module provides:
+- UnitOfWork: Accumulate events and persist at phase boundaries
+- Transactional coordination between EventStore and CheckpointStore
+
+The UnitOfWork pattern ensures that all related persistence operations
+(events and checkpoints) are committed atomically at phase boundaries.
+"""
+
+from collections.abc import Sequence
+
+from ouroboros.core.errors import PersistenceError
+from ouroboros.core.types import Result
+from ouroboros.events.base import BaseEvent
+from ouroboros.persistence.checkpoint import CheckpointData, CheckpointStore
+from ouroboros.persistence.event_store import EventStore
+
+
+class UnitOfWork:
+    """Unit of Work for coordinating event and checkpoint persistence.
+
+    Accumulates events during a phase and persists both events and checkpoints
+    atomically at phase boundaries. Provides transactional semantics for
+    persistence operations.
+
+    Usage:
+        uow = UnitOfWork(event_store, checkpoint_store)
+
+        # Accumulate events during phase
+        uow.add_event(event1)
+        uow.add_event(event2)
+
+        # Commit at phase boundary
+        checkpoint = CheckpointData.create("seed-123", "planning", state)
+        result = await uow.commit(checkpoint)
+        if result.is_ok:
+            # All events and checkpoint persisted
+            pass
+    """
+
+    def __init__(
+        self, event_store: EventStore, checkpoint_store: CheckpointStore
+    ) -> None:
+        """Initialize unit of work.
+
+        Args:
+            event_store: EventStore for persisting events.
+            checkpoint_store: CheckpointStore for persisting checkpoints.
+        """
+        self._event_store = event_store
+        self._checkpoint_store = checkpoint_store
+        self._pending_events: list[BaseEvent] = []
+
+    def add_event(self, event: BaseEvent) -> None:
+        """Add event to pending events for later commit.
+
+        Args:
+            event: Event to add to the unit of work.
+        """
+        self._pending_events.append(event)
+
+    def add_events(self, events: Sequence[BaseEvent]) -> None:
+        """Add multiple events to pending events.
+
+        Args:
+            events: Sequence of events to add.
+        """
+        self._pending_events.extend(events)
+
+    async def commit(
+        self, checkpoint: CheckpointData | None = None
+    ) -> Result[None, PersistenceError]:
+        """Commit all pending events and optional checkpoint.
+
+        Persists all accumulated events to EventStore and optionally saves
+        a checkpoint. Operations are performed in order:
+        1. Persist all events
+        2. Save checkpoint (if provided)
+
+        On failure, the operation stops and returns an error. Already-persisted
+        events remain in the store (event sourcing is append-only).
+
+        Args:
+            checkpoint: Optional checkpoint to save after events.
+
+        Returns:
+            Result.ok(None) on success,
+            Result.err(PersistenceError) on failure.
+        """
+        try:
+            # Persist all pending events atomically in a single batch
+            if self._pending_events:
+                await self._event_store.append_batch(self._pending_events)
+
+            # Save checkpoint if provided
+            if checkpoint is not None:
+                checkpoint_result = self._checkpoint_store.save(checkpoint)
+                if checkpoint_result.is_err:
+                    return checkpoint_result
+
+            # Clear pending events after successful commit
+            self._pending_events.clear()
+
+            return Result.ok(None)
+
+        except PersistenceError as e:
+            # PersistenceError from event store, re-raise as Result
+            return Result.err(e)
+        except Exception as e:
+            # Unexpected error
+            return Result.err(
+                PersistenceError(
+                    f"Unit of work commit failed: {e}",
+                    operation="commit",
+                    details={"pending_events": len(self._pending_events)},
+                )
+            )
+
+    def rollback(self) -> None:
+        """Rollback by discarding all pending events.
+
+        This is useful when an error occurs during phase execution
+        and you want to discard uncommitted events.
+
+        Note: This only affects pending events. Already-committed events
+        cannot be rolled back (event sourcing is append-only).
+        """
+        self._pending_events.clear()
+
+    @property
+    def pending_event_count(self) -> int:
+        """Get count of pending events awaiting commit.
+
+        Returns:
+            Number of events in the unit of work.
+        """
+        return len(self._pending_events)
+
+    def has_pending_events(self) -> bool:
+        """Check if there are pending events.
+
+        Returns:
+            True if there are uncommitted events.
+        """
+        return len(self._pending_events) > 0
+
+
+class PhaseTransaction:
+    """Context manager for phase-based transactions.
+
+    Provides convenient context manager for phase execution with automatic
+    commit or rollback based on success/failure.
+
+    Usage:
+        async with PhaseTransaction(uow, seed_id, "planning", state) as tx:
+            # Execute phase logic
+            tx.add_event(event1)
+            tx.add_event(event2)
+            # Auto-commits on success, rolls back on exception
+    """
+
+    def __init__(
+        self,
+        uow: UnitOfWork,
+        seed_id: str,
+        phase: str,
+        state: dict,
+    ) -> None:
+        """Initialize phase transaction.
+
+        Args:
+            uow: UnitOfWork instance to use.
+            seed_id: Seed identifier for checkpoint.
+            phase: Current phase name.
+            state: State data for checkpoint.
+        """
+        self._uow = uow
+        self._seed_id = seed_id
+        self._phase = phase
+        self._state = state
+        self._committed = False
+
+    def add_event(self, event: BaseEvent) -> None:
+        """Add event to the transaction.
+
+        Args:
+            event: Event to add.
+        """
+        self._uow.add_event(event)
+
+    def add_events(self, events: Sequence[BaseEvent]) -> None:
+        """Add multiple events to the transaction.
+
+        Args:
+            events: Sequence of events to add.
+        """
+        self._uow.add_events(events)
+
+    async def __aenter__(self) -> "PhaseTransaction":
+        """Enter context manager."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> bool:
+        """Exit context manager with auto-commit or rollback.
+
+        Args:
+            exc_type: Exception type if an exception occurred.
+            exc_val: Exception value if an exception occurred.
+            exc_tb: Exception traceback if an exception occurred.
+
+        Returns:
+            False to propagate exceptions (we don't suppress them).
+        """
+        if exc_type is None and not self._committed:
+            # Success path: commit events and checkpoint
+            checkpoint = CheckpointData.create(
+                self._seed_id, self._phase, self._state
+            )
+            result = await self._uow.commit(checkpoint)
+            if result.is_err:
+                # Commit failed, raise the error
+                raise result.error
+            self._committed = True
+        elif exc_type is not None:
+            # Error path: rollback pending events
+            self._uow.rollback()
+
+        # Don't suppress exceptions
+        return False

ouroboros/providers/__init__.py

@@ -0,0 +1,28 @@
+"""LLM provider adapters for Ouroboros.
+
+This module provides unified access to LLM providers through the LLMAdapter
+protocol and LiteLLMAdapter implementation.
+"""
+
+from ouroboros.providers.base import (
+    CompletionConfig,
+    CompletionResponse,
+    LLMAdapter,
+    Message,
+    MessageRole,
+    UsageInfo,
+)
+from ouroboros.providers.litellm_adapter import LiteLLMAdapter
+
+__all__ = [
+    # Protocol
+    "LLMAdapter",
+    # Models
+    "Message",
+    "MessageRole",
+    "CompletionConfig",
+    "CompletionResponse",
+    "UsageInfo",
+    # Implementations
+    "LiteLLMAdapter",
+]

ouroboros/providers/base.py

@@ -0,0 +1,133 @@
+"""Base protocol and models for LLM provider adapters.
+
+This module defines the LLMAdapter protocol and associated data models for
+communicating with LLM providers in a unified way.
+"""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Protocol
+
+from ouroboros.core.errors import ProviderError
+from ouroboros.core.types import Result
+
+
+class MessageRole(StrEnum):
+    """Role of a message in the conversation."""
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+    """A single message in a conversation.
+
+    Attributes:
+        role: The role of the message sender.
+        content: The text content of the message.
+    """
+
+    role: MessageRole
+    content: str
+
+    def to_dict(self) -> dict[str, str]:
+        """Convert message to dict format for LLM API calls.
+
+        Returns:
+            Dictionary with 'role' and 'content' keys.
+        """
+        return {"role": self.role.value, "content": self.content}
+
+
+@dataclass(frozen=True, slots=True)
+class CompletionConfig:
+    """Configuration for LLM completion requests.
+
+    Attributes:
+        model: The model identifier (e.g., 'openrouter/openai/gpt-4').
+        temperature: Sampling temperature (0.0-2.0). Default 0.7.
+        max_tokens: Maximum tokens to generate. Default 4096.
+        stop: Optional stop sequences.
+        top_p: Nucleus sampling parameter. Default 1.0.
+    """
+
+    model: str
+    temperature: float = 0.7
+    max_tokens: int = 4096
+    stop: list[str] | None = None
+    top_p: float = 1.0
+
+
+@dataclass(frozen=True, slots=True)
+class UsageInfo:
+    """Token usage information from a completion.
+
+    Attributes:
+        prompt_tokens: Number of tokens in the prompt.
+        completion_tokens: Number of tokens in the completion.
+        total_tokens: Total tokens used (prompt + completion).
+    """
+
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+@dataclass(frozen=True, slots=True)
+class CompletionResponse:
+    """Response from an LLM completion request.
+
+    Attributes:
+        content: The generated text content.
+        model: The model that generated the response.
+        usage: Token usage information.
+        finish_reason: Why the generation stopped (e.g., 'stop', 'length').
+        raw_response: Optional raw response from the provider for debugging.
+    """
+
+    content: str
+    model: str
+    usage: UsageInfo
+    finish_reason: str = "stop"
+    raw_response: dict[str, object] = field(default_factory=dict)
+
+
+class LLMAdapter(Protocol):
+    """Protocol for LLM provider adapters.
+
+    All LLM adapters must implement this protocol to provide a unified
+    interface for making completion requests.
+
+    Example:
+        adapter: LLMAdapter = LiteLLMAdapter(api_key="...")
+        result = await adapter.complete(
+            messages=[Message(role=MessageRole.USER, content="Hello!")],
+            config=CompletionConfig(model="openrouter/openai/gpt-4"),
+        )
+        if result.is_ok:
+            print(result.value.content)
+        else:
+            log.error("LLM call failed", error=result.error)
+    """
+
+    async def complete(
+        self,
+        messages: list[Message],
+        config: CompletionConfig,
+    ) -> Result[CompletionResponse, ProviderError]:
+        """Make a completion request to the LLM provider.
+
+        This method handles retries internally and converts all expected
+        failures to Result.err(ProviderError). Exceptions should only
+        occur for programming errors (bugs).
+
+        Args:
+            messages: The conversation messages to send.
+            config: Configuration for the completion request.
+
+        Returns:
+            Result containing either the completion response or a ProviderError.
+        """
+        ...