ellements 0.2.0__py3-none-any.whl

ellements/core/__init__.py

@@ -0,0 +1,112 @@
+"""Core primitives and reusable foundations for ellements.
+
+The top-level surface is intentionally small — the **happy path** of
+client + messages + tools + prompts + observability + the full error
+taxonomy. Specialized layers live in subpackages and are imported
+directly from them. The subpackage path is the canonical one; the
+top-level re-exports below exist purely to keep the most common 90%
+of code short::
+
+    from ellements.core import LLMClient, Conversation, Tool, ToolRegistry
+
+Subpackage map:
+
+* :mod:`ellements.core.caching` — caching wrapper + backends
+  (``CachingLLMClient``, ``InMemoryCache``, ``JsonDiskCache``).
+* :mod:`ellements.core.rate_limit` — rate-limit wrapper + token-bucket
+  implementation (``RateLimitedLLMClient``, ``TokenBucketRateLimiter``).
+* :mod:`ellements.core.budgeting` — budget tracker + budgeted wrapper
+  (``BudgetedLLMClient``, ``CallCountBudget``, ``TokenBudget``).
+* :mod:`ellements.core.observability` — event types, observers,
+  Markdown formatters (``LLMRequestEvent``, ``LLMResponseEvent``,
+  ``AgentEvent``, ``format_log_markdown``).
+* :mod:`ellements.core.prompting` — persona / guideline / prompt
+  context (``PromptContext``, ``PersonaSource``, ``GuidelineSource``).
+* :mod:`ellements.core.templating` — Mustache template renderer plus
+  ``render_prompt_template`` convenience helper.
+* :mod:`ellements.core.config` — JSON / TOML loaders + ``overlay``.
+* :mod:`ellements.core.chunking` — text chunking + ``count_tokens``.
+* :mod:`ellements.core.async_utils` — ``parallel_map``.
+* :mod:`ellements.core.tools` — full tool / dialect / registry surface,
+  including the provider dialects (``OpenAIChatDialect``,
+  ``OpenAIResponsesDialect``, ``AnthropicDialect``, ``GeminiDialect``,
+  ``default_dialect_for_model``).
+* :mod:`ellements.core.llm` — extras like multimodal types
+  (``ImageInput``, ``ImageURLPart``, ``ImageGenerationResponse``,
+  ``GeneratedImage``) and the ``LLMClientWrapper`` base.
+* :mod:`ellements.core.exceptions` — full exception hierarchy
+  (already re-exported below for the common ones; specialized
+  exceptions stay here).
+
+Anything not listed in this module's ``__all__`` is reachable from its
+subpackage. There are no hidden names: every subpackage carries its
+own ``__all__``.
+"""
+
+from __future__ import annotations
+
+from .exceptions import (
+    BudgetExceededError,
+    ConversationError,
+    EllementsError,
+    EllementsValidationError,
+    GuidelineNotFoundError,
+    LLMError,
+    LogprobsUnsupportedError,
+    MaxToolIterationsError,
+    PersonaNotFoundError,
+    PromptKeyMissingError,
+    PromptLibraryError,
+    StructuredOutputUnsupportedError,
+)
+from .llm import (
+    Conversation,
+    LLMClient,
+    LLMClientProtocol,
+    Message,
+    MessageContent,
+    MessageInput,
+)
+from .observability import JsonlPromptLogger, LLMObserver
+from .prompting import GuidelineLibrary, PersonaLibrary
+from .templating import TemplateRenderer
+from .tools import (
+    SimpleTool,
+    Tool,
+    ToolCallRecord,
+    ToolCallResponse,
+    ToolRegistry,
+    ToolSpec,
+)
+
+__all__ = [
+    "BudgetExceededError",
+    "Conversation",
+    "ConversationError",
+    "EllementsError",
+    "EllementsValidationError",
+    "GuidelineLibrary",
+    "GuidelineNotFoundError",
+    "JsonlPromptLogger",
+    "LLMClient",
+    "LLMClientProtocol",
+    "LLMError",
+    "LLMObserver",
+    "LogprobsUnsupportedError",
+    "MaxToolIterationsError",
+    "Message",
+    "MessageContent",
+    "MessageInput",
+    "PersonaLibrary",
+    "PersonaNotFoundError",
+    "PromptKeyMissingError",
+    "PromptLibraryError",
+    "SimpleTool",
+    "StructuredOutputUnsupportedError",
+    "TemplateRenderer",
+    "Tool",
+    "ToolCallRecord",
+    "ToolCallResponse",
+    "ToolRegistry",
+    "ToolSpec",
+]

