framework-agents 0.1.0__tar.gz

framework_agents-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# deps
+node_modules/
+.pnpm-store/
+.turbo/
+
+# build output
+dist/
+build/
+*.tsbuildinfo
+
+# test / coverage
+coverage/
+.nyc_output/
+
+# env
+.env
+.env.*
+!.env.example
+
+# OS / editor
+.DS_Store
+*.log
+.vscode/*
+!.vscode/extensions.json
+.idea/
+
+# python (future package)
+__pycache__/
+*.pyc
+.venv/
+.uv/
+
+# docs build
+site/
+.venv-docs/
+
+# python package build
+packages/python/dist/
+packages/python/build/
+*.egg-info/
+uv.lock
+
+# npm tarballs
+*.tgz
+
+# doc scripts / temp
+claude.md

framework_agents-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: framework-agents
+Version: 0.1.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/
+Project-URL: Repository, https://github.com/fab679/framework
+Project-URL: Changelog, https://github.com/fab679/framework/releases
+Author: Framework Agents
+License: MIT
+Keywords: a2a,agents,ai,asyncio,llm,mcp,semantic-web,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Python package — TS parity port (`framework_agents`)
+
+The TypeScript package (`packages/typescript`) is the reference implementation.
+This port targets API parity with the **fixed** TS semantics — every behavior
+that was a real bug during the TS line (and is regression-pinned there) is
+encoded here from day one:
+
+| Pinned semantic | Why |
+|---|---|
+| `reasoning_tokens` is a SUBSET of `output_tokens` | never double-billed in budgets/cost |
+| `cost_usd` only when a price is known | unknown models → `None`, never a fake $0 |
+| `save()` APPENDS; the loop does clear-then-save | history never duplicates across runs |
+| Structured `'auto'` resolves by capability | unresolved auto never throws STRUCTURED_NO_MATCH |
+| `finish_reason=length` + zero content → loud `MODEL_ERROR` | a thinking model burning its whole budget is not a silent empty answer |
+| Tool parameter schemas ride the wire | models see real argument shapes |
+| HITL decisions: exact key THEN bare tool name | resume converges even when models regenerate arg text |
+| Local `ollama:` pricing wins over name collisions | never bill cloud prices for free local models |
+| Storage keys/threadIds reject traversal (`..`) | no writes outside the root |
+| Remote SPARQL: descriptive UA + 429/5xx retry honoring Retry-After | public endpoints reject and rate-limit otherwise |
+
+No personal or brand names appear anywhere in this package.
+
+## Port status (mirroring the TS module map)
+
+| TS module | Python | State |
+|---|---|---|
+| types (messages/blocks/usage) | `types.py` | ✅ |
+| errors + retryable verdicts | `errors.py` | ✅ |
+| tools (define_tool/registry/schemas) | `tools.py` | ✅ |
+| memory (+compaction) | `memory.py`, `memory_compaction.py` | ✅ (MEMORY_CORRUPT loud, atomic unique-tmp writes) |
+| conversation managers | `conversation.py` | ✅ (order-preserving pin; model or fn summarizer) |
+| sessions + snapshots | `sessions.py` | ✅ (validated keys, TS-tested preset semantics) |
+| checkpoint + file locks | `checkpoint.py` | ✅ (O_EXCL + stale reclaim, threadId validation) |
+| runtime (abort/timeout) | `runtime.py` | ✅ |
+| models (mock + OpenAI-compatible + Anthropic + Ollama) | `models/` | ✅ (Together+OpenAI field unions, native Anthropic Messages API w/ thinking budgets + SSE machine, vision capability fail-fast, stream usage, truncation guard) |
+| state (AgentState + invocation) | `state.py`, `agent.py` | ✅ (validated JSON KV, custom-prototype rejection, snapshots/session restore, pause/resume, edit/branch/timelines, v1 reasoning blocks, `with_tools`) |
+| pricing | `pricing.py` | ✅ |
+| config + factory | `config.py` | ✅ (together/openai/ollama/custom) |
+| agent loop (budgets/structured/streaming) | `agent.py` | ✅ (calls stream via drain; budget price refusal; synthesized final answer) |
+| middleware (hooks, HITL, retries, limits, policy, todos, pii) | `middleware.py` | ✅ |
+| orchestration | `orchestration.py` | ✅ (sequential/parallel/router; routed result semantics) |
+| workflows | `workflows.py` | ✅ (dedup'd indegree, retries, propagation) |
+| swarm | `swarm.py` | ✅ (handoff tool + stream events + loop detection default) |
+| evals | `evals.py` | ✅ (JSONL + pass-rate reporter) |
+| skills + TF-IDF routing | `skills.py` | ✅ ($mention word-boundary wins) |
+| prompts (+A/B) | `prompts.py` | ✅ (CRLF/BOM tolerance) |
+| rag (tf-idf retriever + tool) | `rag.py` | ✅ |
+| semantic (store/SHACL/rules/graph memory/linking/JSON-LD/evolution) | `semantic.py`, `ontology_review.py` | ✅ (version graphs under `urn:framework:ontology:*`) |
+| remote SPARQL | `remote_sparql.py` | ✅ (UA + Retry-After retry) |
+| A2A clients (SSE + JSON-RPC) | `a2a_client.py` | ✅ (envelope + contextId chain + retry) |
+| A2A server (contexts/LRU/disconnect/SSE) | `a2a_server.py` | ✅ (stdio-of-asyncio raw HTTP, body caps, CORS) |
+| MCP clients + bridging | `mcp_client.py` | ✅ (stdio child lifecycle, no-id notification, per-tool degrade) |
+| observability + tracing sinks | `observability.py`, `tracing.py` | ✅ |
+| sandbox (JS + shell) | `sandbox.py` | ✅ (caveat: exec timeouts abandon a thread, no hard kill) |
+| serve (framework.json + CLI) | `serve.py` | ✅ (lazy model init, argparse CLI, per-context isolated agents) |
+| React SDK | — | n/a (React-specific; browser clients use A2A/SSE) |
+
+**Batch-2 middleware** (`model_fallback`, `summarization`, `context_editing` +
+`ClearToolUsesEdit`, `llm_tool_selector`, `tool_emulator`, `filesystem`,
+`create_sub_agent`, `pii` tool-results) is ported with deviations pinned in
+`middleware.py`'s docstring (feedback-strings instead of raises on escape
+misses; `older_than_steps` interpreted as a step gate).
+
+## Running
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest tests -q                 # offline parity suite (233 tests)
+E2E_MODEL=1 .venv/bin/python -m pytest tests -q -m live
+# live Together parity runs; OpenAI + Anthropic suites skip cleanly and go
+# live as soon as OPENAI_API_KEY / ANTHROPIC_API_KEY appear in framework/.env
+```
+
+## Known deviations (documented in module docstrings)
+
+- `Agent.stream()` yields a `done` event and stores the result (generators
+  can't return values); run() drains — wire contracts identical.
+- Async file IO runs via `asyncio.to_thread` in filesystem tools; storage
+  classes use blocking IO inside async methods (single-process locality).
+- Sandbox JS cannot hard-interrupt a thread mid-statement (node:vm can) —
+  the timeout surfaces per contract, the abandoned thread dies at exit.
+- Semantic version graphs use `urn:framework:ontology:<version>` (the TS
+  default `urn:fabisch:*` embeds a personal name; both are configurable).
+- Cross-language conformance: the Python A2A client speaks the exact wire
+  contract of the TS A2A server (envelope, SSE frames, [DONE]) and vice
+  versa — see `tests/test_servers_and_clients.py`.

framework_agents-0.1.0/README.md

@@ -0,0 +1,87 @@
+# Python package — TS parity port (`framework_agents`)
+
+The TypeScript package (`packages/typescript`) is the reference implementation.
+This port targets API parity with the **fixed** TS semantics — every behavior
+that was a real bug during the TS line (and is regression-pinned there) is
+encoded here from day one:
+
+| Pinned semantic | Why |
+|---|---|
+| `reasoning_tokens` is a SUBSET of `output_tokens` | never double-billed in budgets/cost |
+| `cost_usd` only when a price is known | unknown models → `None`, never a fake $0 |
+| `save()` APPENDS; the loop does clear-then-save | history never duplicates across runs |
+| Structured `'auto'` resolves by capability | unresolved auto never throws STRUCTURED_NO_MATCH |
+| `finish_reason=length` + zero content → loud `MODEL_ERROR` | a thinking model burning its whole budget is not a silent empty answer |
+| Tool parameter schemas ride the wire | models see real argument shapes |
+| HITL decisions: exact key THEN bare tool name | resume converges even when models regenerate arg text |
+| Local `ollama:` pricing wins over name collisions | never bill cloud prices for free local models |
+| Storage keys/threadIds reject traversal (`..`) | no writes outside the root |
+| Remote SPARQL: descriptive UA + 429/5xx retry honoring Retry-After | public endpoints reject and rate-limit otherwise |
+
+No personal or brand names appear anywhere in this package.
+
+## Port status (mirroring the TS module map)
+
+| TS module | Python | State |
+|---|---|---|
+| types (messages/blocks/usage) | `types.py` | ✅ |
+| errors + retryable verdicts | `errors.py` | ✅ |
+| tools (define_tool/registry/schemas) | `tools.py` | ✅ |
+| memory (+compaction) | `memory.py`, `memory_compaction.py` | ✅ (MEMORY_CORRUPT loud, atomic unique-tmp writes) |
+| conversation managers | `conversation.py` | ✅ (order-preserving pin; model or fn summarizer) |
+| sessions + snapshots | `sessions.py` | ✅ (validated keys, TS-tested preset semantics) |
+| checkpoint + file locks | `checkpoint.py` | ✅ (O_EXCL + stale reclaim, threadId validation) |
+| runtime (abort/timeout) | `runtime.py` | ✅ |
+| models (mock + OpenAI-compatible + Anthropic + Ollama) | `models/` | ✅ (Together+OpenAI field unions, native Anthropic Messages API w/ thinking budgets + SSE machine, vision capability fail-fast, stream usage, truncation guard) |
+| state (AgentState + invocation) | `state.py`, `agent.py` | ✅ (validated JSON KV, custom-prototype rejection, snapshots/session restore, pause/resume, edit/branch/timelines, v1 reasoning blocks, `with_tools`) |
+| pricing | `pricing.py` | ✅ |
+| config + factory | `config.py` | ✅ (together/openai/ollama/custom) |
+| agent loop (budgets/structured/streaming) | `agent.py` | ✅ (calls stream via drain; budget price refusal; synthesized final answer) |
+| middleware (hooks, HITL, retries, limits, policy, todos, pii) | `middleware.py` | ✅ |
+| orchestration | `orchestration.py` | ✅ (sequential/parallel/router; routed result semantics) |
+| workflows | `workflows.py` | ✅ (dedup'd indegree, retries, propagation) |
+| swarm | `swarm.py` | ✅ (handoff tool + stream events + loop detection default) |
+| evals | `evals.py` | ✅ (JSONL + pass-rate reporter) |
+| skills + TF-IDF routing | `skills.py` | ✅ ($mention word-boundary wins) |
+| prompts (+A/B) | `prompts.py` | ✅ (CRLF/BOM tolerance) |
+| rag (tf-idf retriever + tool) | `rag.py` | ✅ |
+| semantic (store/SHACL/rules/graph memory/linking/JSON-LD/evolution) | `semantic.py`, `ontology_review.py` | ✅ (version graphs under `urn:framework:ontology:*`) |
+| remote SPARQL | `remote_sparql.py` | ✅ (UA + Retry-After retry) |
+| A2A clients (SSE + JSON-RPC) | `a2a_client.py` | ✅ (envelope + contextId chain + retry) |
+| A2A server (contexts/LRU/disconnect/SSE) | `a2a_server.py` | ✅ (stdio-of-asyncio raw HTTP, body caps, CORS) |
+| MCP clients + bridging | `mcp_client.py` | ✅ (stdio child lifecycle, no-id notification, per-tool degrade) |
+| observability + tracing sinks | `observability.py`, `tracing.py` | ✅ |
+| sandbox (JS + shell) | `sandbox.py` | ✅ (caveat: exec timeouts abandon a thread, no hard kill) |
+| serve (framework.json + CLI) | `serve.py` | ✅ (lazy model init, argparse CLI, per-context isolated agents) |
+| React SDK | — | n/a (React-specific; browser clients use A2A/SSE) |
+
+**Batch-2 middleware** (`model_fallback`, `summarization`, `context_editing` +
+`ClearToolUsesEdit`, `llm_tool_selector`, `tool_emulator`, `filesystem`,
+`create_sub_agent`, `pii` tool-results) is ported with deviations pinned in
+`middleware.py`'s docstring (feedback-strings instead of raises on escape
+misses; `older_than_steps` interpreted as a step gate).
+
+## Running
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest tests -q                 # offline parity suite (233 tests)
+E2E_MODEL=1 .venv/bin/python -m pytest tests -q -m live
+# live Together parity runs; OpenAI + Anthropic suites skip cleanly and go
+# live as soon as OPENAI_API_KEY / ANTHROPIC_API_KEY appear in framework/.env
+```
+
+## Known deviations (documented in module docstrings)
+
+- `Agent.stream()` yields a `done` event and stores the result (generators
+  can't return values); run() drains — wire contracts identical.
+- Async file IO runs via `asyncio.to_thread` in filesystem tools; storage
+  classes use blocking IO inside async methods (single-process locality).
+- Sandbox JS cannot hard-interrupt a thread mid-statement (node:vm can) —
+  the timeout surfaces per contract, the abandoned thread dies at exit.
+- Semantic version graphs use `urn:framework:ontology:<version>` (the TS
+  default `urn:fabisch:*` embeds a personal name; both are configurable).
+- Cross-language conformance: the Python A2A client speaks the exact wire
+  contract of the TS A2A server (envelope, SSE frames, [DONE]) and vice
+  versa — see `tests/test_servers_and_clients.py`.

framework_agents-0.1.0/examples/01-streaming-tools.py

@@ -0,0 +1,49 @@
+"""LIVE: streaming — real token/thinking deltas through Agent.stream(), and
+tool calls streamed live (tool_call event before execution, tool_result when
+it lands)."""
+
+import asyncio
+
+from pydantic import BaseModel
+
+from framework_agents import Agent, AgentOptions, define_tool, load_config
+from framework_agents.config import init_chat_model
+from framework_agents.middleware import model_retry
+
+
+class Count(BaseModel):
+    count: int
+
+
+async def main() -> None:
+    cfg = load_config()
+    model = init_chat_model(f"together:{cfg.together_model}", max_tokens=2500)
+
+    async def digits(args: Count, ctx) -> str:
+        await asyncio.sleep(0.7)  # the 700ms proves tool_result lands mid-run
+        return "3.14159"
+
+    agent = Agent(AgentOptions(
+        model=model,
+        max_steps=4,
+        middleware=[model_retry(max_retries=3, initial_delay_ms=500)],
+        tools=[define_tool(name="get_pi_digits", description="Returns digits of pi.", schema=Count, execute=digits)],
+    ))
+
+    kinds: dict[str, int] = {}
+    text = ""
+    async for event in agent.stream("Use the get_pi_digits tool with count 5, then reply with exactly the digits it returned."):
+        kinds[event["type"]] = kinds.get(event["type"], 0) + 1
+        if event["type"] in ("token", "thinking"):
+            pass  # deltas stream live through hooks; batched per call here
+        if event["type"] == "done":
+            text = event["text"]
+    print("EVENT KINDS:", kinds)
+    print("TEXT:", text.strip())
+    assert agent._last_result is not None
+    print("USAGE:", agent._last_result.usage)
+    ok = kinds.get("tool_call") and kinds.get("tool_result") and "3.14159" in text
+    print("PASS: tools streamed live" if ok else "NOTE: inspect trace (model variance)")
+
+
+asyncio.run(main())

framework_agents-0.1.0/examples/02-orchestration.py

@@ -0,0 +1,27 @@
+"""LIVE: orchestration — sequential chain, parallel fan-out, model router."""
+import asyncio
+from framework_agents import Agent, AgentOptions, load_config
+from framework_agents.orchestration import OrchestrationPlan, run_orchestrated
+
+cfg = load_config()
+model = lambda: __import__("framework_agents").init_chat_model(f"together:{cfg.together_model}", max_tokens=8000)
+
+async def main():
+    retry = [__import__("framework_agents.middleware", fromlist=["model_retry"]).model_retry(max_retries=3, initial_delay_ms=500)]
+    mk = lambda name, sys, desc="": Agent(AgentOptions(model=model(), name=name, description=desc, system_prompt=sys, middleware=retry, max_steps=2))
+    seq = await run_orchestrated(OrchestrationPlan(strategy="sequential", agents=[
+        mk("math", "Answer with just the number."), mk("halver", "Answer with just half of the number you are given."),
+    ]), "What is 100 + 24?")
+    print("SEQUENTIAL:", seq.text.strip(), "(expect 62)")
+    par = await run_orchestrated(OrchestrationPlan(strategy="parallel", concurrency=2, agents=[
+        mk("a", 'Reply with exactly: AAA'), mk("b", 'Reply with exactly: BBB'), mk("c", 'Reply with exactly: CCC'),
+    ]), "Respond as instructed.")
+    print("PARALLEL:", [r.text.strip() for r in par.results])
+    router = await run_orchestrated(OrchestrationPlan(strategy="router", agents=[
+        mk("poet", "Reply with a one-line poem.", "writes poetry"),
+        mk("calculator", "Answer with just the number.", "does arithmetic"),
+    ]), "What is 12 times 12?")
+    print("ROUTER:", router.routed_to, router.results[0].text.strip(), "(expect 1 / 144)")
+    print("PASS" if "62" in seq.text and router.routed_to == 1 and "144" in router.results[0].text else "NOTE: model variance")
+
+asyncio.run(main())

framework_agents-0.1.0/examples/03-swarm.py

@@ -0,0 +1,25 @@
+"""LIVE: swarm — autonomous handoffs between live members."""
+import asyncio
+from framework_agents import Agent, AgentOptions, load_config
+from framework_agents import Swarm
+
+cfg = load_config()
+model = lambda: __import__("framework_agents").init_chat_model(f"together:{cfg.together_model}", max_tokens=3000)
+
+async def main():
+    from framework_agents.middleware import model_retry
+    retry = [model_retry(max_retries=3, initial_delay_ms=500)]
+    researcher = Agent(AgentOptions(model=model(), name="researcher", description="Gathers key facts",
+        system_prompt="Produce ONE short fact, then call handoff_to_agent to the writer carrying it. Never answer the user directly.", middleware=retry))
+    writer = Agent(AgentOptions(model=model(), name="writer", description="Writes the final answer",
+        system_prompt="Write the final answer in one sentence from the handoff message. Do not call handoff_to_agent.",))
+    swarm = Swarm(agents=[researcher, writer], entry_point="researcher", max_handoffs=2, max_iterations=3, loop_detection_window=4)
+    events = []
+    async for e in swarm.stream("State the boiling point of water in one sentence."):
+        events.append(e.get("type") if e.get("type") != "handoff" else "handoff->" + str(e.get("to")))
+    result = researcher and writer  # noqa - events carry the trace
+    print("EVENTS:", events)
+    ok = any(str(x).startswith("handoff") for x in events)
+    print("PASS: live handoff" if ok else "NOTE: inspect (model variance)")
+
+asyncio.run(main())

framework_agents-0.1.0/examples/04-workflows.py

@@ -0,0 +1,47 @@
+"""LIVE: workflow DAG — levels, dedup'd deps, real node retry."""
+
+import asyncio
+
+from framework_agents import Agent, AgentOptions, load_config, init_chat_model
+from framework_agents.middleware import model_retry
+from framework_agents.workflows import WorkflowNode, run_workflow
+
+cfg = load_config()
+
+
+async def main():
+    retry = [model_retry(max_retries=3, initial_delay_ms=500)]
+    facts_agent = Agent(AgentOptions(
+        model=init_chat_model(f"together:{cfg.together_model}", max_tokens=2000),
+        system_prompt="Answer with exactly: water boils",
+        middleware=retry, max_steps=2,
+    ))
+    calls = {"flaky": 0}
+
+    async def flaky(ctx, invocation_state=None):
+        calls["flaky"] += 1
+        if calls["flaky"] == 1:
+            raise RuntimeError("transient live failure")
+        return "recovered on retry"
+
+    async def facts(ctx, invocation_state=None):
+        return await facts_agent.run("Say your line.")
+
+    async def summary(ctx, invocation_state=None):
+        return {
+            "heard": getattr(ctx.get("facts"), "text", None),
+            "flaky": ctx.get("flaky"),
+        }
+
+    out = await run_workflow([
+        WorkflowNode(id="facts", run=facts),
+        WorkflowNode(id="flaky", run=flaky, retry={"attempts": 2, "backoff_ms": 100}),
+        WorkflowNode(id="summary", depends_on=["facts", "flaky"], run=summary),
+    ])
+    heard = (getattr(out.get("facts"), "text", "") or "").strip()
+    print("FACTS:", heard, "| FLAKY calls:", calls["flaky"])
+    print("SUMMARY:", {k: (str(v)[:30] if v else v) for k, v in (out.get("summary") or {}).items()})
+    print("PASS: DAG + real retry" if "water" in heard and calls["flaky"] == 2 else "NOTE: inspect")
+
+
+asyncio.run(main())

framework_agents-0.1.0/examples/05-memory-sessions.py

@@ -0,0 +1,32 @@
+"""LIVE: memory + sessions — multi-turn recall + restore across a 'restart'."""
+import asyncio
+import tempfile
+
+from framework_agents import Agent, AgentOptions, FileMemory, InMemoryMemory, LocalFileStorage, SessionManager, load_config, init_chat_model
+from framework_agents.middleware import model_retry
+
+cfg = load_config()
+
+async def main():
+    retry = [model_retry(max_retries=3, initial_delay_ms=500)]
+    model = lambda: init_chat_model(f"together:{cfg.together_model}", max_tokens=2500)
+    with tempfile.TemporaryDirectory() as d:
+        # ALSO the pause/resume question, live: pause between turns, resume continues.
+        from framework_agents import FileCheckpointer
+        agent = Agent(AgentOptions(model=model(), memory=FileMemory(d), middleware=retry))
+        await agent.run("My codename is Falcon. Just reply ok.")
+        paused = await agent.pause("conv-1", FileCheckpointer(d))
+        print("PAUSED:", paused)
+        agent2 = Agent(AgentOptions(model=model(), memory=FileMemory(d), middleware=retry))
+        resumed = await agent2.resume("conv-1", None, FileCheckpointer(d))
+        print("RESUMED (no new input):", resumed.text.strip()[:60])
+        # Real multi-agent "restart": a brand-new instance with a session store.
+        sessions = SessionManager(storage=LocalFileStorage(d + "/sessions"), session_id="demo")
+        a1 = Agent(AgentOptions(model=model(), session_manager=sessions, middleware=retry))
+        await a1.run("Remember: the launch word is ZULU-7. Just reply ok.")
+        a2 = Agent(AgentOptions(model=model(), session_manager=SessionManager(storage=LocalFileStorage(d + "/sessions"), session_id="demo"), middleware=retry))
+        recall = await a2.run("What is the launch word? Reply with just the word.")
+        print("RESTORED RECALL:", recall.text.strip(), "(expect ZULU-7)")
+        print("PASS: memory + pause/resume + session restore" if "zulu" in recall.text.lower() else "NOTE: variance")
+
+asyncio.run(main())

framework_agents-0.1.0/examples/06-hitl-resume.py

@@ -0,0 +1,64 @@
+"""LIVE: human-in-the-loop — suspend on a guarded tool, checkpoint, resume
+with the TOOL-NAME WILDCARD decision (models re-issue args on resume).
+
+NOTE: `except ... as first` DELETES the name at the end of the except block
+(a Python gotcha) — stash it before leaving the block.
+"""
+
+import asyncio
+import tempfile
+
+from pydantic import BaseModel
+
+from framework_agents import Agent, AgentOptions, FileCheckpointer, define_tool, init_chat_model, load_config
+from framework_agents.middleware import HitlInterrupt, human_in_the_loop, model_retry
+
+cfg = load_config()
+
+
+class Publish(BaseModel):
+    title: str
+    word: str
+
+
+async def main():
+    cp = FileCheckpointer(tempfile.mkdtemp())
+    model = lambda: init_chat_model(f"together:{cfg.together_model}", max_tokens=1200)
+
+    async def publish(args: Publish, ctx) -> str:
+        return f'published "{args.title}"'
+
+    def mk():
+        return Agent(AgentOptions(
+            model=model(), max_steps=6, tools=[
+                define_tool(
+                    name="publish",
+                    description="Publishes the report. ALWAYS call this tool before finishing.",
+                    schema=Publish,
+                    execute=publish,
+                ),
+            ],
+            middleware=[model_retry(max_retries=2, initial_delay_ms=300), human_in_the_loop(interrupt_on={"publish": True})],
+        ))
+
+    suspended: dict = {}
+    try:
+        await mk().run('Write a one-sentence report about the word "falcon" and publish it.',
+                       checkpointer=cp, thread_id="t1")
+        print("NOTE: model finished without calling publish — model variance, rerun")
+        return
+    except HitlInterrupt as first:
+        # Stash now: the `as` binding is deleted when the except block ends.
+        suspended = {"tool": first.tool, "args": first.args}
+
+    print("SUSPENDED:", suspended)
+    # Human decision: WILDCARD bare tool name (models regenerate arg text; an
+    # exact-key-only approval would never converge after resume).
+    resumed = await mk().resume("t1", {suspended["tool"]: "approve"}, checkpointer=cp)
+    published = next((c.output for c in resumed.tool_calls if c.name == "publish"), None)
+    print("PUBLISHED:", str(published)[:60])
+    print("RESUMED FINAL:", resumed.text.strip()[:60])
+    print("PASS: suspend -> checkpoint -> wildcard-approve -> resume" if published else "NOTE: inspect")
+
+
+asyncio.run(main())

framework_agents-0.1.0/examples/07-guardrails-budgets.py

@@ -0,0 +1,53 @@
+"""LIVE: guardrails + budgets — PII redaction, policy deny, real cost caps."""
+import asyncio
+
+from pydantic import BaseModel
+
+from framework_agents import Agent, AgentOptions, TokenBudgets, define_tool, AgentError, init_chat_model, load_config
+from framework_agents.middleware import model_retry, pii_redact, policy_filter
+
+cfg = load_config()
+model = lambda: init_chat_model(f"together:{cfg.together_model}", max_tokens=2500)
+
+async def main():
+    pii_agent = Agent(AgentOptions(
+        model=model(),
+        middleware=[model_retry(max_retries=2, initial_delay_ms=300), pii_redact("email", strategy="redact", apply_to_output=True)],
+    ))
+    pii = await pii_agent.run("Reply exactly with: my email is foo.bar@corp.example")
+    print("PII REDACTED:", "foo.bar@corp.example" not in pii.text)
+    print("PII TEXT:", pii.text.strip())
+
+    class NoArgs(BaseModel):
+        pass
+
+    executed = []
+
+    async def rm_exec(a, c):
+        executed.append("rm_rf")
+        return "deleted"
+
+    async def safe_exec(a, c):
+        executed.append("noop")
+        return "did nothing"
+
+    rm_rf = define_tool(name="rm_rf", description="Deletes everything.", schema=NoArgs, execute=rm_exec)
+    safe = define_tool(name="safe", description="Does nothing.", schema=NoArgs, execute=safe_exec)
+    policy = Agent(AgentOptions(model=model(), max_steps=4, tools=[rm_rf, safe],
+        middleware=[model_retry(max_retries=2, initial_delay_ms=300), policy_filter(deny=["rm_"], exit_behavior="continue")]))
+    await policy.run('Call the rm_rf tool; if refused call noop instead, then say "done".')
+    print("POLICY:", "rm_rf never executed" if "rm" not in executed else "FAIL — rm executed!", "| calls:", executed)
+
+    try:
+        await Agent(AgentOptions(model=model(), budgets=TokenBudgets(max_tokens=1))).run("Say anything")
+        print("BUDGET: NOTE - no cap hit")
+    except AgentError as e:
+        print("BUDGET CODE:", e.code, "(cap enforced on real usage)")
+
+    ok_pii = "foo.bar@corp.example" not in pii.text
+    ok_policy = "rm" not in executed
+    print("PASS: guardrails live" if ok_pii and ok_policy else "NOTE: inspect — pii redacted: %s, rm blocked: %s" % (ok_pii, ok_policy))
+
+asyncio.run(main())
+
+asyncio.run(main())

framework_agents-0.1.0/examples/08-semantic-graph.py

@@ -0,0 +1,38 @@
+"""LIVE: semantic graph — a live model commits validated facts, the ontology
+self-reports gaps, SHACL is induced from ITS OWN data and adopted."""
+import asyncio
+
+from framework_agents import Agent, AgentOptions, InMemoryGraphStore, define_tool, init_chat_model, load_config
+from framework_agents.middleware import model_retry
+from framework_agents.semantic import graph_add_tool, claim_check_tool, sparql_select_tool
+from framework_agents.ontology_review import propose_shapes, adopt_shapes, review_ontology, review_ontology_tool, propose_shapes_tool
+
+cfg = load_config()
+
+async def main():
+    store = InMemoryGraphStore()
+    model = lambda: init_chat_model(f"together:{cfg.together_model}", max_tokens=1500)
+    writer = Agent(AgentOptions(
+        model=model(), max_steps=8,
+        middleware=[model_retry(max_retries=2, initial_delay_ms=300)],
+        tools=[graph_add_tool(store), review_ontology_tool(store), propose_shapes_tool(store, min_instances=1)],
+    ))
+    run = await writer.run(
+        'Call graph_add once with these 6 quads (source "user:demo", keep quotes): '
+        "1. ex:GlobalCorp rdf:type ex:Company ; 2. ex:GlobalCorp ex:name \"Global Corp\" ; 3. ex:GlobalCorp ex:headcount 42 ; "
+        "4. ex:Acme rdf:type ex:Company ; 5. ex:Acme ex:name \"Acme\" ; 6. ex:Acme ex:headcount 10 . Reply with just: stored"
+    )
+    print("WRITE:", run.text.strip()[:40])
+    review = await review_ontology(store)
+    undeclared = list(review.undeclared) if review.undeclared else []
+    print("UNDECLARED (what to add next):", [getattr(t, "term", t.get("term") if isinstance(t, dict) else t) for t in undeclared])
+    shapes = await propose_shapes(store, min_instances=1)
+    adoption = await adopt_shapes(store, shapes)
+    print("SHACL INDUCED:", bool(shapes), "| adopted:", len(adoption.adopted), "rejected:", len(adoption.rejected))
+    reader = Agent(AgentOptions(model=model(), max_steps=4, tools=[claim_check_tool(store), sparql_select_tool(store)]))
+    answer = await reader.run('How many employees does GlobalCorp have? Ground it with claim_check or sparql_select first.')
+    print("GROUNDED:", answer.text.strip()[:80])
+    ok = "42" in answer.text and adopted
+    print("PASS: graph write + review + SHACL adoption + grounded answer" if ok else "NOTE: model variance — inspect")
+
+asyncio.run(main())

framework_agents-0.1.0/examples/09-a2a-remote.py

@@ -0,0 +1,49 @@
+"""LIVE: A2A over the wire — the Python server hosts a live agent; the Python
+client streams two turns through one context, and a2a_as_tool lets ANOTHER
+agent call it as a tool."""
+import asyncio
+
+from framework_agents import A2AServer, Agent, AgentOptions, a2a_as_tool, init_chat_model, load_config
+from framework_agents.a2a_client import AgentClient
+from framework_agents.middleware import model_retry
+
+cfg = load_config()
+
+async def main():
+    model = lambda: init_chat_model(f"together:{cfg.together_model}", max_tokens=1000)
+    server = A2AServer(
+        card={"name": "specialist", "description": "Knows capitals"},
+        agent_factory=lambda context_id: Agent(AgentOptions(
+            model=model(),
+            system_prompt="Answer capital-city questions in one word.",
+            middleware=[model_retry(max_retries=3, initial_delay_ms=400)],
+        )),
+    )
+    port = await server.start()
+    url = f"http://127.0.0.1:{port}"
+    print("A2A server up:", url)
+    try:
+        client = AgentClient(url)
+        context: list[str] = []
+        async def turn(msg: str) -> str:
+            text = ""
+            async for e in client.stream(msg, context[0] if context else None, None, on_context=context.append):
+                if e["type"] == "done":
+                    text = e["text"]
+            return text
+        t1 = await turn("The capital of France? One word.")
+        t2 = await turn("And of Japan? One word.")
+        print("TURN 1:", t1.strip(), "| TURN 2:", t2.strip(), "| shared contextId:", bool(context))
+
+        from framework_agents.a2a_client import A2AClient
+        remote = a2a_as_tool(A2AClient(url), name="ask_specialist", description="Ask the remote capitals specialist.")
+        orchestrator = Agent(AgentOptions(model=model(), max_steps=4, middleware=[model_retry(max_retries=3, initial_delay_ms=400)], tools=[remote]))
+        res = await orchestrator.run("Use the ask_specialist tool to ask for the capital of Italy, then repeat it.")
+        print("REMOTE-AS-TOOL:", res.text.strip()[:60])
+        ok = "paris" in t1.lower() and res.text.strip()
+        print("PASS: A2A live (stream x2 + remote-as-tool)" if ok else "NOTE: model variance")
+    finally:
+        await server.stop()
+        print("stopped")
+
+asyncio.run(main())