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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.31.2.dev28
+Version: 0.31.2.dev29
 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.dev28 → ouroboros_ai-0.31.2.dev29}/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.dev28'
-__version_tuple__ = version_tuple = (0, 31, 2, 'dev28')
+__version__ = version = '0.31.2.dev29'
+__version_tuple__ = version_tuple = (0, 31, 2, 'dev29')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.31.2.dev28 → ouroboros_ai-0.31.2.dev29}/src/ouroboros/providers/litellm_adapter.py

@@ -4,8 +4,9 @@ This module provides the LiteLLMAdapter class that implements the LLMAdapter
 protocol using LiteLLM for multi-provider support including OpenRouter.
 """
 
+import json
 import os
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import litellm
 import structlog
@@ -21,6 +22,9 @@ from ouroboros.providers.base import (
     UsageInfo,
 )
 
+if TYPE_CHECKING:
+    from ouroboros.events.io_recorder import IOJournalRecorder
+
 log = structlog.get_logger()
 _CREDENTIALS_UNSET = object()
 _PLACEHOLDER_API_KEY_PREFIX = "YOUR_"
@@ -35,6 +39,54 @@ RETRIABLE_EXCEPTIONS = (
 )
 
 
+def _serialise_messages_for_hash(
+    messages: list[Message],
+    request_options: dict[str, Any] | None = None,
+) -> str:
+    """Build a deterministic string of the request payload for hashing.
+
+    Used by the I/O Journal recorder (#517) to compute ``prompt_hash``.
+    The string is stable for identical input and request-shaping options
+    so materially different LiteLLM calls do not collapse to the same
+    hash; it is not the wire payload.
+    """
+    payload: dict[str, Any] = {
+        "messages": [{"role": str(m.role), "content": m.content} for m in messages]
+    }
+    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_litellm_completion(call: Any, parsed: CompletionResponse) -> None:
+    """Populate the recorder's LLMCallRecord from the parsed response.
+
+    Recording the same ``CompletionResponse`` returned to callers keeps
+    the journal aligned with adapter-visible truncation and normalization.
+    """
+    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,
+    )
+
+
+def _request_options_for_hash(config: CompletionConfig) -> dict[str, Any]:
+    """Return request-shaping options not already first-class journal fields."""
+    options: dict[str, Any] = {}
+    model_lower = config.model.lower()
+    if not ("anthropic" in model_lower or "claude" in model_lower):
+        options["top_p"] = config.top_p
+    if config.stop:
+        options["stop"] = config.stop
+    if config.response_format:
+        options["response_format"] = config.response_format
+    return options
+
+
 class LiteLLMAdapter:
     """LLM adapter using LiteLLM for unified provider access.
 
@@ -65,6 +117,7 @@ class LiteLLMAdapter:
         api_base: str | None = None,
         timeout: float = 60.0,
         max_retries: int = 3,
+        io_recorder: "IOJournalRecorder | None" = None,
     ) -> None:
         """Initialize the LiteLLM adapter.
 
@@ -73,12 +126,21 @@ class LiteLLMAdapter:
             api_base: Optional API base URL for custom endpoints.
             timeout: Request timeout in seconds. Default 60.0.
             max_retries: Maximum number of retries for transient errors. Default 3.
+            io_recorder: Optional :class:`IOJournalRecorder` (M3 / #517).
+                When provided, every retry attempt of the outbound LLM
+                call is wrapped in the recorder so paired
+                ``llm.call.requested`` / ``llm.call.returned`` events
+                land on the EventStore — each retry produces its own
+                pair, so failures across retries appear in the journal
+                as distinct attempts. Default ``None`` is byte-for-byte
+                the previous behaviour.
         """
         self._api_key = api_key
         self._api_base = api_base
         self._timeout = timeout
         self._max_retries = max_retries
         self._credentials_cache: object = _CREDENTIALS_UNSET
+        self._io_recorder = io_recorder
 
     def _load_credentials_config(self):
         """Load credentials.yaml once, caching missing-config cases."""
@@ -335,12 +397,29 @@ class LiteLLMAdapter:
             wait_max=10.0,
             wait_jitter=1.0,
         )
-        async def _with_retry() -> litellm.ModelResponse:
-            return await self._raw_complete(messages, config)
+        async def _with_retry() -> CompletionResponse:
+            recorder = self._io_recorder
+            if recorder is None or not recorder.is_active:
+                response = await self._raw_complete(messages, config)
+                return self._parse_response(response, config)
+            request_options = _request_options_for_hash(config)
+            prompt_text = _serialise_messages_for_hash(messages, request_options)
+            async with recorder.record_llm_call(
+                model_id=config.model,
+                prompt_text=prompt_text,
+                caller="litellm_adapter",
+                max_tokens=config.max_tokens,
+                temperature=config.temperature,
+                extra=request_options,
+            ) as call:
+                response = await self._raw_complete(messages, config)
+                parsed = self._parse_response(response, config)
+                _record_litellm_completion(call, parsed)
+            return parsed
 
         try:
