ellements 0.2.0__py3-none-any.whl

ellements/core/observability/jsonl_logger.py

@@ -0,0 +1,244 @@
+"""Async-safe, date-rolling JSON-lines logger for LLM calls.
+
+:class:`JsonlPromptLogger` is the canonical reference implementation of
+:class:`~ellements.core.observability.LLMObserver`. It writes one
+self-contained JSON object per LLM call to a daily ``.jsonl`` file:
+
+- **One file per UTC day**: the active filename incorporates the
+  current UTC date, so file rotation happens automatically without
+  background timers.
+- **Race-free**: every write is serialized through an
+  :class:`asyncio.Lock`, so concurrent strategies sharing a logger
+  cannot interleave bytes.
+- **Resilient**: I/O failures are downgraded to a warning rather than
+  propagated. Telemetry should never break the production path it is
+  observing.
+- **Self-contained records**: the request, response, tool calls,
+  usage, and metadata for a single call all live in one line. There
+  is no cross-line schema to reassemble.
+
+For a human-readable view of an existing log, see
+:func:`~ellements.core.observability.format_log_markdown`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .events import LLMErrorEvent, LLMRequestEvent, LLMResponseEvent
+
+_logger = logging.getLogger(__name__)
+
+
+class LoggedCall(BaseModel):
+    """One self-contained log record for a single LLM call.
+
+    Pydantic gives us free JSON round-tripping (including for
+    multimodal content embedded inside ``messages``) and machine-
+    readable schema introspection for downstream tooling.
+
+    The model is intentionally permissive on input (``messages`` and
+    ``tools`` are ``list[dict]``) because LLM payloads evolve faster
+    than we can express their full structure in types.
+
+    Attributes:
+        call_id: UUID matching the originating
+            :class:`LLMRequestEvent`.
+        timestamp: ISO 8601 UTC timestamp of the call start.
+        method: The :class:`LLMClient` method name (e.g.
+            ``"complete"``).
+        status: ``"ok"``, ``"error"``, or ``"pending"`` (the latter
+            is an internal transient state never written to disk).
+        model: The model identifier the call was sent to.
+        temperature: The temperature parameter, if specified.
+        max_tokens: The max-tokens parameter, if specified.
+        messages: The serialized message list.
+        tools: Provider-formatted tool definitions.
+        response: The final assistant text on success.
+        tool_calls: Tool calls the model issued.
+        usage: Provider-reported token usage.
+        duration_ms: Wall-clock latency.
+        extra_params: Additional provider-specific parameters.
+        metadata: Free-form annotation channel from observers.
+        error_type: Exception class name on failure.
+        error_message: Exception ``str()`` on failure.
+    """
+
+    call_id: str = Field(description="UUID identifying this call across events")
+    timestamp: str = Field(description="ISO 8601 UTC timestamp of the call start")
+    method: str = Field(description="LLMClient method name (e.g. 'complete')")
+    status: str = Field(description="'ok' or 'error'")
+    model: str
+    temperature: float | None = None
+    max_tokens: int | None = None
+    messages: list[dict[str, Any]] = Field(default_factory=list)
+    tools: list[dict[str, Any]] = Field(default_factory=list)
+    response: str = ""
+    tool_calls: list[dict[str, Any]] = Field(default_factory=list)
+    usage: dict[str, Any] | None = None
+    duration_ms: int = 0
+    extra_params: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    error_type: str | None = None
+    error_message: str | None = None
+
+
+class JsonlPromptLogger:
+    """Async-safe, UTC-day-rolling JSON-lines observer for LLM calls.
+
+    The logger stages each call as a :class:`LoggedCall` in an
+    in-memory pending map keyed by ``call_id``. ``on_request`` opens
+    the record; ``on_response``/``on_error`` close it and flush a
+    single JSON line to disk. This means **the file only contains
+    completed calls** — partial calls (e.g. interrupted) leave no
+    trace.
+
+    Args:
+        log_dir: Directory where ``llm-log-YYYY-MM-DD.jsonl`` files
+            are written. Created if it does not exist.
+        filename_pattern: ``strftime``-formatted prefix; the resulting
+            file is ``log_dir / f"{filename_pattern}.jsonl"``. The
+            default ``"llm-log-%Y-%m-%d"`` produces
+            ``llm-log-2024-05-16.jsonl``.
+
+    Concurrency:
+        All writes are serialized by an :class:`asyncio.Lock`, so
+        multiple concurrent strategies sharing a single logger
+        produce a valid JSON-lines file (no torn rows).
+
+    Date rollover:
+        Every write computes the current UTC date through
+        :attr:`current_path`. When the date changes, the next write
+        opens a new file. No background timers, no locking on the
+        clock.
+    """
+
+    def __init__(
+        self,
+        log_dir: str | Path,
+        *,
+        filename_pattern: str = "llm-log-%Y-%m-%d",
+    ) -> None:
+        self.log_dir = Path(log_dir)
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        if os.name != "nt":
+            self.log_dir.chmod(0o700)
+        self._filename_pattern = filename_pattern
+        self._lock = asyncio.Lock()
+        # In-flight requests indexed by call_id so on_response / on_error
+        # can merge with the request payload (messages, tools, params)
+        # without every method plumbing a full record around.
+        self._pending: dict[str, LoggedCall] = {}
+
+    # ── Observer protocol ────────────────────────────────────────────
+
+    async def on_request(self, event: LLMRequestEvent) -> None:
+        """Stage a pending record for *event*.
+
+        The record is not flushed to disk until the matching response
+        or error arrives. This guarantees logged lines correspond to
+        completed calls.
+        """
+        record = LoggedCall(
+            call_id=event.call_id,
+            timestamp=datetime.now(UTC).isoformat(),
+            method=event.method,
+            status="pending",
+            model=event.model,
+            temperature=event.temperature,
+            max_tokens=event.max_tokens,
+            messages=list(event.messages),
+            tools=list(event.tools),
+            extra_params=dict(event.extra_params),
+            metadata=dict(event.metadata),
+        )
+        self._pending[event.call_id] = record
+
+    async def on_response(self, event: LLMResponseEvent) -> None:
+        """Finalize the pending record with success data and flush."""
+        record = self._pending.pop(event.call_id, None)
+        if record is None:
+            # The pending record may be missing if this logger was
+            # attached mid-flight; fall back to a partial record that
+            # still captures everything the response event knows.
+            record = LoggedCall(
+                call_id=event.call_id,
+                timestamp=datetime.now(UTC).isoformat(),
+                method=event.method,
+                status="ok",
+                model=event.model,
+            )
+        record.status = "ok"
+        record.response = event.response
+        record.tool_calls = list(event.tool_calls)
+        record.usage = event.usage
+        record.duration_ms = event.duration_ms
+        record.metadata = {**record.metadata, **event.metadata}
+        await self._write(record)
+
+    async def on_error(self, event: LLMErrorEvent) -> None:
+        """Finalize the pending record with error data and flush."""
+        record = self._pending.pop(event.call_id, None)
+        if record is None:
+            record = LoggedCall(
+                call_id=event.call_id,
+                timestamp=datetime.now(UTC).isoformat(),
+                method=event.method,
+                status="error",
+                model=event.model,
+            )
+        record.status = "error"
+        record.duration_ms = event.duration_ms
+        record.error_type = type(event.error).__name__
+        record.error_message = str(event.error)
+        record.metadata = {**record.metadata, **event.metadata}
+        await self._write(record)
+
+    # ── Paths ────────────────────────────────────────────────────────
+
+    @property
+    def current_path(self) -> Path:
+        """The absolute path the next write will land in.
+
+        Computed fresh on every access so UTC day rollover applies
+        without any external state.
+        """
+        stamp = datetime.now(UTC).strftime(self._filename_pattern)
+        return self.log_dir / f"{stamp}.jsonl"
+
+    # ── Internals ────────────────────────────────────────────────────
+
+    async def _write(self, record: LoggedCall) -> None:
+        """Serialize *record* and append it to :attr:`current_path`.
+
+        I/O happens inside :func:`asyncio.to_thread` so the event loop
+        is not blocked even on slow filesystems. The lock guarantees
+        ordering between concurrent writes.
+        """
+        line = record.model_dump_json() + "\n"
+        async with self._lock:
+            path = self.current_path
+            try:
+                await asyncio.to_thread(self._append_line, path, line)
+            except OSError as exc:
+                # Telemetry must never break the path it is observing.
+                _logger.warning(
+                    "JsonlPromptLogger write failed for %s: %s", path, exc
+                )
+
+    @staticmethod
+    def _append_line(path: Path, line: str) -> None:
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(line)
+        if os.name != "nt":
+            path.chmod(0o600)
+
+
+__all__ = ["JsonlPromptLogger", "LoggedCall"]

ellements/core/observability/markdown_formatter.py

@@ -0,0 +1,197 @@
+"""Render an LLM call log as human-readable Markdown.
+
+This is a pure pretty-printer with no I/O dependencies beyond reading
+the input ``.jsonl`` file. It is decoupled from
+:class:`JsonlPromptLogger` so it works against any
+JSON-lines log that follows the :class:`LoggedCall` schema, including
+files merged from multiple sources.
+
+Output format:
+
+- One ``## 🤖`` heading per call.
+- A parameter table (model, temperature, max tokens, duration).
+- A ``### 📨 Messages`` block, each message in a code fence.
+- A ``### 🔧 Available Tools`` line listing tool names, if present.
+- A ``### ⚙️ Tool Calls`` list of invocations with arguments and
+  truncated results.
+- Either a ``### 💬 Response`` block (on success) or a ``### ❌ Error``
+  block (on failure).
+- A ``### 📋 Metadata`` bullet list, if any.
+
+Truncation:
+    Long fields are clipped with a footer that records the total
+    length. The defaults (3 KB response, 2 KB messages, 300 B tool
+    results) keep the document scannable even for very chatty calls.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+
+def _truncate(text: str, limit: int) -> str:
+    """Clip *text* at *limit* chars and append a length footer."""
+    if len(text) <= limit:
+        return text
+    return text[:limit] + f"\n\n… *(truncated, {len(text):,} chars total)*"
+
+
+def _render_messages_markdown(messages: Iterable[dict[str, Any]]) -> str:
+    """Render a message list as a sequence of fenced code blocks."""
+    parts: list[str] = []
+    for i, message in enumerate(messages, 1):
+        role = str(message.get("role", "unknown")).upper()
+        content = message.get("content", "")
+        if isinstance(content, list):
+            rendered = json.dumps(content, indent=2)
+        else:
+            rendered = str(content)
+        parts.append(
+            f"**Message {i} — {role}**\n\n```\n{_truncate(rendered, 2000)}\n```"
+        )
+    return "\n\n".join(parts)
+
+
+def _render_call_header(record: dict[str, Any]) -> list[str]:
+    """Render the call heading + parameter table."""
+    lines: list[str] = []
+    lines.append(f"## 🤖 {record.get('method', '?')} — {record.get('timestamp', '?')}")
+    lines.append("")
+    lines.append("| Parameter | Value |")
+    lines.append("|-----------|-------|")
+    lines.append(f"| **Status** | `{record.get('status', '?')}` |")
+    lines.append(f"| **Model** | `{record.get('model', '?')}` |")
+    if record.get("temperature") is not None:
+        lines.append(f"| **Temperature** | {record['temperature']} |")
+    if record.get("max_tokens") is not None:
+        lines.append(f"| **Max Tokens** | {record['max_tokens']:,} |")
+    duration = record.get("duration_ms") or 0
+    lines.append(f"| **Duration** | {duration/1000:.2f}s ({duration:,}ms) |")
+    if record.get("extra_params"):
+        for key, value in record["extra_params"].items():
+            lines.append(f"| **{key}** | `{value}` |")
+    lines.append("")
+    return lines
+
+
+def _render_tools_section(record: dict[str, Any]) -> list[str]:
+    """Render the available-tools line + the executed tool-call list."""
+    lines: list[str] = []
+
+    tools = record.get("tools") or []
+    if tools:
+        names = [
+            (tool.get("function") or {}).get("name", "?")
+            for tool in tools
+        ]
+        lines.append(f"### 🔧 Available Tools: {', '.join(names)}")
+        lines.append("")
+
+    tool_calls = record.get("tool_calls") or []
+    if tool_calls:
+        lines.append("### ⚙️ Tool Calls")
+        lines.append("")
+        for i, call in enumerate(tool_calls, 1):
+            name = call.get("name", "?")
+            args = call.get("arguments", {})
+            result = call.get("result", "")
+            lines.append(f"**{i}. `{name}`**")
+            lines.append(f"- Args: `{json.dumps(args)}`")
+            lines.append(f"- Result: {_truncate(str(result), 300)}")
+            lines.append("")
+    return lines
+
+
+def _render_outcome(record: dict[str, Any]) -> list[str]:
+    """Render either the success response or the error block."""
+    lines: list[str] = []
+    if record.get("status") == "ok":
+        lines.append("### 💬 Response")
+        lines.append("")
+        lines.append(f"```\n{_truncate(str(record.get('response', '')), 3000)}\n```")
+        lines.append("")
+    else:
+        lines.append("### ❌ Error")
+        lines.append("")
+        lines.append(f"`{record.get('error_type', 'UnknownError')}`")
+        lines.append("")
+        lines.append(f"```\n{_truncate(str(record.get('error_message', '')), 2000)}\n```")
+        lines.append("")
+    return lines
+
+
+def _render_metadata(record: dict[str, Any]) -> list[str]:
+    """Render the optional metadata bullet list."""
+    lines: list[str] = []
+    metadata = record.get("metadata") or {}
+    if metadata:
+        lines.append("### 📋 Metadata")
+        lines.append("")
+        for key, value in metadata.items():
+            lines.append(f"- **{key}**: {value}")
+        lines.append("")
+    return lines
+
+
+def _render_call_markdown(record: dict[str, Any]) -> str:
+    """Render a single :class:`LoggedCall`-shaped dict as Markdown.
+
+    Composed of four section helpers — header, messages, tools, and
+    outcome + metadata — so each piece stays small and individually
+    testable.
+    """
+    lines: list[str] = []
+    lines.extend(_render_call_header(record))
+
+    messages = record.get("messages") or []
+    if messages:
+        lines.append("### 📨 Messages")
+        lines.append("")
+        lines.append(_render_messages_markdown(messages))
+        lines.append("")
+
+    lines.extend(_render_tools_section(record))
+    lines.extend(_render_outcome(record))
+    lines.extend(_render_metadata(record))
+
+    lines.append("---")
+    return "\n".join(lines)
+
+
+def format_log_markdown(jsonl_path: str | Path) -> str:
+    """Render every record in a ``.jsonl`` log file as Markdown.
+
+    Args:
+        jsonl_path: Path to a file produced by
+            :class:`~ellements.core.observability.JsonlPromptLogger`,
+            or any JSON-lines file following the same schema.
+
+    Returns:
+        A Markdown document with one section per logged LLM call,
+        separated by ``---`` rules.
+
+    Raises:
+        FileNotFoundError: If ``jsonl_path`` does not exist.
+    """
+    path = Path(jsonl_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Log file not found: {path}")
+
+    sections: list[str] = []
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError as exc:
+            sections.append(f"<!-- Skipping malformed line: {exc} -->")
+            continue
+        sections.append(_render_call_markdown(record))
+    return "\n\n".join(sections)
+
+
+__all__ = ["format_log_markdown"]

ellements/core/observability/observer.py

@@ -0,0 +1,56 @@
+"""Observer Protocols for ellements events.
+
+An *observer* receives uniform events from one of ellements' event
+streams without coupling to the producer. Two protocols live here:
+
+:class:`LLMObserver` — push-based. Every
+:class:`~ellements.core.LLMClient` method fires the same three events
+(:class:`LLMRequestEvent`, :class:`LLMResponseEvent`,
+:class:`LLMErrorEvent`) to every attached observer. Observers are
+``async`` so they can do I/O (file writes, network telemetry) without
+blocking the event loop.
+
+Agent events are pulled, not pushed: callers iterate the async stream
+returned by :meth:`~ellements.agents.AgentBackend.stream_run`. There is
+no ``AgentObserver`` Protocol because streaming itself is the observer
+mechanism — the same backend supports zero, one, or many concurrent
+consumers via independent ``stream_run`` invocations.
+
+To convert a streaming agent into a push-based observable, callers
+typically wrap the stream and forward events to whatever sink they
+want (e.g. a GUI bridge). Such adapters belong outside core.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from .events import LLMErrorEvent, LLMRequestEvent, LLMResponseEvent
+
+
+@runtime_checkable
+class LLMObserver(Protocol):
+    """Async push-based observer attached to an :class:`LLMClient`.
+
+    The client guarantees the event triple semantics: every call fires
+    exactly one ``on_request``, followed by exactly one of
+    ``on_response`` (success) or ``on_error`` (failure). The events
+    share a ``call_id`` so stateful observers can correlate them.
+
+    All three methods are ``async`` to permit non-blocking I/O. The
+    client awaits each method in sequence; observers that need to
+    fan out to many sinks should buffer internally rather than block
+    the LLM call.
+    """
+
+    async def on_request(self, event: LLMRequestEvent) -> None:
+        """Receive the pre-flight event for an LLM call."""
+
+    async def on_response(self, event: LLMResponseEvent) -> None:
+        """Receive the success event for an LLM call."""
+
+    async def on_error(self, event: LLMErrorEvent) -> None:
+        """Receive the failure event for an LLM call."""
+
+
+__all__ = ["LLMObserver"]

ellements/core/prompting/__init__.py

@@ -0,0 +1,14 @@
+"""Prompting-related core mechanisms."""
+
+from .context import PromptContext
+from .guideline import GuidelineLibrary
+from .persona import PersonaLibrary
+from .sources import GuidelineSource, PersonaSource
+
+__all__ = [
+    "GuidelineLibrary",
+    "GuidelineSource",
+    "PersonaLibrary",
+    "PersonaSource",
+    "PromptContext",
+]