ouroboros-ai 0.31.2.dev26__tar.gz → 0.31.2.dev28__tar.gz

{ouroboros_ai-0.31.2.dev26 → ouroboros_ai-0.31.2.dev28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.31.2.dev26
+Version: 0.31.2.dev28
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.31.2.dev26 → ouroboros_ai-0.31.2.dev28}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.31.2.dev26'
-__version_tuple__ = version_tuple = (0, 31, 2, 'dev26')
+__version__ = version = '0.31.2.dev28'
+__version_tuple__ = version_tuple = (0, 31, 2, 'dev28')
 
 __commit_id__ = commit_id = None

ouroboros_ai-0.31.2.dev28/src/ouroboros/events/io_recorder.py

@@ -0,0 +1,391 @@
+"""Async context-manager helper that records I/O Journal events.
+
+Issue #517 — slice 2 of #517. Adapters and tool dispatchers wrap their
+LLM/tool calls in :class:`IOJournalRecorder` so the journal entry
+emission becomes a 4-line addition instead of duplicating the
+factory + hashing + privacy + timing boilerplate at every call site.
+
+Design choices baked in:
+
+* The recorder is **always opt-in**. ``event_store=None`` produces a
+  no-op recorder that returns the same context-manager shape but
+  emits nothing. Adapters that have not yet adopted the journal pass
+  ``None`` and continue to work unchanged.
+* The recorder **owns** the ``call_id``, the timing, the hashing, and
+  the privacy switch. Callers only provide payload text and metadata.
+* The recorder pairs a ``*.started`` / ``*.requested`` event with a
+  ``*.returned`` / ``*.returned`` event using a shared ``call_id``.
+  On exception inside the context block the recorder still emits the
+  paired ``returned`` event with ``is_error=True`` so projections see
+  the failure rather than a half-open call.
+* The recorder is **async** so it can ``await event_store.append``;
+  inside the context block the caller can use ordinary ``await``.
+
+The recorder does not import from :mod:`ouroboros.persistence` — it
+takes a duck-typed ``event_store`` with an ``append(event)`` coroutine.
+That keeps it cheaply testable with a ``list``-backed fake.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+import logging
+import time
+from typing import Any, Protocol
+
+from ouroboros.events.base import BaseEvent
+from ouroboros.events.io import (
+    PREVIEW_DEFAULT_CHARS,
+    PREVIEW_HARD_CAP_CHARS_LLM,
+    PREVIEW_HARD_CAP_CHARS_TOOL,
+    PrivacyMode,
+    content_hash,
+    create_llm_call_requested_event,
+    create_llm_call_returned_event,
+    create_tool_call_returned_event,
+    create_tool_call_started_event,
+    new_call_id,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class _AppendableEventStore(Protocol):
+    """Structural type for the recorder's ``event_store`` argument."""
+
+    def append(self, event: BaseEvent) -> Awaitable[None]: ...
+
+
+@dataclass(slots=True)
+class LLMCallRecord:
+    """Mutable handle returned to the caller inside a recorded LLM call.
+
+    The caller fills this in *before* the context exits so the recorder
+    can emit a fully-populated ``llm.call.returned`` event. Any field
+    left at its default reflects "not provided"; the recorder omits
+    ``None`` fields from the persisted payload (matching the policy in
+    ``events/control.py`` and ``events/io.py``).
+    """
+
+    completion_text: str | None = None
+    finish_reason: str | None = None
+    token_count_in: int | None = None
+    token_count_out: int | None = None
+    is_error: bool = False
+    error_kind: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def record_completion(
+        self,
+        *,
+        completion_text: str | None = None,
+        finish_reason: str | None = None,
+        token_count_in: int | None = None,
+        token_count_out: int | None = None,
+        is_error: bool = False,
+        error_kind: str | None = None,
+        **extra: Any,
+    ) -> None:
+        """Fluent setter that mirrors the keyword shape of the factory."""
+        if completion_text is not None:
+            self.completion_text = completion_text
+        if finish_reason is not None:
+            self.finish_reason = finish_reason
+        if token_count_in is not None:
+            self.token_count_in = token_count_in
+        if token_count_out is not None:
+            self.token_count_out = token_count_out
+        if is_error:
+            self.is_error = True
+        if error_kind is not None:
+            self.error_kind = error_kind
+            self.is_error = True
+        if extra:
+            self.extra.update(extra)
+
+    def record_error(self, *, error_kind: str, completion_text: str | None = None) -> None:
+        """Mark a handled provider-level failure without raising from the context."""
+        self.is_error = True
+        self.error_kind = error_kind
+        if completion_text is not None:
+            self.completion_text = completion_text
+
+
+@dataclass(slots=True)
+class ToolCallRecord:
+    """Mutable handle returned to the caller inside a recorded tool call."""
+
+    result_text: str | None = None
+    is_error: bool = False
+    error_kind: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def record_result(
+        self,
+        *,
+        result_text: str | None = None,
+        error_kind: str | None = None,
+        **extra: Any,
+    ) -> None:
+        if result_text is not None:
+            self.result_text = result_text
+        if error_kind is not None:
+            self.error_kind = error_kind
+            self.is_error = True
+        if extra:
+            self.extra.update(extra)
+
+    def record_error(self, *, error_kind: str, result_text: str | None = None) -> None:
+        """Mark a handled tool failure without raising from the context."""
+        self.is_error = True
+        self.error_kind = error_kind
+        if result_text is not None:
+            self.result_text = result_text
+
+
+@dataclass(frozen=True, slots=True)
+class IOJournalRecorder:
+    """Adapter-side helper that wraps LLM and tool calls in journal events.
+
+    Construction:
+        recorder = IOJournalRecorder(
+            event_store=event_store,         # or None for no-op
+            target_type="execution",
+            target_id="exec_123",
+            session_id="sess_x",             # optional correlation
+            execution_id="exec_123",
+            lineage_id=None,
+            generation_number=None,
+            phase=None,
+        )
+
+    Usage::
+
+        async with recorder.record_llm_call(
+            model_id="claude-opus-4",
+            prompt_text=prompt_str,
+            caller="anthropic_adapter",
+        ) as call:
+            response = await client.messages.create(**kwargs)
+            call.record_completion(
+                completion_text=text,
+                finish_reason="stop",
+                token_count_in=120,
+                token_count_out=80,
+            )
+    """
+
+    event_store: _AppendableEventStore | None
+    target_type: str
+    target_id: str
+    session_id: str | None = None
+    execution_id: str | None = None
+    lineage_id: str | None = None
+    generation_number: int | None = None
+    phase: str | None = None
+    privacy: PrivacyMode | None = None
+
+    @property
+    def is_active(self) -> bool:
+        """``True`` when the recorder has somewhere to append events."""
+        return self.event_store is not None
+
+    @asynccontextmanager
+    async def record_llm_call(
+        self,
+        *,
+        model_id: str,
+        prompt_text: str,
+        caller: str | None = None,
+        max_tokens: int | None = None,
+        temperature: float | None = None,
+        tool_choice: str | None = None,
+        preview_cap: int = PREVIEW_DEFAULT_CHARS,
+        preview_hard_cap: int = PREVIEW_HARD_CAP_CHARS_LLM,
+        extra: dict[str, Any] | None = None,
+    ) -> AsyncIterator[LLMCallRecord]:
+        """Wrap an outbound LLM call and emit started/returned events.
+
+        The recorder owns the ``call_id``, the timing, the prompt hash,
+        and the privacy-aware preview shaping. The caller's job is to
+        fill in completion details on the yielded :class:`LLMCallRecord`
+        before the context exits.
+        """
+        record = LLMCallRecord()
+        if not self.is_active:
+            yield record
+            return
+
+        call_id = new_call_id()
+        prompt_hash_value = content_hash(prompt_text)
+        started = create_llm_call_requested_event(
+            target_type=self.target_type,
+            target_id=self.target_id,
+            call_id=call_id,
+            model_id=model_id,
+            prompt_hash=prompt_hash_value,
+            prompt_preview=prompt_text,
+            preview_cap=preview_cap,
+            preview_hard_cap=preview_hard_cap,
+            privacy=self.privacy,
+            caller=caller,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            tool_choice=tool_choice,
+            session_id=self.session_id,
+            execution_id=self.execution_id,
+            lineage_id=self.lineage_id,
+            generation_number=self.generation_number,
+            phase=self.phase,
+            extra=extra,
+        )
+        started_persisted = await self._append(started)
+
+        start_perf = time.perf_counter()
+        is_error = False
+        error_kind: str | None = None
+        try:
+            yield record
+        except BaseException as exc:  # noqa: BLE001 — the journal must capture every failure path
+            is_error = True
+            error_kind = type(exc).__name__
+            raise
+        finally:
+            duration_ms = int((time.perf_counter() - start_perf) * 1000)
+            completion_hash_value = (
+                content_hash(record.completion_text) if record.completion_text is not None else None
+            )
+            if started_persisted:
+                returned = create_llm_call_returned_event(
+                    target_type=self.target_type,
+                    target_id=self.target_id,
+                    call_id=call_id,
+                    model_id=model_id,
+                    prompt_hash=prompt_hash_value,
+                    duration_ms=duration_ms,
+                    is_error=is_error or record.is_error,
+                    completion_preview=record.completion_text,
+                    preview_cap=preview_cap,
+                    preview_hard_cap=preview_hard_cap,
+                    privacy=self.privacy,
+                    completion_hash=completion_hash_value,
+                    finish_reason=record.finish_reason,
+                    token_count_in=record.token_count_in,
+                    token_count_out=record.token_count_out,
+                    error_kind=error_kind or record.error_kind,
+                    session_id=self.session_id,
+                    execution_id=self.execution_id,
+                    lineage_id=self.lineage_id,
+                    generation_number=self.generation_number,
+                    phase=self.phase,
+                    extra=record.extra or None,
+                )
+                await self._append(returned)
+
+    @asynccontextmanager
+    async def record_tool_call(
+        self,
+        *,
+        tool_name: str,
+        args_text: str,
+        caller: str | None = None,
+        mcp_server: str | None = None,
+        preview_cap: int = PREVIEW_DEFAULT_CHARS,
+        preview_hard_cap: int = PREVIEW_HARD_CAP_CHARS_TOOL,
+        extra: dict[str, Any] | None = None,
+    ) -> AsyncIterator[ToolCallRecord]:
+        """Wrap a tool dispatch and emit started/returned events."""
+        record = ToolCallRecord()
+        if not self.is_active:
+            yield record
+            return
+
+        call_id = new_call_id()
+        args_hash_value = content_hash(args_text)
+        started = create_tool_call_started_event(
+            target_type=self.target_type,
+            target_id=self.target_id,
+            call_id=call_id,
+            tool_name=tool_name,
+            args_hash=args_hash_value,
+            args_preview=args_text,
+            preview_cap=preview_cap,
+            preview_hard_cap=preview_hard_cap,
+            privacy=self.privacy,
+            caller=caller,
+            mcp_server=mcp_server,
+            session_id=self.session_id,
+            execution_id=self.execution_id,
+            lineage_id=self.lineage_id,
+            generation_number=self.generation_number,
+            phase=self.phase,
+            extra=extra,
+        )
+        started_persisted = await self._append(started)
+
+        start_perf = time.perf_counter()
+        is_error = False
+        error_kind: str | None = None
+        try:
+            yield record
+        except BaseException as exc:  # noqa: BLE001 — capture every failure
+            is_error = True
+            error_kind = type(exc).__name__
+            raise
+        finally:
+            duration_ms = int((time.perf_counter() - start_perf) * 1000)
+            result_hash_value = (
+                content_hash(record.result_text) if record.result_text is not None else None
+            )
+            if started_persisted:
+                returned = create_tool_call_returned_event(
+                    target_type=self.target_type,
+                    target_id=self.target_id,
+                    call_id=call_id,
+                    tool_name=tool_name,
+                    duration_ms=duration_ms,
+                    is_error=is_error or record.is_error,
+                    result_hash=result_hash_value,
+                    result_preview=record.result_text,
+                    preview_cap=preview_cap,
+                    preview_hard_cap=preview_hard_cap,
+                    privacy=self.privacy,
+                    error_kind=error_kind or record.error_kind,
+                    session_id=self.session_id,
+                    execution_id=self.execution_id,
+                    lineage_id=self.lineage_id,
+                    generation_number=self.generation_number,
+                    phase=self.phase,
+                    extra=record.extra or None,
+                )
+                await self._append(returned)
+
+    async def _append(self, event: BaseEvent) -> bool:
+        """Best-effort append, returning whether the event was persisted.
+
+        A failed start/request append suppresses the paired return event
+        so the EventStore never contains orphaned ``*.returned`` rows.
+        Failures remain observational: the underlying LLM/tool call is
+        never failed because the journal could not record it, but the
+        drop is logged here because generic EventStore failures are not
+        guaranteed to log before raising.
+        """
+        store = self.event_store
+        if store is None:
+            return False
+        try:
+            await store.append(event)
+        except Exception:  # noqa: BLE001 — observational-first
+            logger.warning(
+                "io_journal.append_failed",
+                extra={
+                    "event_type": event.type,
+                    "target_type": event.aggregate_type,
+                    "target_id": event.aggregate_id,
+                },
+                exc_info=True,
+            )
+            return False
+        return True