-            response = await _with_retry()
-            return Result.ok(self._parse_response(response, config))
+            parsed = await _with_retry()
+            return Result.ok(parsed)
         except RETRIABLE_EXCEPTIONS as e:
             # All retries exhausted
             log.warning(

ouroboros_ai-0.31.2.dev29/tests/unit/providers/test_litellm_adapter_io_recorder.py

@@ -0,0 +1,282 @@
+"""LiteLLM adapter wires the I/O Journal recorder (slice 4 of #517).
+
+Same shape as the Anthropic-adapter slice (#535): legacy constructor
+remains valid, ``io_recorder=None`` is byte-for-byte the previous
+behaviour, and per-attempt emission lands a paired
+``llm.call.requested`` / ``llm.call.returned`` for every retry attempt.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from ouroboros.core.security import MAX_LLM_RESPONSE_LENGTH
+from ouroboros.events.base import BaseEvent
+from ouroboros.events.io import content_hash
+from ouroboros.events.io_recorder import IOJournalRecorder, LLMCallRecord
+from ouroboros.providers.base import (
+    CompletionConfig,
+    CompletionResponse,
+    Message,
+    MessageRole,
+    UsageInfo,
+)
+from ouroboros.providers.litellm_adapter import (
+    LiteLLMAdapter,
+    _record_litellm_completion,
+    _serialise_messages_for_hash,
+)
+
+
+class _FakeEventStore:
+    def __init__(self) -> None:
+        self.appended: list[BaseEvent] = []
+
+    async def append(self, event: BaseEvent) -> None:
+        self.appended.append(event)
+
+
+def _stub_response(
+    *,
+    content: str = "hi",
+    finish_reason: str = "stop",
+    prompt_tokens: int = 10,
+    completion_tokens: int = 4,
+    model: str = "openrouter/openai/gpt-4",
+) -> Any:
+    """Build a MagicMock that mirrors a litellm ModelResponse."""
+    response = MagicMock()
+    response.choices = [MagicMock()]
+    response.choices[0].message.content = content
+    response.choices[0].finish_reason = finish_reason
+    response.usage = MagicMock(
+        prompt_tokens=prompt_tokens,
+        completion_tokens=completion_tokens,
+        total_tokens=prompt_tokens + completion_tokens,
+    )
+    response.model = model
+    response.model_dump = lambda: {"stub": True}
+    return response
+
+
+class TestSerialiseMessagesForHash:
+    def test_deterministic_for_same_input(self) -> None:
+        a = _serialise_messages_for_hash([Message(role=MessageRole.USER, content="hi")])
+        b = _serialise_messages_for_hash([Message(role=MessageRole.USER, content="hi")])
+        assert a == b
+
+    def test_different_for_different_input(self) -> None:
+        a = _serialise_messages_for_hash([Message(role=MessageRole.USER, content="a")])
+        b = _serialise_messages_for_hash([Message(role=MessageRole.USER, content="b")])
+        assert a != b
+
+
+class TestRecordLitellmCompletion:
+    def test_populates_record_from_parsed_response(self) -> None:
+        record = LLMCallRecord()
+        parsed = CompletionResponse(
+            content="hi",
+            model="openrouter/openai/gpt-4",
+            usage=UsageInfo(prompt_tokens=10, completion_tokens=4, total_tokens=14),
+            finish_reason="stop",
+        )
+        _record_litellm_completion(record, parsed)
+        assert record.completion_text == "hi"
+        assert record.finish_reason == "stop"
+        assert record.token_count_in == 10
+        assert record.token_count_out == 4
+
+    def test_handles_missing_usage_gracefully(self) -> None:
+        parsed = CompletionResponse(
+            content="hi",
+            model="openrouter/openai/gpt-4",
+            usage=None,
+            finish_reason="stop",
+        )
+        record = LLMCallRecord()
+        _record_litellm_completion(record, parsed)
+        assert record.completion_text == "hi"
+        assert record.token_count_in is None
+        assert record.token_count_out is None
+
+
+class TestAdapterConstructor:
+    def test_accepts_io_recorder_kwarg(self) -> None:
+        recorder = IOJournalRecorder(
+            event_store=_FakeEventStore(),
+            target_type="execution",
+            target_id="exec_test",
+        )
+        adapter = LiteLLMAdapter(api_key="dummy", io_recorder=recorder)
+        assert adapter._io_recorder is recorder
+
+    def test_legacy_constructor_unchanged(self) -> None:
+        adapter = LiteLLMAdapter(api_key="dummy")
+        assert adapter._io_recorder is None
+
+
+def test_prompt_hash_serialisation_includes_request_options() -> None:
+    base = _serialise_messages_for_hash(
+        [Message(role=MessageRole.USER, content="hi")],
+        {"top_p": 0.9, "stop": ["STOP"]},
+    )
+    changed = _serialise_messages_for_hash(
+        [Message(role=MessageRole.USER, content="hi")],
+        {"top_p": 0.8, "stop": ["STOP"]},
+    )
+    assert base != changed
+
+
+@pytest.mark.asyncio
+async def test_complete_records_request_options_in_journal_extra(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    store = _FakeEventStore()
+    recorder = IOJournalRecorder(
+        event_store=store,
+        target_type="execution",
+        target_id="exec_options",
+    )
+    adapter = LiteLLMAdapter(api_key="dummy", io_recorder=recorder)
+
+    response = _stub_response()
+    monkeypatch.setattr(adapter, "_raw_complete", AsyncMock(return_value=response))
+
+    result = await adapter.complete(
+        messages=[Message(role=MessageRole.USER, content="hello")],
+        config=CompletionConfig(
+            model="openrouter/openai/gpt-4",
+            max_tokens=64,
+            top_p=0.7,
+            stop=["STOP"],
+            response_format={"type": "json_object"},
+        ),
+    )
+    assert result.is_ok
+
+    assert store.appended[0].data["extra"] == {
+        "top_p": 0.7,
+        "stop": ["STOP"],
+        "response_format": {"type": "json_object"},
+    }
+
+
+@pytest.mark.asyncio
+async def test_complete_records_truncated_completion_seen_by_caller(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    store = _FakeEventStore()
+    recorder = IOJournalRecorder(
+        event_store=store,
+        target_type="execution",
+        target_id="exec_truncated",
+    )
+    adapter = LiteLLMAdapter(api_key="dummy", io_recorder=recorder)
+
+    too_long = "x" * (MAX_LLM_RESPONSE_LENGTH + 1)
+    response = _stub_response(content=too_long)
+    monkeypatch.setattr(adapter, "_raw_complete", AsyncMock(return_value=response))
+
+    result = await adapter.complete(
+        messages=[Message(role=MessageRole.USER, content="hello")],
+        config=CompletionConfig(model="openrouter/openai/gpt-4", max_tokens=64),
+    )
+    assert result.is_ok
+    assert len(result.value.content) == MAX_LLM_RESPONSE_LENGTH
+
+    returned = store.appended[1]
+    assert returned.data["completion_hash"] == content_hash(result.value.content)
+    assert returned.data["completion_preview"].startswith("x")
+    assert len(returned.data["completion_preview"]) < len(too_long)
+
+
+@pytest.mark.asyncio
+async def test_complete_emits_paired_events_when_recorder_present(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    store = _FakeEventStore()
+    recorder = IOJournalRecorder(
+        event_store=store,
+        target_type="execution",
+        target_id="exec_test",
+    )
+    adapter = LiteLLMAdapter(api_key="dummy", io_recorder=recorder)
+
+    response = _stub_response()
+    monkeypatch.setattr(adapter, "_raw_complete", AsyncMock(return_value=response))
+
+    result = await adapter.complete(
+        messages=[Message(role=MessageRole.USER, content="hello")],
+        config=CompletionConfig(model="openrouter/openai/gpt-4", max_tokens=64),
+    )
+    assert result.is_ok
+
+    assert [e.type for e in store.appended] == [
+        "llm.call.requested",
+        "llm.call.returned",
+    ]
+    started, returned = store.appended
+    assert started.data["call_id"] == returned.data["call_id"]
+    assert started.data["caller"] == "litellm_adapter"
+    assert returned.data["finish_reason"] == "stop"
+    assert returned.data["token_count_in"] == 10
+    assert returned.data["is_error"] is False
+
+
+@pytest.mark.asyncio
+async def test_complete_does_not_emit_when_recorder_absent(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    adapter = LiteLLMAdapter(api_key="dummy")  # no recorder
+
+    response = _stub_response()
+    monkeypatch.setattr(adapter, "_raw_complete", AsyncMock(return_value=response))
+
+    result = await adapter.complete(
+        messages=[Message(role=MessageRole.USER, content="hello")],
+        config=CompletionConfig(model="openrouter/openai/gpt-4", max_tokens=8),
+    )
+    assert result.is_ok
+
+
+@pytest.mark.asyncio
+async def test_complete_emits_returned_with_is_error_on_exception(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    store = _FakeEventStore()
+    recorder = IOJournalRecorder(
+        event_store=store,
+        target_type="execution",
+        target_id="exec_err",
+    )
+    adapter = LiteLLMAdapter(
+        api_key="dummy",
+        io_recorder=recorder,
+        max_retries=1,
+    )
+
+    monkeypatch.setattr(
+        adapter,
+        "_raw_complete",
+        AsyncMock(side_effect=RuntimeError("simulated provider failure")),
+    )
+
+    result = await adapter.complete(
+        messages=[Message(role=MessageRole.USER, content="hello")],
+        config=CompletionConfig(model="openrouter/openai/gpt-4", max_tokens=8),
+    )
+    assert result.is_err
+
+    # The recorder still emitted a paired returned event for each
+    # attempt — at least one attempt should be recorded.
+    assert any(e.type == "llm.call.returned" for e in store.appended)
+    failure_events = [
+        e
+        for e in store.appended
+        if e.type == "llm.call.returned" and e.data.get("is_error") is True
+    ]
+    assert failure_events
+    assert failure_events[0].data["error_kind"] == "RuntimeError"