ellements/core/async_utils.py

@@ -0,0 +1,42 @@
+"""Async helpers for bounded parallel work."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Iterable
+from typing import TypeVar, cast
+
+T = TypeVar("T")
+R = TypeVar("R")
+
+
+async def parallel_map(
+    items: Iterable[T],
+    worker: Callable[[T], Awaitable[R]],
+    *,
+    max_concurrency: int = 3,
+) -> list[R]:
+    """Apply an async worker to items with bounded concurrency.
+
+    Results preserve the input order even when items finish out of order.
+    If any worker raises, the remaining in-flight tasks are cancelled.
+    """
+    if max_concurrency < 1:
+        raise ValueError("max_concurrency must be at least 1")
+
+    item_list = list(items)
+    if not item_list:
+        return []
+
+    semaphore = asyncio.Semaphore(max_concurrency)
+    results: list[R | None] = [None] * len(item_list)
+
+    async def _run(index: int, item: T) -> None:
+        async with semaphore:
+            results[index] = await worker(item)
+
+    async with asyncio.TaskGroup() as task_group:
+        for index, item in enumerate(item_list):
+            task_group.create_task(_run(index, item))
+
+    return [cast(R, result) for result in results]

ellements/core/budgeting/__init__.py

@@ -0,0 +1,43 @@
+"""Optional cost-tracking layer for :class:`LLMClient`.
+
+This subpackage lets callers cap how much an :class:`LLMClient` is
+allowed to spend before requests start failing fast — a defensive
+measure for evaluation runs, agent loops, and any code path that might
+otherwise burn through tokens without bound.
+
+The design mirrors :mod:`ellements.core.caching` and
+:mod:`ellements.core.rate_limit`:
+
+* :class:`BudgetTrackerProtocol` — a structural :class:`typing.Protocol`
+  callers can satisfy with their own bookkeeping.
+* :class:`CallCountBudget` — a tiny tracker that counts requests.
+* :class:`TokenBudget` — accounts for input and output tokens against
+  a per-model price table (cost units are caller-defined; treat them
+  as USD or anything else consistent).
+* :class:`BudgetedLLMClient` — composition wrapper that satisfies
+  :class:`~ellements.core.llm.LLMClientProtocol`, charging the active
+  budget around each call and raising
+  :class:`~ellements.core.exceptions.BudgetExceededError` when the cap
+  is hit.
+
+Costs are advisory and apply only to ``complete``, ``complete_structured``,
+``complete_with_tools``, ``continue_conversation``, ``loglikelihood``,
+and ``generate_image``. Streaming output is forwarded uncharged — the
+provider's token counts are unavailable until the stream completes and
+we deliberately keep this layer simple. Tag streaming usage manually
+via :meth:`BudgetTrackerProtocol.charge` if you need it.
+"""
+
+from __future__ import annotations
+
+from .client import BudgetedLLMClient
+from .protocol import BudgetTrackerProtocol
+from .trackers import CallCountBudget, TokenBudget, TokenPrice
+
+__all__ = [
+    "BudgetTrackerProtocol",
+    "BudgetedLLMClient",
+    "CallCountBudget",
+    "TokenBudget",
+    "TokenPrice",
+]

ellements/core/budgeting/client.py

@@ -0,0 +1,276 @@
+"""Wrapping :class:`LLMClient` for budget-aware operation.
+
+The wrapper enforces a *predictable* cost per method (the caller's
+estimate, not provider-reported tokens) for two reasons:
+
+1. Many callers want a hard ceiling on requests where the unit is
+   simply "number of calls". :class:`CallCountBudget` covers that.
+2. Provider-reported token usage only arrives *after* a response, so
+   token-accurate budgeting cannot gate a call before it is made. For
+   that workflow, attach a :class:`TokenBudget` as an observer on the
+   wrapped :class:`LLMClient` directly — see
+   :meth:`ellements.core.budgeting.TokenBudget.charge` and the
+   :class:`~ellements.core.observability.LLMResponseEvent`'s ``usage``
+   field, which carries provider-reported token counts.
+
+The wrapper's job is the pre-call gate and the post-call accounting
+of the *flat* estimate; combining the two layers gives both fast
+failure and exact accounting.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterable, Mapping
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from ..exceptions import BudgetExceededError
+from ..llm.wrapper import LLMClientWrapper
+from .protocol import BudgetTrackerProtocol
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from ..llm.images import ImageGenerationResponse
+    from ..llm.messages import Conversation, MessageInput
+    from ..llm.protocol import LLMClientProtocol
+    from ..tools import ToolCallResponse, ToolDialect, ToolExecutor, ToolRegistry
+
+T = TypeVar("T", bound="BaseModel")
+
+
+class BudgetedLLMClient(LLMClientWrapper):
+    """Decorate an LLM client so spend is tracked against a budget.
+
+    Args:
+        inner: The wrapped LLM client. Must satisfy
+            :class:`~ellements.core.llm.LLMClientProtocol`.
+        tracker: The :class:`BudgetTrackerProtocol` to consult before
+            and after each call.
+        cost_per_method: Optional override of the flat cost charged for
+            specific methods. Keys are method names (``"complete"``,
+            ``"complete_structured"``, ``"complete_with_tools"``,
+            ``"continue_conversation"``, ``"loglikelihood"``,
+            ``"generate_image"``). Methods not present use
+            ``default_cost``.
+        default_cost: Cost charged for any method without an explicit
+            override. Defaults to ``1.0``.
+
+    Streams (:meth:`stream`) are forwarded uncharged because their
+    token usage is only known after the stream completes. If you need
+    streaming inside a budget, charge it yourself once the stream is
+    drained.
+    """
+
+    def __init__(
+        self,
+        *,
+        inner: LLMClientProtocol,
+        tracker: BudgetTrackerProtocol,
+        cost_per_method: dict[str, float] | None = None,
+        default_cost: float = 1.0,
+    ) -> None:
+        super().__init__(inner=inner)
+        self._tracker = tracker
+        self._cost_per_method = dict(cost_per_method or {})
+        self._default_cost = float(default_cost)
+
+    @property
+    def tracker(self) -> BudgetTrackerProtocol:
+        """The active budget tracker (useful for inspection or reset)."""
+        return self._tracker
+
+    def _cost_for(self, method: str) -> float:
+        """Resolve the configured cost for ``method``."""
+        return self._cost_per_method.get(method, self._default_cost)
+
+    def _gate(self, method: str) -> float:
+        """Pre-call check; returns the cost we plan to charge.
+
+        Raises:
+            BudgetExceededError: When :meth:`BudgetTrackerProtocol.can_afford`
+                rejects the projected cost.
+        """
+        cost = self._cost_for(method)
+        if not self._tracker.can_afford(cost):
+            remaining = self._tracker.remaining()
+            raise BudgetExceededError(
+                f"budget exhausted before {method!r} "
+                f"(remaining={remaining:.4f}, attempted={cost:.4f})",
+                limit=remaining + cost,
+                spent=remaining,
+                attempted=cost,
+            )
+        return cost
+
+    async def complete(
+        self,
+        messages: MessageInput,
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Gate on the budget, run ``complete``, then charge the flat cost."""
+        cost = self._gate("complete")
+        result = await self._inner.complete(
+            messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            **kwargs,
+        )
+        self._tracker.charge(cost, details={"method": "complete"})
+        return result
+
+    async def complete_structured(
+        self,
+        messages: MessageInput,
+        response_model: type[T],
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> T:
+        """Gate on the budget, run ``complete_structured``, then charge."""
+        cost = self._gate("complete_structured")
+        result = await self._inner.complete_structured(
+            messages,
+            response_model,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            **kwargs,
+        )
+        self._tracker.charge(cost, details={"method": "complete_structured"})
+        return result
+
+    async def complete_with_tools(
+        self,
+        messages: MessageInput,
+        tools: ToolRegistry | Mapping[str, Any] | Iterable[Any],
+        *,
+        tool_executor: ToolExecutor | None = None,
+        dialect: ToolDialect | None = None,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        max_iterations: int = 10,
+        **kwargs: Any,
+    ) -> ToolCallResponse:
+        """Charge once for the whole tool-using turn.
+
+        Internal tool-iteration calls made by the inner client are not
+        re-billed here; the cost reflects "one user-facing turn".
+        """
+        cost = self._gate("complete_with_tools")
+        result = await self._inner.complete_with_tools(
+            messages,
+            tools,
+            tool_executor=tool_executor,
+            dialect=dialect,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            max_iterations=max_iterations,
+            **kwargs,
+        )
+        self._tracker.charge(cost, details={"method": "complete_with_tools"})
+        return result
+
+    def stream(
+        self,
+        messages: MessageInput,
+        *,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[str]:
+        """Forward streamed completions to the inner client untouched.
+
+        Streams are not charged because their token usage is only
+        known after the stream completes. Charge yourself once the
+        stream is drained if you need streaming inside a budget.
+        """
+        return self._inner.stream(
+            messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            **kwargs,
+        )
+
+    async def continue_conversation(
+        self,
+        conversation: Conversation,
+        user_message: str,
+        *,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Gate on the budget per turn, then forward."""
+        cost = self._gate("continue_conversation")
+        result = await self._inner.continue_conversation(
+            conversation,
+            user_message,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            **kwargs,
+        )
+        self._tracker.charge(cost, details={"method": "continue_conversation"})
+        return result
+
+    async def loglikelihood(
+        self,
+        context: str,
+        continuation: str,
+        *,
+        model: str | None = None,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> tuple[float, bool]:
+        """Gate on the budget, run ``loglikelihood``, then charge."""
+        cost = self._gate("loglikelihood")
+        result = await self._inner.loglikelihood(
+            context,
+            continuation,
+            model=model,
+            max_tokens=max_tokens,
+            **kwargs,
+        )
+        self._tracker.charge(cost, details={"method": "loglikelihood"})
+        return result
+
+    async def generate_image(
+        self,
+        prompt: str,
+        *,
+        model: str | None = None,
+        n: int = 1,
+        size: str | None = None,
+        quality: str | None = None,
+        style: str | None = None,
+        response_format: str = "url",
+        **kwargs: Any,
+    ) -> ImageGenerationResponse:
+        """Gate on the budget, run ``generate_image``, then charge.
+
+        Pass a higher cost via ``cost_per_method={"generate_image": …}``
+        to reflect the typically larger per-call price of images.
+        """
+        cost = self._gate("generate_image")
+        result = await self._inner.generate_image(
+            prompt,
+            model=model,
+            n=n,
+            size=size,
+            quality=quality,
+            style=style,
+            response_format=response_format,
+            **kwargs,
+        )
+        self._tracker.charge(cost, details={"method": "generate_image"})
+        return result

ellements/core/budgeting/protocol.py

@@ -0,0 +1,51 @@
+"""Protocol defining how a budget tracker is consumed by wrappers."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class BudgetTrackerProtocol(Protocol):
+    """Structural type for cost trackers consumed by :class:`BudgetedLLMClient`.
+
+    Implementations are expected to be lightweight, in-process bookkeepers.
+    They are *not* concurrency-safe across multiple processes; if you need
+    cross-process budgets, persist spend yourself and rebuild the tracker
+    on startup.
+
+    Methods
+    -------
+    can_afford
+        Predicate evaluated *before* a request is dispatched. Trackers
+        that gate on call count or a hard limit should refuse early
+        rather than after the spend has occurred. ``estimate`` is the
+        caller's best guess at the upcoming cost; trackers may ignore
+        it.
+    charge
+        Records actual spend after a request completes. ``details`` is
+        a free-form mapping (e.g. ``{"input_tokens": 42, "output_tokens": 11,
+        "model": "openai/gpt-4o"}``) so trackers can compute the true
+        cost from raw provider usage data when an estimate is not enough.
+        Must raise :class:`~ellements.core.exceptions.BudgetExceededError`
+        when the recorded charge pushes spend past the configured cap.
+    remaining
+        Returns the headroom left under the cap, or ``math.inf`` for
+        unlimited trackers. Useful for diagnostics and for callers that
+        want to short-circuit large batches before they start.
+    """
+
+    def can_afford(self, estimate: float = 0.0) -> bool:
+        """Return ``True`` if ``estimate`` cost is plausibly affordable."""
+        ...
+
+    def charge(self, cost: float, *, details: dict[str, Any] | None = None) -> None:
+        """Record ``cost`` against the budget, raising if the cap is exceeded."""
+        ...
+
+    def remaining(self) -> float:
+        """Return the unspent portion of the budget (``math.inf`` if uncapped)."""
+        ...
+
+
+__all__ = ["BudgetTrackerProtocol"]