ellements 0.2.0__py3-none-any.whl

ellements/core/llm/requests.py

@@ -0,0 +1,100 @@
+"""Shared LiteLLM request normalization helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import litellm
+
+from .model_params import filter_parameters, get_unsupported_parameters
+
+
+@dataclass(frozen=True)
+class CompletionRequest:
+    """Normalized chat-completion request settings."""
+
+    model: str
+    params: dict[str, Any]
+    logged_max_tokens: int | None
+
+
+def configure_litellm_globals(config: Mapping[str, Any]) -> None:
+    """Apply top-level LiteLLM configuration from a client config mapping."""
+    if "api_key" in config:
+        litellm.api_key = config["api_key"]
+    if "base_url" in config:
+        litellm.api_base = config["base_url"]
+
+
+def resolve_model_name(
+    model: str,
+    *,
+    use_responses_api: bool = False,
+) -> tuple[str, bool]:
+    """Resolve provider-prefixed model names for special GPT-5 routing."""
+    is_gpt5 = "gpt-5" in model.lower()
+    target_model = model
+
+    if is_gpt5 and not model.startswith("openai/"):
+        if use_responses_api:
+            target_model = f"openai/responses/{model}"
+        else:
+            target_model = f"openai/{model}"
+
+    return target_model, is_gpt5
+
+
+def prepare_completion_request(
+    *,
+    model: str,
+    temperature: float | None,
+    max_tokens: int | None,
+    use_responses_api: bool = False,
+    extra_params: Mapping[str, Any] | None = None,
+    default_reasoning_effort: str | None = "medium",
+) -> CompletionRequest:
+    """Normalize model routing and provider parameters for a chat completion."""
+    params: dict[str, Any] = dict(extra_params or {})
+    target_model, is_gpt5 = resolve_model_name(
+        model,
+        use_responses_api=use_responses_api,
+    )
+    unsupported = get_unsupported_parameters(target_model)
+    logged_max_tokens = max_tokens
+    target_max_tokens = max_tokens
+
+    if (
+        is_gpt5
+        and use_responses_api
+        and default_reasoning_effort
+        and "reasoning_effort" not in params
+    ):
+        params["reasoning_effort"] = default_reasoning_effort
+
+    if is_gpt5 and target_max_tokens is not None:
+        if use_responses_api:
+            params["max_output_tokens"] = target_max_tokens
+        else:
+            params["max_completion_tokens"] = target_max_tokens
+        target_max_tokens = None
+
+    if temperature is not None and "temperature" not in unsupported:
+        params["temperature"] = temperature
+    if target_max_tokens is not None:
+        params["max_tokens"] = target_max_tokens
+
+    return CompletionRequest(
+        model=target_model,
+        params=filter_parameters(target_model, **params),
+        logged_max_tokens=logged_max_tokens,
+    )
+
+
+def extract_response_text(response: Any) -> str:
+    """Read text content from a LiteLLM response object."""
+    content = response.choices[0].message.content
+    if content is None:
+        return ""
+    return str(content)

ellements/core/llm/structured.py

@@ -0,0 +1,91 @@
+"""Structured-output helpers built on litellm's native ``response_format``.
+
+Modern litellm supports passing a Pydantic ``BaseModel`` subclass to the
+``response_format`` parameter of ``litellm.acompletion``. Providers that
+support JSON-mode (OpenAI, Anthropic, Mistral, Gemini, …) will return a
+JSON document validating against the schema; providers that don't will
+raise an exception, which we surface as
+:class:`StructuredOutputUnsupportedError`.
+
+This module deliberately does *not* re-implement schema-to-prompt
+conversion. Hand-rolled "please respond with JSON like this…" prompts
+are inferior — they don't constrain generation, only post-hoc parsing.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import TypeVar
+
+import litellm
+from pydantic import BaseModel
+from pydantic import ValidationError as PydanticValidationError
+
+from ..exceptions import LLMError, StructuredOutputUnsupportedError
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def supports_structured_output(model: str) -> bool:
+    """Return whether *model* supports litellm's native ``response_format``."""
+    try:
+        return bool(litellm.supports_response_schema(model=model))
+    except Exception:
+        # Older litellm versions or unknown models — be conservative and
+        # fall through to the attempt, which will raise if unsupported.
+        return True
+
+
+def ensure_structured_support(model: str) -> None:
+    """Hard-fail when *model* cannot produce native structured outputs."""
+    if not supports_structured_output(model):
+        raise StructuredOutputUnsupportedError(
+            f"Model {model!r} does not support native structured outputs. "
+            "Choose a model with JSON-mode / response_format support."
+        )
+
+
+def extract_json_payload(content: str) -> str:
+    """Extract a JSON document from a response that may include code fences."""
+    stripped = content.strip()
+    if "```json" in stripped:
+        match = re.search(r"```json\s*\n(.*?)\n```", stripped, re.DOTALL)
+        if match:
+            return match.group(1).strip()
+    if "```" in stripped:
+        match = re.search(r"```\s*\n(.*?)\n```", stripped, re.DOTALL)
+        if match:
+            return match.group(1).strip()
+    return stripped
+
+
+def parse_structured_content(
+    content: str,
+    response_model: type[T],
+    *,
+    error_context: str = "Failed to parse structured response",
+) -> T:
+    """Parse JSON *content* into an instance of *response_model*.
+
+    Raises:
+        LLMError: If *content* is not valid JSON or does not validate
+            against the model's schema.
+    """
+    payload = extract_json_payload(content)
+    try:
+        data = json.loads(payload)
+        return response_model.model_validate(data)
+    except (json.JSONDecodeError, PydanticValidationError, ValueError) as exc:
+        preview = payload[:200] if len(payload) > 200 else payload
+        raise LLMError(
+            f"{error_context}: {exc}\nContent preview: {preview}"
+        ) from exc
+
+
+__all__ = [
+    "ensure_structured_support",
+    "extract_json_payload",
+    "parse_structured_content",
+    "supports_structured_output",
+]

