loom-kernel 2.0.0__tar.gz → 2.1.0__tar.gz

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/PKG-INFO

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

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/docs/ai/artifacts.md

@@ -1029,6 +1029,38 @@ never edits the history. An out-of-range value is reported as a
 coded issue (`POLICY_OUT_OF_RANGE`) rather than a decoding failure, so it
 accumulates with the other problems in the file instead of hiding them.
 
+### `retries` — two axes, one knob
+
+One authored number governs two independent retry loops, and honouring
+either loop's outcome for both would double-invoke a granted use case:
+
+- `AgentSpec.retries` (`loom.ai.engines.pydantic_ai._spec`) retries a failed
+  tool call, and an answer `output_check` rejects, inside one run — always,
+  regardless of what the plan grants.
+- `PydanticAIEngine`'s own attempt loop (`_engine.py`, `_may_retry`) retries a
+  failed **provider** call across runs — only when the plan holds no
+  capability at all.
+
+The second loop stops as soon as the plan grants any capability
+(`PydanticAIEngine._may_retry`): by the time a provider call fails, the model
+may already have invoked an application operation, and nothing about a
+granted use case is idempotent or keyed, so replaying the run would invoke it
+again. That is the behaviour `docs/ai/artifacts.md` and
+`engines/pydantic_ai/_spec.py`'s own module docstring already document; this
+section exists so the field an author reads says the same thing, not a
+different rule.
+
+Two things this field does **not** do, on purpose:
+
+- It does not raise a compile-time warning when a capability-bearing plan
+  keeps the default. `RETRIES_DEFAULT` is `2`, so every capability-bearing
+  artefact that never touched the field would warn — a warning firing on the
+  common case trains an operator to ignore warnings, which is worse than no
+  warning at all.
+- Loom does not "honour" the plan's `retries` for the provider loop once a
+  capability is granted. Doing so is exactly the double invocation the guard
+  above exists to prevent.
+
 ### Spend caps
 
 ```yaml

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/src/loom/ai/abc.py

@@ -152,7 +152,8 @@ class AgentResult(LoomFrozenStruct, frozen=True, kw_only=True):
         hook_result: Return value of the ``on_output`` use case, when the plan
             declares one.
         messages: New messages of this run in the engine's own serialised
-            form; ``None`` unless the run carried a conversation.
+            form; ``None`` when they are longer than
+            ``policies.max_history_bytes``.
     """
 
     output: object
@@ -592,7 +593,8 @@ class FinalEvent(LoomFrozenStruct, frozen=True, kw_only=True, tag="final", tag_f
         hook_result: Return value of the ``on_output`` use case, when the plan
             declares one.
         messages: New messages of this run in the engine's own serialised
-            form; ``None`` unless the run carried a conversation.
+            form; ``None`` when they are longer than
+            ``policies.max_history_bytes``.
     """
 
     output: object
@@ -646,8 +648,8 @@ class AgentEngine(Protocol):
                 own declared defaults instead of an empty value.
 
         Returns:
-            The validated output and the run's usage, plus ``messages`` when a
-            conversation was passed.
+            The validated output, the run's usage and this run's messages,
+            bounded by ``policies.max_history_bytes`` (``None`` above it).
         """
         ...
 

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/src/loom/ai/declarative/_schema.py

@@ -55,6 +55,7 @@ from ._v1 import (
     ON_UNPRICED_SPEND_POLICIES,
     RESERVED_INSTRUCTION_NAME,
     RETRIES_DEFAULT,
+    RETRIES_DESCRIPTION,
     RETRIES_MAX,
     RETRIES_MIN,
     RUN_TIMEOUT_MS_DEFAULT,
@@ -417,6 +418,7 @@ def _policy_properties() -> dict[str, Any]:
             "minimum": RETRIES_MIN,
             "maximum": RETRIES_MAX,
             "default": RETRIES_DEFAULT,
+            "description": RETRIES_DESCRIPTION,
         },
         "tool_timeout_ms": {
             "type": "integer",

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/src/loom/ai/declarative/_v1.py

@@ -81,6 +81,15 @@ RETRIES_DEFAULT: Final[int] = 2
 RETRIES_MIN: Final[int] = 0
 RETRIES_MAX: Final[int] = 10
 
+RETRIES_DESCRIPTION: Final[str] = (
+    "Retries a failed tool call, and an answer output_check rejects, inside "
+    "one run, always. Retries a failed provider call across runs, only when "
+    "the plan holds no capability; see 'retries' in docs/ai/artifacts.md."
+)
+"""Single source of the ``retries`` field's published description; also cited
+by :class:`PolicySpec`'s own docstring so the two never retype the same
+sentence."""
+
 TOOL_TIMEOUT_MS_DEFAULT: Final[int] = 20000
 TOOL_TIMEOUT_MS_MIN: Final[int] = 100
 TOOL_TIMEOUT_MS_MAX: Final[int] = 600000
@@ -451,7 +460,11 @@ class PolicySpec(
     behind the fields below.
 
     Args:
-        retries:         Attempts the engine makes before a failure is final.
+        retries:         Retries a failed tool call, and an answer
+            ``output_check`` rejects, inside one run, always. Retries a
+            failed provider call across runs, only when the plan holds no
+            capability. See :data:`RETRIES_DESCRIPTION` and "``retries``" in
+            ``docs/ai/artifacts.md``.
         tool_timeout_ms: Deadline of a single tool call.
         max_iterations:  Maximum ``ToolCallEvent``\\ s loom's own supervisor
             observes over the event stream in one run; see "``max_iterations``

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/src/loom/ai/declarative/schemas/agent-spec-v1.schema.json

@@ -402,7 +402,8 @@
           "type": "integer",
           "minimum": 0,
           "maximum": 10,
-          "default": 2
+          "default": 2,
+          "description": "Retries a failed tool call, and an answer output_check rejects, inside one run, always. Retries a failed provider call across runs, only when the plan holds no capability; see 'retries' in docs/ai/artifacts.md."
         },
         "tool_timeout_ms": {
           "type": "integer",

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/src/loom/ai/engines/pydantic_ai/_engine.py

@@ -182,8 +182,8 @@ class PydanticAIEngine:
                 forwarded to :attr:`_deps` unchanged.
 
         Returns:
-            The validated output, the run's usage and — when the run carried a
-            conversation — the messages it added.
+            The validated output, the run's usage and the messages it added,
+            bounded by ``policies.max_history_bytes`` (``None`` above it).
 
         Raises:
             AgentRunError: Carrying the coded, classified failure and what the
@@ -206,7 +206,11 @@ class PydanticAIEngine:
         return AgentResult(
             output=output,
             usage=self._usage(spend, started, unpriced_requests=unpriced),
-            messages=new_messages(result, decoded),
+            messages=new_messages(
+                result,
+                agent=self._plan.name,
+                max_history_bytes=self._plan.policies.max_history_bytes,
+            ),
         )
 
     def run_stream(
@@ -518,7 +522,7 @@ class PydanticAIEngine:
                     "trailing AgentRunResultEvent"
                 )
             try:
-                final = self._conclude(outcome[0], spend, started, decoded, output_type)
+                final = self._conclude(outcome[0], spend, started, output_type)
             except Exception as exc:
                 error, _ = self._record_attempt_failure(exc, attempt, emitted=True)
                 yield ErrorEvent(
@@ -592,7 +596,6 @@ class PydanticAIEngine:
         result: AgentRunResult[Any],
         spend: RunUsage,
         started: float,
-        conversation: RunConversation | None,
         output_type: type[Any] | None,
     ) -> FinalEvent:
         """Apply ``on_unpriced_spend`` to a finished attempt and build its ``final`` event.
@@ -604,16 +607,13 @@ class PydanticAIEngine:
                 excludes it.
         """
         unpriced = self._apply_unpriced_spend_policy(result)
-        return self._final(
-            result, spend, started, conversation, output_type, unpriced_requests=unpriced
-        )
+        return self._final(result, spend, started, output_type, unpriced_requests=unpriced)
 
     def _final(
         self,
         result: AgentRunResult[Any],
         spend: RunUsage,
         started: float,
-        conversation: RunConversation | None,
         output_type: type[Any] | None,
         *,
         unpriced_requests: int = 0,
@@ -629,7 +629,11 @@ class PydanticAIEngine:
         return FinalEvent(
             output=output,
             usage=self._usage(spend, started, unpriced_requests=unpriced_requests),
-            messages=new_messages(result, conversation),
+            messages=new_messages(
+                result,
+                agent=self._plan.name,
+                max_history_bytes=self._plan.policies.max_history_bytes,
+            ),
         )
 
 

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/src/loom/ai/engines/pydantic_ai/_history.py

@@ -83,8 +83,29 @@ def run_kwargs(conversation: RunConversation | None) -> dict[str, Any]:
     }
 
 
-def new_messages(result: AgentRunResult[Any], conversation: RunConversation | None) -> bytes | None:
-    """Return this run's messages, serialised; ``None`` for a single shot."""
-    if conversation is None:
+def new_messages(
+    result: AgentRunResult[Any], *, agent: str, max_history_bytes: int
+) -> bytes | None:
+    """Return this run's messages, serialised, bounded by ``policies.max_history_bytes``.
+
+    Args:
+        result: A completed attempt's result.
+        agent: Name of the plan this run served, for the over-bound log line.
+        max_history_bytes: ``policies.max_history_bytes`` of the plan.
+
+    Returns:
+        This run's messages, whether or not it carried a conversation;
+        ``None`` when they are longer than *max_history_bytes* — logged with
+        *agent*, the measured size and the bound.
+    """
+    encoded = result.new_messages_json()
+    if len(encoded) > max_history_bytes:
+        _logger.warning(
+            "agent %r produced %d bytes of new messages, above max_history_bytes "
+            "(%d); the run's hook receives none",
+            agent,
+            len(encoded),
+            max_history_bytes,
+        )
         return None
-    return result.new_messages_json()
+    return encoded

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/src/loom/ai/runtime/_hooks.py

@@ -63,7 +63,7 @@ def hook_command(
         run: Context of the admitted run.
         accepted: Internal names the Input declares.
         messages: The run's new messages in the engine's serialised form;
-            ``None`` on a run without a conversation.
+            ``None`` when they are longer than ``policies.max_history_bytes``.
 
     Returns:
         The payload ``from_payload`` will decode.

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/tests/integration/ai/test_conversation.py

@@ -723,7 +723,7 @@ class TestMessagesInTheHook:
         conversation_deps: RecordingDepsFactory,
         container: LoomContainer,
     ) -> None:
-        """A single-shot run offers ``None`` and the result carries ``None``."""
+        """A run whose engine reports no messages offers ``None``; the result carries ``None``."""
         engine = ScriptedEngine(script=default_script({"answer": "42"}))
         plan = _plan(loader=None, hook=RecordTurn)
         runtime = _runtime(engine, plan, deps=conversation_deps, container=container)

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/tests/unit/ai/engines/test_pydantic_ai_conversation.py

@@ -8,6 +8,8 @@ not validate fails before the model is called, with nothing spent.
 
 from __future__ import annotations
 
+import logging
+
 import pytest
 from pydantic_ai.messages import (
     ModelMessage,
@@ -19,6 +21,8 @@ from pydantic_ai.messages import (
 )
 
 from loom.ai.abc import AgentEngine, AgentEvent, Conversation, ErrorEvent, FinalEvent
+from loom.ai.declarative import PolicySpec
+from loom.ai.declarative._v1 import MAX_HISTORY_BYTES_MIN
 from loom.ai.errors import CONVERSATION_LOAD_FAILED_MESSAGE, AgentRunError, AgentRunErrorCode
 from loom.core.identity import Identity
 from tests.helpers.pydantic_ai_engine import (
@@ -150,22 +154,61 @@ class TestHistory:
 
 
 class TestSingleShot:
-    async def test_serialises_no_messages_when_run_carries_no_conversation(self) -> None:
+    async def test_serialises_this_turns_messages_when_run_carries_no_conversation(self) -> None:
+        """L19: the hook can see the tool traffic of a single-shot run (T901)."""
         seen: list[list[ModelMessage]] = []
         engine = _engine(seen)
 
         result = await engine.run(_PROMPT, identity=_IDENTITY, conversation=None)
 
         assert _prompts(seen[0]) == [_PROMPT]
-        assert result.messages is None
+        assert result.messages is not None
+        assert _prompts(_decode(result.messages)) == [_PROMPT]
 
-    async def test_serialises_no_messages_when_the_stream_carries_no_conversation(self) -> None:
+    async def test_serialises_this_turns_messages_when_the_stream_carries_no_conversation(
+        self,
+    ) -> None:
+        """L19: a streamed single-shot run's terminal event carries the same traffic."""
         seen: list[list[ModelMessage]] = []
         engine = _engine(seen)
 
         events = await _collect(engine, None)
 
         assert len(seen) == 1
+        messages = _final(events).messages
+        assert messages is not None
+        assert _prompts(_decode(messages)) == [_PROMPT]
+
+
+class TestOverBound:
+    async def test_gives_none_and_logs_the_agent_size_and_bound_when_messages_exceed_it(
+        self, caplog: pytest.LogCaptureFixture
+    ) -> None:
+        """L19: over ``max_history_bytes`` the hook gets ``None`` and the run logs why (T901)."""
+        oversized = encode({"answer": "x" * MAX_HISTORY_BYTES_MIN})
+        engine = build_engine(
+            make_plan(policies=PolicySpec(max_history_bytes=MAX_HISTORY_BYTES_MIN)),
+            recording_model(oversized, []),
+        )
+
+        with caplog.at_level(logging.WARNING, logger="loom.ai.engines.pydantic_ai._history"):
+            result = await engine.run(_PROMPT, identity=_IDENTITY, conversation=None)
+
+        assert result.messages is None
+        [record] = caplog.records
+        assert "contract" in record.message
+        assert str(MAX_HISTORY_BYTES_MIN) in record.message
+
+    async def test_gives_none_when_the_stream_carries_messages_over_the_bound(self) -> None:
+        """The streamed terminal event is bounded the same way as the non-streaming run."""
+        oversized = encode({"answer": "x" * MAX_HISTORY_BYTES_MIN})
+        engine = build_engine(
+            make_plan(policies=PolicySpec(max_history_bytes=MAX_HISTORY_BYTES_MIN)),
+            recording_model(oversized, []),
+        )
+
+        events = await _collect(engine, None)
+
         assert _final(events).messages is None
 
 

{loom_kernel-2.0.0 → loom_kernel-2.1.0}/tests/unit/ai/test_schema_emission.py

@@ -27,7 +27,11 @@ import pytest
 from jsonschema import Draft202012Validator
 
 from loom.ai.declarative import agent_spec_json_schema, agent_spec_schema_path
-from loom.ai.declarative._v1 import DEPS_TYPE_PATTERN, INSTRUCTION_NAME_PATTERN
+from loom.ai.declarative._v1 import (
+    DEPS_TYPE_PATTERN,
+    INSTRUCTION_NAME_PATTERN,
+    RETRIES_DESCRIPTION,
+)
 
 _CONTRACT_PATH: Path = agent_spec_schema_path(1)
 
@@ -300,6 +304,11 @@ def test_emitted_instruction_block_name_pattern_is_the_struct_constant_not_a_cop
     assert pattern == INSTRUCTION_NAME_PATTERN
 
 
+def test_emitted_retries_description_is_the_struct_constant_not_a_copy() -> None:
+    """L20: the schema names both axes from the constant the docstring cites, never re-typed."""
+    assert _policy_properties(_emitted())["retries"]["description"] == RETRIES_DESCRIPTION
+
+
 def test_emitted_deps_type_description_states_the_dict_waiver() -> None:
     """FR-006 must be readable in the schema text itself, not only in the struct docstring."""
     assert "waive" in _emitted()["properties"]["deps_type"]["description"]