framework-agents 0.1.1__tar.gz → 0.2.0__tar.gz

{framework_agents-0.1.1 → framework_agents-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: framework-agents
-Version: 0.1.1
+Version: 0.2.0
 Summary: Python agent framework: ReAct loop, tools, memory, streaming, budgets, middleware, multi-agent, semantic graph, A2A serving - parity with the TypeScript package
 Project-URL: Homepage, https://github.com/fab679/framework
 Project-URL: Documentation, https://fab679.github.io/framework/

{framework_agents-0.1.1 → framework_agents-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "framework-agents"
-version = "0.1.1"
+version = "0.2.0"
 description = "Python agent framework: ReAct loop, tools, memory, streaming, budgets, middleware, multi-agent, semantic graph, A2A serving - parity with the TypeScript package"
 readme = "README.md"
 requires-python = ">=3.11"

{framework_agents-0.1.1 → framework_agents-0.2.0}/src/framework_agents/agent.py

@@ -12,8 +12,11 @@ from the FIXED versions):
   ends on a dangling tool-call tail).
 - Unknown tools / invalid args become model-visible feedback; loop continues.
 - result.usage.cost_usd set only when a price is known — never guessed.
-- Stream parity: token/thinking deltas batch per model call (as in TS), tool
-  events yield live, budget errors pass through unretried.
+- Stream parity: token/thinking deltas stream LIVE during the model call when
+  no middleware declares wrap_model/after_model; batched fallback (retry
+  compat) otherwise — tool events yield live, budget errors pass through
+  unretried. Providers stamp post-delta failures non-retryable so retries
+  never duplicate streamed text.
 - Per-stream results: AgentStream captures its OWN AgentResult at the done
   event; concurrent streams on one agent never cross-contaminate.
 - beforeModel REPLACEMENTS feed the model call only: the loop's message list
@@ -35,7 +38,7 @@ from typing import Any, AsyncIterator, Callable, Literal, Optional, Type
 from pydantic import BaseModel, ValidationError
 
 from .checkpoint import PendingCall, ThreadCheckpoint