{ouroboros_ai-0.31.2.dev26 → ouroboros_ai-0.31.2.dev28}/src/ouroboros/providers/anthropic_adapter.py

@@ -13,6 +13,7 @@ import structlog
 from ouroboros.core.errors import ProviderError
 from ouroboros.core.security import MAX_LLM_RESPONSE_LENGTH, InputValidator
 from ouroboros.core.types import Result
+from ouroboros.events.io_recorder import IOJournalRecorder
 from ouroboros.providers.base import (
     CompletionConfig,
     CompletionResponse,
@@ -26,6 +27,46 @@ log = structlog.get_logger()
 DEFAULT_MODEL = "claude-sonnet-4-6"
 
 
+def _serialise_prompt_for_hash(
+    api_messages: list[dict[str, str]],
+    system_parts: list[str],
+    request_options: dict[str, Any] | None = None,
+) -> str:
+    """Build a deterministic string representation of a request for hashing.
+
+    Used by the I/O Journal recorder (#517) to compute ``prompt_hash``
+    without depending on any provider-specific message format. The
+    string itself is **not** the wire payload — it just needs to be
+    stable for the same input so identical prompts collapse to the same
+    hash across runs.
+    """
+    import json
+
+    payload: dict[str, Any] = {"messages": api_messages}
+    if system_parts:
+        payload["system"] = "\n\n".join(system_parts)
+    if request_options:
+        payload["request_options"] = {
+            key: value for key, value in request_options.items() if value is not None
+        }
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"))
+
+
+def _record_completion(call: Any, parsed: CompletionResponse) -> None:
+    """Populate the recorder's LLMCallRecord from a parsed completion.
+
+    Kept as a free function so the recording fields stay close to the
+    parser; the adapter does not need to know about the recorder's
+    internal field names beyond what shows up here.
+    """
+    call.record_completion(
+        completion_text=parsed.content,
+        finish_reason=parsed.finish_reason,
+        token_count_in=parsed.usage.prompt_tokens if parsed.usage else None,
+        token_count_out=parsed.usage.completion_tokens if parsed.usage else None,
+    )
+
+
 class AnthropicAdapter:
     """LLM adapter using the official Anthropic Python SDK.
 
@@ -47,6 +88,7 @@ class AnthropicAdapter:
         timeout: float = 120.0,
         max_retries: int = 2,
         default_model: str = DEFAULT_MODEL,
+        io_recorder: IOJournalRecorder | None = None,
     ) -> None:
         """Initialize the Anthropic adapter.
 
@@ -55,12 +97,20 @@ class AnthropicAdapter:
             timeout: Request timeout in seconds. Default 120.0.
             max_retries: Max retries for transient errors (handled by SDK). Default 2.
             default_model: Fallback model when config.model is empty or generic.
+            io_recorder: Optional :class:`IOJournalRecorder` (M3 / #517).
+                When provided, the adapter wraps each outbound LLM call
+                in the recorder so paired ``llm.call.requested`` /
+                ``llm.call.returned`` events land on the EventStore. The
+                default ``None`` is byte-for-byte the previous
+                behaviour: no journal events, no signature visible to
+                callers that have not adopted the recorder.
         """
         self._api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
         self._timeout = timeout
         self._max_retries = max_retries
         self._default_model = default_model
         self._client: Any = None
+        self._io_recorder = io_recorder
 
     def _get_client(self) -> Any:
         """Lazy-initialize the Anthropic async client.
@@ -190,6 +240,25 @@ class AnthropicAdapter:
         )
 
         try:
+            if self._io_recorder is not None and self._io_recorder.is_active:
+                prompt_text = _serialise_prompt_for_hash(
+                    api_messages,
+                    system_parts,
+                    {"top_p": config.top_p, "stop_sequences": config.stop},
+                )
+                async with self._io_recorder.record_llm_call(
+                    model_id=model,
+                    prompt_text=prompt_text,
+                    caller="anthropic_adapter",
+                    max_tokens=config.max_tokens,
+                    temperature=config.temperature,
+                    extra={"top_p": config.top_p, "stop_sequences": config.stop},
+                ) as call:
+                    response = await client.messages.create(**kwargs)
+                    parsed = self._parse_response(response, model, json_prefill)
+                    _record_completion(call, parsed)
+                return Result.ok(parsed)
+
             response = await client.messages.create(**kwargs)
             return Result.ok(self._parse_response(response, model, json_prefill))