ellements/core/llm/wrapper.py

@@ -0,0 +1,79 @@
+"""Shared base class for LLM-client wrappers.
+
+The composition layers in :mod:`ellements.core.caching`,
+:mod:`ellements.core.rate_limit`, and :mod:`ellements.core.budgeting`
+all decorate a :class:`LLMClientProtocol`. They share two boring
+pieces: storing the wrapped client and proxying the ``model``
+attribute. This module centralizes those, plus a default
+:meth:`continue_conversation` passthrough.
+
+The base intentionally does **not** provide default passthroughs for
+:meth:`complete`, :meth:`complete_structured`, :meth:`complete_with_tools`,
+:meth:`stream`, :meth:`loglikelihood`, or :meth:`generate_image`.
+A half-decorated wrapper that silently forwards methods it forgot to
+override would defeat the purpose of the wrapper. Subclasses must
+implement every method they care about, and the type checker will flag
+any that are missing from :class:`LLMClientProtocol`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .messages import Conversation
+    from .protocol import LLMClientProtocol
+
+
+class LLMClientWrapper:
+    """Storage + minimal proxying for LLM-client decorators.
+
+    Args:
+        inner: The wrapped client. Must satisfy
+            :class:`~ellements.core.llm.LLMClientProtocol`.
+
+    Subclasses are expected to expose the same methods as
+    :class:`LLMClientProtocol`, overriding the ones they intercept
+    and letting :meth:`continue_conversation` use the default
+    passthrough provided here (or override it too if they want to
+    charge/throttle multi-turn calls).
+    """
+
+    def __init__(self, *, inner: LLMClientProtocol) -> None:
+        self._inner = inner
+
+    @property
+    def inner(self) -> LLMClientProtocol:
+        """The wrapped client (read-only access for debugging/inspection)."""
+        return self._inner
+
+    @property
+    def model(self) -> str:
+        """Proxy the wrapped client's model identifier."""
+        return self._inner.model
+
+    async def continue_conversation(
+        self,
+        conversation: Conversation,
+        user_message: str,
+        *,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Forward to the wrapped client unchanged.
+
+        Subclasses may override to intercept multi-turn calls (e.g. to
+        charge the budget once per turn, or to count the turn toward a
+        rate limit).
+        """
+        return await self._inner.continue_conversation(
+            conversation,
+            user_message,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            **kwargs,
+        )
+
+
+__all__ = ["LLMClientWrapper"]

ellements/core/observability/__init__.py

@@ -0,0 +1,39 @@
+"""Observability primitives for ellements.
+
+This subpackage centralises everything related to *seeing what
+happened* inside an ellements run:
+
+- :mod:`.events` — the event vocabulary
+  (:class:`LLMRequestEvent`, :class:`LLMResponseEvent`,
+  :class:`LLMErrorEvent`, :class:`AgentEvent`).
+- :mod:`.observer` — the :class:`LLMObserver` Protocol.
+- :mod:`.jsonl_logger` — :class:`JsonlPromptLogger`, the canonical
+  observer implementation, and its :class:`LoggedCall` record schema.
+- :mod:`.markdown_formatter` — :func:`format_log_markdown`, a
+  human-readable view over any ``.jsonl`` log file.
+
+This ``__init__`` re-exports the full public surface so callers can
+``from ellements.core.observability import …`` without reaching into
+specific submodules.
+"""
+
+from .events import (
+    AgentEvent,
+    LLMErrorEvent,
+    LLMRequestEvent,
+    LLMResponseEvent,
+)
+from .jsonl_logger import JsonlPromptLogger, LoggedCall
+from .markdown_formatter import format_log_markdown
+from .observer import LLMObserver
+
+__all__ = [
+    "AgentEvent",
+    "JsonlPromptLogger",
+    "LLMErrorEvent",
+    "LLMObserver",
+    "LLMRequestEvent",
+    "LLMResponseEvent",
+    "LoggedCall",
+    "format_log_markdown",
+]

ellements/core/observability/events.py

@@ -0,0 +1,169 @@
+"""Event records emitted across ellements layers.
+
+This module owns the **vocabulary** observers consume. We keep it
+deliberately small and immutable-by-default so that every observer
+implementation knows the exact shape of every field, with no surprises
+from subclassing.
+
+Two families of events live here:
+
+LLM call events (consumed by :class:`LLMObserver`)
+    Every method on :class:`~ellements.core.LLMClient` (``complete``,
+    ``complete_structured``, ``complete_with_tools``, ``stream``,
+    ``generate_image``, ``loglikelihood``) fires the same three events:
+    :class:`LLMRequestEvent` before the call leaves the client,
+    :class:`LLMResponseEvent` on success, :class:`LLMErrorEvent` on
+    failure. The triple shares a ``call_id`` so observers can correlate
+    them.
+
+Agent run events (consumed by streaming agent backends)
+    :class:`AgentEvent` is the uniform shape yielded by
+    :meth:`~ellements.agents.AgentBackend.stream_run`. Backends
+    translate their native event streams (OpenAI Agents SDK,
+    Claude Agents SDK, etc.) onto this small vocabulary so UIs can
+    consume them without backend-specific code.
+
+Co-locating both families here makes ellements' observability surface
+discoverable from a single place. Layers that need only one family
+import only what they need (events are independent).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# LLM call events
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class LLMRequestEvent:
+    """Event fired before an LLM call leaves the client.
+
+    Observers receive this event before the network request hits the
+    provider, which makes it the right place to record the exact
+    payload (messages, parameters, available tools) that will be sent.
+
+    Attributes:
+        call_id: UUID that identifies this call across the
+            ``request``/``response``/``error`` triple.
+        method: The :class:`LLMClient` method name that initiated this
+            call (e.g. ``"complete"``, ``"stream"``).
+        model: The model identifier the call is targeting.
+        messages: The serialized message list as sent to the provider.
+        temperature: The temperature parameter, if specified.
+        max_tokens: The max-tokens parameter, if specified.
+        tools: Provider-formatted tool definitions, if any.
+        extra_params: Additional provider-specific parameters.
+        metadata: Free-form, observer-supplied annotation channel.
+            Observers may carry context (e.g. workstream id) here from
+            request through response/error.
+    """
+
+    call_id: str
+    method: str
+    model: str
+    messages: list[dict[str, Any]]
+    temperature: float | None
+    max_tokens: int | None
+    tools: list[dict[str, Any]] = field(default_factory=list)
+    extra_params: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class LLMResponseEvent:
+    """Event fired after a successful LLM call returns.
+
+    Attributes:
+        call_id: Matches the originating :class:`LLMRequestEvent`.
+        method: Same as on the request event.
+        model: Same as on the request event.
+        response: The final assistant text. For streaming calls this
+            is the concatenated content.
+        duration_ms: Wall-clock latency in milliseconds.
+        tool_calls: Tool calls the model issued during this turn,
+            already merged with any tool-call results the client
+            looped back internally.
+        usage: Provider-reported token usage, when available.
+        metadata: Free-form, observer-supplied annotation channel.
+    """
+
+    call_id: str
+    method: str
+    model: str
+    response: str
+    duration_ms: int
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    usage: dict[str, Any] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class LLMErrorEvent:
+    """Event fired when an LLM call raises (after any retries).
+
+    Attributes:
+        call_id: Matches the originating :class:`LLMRequestEvent`.
+        method: Same as on the request event.
+        model: Same as on the request event.
+        error: The actual exception instance that ended the call.
+            Observers should not assume the exception is JSON-safe;
+            persistent loggers usually record ``type(error).__name__``
+            and ``str(error)`` instead of the live object.
+        duration_ms: Wall-clock time spent before the failure.
+        metadata: Free-form, observer-supplied annotation channel.
+    """
+
+    call_id: str
+    method: str
+    model: str
+    error: BaseException
+    duration_ms: int
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Agent run events
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class AgentEvent:
+    """One incremental event surfaced by streaming agent runs.
+
+    Backends map their native event types onto a small,
+    backend-agnostic vocabulary so UIs can consume agent streams
+    without knowing which SDK powers the backend:
+
+    - ``"agent_active"``: a new sub-agent took the floor.
+      Payload: ``{"name": str}``.
+    - ``"tool_call"``: the agent invoked a tool.
+      Payload: ``{"name": str, "arguments": Mapping[str, Any] | str}``.
+    - ``"tool_output"``: a tool produced an output.
+      Payload: ``{"output": Any}``.
+    - ``"message"``: the agent produced a (possibly partial) message.
+      Payload: ``{"text": str, "final": bool}``.
+
+    Backends MAY surface additional event types under
+    backend-namespaced keys (e.g. ``"openai.raw_response"``).
+    Consumers should ignore unknown types.
+
+    Attributes:
+        type: One of the type strings above (or a backend-namespaced
+            extension).
+        payload: Type-specific payload as documented above.
+    """
+
+    type: str
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+__all__ = [
+    "AgentEvent",
+    "LLMErrorEvent",
+    "LLMRequestEvent",
+    "LLMResponseEvent",
+]