-from .errors import AgentError
+from .errors import AgentError, get_retryable, stamp_retryable
 from .memory import InMemoryMemory, Memory
 from .middleware import (
     HITL_DECISIONS_KEY,
@@ -608,19 +611,25 @@ class Agent:
                 rt.events and rt.events.on_step and rt.events.on_step(step)
                 yield {"type": "step", "step": step}
 
-                # Token/thinking deltas batch per model call (TS parity) while the
-                # events hooks fire live inside provider.complete.
+                # Live delta streaming (parity: TS runLoop): when no middleware
+                # declares wrap_model (retrying an attempt whose deltas were
+                # already delivered would duplicate streamed text) or
+                # after_model (output scrubbing must run BEFORE tokens reach
+                # the UI), deltas stream LIVE via a queue while the model call
+                # is still running; the batched fallback buffers until it settles.
+                needs_batching = any(
+                    getattr(m, "wrap_model", None) or getattr(m, "after_model", None) for m in mw
+                )
                 pending: list[StreamEvent] = []
+                channel: asyncio.Queue = asyncio.Queue()
+                deltas_emitted = False
 
-                def on_token(delta: str) -> None:
-                    if rt.events and rt.events.on_token:
-                        rt.events.on_token(delta)
-                    pending.append({"type": "token", "delta": delta})
-
-                def on_thinking(delta: str) -> None:
-                    if rt.events and rt.events.on_thinking:
-                        rt.events.on_thinking(delta)
-                    pending.append({"type": "thinking", "delta": delta})
+                def emit_delta(kind: str, delta: str) -> None:
+                    event = {"type": kind, "delta": delta}
+                    if needs_batching:
+                        pending.append(event)
+                    else:
+                        channel.put_nowait(event)
 
                 response_format = None
                 if strategy == "provider" and fmt is not None:
@@ -632,15 +641,40 @@ class Agent:
                 ctx = HookContext(step=step, invocation_state=invocation_state)
 
                 async def _call_model(req: ModelRequest) -> Any:
-                    return await rt.model.complete(
-                        CompleteOptions(
-                            messages=req.messages,
-                            tools=req.tools,
-                            response_format=req.response_format,
-                            on_token=on_token,
-                            on_thinking=on_thinking,
+                    # One closure per attempt (the wrap chain re-invokes
+                    # _call_model on every retry): deltas buffered by a FAILED
+                    # attempt never flush — the retried call replaces them.
+                    # Live path: deltas went onto the channel and were already
+                    # delivered, so there is nothing to roll back by design.
+                    start = len(pending)
+                    failed = {"v": False}
+
+                    def attempt_on_token(delta: str) -> None:
+                        if rt.events and rt.events.on_token:
+                            rt.events.on_token(delta)
+                        if not failed["v"]:
+                            emit_delta("token", delta)
+
+                    def attempt_on_thinking(delta: str) -> None:
+                        if rt.events and rt.events.on_thinking:
+                            rt.events.on_thinking(delta)
+                        if not failed["v"]:
+                            emit_delta("thinking", delta)
+
+                    try:
+                        return await rt.model.complete(
+                            CompleteOptions(
+                                messages=req.messages,
+                                tools=req.tools,
+                                response_format=req.response_format,
+                                on_token=attempt_on_token,
+                                on_thinking=attempt_on_thinking,
+                            )
                         )
-                    )
+                    except BaseException:
+                        failed["v"] = True
+                        del pending[start:]
+                        raise
 
                 request = ModelRequest(
                     messages=messages,
@@ -652,18 +686,61 @@ class Agent:
                 )
                 if mw:
                     request = await run_before_model(mw, request, ctx)
-                    completion = await compose_model_call(mw, _call_model, ctx)(request)
+                call = compose_model_call(mw, _call_model, ctx) if mw else _call_model
+
+                async def _call_and_close(req: ModelRequest) -> Any:
+                    # Live path: the None sentinel must arrive AFTER every
+                    # delta the attempt pushed — push it when the call settles
+                    # (success or failure).
+                    try:
+                        return await call(req)
+                    finally:
+                        channel.put_nowait(None)
+
+                try:
+                    if needs_batching:
+                        completion = await call(request)
+                        # A before_model hook may have REPLACED the message list for
+                        # this call: replacements feed the model call only; history is
+                        # preserved (TS parity). The loop's `messages` list stays
+                        # authoritative for appends and the end-of-run save — adopting
+                        # a shortened replacement here once destroyed long-term memory.
+                        for event in pending:
+                            if event.get("delta"):
+                                yield event
+                    else:
+                        # LIVE: drain the queue concurrently with the running
+                        # model call, yielding deltas as they arrive. If the
+                        # run is torn down mid-call (abort/disconnect, the
+                        # consumer walking away), the in-flight provider task
+                        # is cancelled with it — deltas it would push are
+                        # discarded by design.
+                        task = asyncio.ensure_future(_call_and_close(request))
+                        try:
+                            while True:
+                                event = await channel.get()
+                                if event is None:
+                                    break
+                                deltas_emitted = True
+                                if event.get("delta"):
+                                    yield event
+                            completion = await task
+                        finally:
+                            if not task.done():
+                                task.cancel()
+                except Exception as err:
+                    # Belt-and-braces for the batched path: nothing buffered
+                    # from failed attempts may ever flush. A LIVE-path failure
+                    # after deltas were delivered must not be retried (a retry
+                    # would duplicate streamed text) — our providers stamp
+                    # that (delivered-verdict); foreign providers without any
+                    # verdict get it stamped here.
+                    del pending[:]
+                    if deltas_emitted and get_retryable(err) is None:
+                        stamp_retryable(err, False)
+                    raise
+                if mw:
                     completion = await run_after_model(mw, completion, request, ctx)
-                else:
-                    completion = await _call_model(request)
-                # A before_model hook may have REPLACED the message list for
-                # this call: replacements feed the model call only; history is
-                # preserved (TS parity). The loop's `messages` list stays
-                # authoritative for appends and the end-of-run save — adopting
-                # a shortened replacement here once destroyed long-term memory.
-                for event in pending:
-                    if event.get("delta"):
-                        yield event
 
                 usage = usage + completion.usage
                 self._check_budgets(rt.budgets, usage, started, rt.model.id)

{framework_agents-0.1.1 → framework_agents-0.2.0}/src/framework_agents/models/anthropic.py

@@ -237,70 +237,94 @@ class AnthropicProvider:
         json_input = ""
         buffer = ""
         event = ""
-        async for chunk in res.aiter_text():
-            buffer += chunk
-            lines = buffer.split("\n")
-            buffer = lines.pop()
-            for line in lines:
-                stripped = line.strip()
-                if not stripped:
-                    continue
-                if stripped.startswith("event:"):
-                    # CRITICAL: the event name must carry across chunk
-                    # boundaries — re-initializing per chunk silently drops
-                    # every delta whose event line landed in a prior packet.
-                    event = stripped[6:].strip()
-                    continue
-                if not stripped.startswith("data:"):
-                    continue
-                payload = stripped[5:].strip()
-                if not payload:
-                    continue
-                try:
-                    data = json.loads(payload)
-                except ValueError:
-                    continue
-                if event == "message_start":
-                    # message_start carries the input-side usage up front.
-                    message = data.get("message") or {}
-                    usage = message.get("usage") or {}
-                    if usage.get("input_tokens") is not None:
-                        input_tokens = usage["input_tokens"]
-                elif event == "message_delta":
-                    # message_delta.usage.output_tokens is cumulative — assign.
-                    usage = data.get("usage") or {}
-                    if usage.get("output_tokens") is not None:
-                        output_tokens = usage["output_tokens"]
-                    delta = data.get("delta") or {}
-                    if delta.get("stop_reason"):
-                        stop_reason = _normalize_stop(delta["stop_reason"])
-                elif event == "content_block_start":
-                    block = data.get("content_block") or {}
-                    current = {"type": block.get("type"), "id": block.get("id"), "name": block.get("name")}
-                    json_input = ""
-                elif event == "content_block_delta":
-                    delta = data.get("delta") or {}
-                    if delta.get("text"):
-                        text += delta["text"]
-                        current = current or {"type": "text"}
-                        current["text"] = (current.get("text") or "") + delta["text"]
-                        options.on_token and options.on_token(delta["text"])
-                    elif delta.get("thinking"):
-                        thinking += delta["thinking"]
-                        current = current or {"type": "thinking"}
-                        current["thinking"] = (current.get("thinking") or "") + delta["thinking"]
-                        options.on_thinking and options.on_thinking(delta["thinking"])
-                    elif delta.get("partial_json"):
-                        json_input += delta["partial_json"]
-                elif event == "content_block_stop":
-                    if current is not None:
-                        if current.get("type") == "tool_use":
-                            try:
-                                current["input"] = json.loads(json_input or "{}")
-                            except ValueError:
-                                current["input"] = {}
-                        blocks.append(current)
-                        current = None
+        # Retry-verdict rule: once a delta (text/thinking/tool fragment)
+        # reached the caller, a mid-stream failure is NON-retryable (re-running
+        # would duplicate already-streamed text); before any delta, failures
+        # stay retryable (nothing was delivered).
+        delivered = False
+        try:
+            async for chunk in res.aiter_text():
+                buffer += chunk
+                lines = buffer.split("\n")
+                buffer = lines.pop()
+                for line in lines:
+                    stripped = line.strip()
+                    if not stripped:
+                        continue
+                    if stripped.startswith("event:"):
+                        # CRITICAL: the event name must carry across chunk
+                        # boundaries — re-initializing per chunk silently drops
+                        # every delta whose event line landed in a prior packet.
+                        event = stripped[6:].strip()
+                        continue
+                    if not stripped.startswith("data:"):
+                        continue
+                    payload = stripped[5:].strip()
+                    if not payload:
+                        continue
+                    try:
+                        data = json.loads(payload)
+                    except ValueError:
+                        continue
+                    if event == "message_start":
+                        # message_start carries the input-side usage up front.
+                        message = data.get("message") or {}
+                        usage = message.get("usage") or {}
+                        if usage.get("input_tokens") is not None:
+                            input_tokens = usage["input_tokens"]
+                    elif event == "message_delta":
+                        # message_delta.usage.output_tokens is cumulative — assign.
+                        usage = data.get("usage") or {}
+                        if usage.get("output_tokens") is not None:
+                            output_tokens = usage["output_tokens"]
+                        delta = data.get("delta") or {}
+                        if delta.get("stop_reason"):
+                            stop_reason = _normalize_stop(delta["stop_reason"])
+                    elif event == "content_block_start":
+                        block = data.get("content_block") or {}
+                        current = {"type": block.get("type"), "id": block.get("id"), "name": block.get("name")}
+                        json_input = ""
+                    elif event == "content_block_delta":
+                        delta = data.get("delta") or {}
+                        if delta.get("text"):
+                            text += delta["text"]
+                            delivered = True
+                            current = current or {"type": "text"}
+                            current["text"] = (current.get("text") or "") + delta["text"]
+                            options.on_token and options.on_token(delta["text"])
+                        elif delta.get("thinking"):
+                            thinking += delta["thinking"]
+                            # Thinking deltas reach the caller like text deltas
+                            # do — the delivered verdict covers them (and the
+                            # tool fragment below).
+                            delivered = True
+                            current = current or {"type": "thinking"}
+                            current["thinking"] = (current.get("thinking") or "") + delta["thinking"]
+                            options.on_thinking and options.on_thinking(delta["thinking"])
+                        elif delta.get("partial_json"):
+                            # Tool-call fragments are delivered state too: a
+                            # retry would re-issue a call mid-assembly, so the
+                            # attempt counts as spent.
+                            delivered = True
+                            json_input += delta["partial_json"]
+                    elif event == "content_block_stop":
+                        if current is not None:
+                            if current.get("type") == "tool_use":
+                                try:
+                                    current["input"] = json.loads(json_input or "{}")
+                                except ValueError:
+                                    current["input"] = {}
+                            blocks.append(current)
+                            current = None
+        except Exception as err:
+            # Delivered-aware verdict: deltas already streamed => non-retryable
+            # (a retry would duplicate the delivered text); before any delta
+            # the failure stays retryable.
+            raise AgentError(
+                "MODEL_ERROR",
+                f"Stream broke mid-response{' (deltas already delivered)' if delivered else ''}: {err}",
+                retryable=not delivered,
+            ) from err
         if current is not None:
             blocks.append(current)
 

{framework_agents-0.1.1 → framework_agents-0.2.0}/src/framework_agents/models/openai_compatible.py

@@ -260,6 +260,12 @@ class OpenAICompatibleProvider:
         finish_reason: str | None = None
         tool_buffers: dict[int, dict[str, str]] = {}
 
+        # Retry-verdict rule: once a delta (content/thinking/tool fragment)
+        # reached the caller, a mid-stream failure is NON-retryable (re-running
+        # would duplicate already-streamed text); before any delta, failures
+        # stay retryable (nothing was delivered).
+        delivered = False
+
         # A line can SPLIT across TCP reads: the first fragment would fail
         # json.loads and the continuation would not start with "data:" — both
         # silently dropped. Accumulate a buffer and only parse COMPLETE
@@ -307,12 +313,21 @@ class OpenAICompatibleProvider:
                     think = _thinking_of(delta)
                     if think:
                         thinking += think
+                        # Thinking deltas reach the caller like token deltas
+                        # do — the delivered verdict covers them (and tool
+                        # fragments below).
+                        delivered = True
                         options.on_thinking and options.on_thinking(think)
                     if delta.get("content"):
                         text += delta["content"]
+                        delivered = True
                         options.on_token and options.on_token(delta["content"])
                     for i, tc in enumerate(delta.get("tool_calls") or []):
                         key = tc.get("index", i)
+                        # Tool-call fragments are delivered state too: a retry
+                        # would re-issue a call mid-assembly, so treat the
+                        # attempt as spent.
+                        delivered = True
                         slot = tool_buffers.setdefault(key, {"id": "", "name": "", "args": ""})
                         if tc.get("id"):
                             slot["id"] = tc["id"]
@@ -321,6 +336,20 @@ class OpenAICompatibleProvider:
                             slot["name"] = fn["name"]
                         if fn.get("arguments"):
                             slot["args"] += fn["arguments"]
+        except Exception as err:
+            # The run's own signal fired mid-request (abort): report ABORTED,
+            # never a stream error.
+            probe = getattr(options.signal, "is_set", None)
+            if callable(probe) and probe():
+                raise AgentError("ABORTED", "Run aborted", retryable=False) from err
+            # Delivered-aware verdict: deltas already streamed => non-retryable
+            # (a retry would duplicate the delivered text); before any delta
+            # the failure stays retryable.
+            raise AgentError(
+                "MODEL_ERROR",
+                f"Stream broke mid-response{' (deltas already delivered)' if delivered else ''}: {err}",
+                retryable=not delivered,
+            ) from err
         finally:
             if watchdog is not None:
                 watchdog.cancel()

{framework_agents-0.1.1 → framework_agents-0.2.0}/tests/test_gaps.py

@@ -37,6 +37,8 @@ from framework_agents import (  # noqa: E402
     assert_can_handle,
     collect_stream,
     define_tool,
+    get_retryable,
+    model_retry,
     ollama,
     supports_vision,
 )
@@ -775,3 +777,167 @@ def test_stream_sync_iteration_script_and_running_loop():
 
     kinds2 = asyncio.run(notebook_cell())
     assert "done" in kinds2
+
+
+# ---------------------------------------------------------------------------
+# Live delta streaming (Path B, TS parity): deltas stream LIVE during the
+# model call when no middleware declares wrap_model/after_model; batched
+# fallback otherwise. Deltas from FAILED attempts never leak into the stream
+# (delivered-verdict contract: our providers stamp post-delta failures
+# non-retryable so retries never duplicate streamed text).
+# ---------------------------------------------------------------------------
+
+
+class _ScriptedStreamProvider:
+    """Runs a scripted behavior per attempt; records how many attempts ran."""
+
+    id = "scripted-stream"
+    capabilities = {"structured_output": False, "streaming": True}
+
+    def __init__(self, *behaviors: Any) -> None:
+        self._behaviors = list(behaviors)
+        self.calls = 0
+
+    async def complete(self, options: CompleteOptions) -> ModelCompletion:
+        self.calls += 1
+        behavior = self._behaviors[min(self.calls - 1, len(self._behaviors) - 1)]
+        outcome = behavior(options)
+        if asyncio.iscoroutine(outcome):
+            return await outcome
+        return outcome
+
+
+def _clean_completion(options: CompleteOptions, text: str) -> ModelCompletion:
+    options.on_token(text)
+    return ModelCompletion(
+        text=text,
+        tool_calls=[],
+        usage=TokenUsage(input_tokens=1, output_tokens=len(text)),
+    )
+
+
+async def _drain(agent) -> tuple[list[str], str | None, Any]:
+    tokens: list[str] = []
+    done_text: str | None = None
+    error: Any = None
+    try:
+        async for event in agent.stream("q"):
+            if event["type"] == "token":
+                tokens.append(event["delta"])
+            elif event["type"] == "done":
+                done_text = event.get("text")
+    except BaseException as err:  # noqa: BLE001 - the contract under test
+        error = err
+    return tokens, done_text, error
+
+
+@pytest.mark.asyncio
+async def test_first_delta_yields_while_provider_call_is_in_flight():
+    finished = [False]
+
+    def early(options: CompleteOptions) -> Any:
+        options.on_token("early")
+        return _late(options)
+
+    async def _late(options: CompleteOptions) -> ModelCompletion:
+        await asyncio.sleep(0.05)
+        options.on_token("-late")
+        finished[0] = True
+        return ModelCompletion(
+            text="early-late",
+            tool_calls=[],
+            usage=TokenUsage(input_tokens=1, output_tokens=3),
+        )
+
+    provider = _ScriptedStreamProvider(early)  # live path: no middleware
+    agent = Agent(AgentOptions(model=provider))
+    seen: list[tuple[str, bool]] = []
+    done_text: str | None = None
+    async for event in agent.stream("q"):
+        if event["type"] == "token":
+            # The flag is read AT yield time: "early" must arrive while the
+            # provider call is still running (its await has not resolved).
+            seen.append((event["delta"], finished[0]))
+        elif event["type"] == "done":
+            done_text = event.get("text")
+    assert seen == [("early", False), ("-late", True)]
+    assert done_text == "early-late"
+
+
+@pytest.mark.asyncio
+async def test_post_delta_failure_never_leaks_and_is_not_retried():
+    def attempt1(options: CompleteOptions) -> Any:
+        options.on_token("poison")
+        raise AgentError("MODEL_ERROR", "stream broke after deltas", retryable=False)
+
+    provider = _ScriptedStreamProvider(
+        attempt1,
+        lambda options: _clean_completion(options, "clean"),
+    )
+    agent = Agent(
+        AgentOptions(model=provider, middleware=[model_retry(max_retries=2, initial_delay_ms=0, jitter=False)])
+    )
+    tokens, _, error = await _drain(agent)
+    # The delivered-verdict stamps post-delta failures non-retryable: NO
+    # retry (a retry would duplicate the delivered text), nothing leaks.
+    assert isinstance(error, AgentError)
+    assert error.retryable is False
+    assert tokens == []
+    assert provider.calls == 1
+
+
+@pytest.mark.asyncio
+async def test_pre_delta_failure_is_retried_and_second_attempt_streams_cleanly():
+    def attempt1(options: CompleteOptions) -> Any:
+        # BEFORE any on_token: nothing was delivered, so a retry is safe.
+        raise AgentError("MODEL_ERROR", "connection refused", retryable=True)
+
+    provider = _ScriptedStreamProvider(
+        attempt1,
+        lambda options: _clean_completion(options, "clean"),
+    )
+    agent = Agent(
+        AgentOptions(model=provider, middleware=[model_retry(max_retries=2, initial_delay_ms=0, jitter=False)])
+    )
+    tokens, done_text, error = await _drain(agent)
+    assert error is None
+    assert tokens == ["clean"]
+    assert done_text == "clean"
+    assert provider.calls == 2
+
+
+@pytest.mark.asyncio
+async def test_batched_deltas_of_failed_attempt_roll_back_even_when_retryable():
+    def attempt1(options: CompleteOptions) -> Any:
+        options.on_token("poison")
+        raise AgentError("MODEL_ERROR", "mid-stream reset", retryable=True)
+
+    provider = _ScriptedStreamProvider(
+        attempt1,
+        lambda options: _clean_completion(options, "clean"),
+    )
+    agent = Agent(
+        AgentOptions(model=provider, middleware=[model_retry(max_retries=2, initial_delay_ms=0, jitter=False)])
+    )
+    tokens, done_text, error = await _drain(agent)
+    assert error is None
+    # The failed attempt's buffered delta never flushes; the retried call's
+    # output replaces it.
+    assert tokens == ["clean"]
+    assert done_text == "clean"
+    assert provider.calls == 2
+
+
+@pytest.mark.asyncio
+async def test_live_path_failure_after_deltas_gets_stamped_non_retryable():
+    def attempt1(options: CompleteOptions) -> Any:
+        options.on_token("part")
+        raise ValueError("socket exploded")  # foreign provider: no verdict
+
+    provider = _ScriptedStreamProvider(attempt1)  # live path: no middleware
+    agent = Agent(AgentOptions(model=provider))
+    tokens, _, error = await _drain(agent)
+    # Deltas were already delivered live (by design — they cannot be
+    # unsent); the loop stamps the verdictless error non-retryable.
+    assert tokens == ["part"]
+    assert get_retryable(error) is False