loom-kernel 2.3.0__tar.gz → 2.4.0__tar.gz

{loom_kernel-2.3.0 → loom_kernel-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.3.0
+Version: 2.4.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed

{loom_kernel-2.3.0 → loom_kernel-2.4.0}/docs/ai/overview.md

@@ -207,6 +207,54 @@ place with no models starts the application with a WARNING that names
 `persistence.backend: none` as the way out, and still requires a reachable
 database.
 
+## When loom is not enough: the escape hatch
+
+Loom is a wrapper over pydantic-ai, and a wrapper you cannot step around is a
+ceiling. `native_agent` is the step around it: an async context manager that
+hands back the very `Agent` this deployment runs, the dependency bundle of
+the calling identity, and the artifact's spend caps already projected, so
+calling code can drive pydantic-ai with its own API — `iter()`,
+`run(event_stream_handler=...)`, `capture_run_messages()`, a capability of
+its own.
+
+```python
+from loom.ai.engines.pydantic_ai import native_agent
+
+async def execute(self, triage: AgentHandle[Assessment] = Agent("incident-triage")):
+    async with (
+        native_agent(triage) as access,
+        access.agent.iter(
+            "classify this page", deps=access.deps, usage_limits=access.usage_limits
+        ) as run,
+    ):
+        async for node in run:
+            ...  # your own decision between nodes
+```
+
+Loom's chain-cycle, depth and admission bounds hold for the whole block —
+there is no supported way to drive the hatch outside them, so skipping
+`max_concurrent_runs` is never the default path. Pass `access.usage_limits`
+explicitly — pydantic-ai enforces no cap you do not pass it yourself. To add
+a tool for this one run only, pass `toolsets=`/`capabilities=` to `iter()`
+rather than registering it on the shared agent (see the rule below).
+
+It lives in `loom.ai.engines.pydantic_ai`, not in `loom.ai`: importing an engine
+is the explicit act of leaving loom's neutral surface, and the neutral
+`AgentHandle.native()` returns `object` precisely so the engine package is the
+one that names the type.
+
+The full account of what still holds and what is lost is written once, on
+`AgentHandle.native()`'s own docstring — read it before relying on this hatch
+for anything beyond the sketch above.
+
+**One rule.** The `agent` you receive is the single object serving every run of
+that agent in this worker. Read it, run it, never mutate it: registering a tool,
+a validator or a capability on it changes every other run, including the ones
+loom itself drives. `access.shaped_agent` — the same spec with no output
+validator registered — stands in for it when the plan declares `output_check`
+and this run overrides the output shape: pydantic-ai refuses a run-level
+`output_type` on an agent holding one.
+
 ## Where to go next
 
 - **[Artifact reference](artifacts.md)** — the complete `spec_version: 1`

{loom_kernel-2.3.0 → loom_kernel-2.4.0}/docs/ai/providers.md

@@ -127,7 +127,7 @@ redacts itself:
 
 ```pycon
 >>> print(target)
-InferenceTarget(provider='bedrock', model='anthropic.claude-sonnet-4-...', region='eu-west-1', endpoint=None, output_mode=None, credentials_ref=<redacted>, options=<redacted>)
+InferenceTarget(provider='bedrock', model='anthropic.claude-sonnet-4-...', region='eu-west-1', endpoint=None, output_mode=None, streaming=True, credentials_ref=<redacted>, options=<redacted>)
 ```
 
 and **refuses** to be serialised at all when it carries a secret reference —
@@ -195,6 +195,34 @@ loom does not infer it per provider. Two consequences follow from that:
   model before the first request, so a wrong pin is found there, not at
   start-up.
 
+## Asking for the answer whole, not as a stream
+
+Loom streams every run, so it can supervise it as it happens; the provider
+is asked to stream too. Some models stream badly: on Bedrock, one family
+delivers a short tool call with its opening characters missing, one answer
+in two, while the same answer asked without streaming arrives whole -- the
+provider parses it before sending it. A binding can ask for that instead:
+
+```yaml
+ai:
+  models:
+    reasoning:
+      provider: bedrock
+      model: <model id>
+      streaming: false
+```
+
+What changes for that role, and only for it: each model request is answered in
+one piece. A run loses nothing else — the answer is validated and retried the
+same way, the usage is the same, and a `run_stream` caller still receives what
+the model said and every tool call and result, in order; the text simply
+arrives as one delta per text part instead of many. The policies
+(`run_timeout_ms`, `max_iterations`, `max_requests`) apply as before.
+
+It is the choice pydantic-ai offers between `run` and `run_stream`, made per
+model binding rather than per call: the artifact never has to know which model
+serves it, and a role can be moved back by deleting the line.
+
 ## What does not happen
 
 **No fallback routing.** An exhausted or failing provider fails the run. It is

{loom_kernel-2.3.0 → loom_kernel-2.4.0}/src/loom/ai/__init__.py

@@ -33,6 +33,7 @@ from loom.ai.abc import (
     McpSession,
     McpToolCallResult,
     McpToolInfo,
+    NativeCapableEngine,
     OutputCheck,
     Prompt,
     SqlGrantHandle,
@@ -88,6 +89,7 @@ __all__ = [
     "McpSession",
     "McpToolCallResult",
     "McpToolInfo",
+    "NativeCapableEngine",
     "OutputCheck",
     "Prompt",
     "SqlGrantHandle",

{loom_kernel-2.3.0 → loom_kernel-2.4.0}/src/loom/ai/abc.py

@@ -19,7 +19,18 @@ from __future__ import annotations
 from collections.abc import AsyncIterator, Callable, Mapping, Sequence
 from contextlib import AbstractAsyncContextManager
 from decimal import Decimal
-from typing import Any, ClassVar, Final, Generic, Literal, Protocol, TypeAlias, TypeVar, overload
+from typing import (
+    Any,
+    ClassVar,
+    Final,
+    Generic,
+    Literal,
+    Protocol,
+    TypeAlias,
+    TypeVar,
+    overload,
+    runtime_checkable,
+)
 
 from loom.ai.errors import AgentRunErrorCode
 from loom.ai.inference import InferenceTarget
@@ -519,6 +530,62 @@ class AgentHandle(Protocol[AnswerT]):
         """
         ...
 
+    def native(self, *, state: object | None = None) -> object:
+        """Return the engine's own objects for this agent, outside loom's supervision.
+
+        The escape hatch: whatever the engine serving this agent was built
+        from, handed over so calling code can drive the underlying library
+        itself when loom's neutral surface does not cover what it needs.
+        Typed as ``object`` because this module names no engine; the engine
+        package publishes the accessor that narrows it — for the pydantic-ai
+        engine, :func:`loom.ai.engines.pydantic_ai.native_agent`. This is the
+        one place the full what-holds/what-is-lost list is written; every
+        other mention of it points back here.
+
+        **What still holds.** The identity bound to this handle and the
+        artefact's grants: already built into what is returned, so a run
+        driven this way still reaches exactly what the artefact granted, as
+        this caller. ``policies.tool_timeout_ms`` still bounds every
+        capability call, because it is compiled into the tools the returned
+        agent already carries. The artefact's ``output_check`` validator
+        still runs, for the same reason. So do loom's chain-cycle and
+        agent-chain-depth bounds and its admission limit
+        (``max_concurrent_runs``): the returned engine-native objects are
+        reachable only inside the accessor's own ``async with`` block
+        (:func:`loom.ai.engines.pydantic_ai.native_agent` for the
+        pydantic-ai engine), which rejoins those bounds for the whole body.
+
+        **What is lost**, always: loom's own retry policy (including the
+        rule that an agent holding a capability never retries), ``run_timeout_ms``,
+        ``max_iterations``, ``policies.on_unpriced_spend`` and the
+        ``COST_NOT_MEASURABLE`` refusal it can raise, the ``on_output`` hook,
+        the ``conversation`` loader, the event projection, loom's own output
+        decoding (:func:`~loom.ai.engines.pydantic_ai._output.decode_output`
+        for a ``msgspec.Struct`` artefact — a native run returns pydantic-ai's
+        own answer, a mapping, not the artefact's declared type) and
+        ``max_history_bytes``. An application using this hatch is also pinned
+        to the engine it names: nothing here is portable across engines.
+
+        Args:
+            state: This run's state, resolved against the artefact's declared
+                shape exactly as :meth:`run` resolves it.
+
+        Returns:
+            The engine-native objects, in the engine's own types.
+
+        Raises:
+            AgentRunError: With ``UNAUTHORIZED`` when this handle's identity
+                is anonymous, so the hatch never yields what :meth:`run`
+                would have refused; with ``STATE_UNDECLARED`` or
+                ``STATE_REQUIRED`` when *state* does not match the
+                artefact's declared shape.
+            RuntimeError: When the runtime serving this handle was never
+                entered.
+            NotImplementedError: When the engine serving this agent publishes
+                no native form.
+        """
+        ...
+
     def grants(self) -> tuple[str, ...]:
         """Return every grant name reachable through :meth:`mcp` and :meth:`sql`.
 
@@ -708,6 +775,38 @@ class AgentEngine(Protocol):
         ...
 
 
+@runtime_checkable
+class NativeCapableEngine(Protocol):
+    """An :class:`AgentEngine` that also publishes its own native form.
+
+    ``native`` is optional on :class:`AgentEngine` itself; this Protocol
+    exists only so :meth:`~loom.ai.runtime.AgentRuntime.native` can narrow to
+    it with ``isinstance`` instead of reflecting over ``getattr``.
+    """
+
+    def native(
+        self,
+        *,
+        identity: Identity,
+        state: object | None = None,
+        guard: Callable[[], AbstractAsyncContextManager[None]],
+    ) -> object:
+        """Return this engine's own objects, bound to *identity*.
+
+        Args:
+            identity: Verified caller the returned objects are built for.
+            state: This run's state, already resolved against the plan's
+                declared shape.
+            guard: Zero-argument factory of the async context manager a
+                driven run enters to rejoin the runtime's chain and
+                admission bounds.
+
+        Returns:
+            The engine's own objects, in the engine's own types.
+        """
+        ...
+
+
 HealthState = Literal["ok", "degraded", "unavailable"]
 """The three health states. Defined beside the struct that carries it so the alias
 and the field cannot drift apart."""

{loom_kernel-2.3.0 → loom_kernel-2.4.0}/src/loom/ai/engines/pydantic_ai/__init__.py

@@ -20,12 +20,30 @@ free function, because the session it opens is the very toolset the run path
 uses: one connection per server for the whole worker. :func:`create_mcp_client`
 opens a session of its own and is for diagnostics, never for wiring the
 runtime.
+
+:func:`native_agent` is the escape hatch out of loom: an async context
+manager over the agent this adapter built, handed to calling code so it can
+drive pydantic-ai directly for what loom's neutral surface does not serve.
+Being *this* package's export is the point — a caller reaching it has
+imported an engine on purpose. It rejoins loom's chain and admission bounds
+around its body; see :meth:`~loom.ai.abc.AgentHandle.native` for what a
+driven run keeps and loses. :func:`as_run_error` is exported alone for a
+driver that wants loom's error classification without that context manager.
 """
 
 from __future__ import annotations
 
 from loom.ai.engines.pydantic_ai._a2a import create_a2a_client
+from loom.ai.engines.pydantic_ai._errors import as_run_error
+from loom.ai.engines.pydantic_ai._escape import NativeAgent, native_agent
 from loom.ai.engines.pydantic_ai._mcp import create_mcp_client
 from loom.ai.engines.pydantic_ai.provider import PydanticAIEngineProvider
 
-__all__ = ["PydanticAIEngineProvider", "create_a2a_client", "create_mcp_client"]
+__all__ = [
+    "NativeAgent",
+    "PydanticAIEngineProvider",
+    "as_run_error",
+    "create_a2a_client",
+    "create_mcp_client",
+    "native_agent",
+]

{loom_kernel-2.3.0 → loom_kernel-2.4.0}/src/loom/ai/engines/pydantic_ai/_engine.py

@@ -32,14 +32,22 @@ carries the same gap forward once observed.
 from __future__ import annotations
 
 import asyncio
-from collections.abc import AsyncGenerator, AsyncIterator, Mapping, Sequence
+import logging
+from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping, Sequence
 from contextlib import AbstractAsyncContextManager, asynccontextmanager
-from dataclasses import fields
+from dataclasses import fields, replace
 from time import perf_counter
 from types import MappingProxyType
 from typing import Any, Final, cast
 
-from pydantic_ai import Agent, AgentRunResult, AgentRunResultEvent, BinaryContent
+from pydantic_ai import (
+    Agent,
+    AgentRun,
+    AgentRunResult,
+    AgentRunResultEvent,
+    BinaryContent,
+    CallToolsNode,
+)
 from pydantic_ai.messages import ModelResponse, PartStartEvent
 from pydantic_ai.usage import RunUsage, UsageLimits
 
@@ -57,6 +65,7 @@ from loom.ai.abc import (
 )
 from loom.ai.compiler import AgentPlan
 from loom.ai.engines.pydantic_ai._errors import as_run_error
+from loom.ai.engines.pydantic_ai._escape import NativeAgent, _NativeAccess
 from loom.ai.engines.pydantic_ai._events import translate
 from loom.ai.engines.pydantic_ai._history import (
     RunConversation,
@@ -69,6 +78,8 @@ from loom.ai.errors import AgentRunError, AgentRunErrorCode, is_retriable
 from loom.core.di import LoomContainer
 from loom.core.identity import Identity
 
+_logger = logging.getLogger(__name__)
+
 RETRY_BACKOFF_MS = 200
 """Base wait before a retried attempt; doubled per attempt (FR-028).
 
@@ -76,6 +87,9 @@ A constant rather than a policy field: ``policies`` describes what the agent
 is allowed to spend, and no requirement asks the artifact to tune the wait.
 """
 
+MAX_LOGGED_CAUSE_CHARS = 500
+"""Cap on a logged failure cause: it is model-authored text, unbounded at the source."""
+
 _HEALTHY = HealthStatus(status="ok")
 
 # Counters :class:`~loom.ai.abc.AgentUsage` names itself, plus the engine's own
@@ -321,8 +335,59 @@ class PydanticAIEngine:
             return _UNPRICED_SPEND_HEALTH
         return _HEALTHY
 
+    def native(
+        self,
+        *,
+        identity: Identity,
+        state: object | None = None,
+        guard: Callable[[], AbstractAsyncContextManager[None]],
+    ) -> _NativeAccess:
+        """Return this engine's own objects, for a caller driving the run itself.
+
+        Serves :meth:`~loom.ai.abc.AgentHandle.native` through
+        :meth:`~loom.ai.runtime.AgentRuntime.native`; the accessor that names
+        the returned type for calling code is
+        :func:`~loom.ai.engines.pydantic_ai.native_agent`. What a driver keeps
+        and loses is stated once, on :meth:`~loom.ai.abc.AgentHandle.native`.
+
+        Args:
+            identity: Verified caller the dependency bundle is built for.
+            state: This run's state, already resolved against the plan's
+                declared shape by :class:`~loom.ai.runtime.AgentRuntime`.
+            guard: Zero-argument factory of the async context manager a
+                driven run enters to rejoin this runtime's chain and
+                admission bounds; built by
+                :meth:`~loom.ai.runtime.AgentRuntime.native` and carried on
+                the returned carrier unchanged.
+
+        Returns:
+            The plan's own agent, its shaped counterpart, this caller's
+            dependency bundle and the plan's projected spend caps, paired
+            with *guard*.
+        """
+        return _NativeAccess(
+            native=NativeAgent(
+                agent=self._agent,
+                shaped_agent=self._shaped_agent,
+                deps=self._build_deps(identity, state),
+                usage_limits=replace(self._usage_limits),
+            ),
+            guard=guard,
+        )
+
     # -- internals ---------------------------------------------------------
 
+    def _build_deps(self, identity: Identity, state: object | None) -> object:
+        """Build one invocation's dependency bundle for *identity*.
+
+        *state* arrives already resolved against the plan's declared shape; it
+        is cast, never re-validated, into the mapping
+        :class:`~loom.ai.abc.DepsFactory` declares (FR-009).
+        """
+        return self._deps.build(
+            identity, self._container, state=cast("Mapping[str, Any] | None", state)
+        )
+
     async def _run_with_retries(
         self,
         prompt: Prompt,
@@ -337,15 +402,8 @@ class PydanticAIEngine:
         run cost even when the call raises — and it accumulates across retried
         attempts, because a retry spends the provider's tokens again. The
         decoded history, by contrast, is the same list on every attempt.
-
-        *state* is already resolved by
-        :class:`~loom.ai.runtime.AgentRuntime` against the plan's declared
-        shape; it is cast, never re-validated, into the mapping
-        :class:`~loom.ai.abc.DepsFactory` declares (FR-009).
         """
-        deps = self._deps.build(
-            identity, self._container, state=cast("Mapping[str, Any] | None", state)
-        )
+        deps = self._build_deps(identity, state)
         for attempt in range(self._attempts):
             try:
                 result = await self._agent.run(
@@ -358,6 +416,7 @@ class PydanticAIEngine:
             except Exception as exc:
                 error = as_run_error(exc)
                 self._record(error.code)
+                self._log_cause(error, exc)
                 if self._may_retry(error.code, attempt):
                     await _backoff(attempt)
                     continue
@@ -412,8 +471,20 @@ class PydanticAIEngine:
         """
         error = as_run_error(exc)
         self._record(error.code)
+        self._log_cause(error, exc)
         return error, not emitted and self._may_retry(error.code, attempt)
 
+    def _log_cause(self, error: AgentRunError, exc: Exception) -> None:
+        """Log what the published failure cannot carry: the answer that caused it, truncated."""
+        if exc.__cause__ is not None:
+            cause = str(exc.__cause__)[:MAX_LOGGED_CAUSE_CHARS]
+            _logger.warning(
+                "agent %s failed with %s, raised from: %s",
+                self._plan.name,
+                error.code.value,
+                cause,
+            )
+
     def _apply_unpriced_spend_policy(self, result: AgentRunResult[Any]) -> int:
         """Act on this run's responses that pydantic-ai could not price.
 
@@ -509,9 +580,7 @@ class PydanticAIEngine:
         except AgentRunError as rejected:
             yield ErrorEvent(code=rejected.code, message=str(rejected))
             return
-        deps = self._deps.build(
-            identity, self._container, state=cast("Mapping[str, Any] | None", state)
-        )
+        deps = self._build_deps(identity, state)
         spend = RunUsage()
         started = perf_counter()
         for attempt in range(self._attempts):
@@ -537,7 +606,7 @@ class PydanticAIEngine:
             if not outcome:
                 raise AssertionError(
                     "unreachable: the engine's own event stream always ends with a "
-                    "trailing AgentRunResultEvent"
+                    "trailing AgentRunResultEvent, or, for a whole run, its own result"
                 )
             try:
                 final = self._conclude(outcome[0], spend, started, output_type)
@@ -572,8 +641,8 @@ class PydanticAIEngine:
         than relayed live, and flushed only once this attempt's
         ``AgentRunResultEvent`` arrives: an ``output_check`` rejection and a
         pydantic validation failure alike replay the model request inside
-        this same call, each replay's ``PartStartEvent`` starts again at
-        ``index=0``, and a delta already relayed cannot be un-sent. A plan
+        this same call, and each replay opens with a new response's first
+        part, at ``index=0``, so a delta already relayed cannot be un-sent. A plan
         that withholds nothing never buffers: *pending* stays empty and every
         mapped event is yielded as it arrives, exactly as before
         ``output_check`` existed.
@@ -582,40 +651,77 @@ class PydanticAIEngine:
         :attr:`_shaped_agent`, carrying no output validator, when given —
         pydantic-ai refuses a run-level ``output_type`` on an agent holding
         one — and :attr:`_agent`, the plan's own checked agent, otherwise.
+
+        A binding that declares ``streaming: false`` is served by
+        :meth:`_one_run_whole` instead, which relays the same events.
         """
-        withhold = self._withhold
         pending: list[AgentEvent] = []
         pinned: dict[str, Any] = {} if output_type is None else {"output_type": output_type}
         agent = self._agent if output_type is None else self._shaped_agent
-        async with agent.run_stream_events(
-            _user_prompt(prompt),
-            deps=deps,
-            usage=spend,
-            usage_limits=self._usage_limits,
+        run_args: dict[str, Any] = {
+            "deps": deps,
+            "usage": spend,
+            "usage_limits": self._usage_limits,
             **run_kwargs(conversation),
             **pinned,
-        ) as stream:
+        }
+        if not self._plan.inference.streaming:
+            async for relayed in self._one_run_whole(prompt, agent, run_args, pending, outcome):
+                yield relayed
+            return
+        async with agent.run_stream_events(_user_prompt(prompt), **run_args) as stream:
             async for event in stream:
                 if isinstance(event, AgentRunResultEvent):
                     outcome.append(event.result)
                     for held in pending:
                         yield held
                     return
-                mapped = self._relay_or_buffer(event, withhold, pending)
+                mapped = self._relay_or_buffer(event, self._withhold, pending)
                 if mapped is not None:
                     yield mapped
 
+    async def _one_run_whole(
+        self,
+        prompt: Prompt,
+        agent: Agent[Any, Any],
+        run_args: dict[str, Any],
+        pending: list[AgentEvent],
+        outcome: list[AgentRunResult[Any]],
+    ) -> AsyncIterator[AgentEvent]:
+        """One attempt whose model requests are answered whole, never streamed.
+
+        The run is driven node by node, as pydantic-ai's own ``run`` drives it,
+        so every request is answered in one piece -- parsed by the provider
+        before it is sent -- and the attempt keeps its validation, its tool
+        retries and its usage.
+        """
+        async with agent.iter(_user_prompt(prompt), **run_args) as run:
+            node = run.next_node
+            while not Agent.is_end_node(node):
+                if Agent.is_call_tools_node(node):
+                    async for event in _whole_response(node, run):
+                        mapped = self._relay_or_buffer(event, self._withhold, pending)
+                        if mapped is not None:
+                            yield mapped
+                node = await run.next(node)
+            # pydantic-ai leaves ``result`` typed optional though the ``End`` node just
+            # reached guarantees it; appended unconditionally, so a violated guarantee
+            # surfaces through ``_conclude``'s own classified failure, not a skipped outcome.
+            outcome.append(cast("AgentRunResult[Any]", run.result))
+        for held in pending:
+            yield held
+
     @staticmethod
     def _relay_or_buffer(
         event: object, withhold: bool, pending: list[AgentEvent]
     ) -> AgentEvent | None:
         """Translate one non-terminal stream *event* and apply the buffering policy.
 
-        A fresh replay's ``PartStartEvent`` at ``index=0`` discards whatever
-        this attempt had buffered so far. A mapped text delta is appended to
-        *pending* instead of returned when *withhold* is set, so the caller
-        never yields it directly; every other mapped event is returned as-is
-        for the caller to yield.
+        A new response's first part -- ``PartStartEvent`` at ``index=0`` --
+        discards whatever this attempt had buffered so far. A mapped text
+        delta is appended to *pending* instead of returned when *withhold*
+        is set, so the caller never yields it directly; every other mapped
+        event is returned as-is for the caller to yield.
         """
         if withhold and isinstance(event, PartStartEvent) and event.index == 0:
             pending.clear()
@@ -733,6 +839,21 @@ async def _backoff(attempt: int) -> None:
     await asyncio.sleep(RETRY_BACKOFF_MS * (2**attempt) / 1000)
 
 
+async def _whole_response(
+    node: CallToolsNode[Any, Any], run: AgentRun[Any, Any]
+) -> AsyncIterator[object]:
+    """Every engine event of one whole response: its own parts first, then its tool events.
+
+    A whole response carries its text already complete, so each part is offered as the
+    ``PartStartEvent`` a streamed run would have opened it with.
+    """
+    for index, part in enumerate(node.model_response.parts):
+        yield PartStartEvent(index=index, part=part)
+    async with node.stream(run.ctx) as events:
+        async for event in events:
+            yield event
+
+
 def _user_prompt(prompt: Prompt) -> str | Sequence[str | BinaryContent]:
     """The prompt as pydantic-ai takes it: an attachment becomes ``BinaryContent``."""
     if isinstance(prompt, str):