agentix-toolkit 0.2.1__tar.gz → 0.3.0__tar.gz

{agentix_toolkit-0.2.1 → agentix_toolkit-0.3.0}/CHANGELOG.md

@@ -6,6 +6,53 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-23
+
+### Added
+- Suspendable human-in-the-loop (P18) — `Agent(suspend_on_confirm=True)` pauses a
+  run when a tool needs confirmation instead of awaiting `confirm_fn` inline: it
+  checkpoints (with the assistant tool-turn as the tail) and returns
+  `AgentOutcome(status="suspended", pending=[PendingApproval(...)])`. A later
+  `resume(run_id, decisions={call_id: bool})` — on the same or a brand-new Agent,
+  since the state lives in the store — finishes that turn (approve/deny;
+  undecided pending calls fail closed) and continues. Requires a store + run_id;
+  adds the `on_suspend` event and the `PendingApproval` type. Built for
+  web/serverless flows where the request coroutine can't block. See
+  `examples/24_suspend_resume.py`.
+- Sandboxed execution (P16) — `SubprocessExecutor` (a `ToolExecutor`) runs each
+  tool as a separate OS process and actually enforces the limits the loop passes:
+  network egress is **denied when `network_allowlist` is empty** (Linux network
+  namespace via `unshare`, auto-detected; **fails closed** if it can't isolate,
+  unless `require_network_isolation=False`), plus POSIX CPU/memory/file-size/
+  process rlimits, a fresh per-call temp working directory, a scrubbed
+  environment (no parent secrets leak), an output cap, and a timeout that kills
+  the process group. Ships `SandboxPolicy` and `Command`. This closes the gap
+  where `LocalToolExecutor` ignored `network_allowlist`. See
+  `examples/23_sandbox.py`.
+- Multimodal input (P15) — `Message.content` is now `str | list[ContentPart]`,
+  with `TextPart`, `ImagePart`, `DocumentPart`, and `AudioPart` (build via
+  `from_path` / `from_bytes` / `from_base64` / `from_url`). `Message.text` gives
+  a string view. `Agent.run`/`run_sync`/`stream` accept a parts list anywhere a
+  string request goes. Every adapter translates supported media to its provider
+  format and raises a clear error otherwise (e.g. audio on Anthropic, URL images
+  on Bedrock). Plain-string content is fully backward compatible. See
+  `examples/22_multimodal.py`.
+- Multi-provider adapters (P14) — the toolkit now ships five more model
+  backends alongside Anthropic, each behind its own extra and each a drop-in
+  `ModelFn`: `OpenAIModel` (`agentix[openai]`; Chat Completions, also drives any
+  OpenAI-compatible `base_url`, with streaming), `GeminiModel`
+  (`agentix[gemini]`), `BedrockModel` (`agentix[bedrock]`; AWS Converse API, run
+  off-thread), `OllamaModel` (`agentix[ollama]`; local models), and `LiteLLMModel`
+  (`agentix[litellm]`; one bridge to 100+ providers). Best-effort pricing added
+  for common OpenAI/Gemini models (override with `register_price`). See
+  `examples/21_providers.py`.
+- `AnthropicModel` typed reasoning/cost knobs: `thinking` (`True`/`"adaptive"`/
+  `"summarized"`/`"disabled"`/dict), `effort` (`low`…`max`), and `task_budget`
+  (int; adds the required beta header) — previously only via opaque `extra`.
+  Docstring documents refusal-fallback behavior.
+- `PromptRegistry`: lightweight in-process prompt versioning with `register` /
+  `get` / `rollback` / `render` and `to_dict`/`from_dict` persistence.
+
 ## [0.2.1] - 2026-06-23
 
 ### Fixed
@@ -82,7 +129,8 @@ Initial release.
   `cost_usd`; `AgentPolicy.max_budget_usd` aborts a run over budget.
 - `Interrupt` stops a run or stream at the next safe boundary.
 
-[Unreleased]: https://github.com/skwijeratne/agentix-toolkit/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/skwijeratne/agentix-toolkit/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/skwijeratne/agentix-toolkit/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/skwijeratne/agentix-toolkit/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/skwijeratne/agentix-toolkit/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/skwijeratne/agentix-toolkit/releases/tag/v0.1.0

{agentix_toolkit-0.2.1 → agentix_toolkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentix-toolkit
-Version: 0.2.1
+Version: 0.3.0
 Summary: A generic, batteries-included agent toolkit: configure the loop, tools, guards, and observability instead of rewriting them.
 Project-URL: Homepage, https://github.com/skwijeratne/agentix-toolkit
 Project-URL: Repository, https://github.com/skwijeratne/agentix-toolkit
@@ -20,8 +20,18 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.34; extra == 'bedrock'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=0.3; extra == 'gemini'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.40; extra == 'litellm'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.3; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
 Description-Content-Type: text/markdown
@@ -54,18 +64,29 @@ outcome = await agent.run("What's the weather in Lisbon?")
 ```
 
 - **Async-first** core loop (`run` / `stream` / `resume`) with a sync wrapper.
-- **Provider-agnostic** — bring any model; a real **Anthropic** adapter is included.
+- **Provider-agnostic** — bring any model, or use a shipped adapter:
+  **Anthropic**, **OpenAI** (+ any OpenAI-compatible URL), **Gemini**,
+  **Bedrock**, **Ollama** (local), and a **LiteLLM** bridge (100+ providers).
 - **Tools from type hints** — one `@tool` decorator generates the JSON schema;
   **MCP** servers and **subagents** plug in as tools too.
+- **Multimodal input** — a message is a string *or* a list of parts: text plus
+  **images / PDFs / audio**, translated per adapter (clear errors for what a
+  given provider can't accept).
 - **Security, opt-in** — trust boundary, permission tiers + dynamic
-  `can_use_tool` callbacks, PII/injection guards, human confirmation, audit events.
+  `can_use_tool` callbacks, PII/injection guards, human confirmation, audit events,
+  and a **sandboxed executor** that runs untrusted / model-generated code in an
+  isolated subprocess (no network by default, plus CPU/memory/fs limits).
 - **Cost & control** — token **and USD** cost tracking, step/token/USD budgets,
   cooperative `Interrupt`.
+- **Human-in-the-loop, durably** — `suspend_on_confirm` pauses at a confirmation,
+  persists, and returns `status="suspended"`; `resume(run_id, decisions=…)`
+  approves/denies on a later request (web/serverless-friendly), not just an
+  inline blocking prompt.
 - **Reliability** — output **validation + retry** (`outcome.parsed`), model
   **fallback/retry**, self-consistency, and LLM-as-judge.
 - **Scale & ops** — streaming, checkpoint/resume, context trimming, fleet
-  backpressure, an **eval harness** (gate CI on quality), and **OpenTelemetry**
-  tracing.
+  backpressure, an **eval harness** (gate CI on quality), **OpenTelemetry**
+  tracing, and **prompt versioning** (roll back a regressed prompt).
 
 > Status: **alpha**, under active development. APIs may change before `1.0`.
 
@@ -82,6 +103,7 @@ With [uv](https://docs.astral.sh/uv/) (recommended):
 ```bash
 uv add agentix-toolkit                       # core (no required deps)
 uv add "agentix-toolkit[anthropic]"          # + Anthropic adapter
+uv add "agentix-toolkit[openai]"             # + OpenAI adapter (pick your provider)
 uv add "agentix-toolkit[anthropic,mcp,otel]" # + MCP client + OpenTelemetry tracing
 ```
 
@@ -91,8 +113,10 @@ Or with pip:
 pip install "agentix-toolkit[anthropic]"
 ```
 
-Extras are opt-in: `anthropic` (the model adapter), `mcp` (MCP client),
-`otel` (OpenTelemetry tracing). The core has **no required dependencies**.
+Extras are opt-in and the core has **no required dependencies**. Provider
+adapters: `anthropic`, `openai`, `gemini`, `bedrock`, `ollama`, `litellm`
+(the LiteLLM bridge reaches 100+ providers on its own). Plus `mcp` (MCP client)
+and `otel` (OpenTelemetry tracing).
 
 ### 2. Run an agent with no API key
 
@@ -226,6 +250,11 @@ Each links to a runnable example in [`examples/`](./examples):
 | Eval | score golden cases, gate CI on pass rate | `17_eval.py` |
 | Verify | self-consistency + LLM-as-judge | `18_verification.py` |
 | Tracing | OpenTelemetry model/tool/run spans | `19_tracing.py` |
+| Prompts | versioning + rollback; typed Anthropic reasoning knobs | `20_prompts.py` |
+| Providers | OpenAI / Gemini / Bedrock / Ollama / LiteLLM, one-line swap | `21_providers.py` |
+| Multimodal | text + image / PDF / audio parts; per-adapter translation | `22_multimodal.py` |
+| Sandbox | run untrusted code in an isolated subprocess (no net, rlimits) | `23_sandbox.py` |
+| Suspend/resume | pause for human approval, persist, resume on a later request | `24_suspend_resume.py` |
 
 ---
 

{agentix_toolkit-0.2.1 → agentix_toolkit-0.3.0}/PLAN.md

@@ -127,8 +127,10 @@ agentix/
 - **P13 — OpenTelemetry tracing.** ✅ `agentix.tracing` (`agentix[otel]`):
   `TracingModel` (model spans), `tracing_events()` (tool spans + guard/confirm),
   `trace_run()` (root span). Tests + example 19 (verified vs the real OTel SDK).
-  Roadmap remainders (prompt versioning, citation guard, eval loaders) in
-  `PLAN.gaps.md`.
+- **Polish.** ✅ Typed `thinking`/`effort`/`task_budget` on `AnthropicModel`
+  (+ refusal-fallback docs); `PromptRegistry` (prompt versioning + rollback).
+  Example 20. The "perfect toolkit" frontier (P14+: more providers, multi-modal,
+  sandboxed executor, docs site, …) is tracked in `PLAN.gaps.md`.
 
 > ⚠️ Streaming caveat: `on_answer` egress guards (PII redaction) can't un-send
 > already-streamed deltas — deltas are raw; `Done.outcome.answer` is redacted.

{agentix_toolkit-0.2.1 → agentix_toolkit-0.3.0}/README.md

@@ -26,18 +26,29 @@ outcome = await agent.run("What's the weather in Lisbon?")
 ```
 
 - **Async-first** core loop (`run` / `stream` / `resume`) with a sync wrapper.
-- **Provider-agnostic** — bring any model; a real **Anthropic** adapter is included.
+- **Provider-agnostic** — bring any model, or use a shipped adapter:
+  **Anthropic**, **OpenAI** (+ any OpenAI-compatible URL), **Gemini**,
+  **Bedrock**, **Ollama** (local), and a **LiteLLM** bridge (100+ providers).
 - **Tools from type hints** — one `@tool` decorator generates the JSON schema;
   **MCP** servers and **subagents** plug in as tools too.
+- **Multimodal input** — a message is a string *or* a list of parts: text plus
+  **images / PDFs / audio**, translated per adapter (clear errors for what a
+  given provider can't accept).
 - **Security, opt-in** — trust boundary, permission tiers + dynamic
-  `can_use_tool` callbacks, PII/injection guards, human confirmation, audit events.
+  `can_use_tool` callbacks, PII/injection guards, human confirmation, audit events,
+  and a **sandboxed executor** that runs untrusted / model-generated code in an
+  isolated subprocess (no network by default, plus CPU/memory/fs limits).
 - **Cost & control** — token **and USD** cost tracking, step/token/USD budgets,
   cooperative `Interrupt`.
+- **Human-in-the-loop, durably** — `suspend_on_confirm` pauses at a confirmation,
+  persists, and returns `status="suspended"`; `resume(run_id, decisions=…)`
+  approves/denies on a later request (web/serverless-friendly), not just an
+  inline blocking prompt.
 - **Reliability** — output **validation + retry** (`outcome.parsed`), model
   **fallback/retry**, self-consistency, and LLM-as-judge.
 - **Scale & ops** — streaming, checkpoint/resume, context trimming, fleet
-  backpressure, an **eval harness** (gate CI on quality), and **OpenTelemetry**
-  tracing.
+  backpressure, an **eval harness** (gate CI on quality), **OpenTelemetry**
+  tracing, and **prompt versioning** (roll back a regressed prompt).
 
 > Status: **alpha**, under active development. APIs may change before `1.0`.
 
@@ -54,6 +65,7 @@ With [uv](https://docs.astral.sh/uv/) (recommended):
 ```bash
 uv add agentix-toolkit                       # core (no required deps)
 uv add "agentix-toolkit[anthropic]"          # + Anthropic adapter
+uv add "agentix-toolkit[openai]"             # + OpenAI adapter (pick your provider)
 uv add "agentix-toolkit[anthropic,mcp,otel]" # + MCP client + OpenTelemetry tracing
 ```
 
@@ -63,8 +75,10 @@ Or with pip:
 pip install "agentix-toolkit[anthropic]"
 ```
 
-Extras are opt-in: `anthropic` (the model adapter), `mcp` (MCP client),
-`otel` (OpenTelemetry tracing). The core has **no required dependencies**.
+Extras are opt-in and the core has **no required dependencies**. Provider
+adapters: `anthropic`, `openai`, `gemini`, `bedrock`, `ollama`, `litellm`
+(the LiteLLM bridge reaches 100+ providers on its own). Plus `mcp` (MCP client)
+and `otel` (OpenTelemetry tracing).
 
 ### 2. Run an agent with no API key
 
@@ -198,6 +212,11 @@ Each links to a runnable example in [`examples/`](./examples):
 | Eval | score golden cases, gate CI on pass rate | `17_eval.py` |
 | Verify | self-consistency + LLM-as-judge | `18_verification.py` |
 | Tracing | OpenTelemetry model/tool/run spans | `19_tracing.py` |
+| Prompts | versioning + rollback; typed Anthropic reasoning knobs | `20_prompts.py` |
+| Providers | OpenAI / Gemini / Bedrock / Ollama / LiteLLM, one-line swap | `21_providers.py` |
+| Multimodal | text + image / PDF / audio parts; per-adapter translation | `22_multimodal.py` |
+| Sandbox | run untrusted code in an isolated subprocess (no net, rlimits) | `23_sandbox.py` |
+| Suspend/resume | pause for human approval, persist, resume on a later request | `24_suspend_resume.py` |
 
 ---
 

agentix_toolkit-0.3.0/examples/20_prompts.py

@@ -0,0 +1,47 @@
+"""20 — Prompt registry & versioning (+ provider reasoning knobs).
+
+`PromptRegistry` keeps named prompts under version control so you can roll back a
+change that regressed. Combine it with the eval harness to compare versions.
+
+Also shown: the typed reasoning/cost knobs on the Anthropic adapter
+(`thinking` / `effort` / `task_budget`) — configured below but not called (no API
+key needed for this demo).
+
+Run:
+    PYTHONPATH=src python examples/20_prompts.py
+"""
+
+from __future__ import annotations
+
+from agentix import PromptRegistry
+
+
+def main() -> None:
+    prompts = PromptRegistry()
+
+    v1 = prompts.register("assistant", "You are a helpful assistant.")
+    v2 = prompts.register("assistant", "You are a terse, snarky assistant.")  # regressed
+    print(f"registered v{v1} and v{v2}; active = v{prompts.active('assistant')}")
+    print("active prompt:", prompts.get("assistant"))
+
+    # The v2 change tanked your eval pass-rate — roll back.
+    prompts.rollback("assistant", v1)
+    print(f"\nrolled back; active = v{prompts.active('assistant')}")
+    print("active prompt:", prompts.get("assistant"))
+
+    # Templating + persistence.
+    prompts.register("greet", "Hello {name}, welcome to {product}.")
+    print("\nrendered:", prompts.render("greet", name="Sam", product="agentix"))
+    blob = prompts.to_dict()                 # persist via a Store / JSON
+    restored = PromptRegistry.from_dict(blob)
+    print("restored active 'assistant':", restored.get("assistant"))
+
+    # --- reasoning / cost knobs on the Anthropic adapter (config only) ---
+    print("\nAnthropic reasoning/cost knobs (typed, no opaque extra):")
+    print("  AnthropicModel(thinking='summarized', effort='low')   # cheaper, shows reasoning")
+    print("  AnthropicModel(effort='xhigh')                        # max quality for hard tasks")
+    print("  AnthropicModel(task_budget=50_000)                    # self-moderated loop budget")
+
+
+if __name__ == "__main__":
+    main()

agentix_toolkit-0.3.0/examples/21_providers.py

@@ -0,0 +1,84 @@
+"""21 — One agent, many providers.
+
+`agentix` is provider-agnostic: the loop, tools, and guards are identical no
+matter which model backs them. Swapping providers is a one-line change to the
+`model=` argument. This example is the gallery of those one-liners, plus a
+dependency-free demo proving the loop itself doesn't care which you pick.
+
+Each adapter defers its SDK import to construction, so importing the classes is
+always safe; you only need the matching extra to actually *run* one:
+
+    pip install "agentix[openai]"     # OpenAIModel  (+ any OpenAI-compatible URL)
+    pip install "agentix[gemini]"     # GeminiModel
+    pip install "agentix[bedrock]"    # BedrockModel (AWS Converse API)
+    pip install "agentix[ollama]"     # OllamaModel  (local models)
+    pip install "agentix[litellm]"    # LiteLLMModel (100+ providers via one bridge)
+
+Run:
+    python examples/21_providers.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from agentix import Agent, MockModel, ModelResponse, ToolCall, tool
+
+
+@tool
+def get_weather(city: str) -> str:
+    """Get the current weather for a city.
+
+    Args:
+        city: City name, e.g. 'Paris'.
+    """
+    return f"{city}: 21C, partly cloudy."
+
+
+# ── How you'd construct each provider (copy the line you need) ───────────────
+#
+#   from agentix.providers.openai import OpenAIModel
+#   model = OpenAIModel(model="gpt-4o")                 # reads OPENAI_API_KEY
+#   model = OpenAIModel(base_url="http://localhost:11434/v1", api_key="ollama",
+#                       model="llama3.1")               # any OpenAI-compatible URL
+#
+#   from agentix.providers.gemini import GeminiModel
+#   model = GeminiModel(model="gemini-2.0-flash")       # reads GOOGLE_API_KEY
+#
+#   from agentix.providers.bedrock import BedrockModel
+#   model = BedrockModel(model="anthropic.claude-3-5-sonnet-20241022-v2:0")
+#                                                        # uses the AWS cred chain
+#   from agentix.providers.ollama import OllamaModel
+#   model = OllamaModel(model="llama3.1")               # local; needs `ollama serve`
+#
+#   from agentix.providers.litellm import LiteLLMModel
+#   model = LiteLLMModel(model="anthropic/claude-opus-4-8")  # provider-prefixed ids
+#
+# Then it's the same Agent for every one of them:
+#
+#   agent = Agent(model=model, system_prompt="...", tools=[get_weather])
+#   outcome = await agent.run("What's the weather in Paris?")
+
+
+async def main() -> None:
+    # The dependency-free proof: a scripted MockModel drives the exact same loop
+    # (tool call -> tool result -> final answer) that every real adapter drives.
+    model = MockModel(
+        [
+            ModelResponse(tool_calls=[ToolCall("get_weather", {"city": "Paris"})]),
+            ModelResponse(text="It's 21C and partly cloudy in Paris."),
+        ]
+    )
+    agent = Agent(
+        model=model,
+        system_prompt="You are a concise weather assistant.",
+        tools=[get_weather],
+    )
+    outcome = await agent.run("What's the weather in Paris?")
+
+    print("answer:", outcome.answer)
+    print("(swap `model=` for any provider above — nothing else changes.)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentix_toolkit-0.3.0/examples/22_multimodal.py

@@ -0,0 +1,71 @@
+"""22 — Multimodal input (vision, documents, audio).
+
+A message's content can be a plain string *or* a list of parts: text interleaved
+with images, documents (PDF), and audio. You build the parts the same way for
+every provider; each adapter translates them to that vendor's wire format (and
+raises a clear error for media a provider can't accept — e.g. audio on Anthropic,
+URL images on Bedrock).
+
+This demo is dependency-free: a MockModel stands in for a vision model so you can
+see the plumbing without a key. Swap `model=` for any vision-capable adapter
+(AnthropicModel, OpenAIModel, GeminiModel, …) and it works unchanged.
+
+Run:
+    python examples/22_multimodal.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from agentix import (
+    Agent,
+    DocumentPart,
+    ImagePart,
+    MockModel,
+    ModelResponse,
+    TextPart,
+)
+
+# A 1x1 transparent PNG — stands in for "an image you loaded".
+_PNG = bytes.fromhex(
+    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4"
+    "890000000a49444154789c6300010000050001"
+)
+
+
+async def main() -> None:
+    # Build a multimodal user turn. Parts can come from bytes, a file, a URL,
+    # or raw base64 — pick whichever you have:
+    user_turn = [
+        TextPart("What's in this image, and how does it relate to the attached doc?"),
+        ImagePart.from_bytes(_PNG, "image/png"),          # inline bytes
+        # ImagePart.from_path("diagram.png"),             # a local file (mime inferred)
+        # ImagePart.from_url("https://example.com/x.jpg"),# a remote URL
+        DocumentPart.from_url("https://example.com/spec.pdf", "application/pdf"),
+    ]
+
+    agent = Agent(
+        model=MockModel([ModelResponse(text="A 1x1 PNG; the doc is a linked PDF spec.")]),
+        system_prompt="You are a concise visual assistant.",
+    )
+
+    # The loop accepts the parts list anywhere a string request would go.
+    outcome = await agent.run(user_turn)
+    print("answer:", outcome.answer)
+
+    # `.text` gives a string view of any message (media parts contribute nothing).
+    from agentix import Message, Role
+
+    print("text view:", Message(Role.USER, user_turn).text)
+
+
+# To use a real vision model instead of the mock:
+#
+#   from agentix.providers.anthropic import AnthropicModel
+#   agent = Agent(model=AnthropicModel(), system_prompt="...")
+#   await agent.run([TextPart("Describe this"), ImagePart.from_path("cat.png")])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentix_toolkit-0.3.0/examples/23_sandbox.py

@@ -0,0 +1,86 @@
+"""23 — Sandboxed execution of untrusted / model-generated code.
+
+`LocalToolExecutor` runs tools in-process — great for trusted tools, but it can't
+contain code you don't trust and can't honour `network_allowlist`. `SubprocessExecutor`
+runs each tool as a separate OS process with real limits: no network (Linux
+netns, fail-closed), CPU/memory/file-size/process rlimits, an isolated temp
+working directory, a scrubbed environment, and a hard timeout.
+
+Run:
+    python examples/23_sandbox.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from agentix import Command, SubprocessExecutor
+from agentix.types import ToolCall
+
+# A "run this Python" tool: argv runs the interpreter reading code from stdin.
+run_python = {"run_python": Command(argv=[sys.executable, "-"], stdin="code")}
+
+
+async def main() -> None:
+    # network_allowlist is what the Agent loop passes from AgentPolicy. Empty =>
+    # egress denied (enforced via a network namespace; the call fails closed if
+    # the host can't provide one). A non-empty list => network allowed.
+    allow_net = ["pypi.org"]
+
+    executor = SubprocessExecutor(run_python)
+
+    # 1) Run some code; capture stdout.
+    res = await executor(
+        ToolCall("run_python", {"code": "print(6 * 7)"}),
+        network_allowlist=allow_net,
+    )
+    print("1) output:", res.content.strip(), "| ok:", res.ok)
+
+    # 2) Secrets in this process do NOT leak into the child by default.
+    import os
+
+    os.environ["MY_API_KEY"] = "sk-secret"
+    peek = "import os; print(os.environ.get('MY_API_KEY', 'HIDDEN'))"
+    res = await executor(
+        ToolCall("run_python", {"code": peek}),
+        network_allowlist=allow_net,
+    )
+    print("2) child sees the key?:", res.content.strip())
+
+    # 3) A runaway is killed by the timeout (not the full 30s).
+    res = await executor(
+        ToolCall("run_python", {"code": "import time; time.sleep(30)"}),
+        network_allowlist=allow_net,
+        timeout_s=0.5,
+    )
+    print("3) runaway:", res.content.strip(), "| ok:", res.ok)
+
+    # 4) The headline guarantee: deny network. With the default policy
+    # (require_network_isolation=True), if the host can't isolate the network the
+    # tool REFUSES rather than running untrusted code with egress.
+    fetch = "import urllib.request; urllib.request.urlopen('http://example.com')"
+    res = await executor(
+        ToolCall("run_python", {"code": fetch}),
+        network_allowlist=[],  # deny all egress
+    )
+    print("4) network-denied result ok?:", res.ok)
+    print("   ->", res.content.strip()[:120])
+
+    # Wiring into an Agent: pass the executor + tool_schemas, and the loop hands
+    # it AgentPolicy.network_allowlist / tool_timeout_s automatically:
+    #
+    #   agent = Agent(
+    #       model=my_model,
+    #       system_prompt="Use run_python to compute things.",
+    #       tool_executor=SubprocessExecutor(run_python),
+    #       tool_schemas=[{"name": "run_python", "description": "...",
+    #                      "parameters": {"type": "object",
+    #                                     "properties": {"code": {"type": "string"}},
+    #                                     "required": ["code"]}}],
+    #       policy=AgentPolicy(network_allowlist=[]),  # no egress for tools
+    #   )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentix_toolkit-0.3.0/examples/24_suspend_resume.py

@@ -0,0 +1,87 @@
+"""24 — Suspendable human-in-the-loop (pause → persist → resume).
+
+A web or serverless agent can't block a request coroutine waiting for a human to
+click "approve" minutes later. With `suspend_on_confirm=True`, when a tool needs
+confirmation the loop *checkpoints to the store and returns* `status="suspended"`
+with the pending approvals — the request can end. A later request (even in a new
+process) calls `resume(run_id, decisions=...)` to approve/deny and continue.
+
+This demo uses a scripted model and a FileStore, and resumes on a brand-new
+Agent instance to prove the paused state lives entirely in the store.
+
+Run:
+    python examples/24_suspend_resume.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import tempfile
+from collections.abc import Sequence
+
+from agentix import (
+    Agent,
+    AgentPolicy,
+    FileStore,
+    MockModel,
+    ModelResponse,
+    Role,
+    TierGuard,
+    ToolCall,
+    tool,
+)
+from agentix.types import Message
+
+
+@tool
+def wire_funds(to: str, amount: int) -> str:
+    """Wire money to an account."""
+    return f"wired ${amount} to {to}"
+
+
+def model(messages: Sequence[Message]) -> ModelResponse:
+    # Stateless, like a real model: answer once the tool result is present.
+    if any(m.role is Role.TOOL for m in messages):
+        return ModelResponse(text="Done — the transfer is complete.")
+    call = ToolCall("wire_funds", {"to": "acct-42", "amount": 9000}, id="c1")
+    return ModelResponse(tool_calls=[call])
+
+
+def build_agent(store: FileStore) -> Agent:
+    return Agent(
+        model=MockModel(model),
+        system_prompt="You are a finance assistant.",
+        tools=[wire_funds],
+        guards=[TierGuard()],
+        policy=AgentPolicy(confirm_first={"wire_funds"}),  # gate the risky tool
+        store=store,
+        suspend_on_confirm=True,
+    )
+
+
+async def main() -> None:
+    with tempfile.TemporaryDirectory() as tmp:
+        store = FileStore(tmp)
+
+        # --- Request 1: start the run; it pauses for approval and returns. ---
+        first = await build_agent(store).run("Pay invoice 42", run_id="run-1")
+        print("after request 1:", first.status)
+        for p in first.pending:
+            c = p.call
+            print(f"  awaiting approval: {c.name}({c.args}) — {p.reason}")
+
+        # ... the HTTP handler returns here; nothing is blocked. The human
+        # reviews and approves out-of-band. Later, a *new* process handles the
+        # approval callback: ---
+
+        # --- Request 2: a fresh Agent (same store) resumes with the decision. ---
+        approved = await build_agent(store).resume("run-1", decisions={"c1": True})
+        print("after request 2:", approved.status, "->", approved.answer)
+
+        # Denying instead would have declined the tool and still completed:
+        denied = await build_agent(store).resume("run-1", decisions={"c1": False})
+        print("if denied:", denied.status, "->", denied.answer)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{agentix_toolkit-0.2.1 → agentix_toolkit-0.3.0}/examples/README.md

@@ -30,6 +30,11 @@ uv run python examples/01_hello_agent.py
 | `17_eval.py` | Eval harness: score an agent over golden cases, gate CI on pass rate. | — |
 | `18_verification.py` | Self-consistency (`SelfConsistencyModel`) + LLM-as-judge (`JudgeGuard`). | — |
 | `19_tracing.py` | OpenTelemetry tracing: model/tool/run spans. | `agentix[otel]` + `opentelemetry-sdk` |
+| `20_prompts.py` | Prompt registry/versioning + typed Anthropic reasoning knobs. | — |
+| `21_providers.py` | Provider gallery: OpenAI / Gemini / Bedrock / Ollama / LiteLLM, one-line swap. | — (per-provider extra to run live) |
+| `22_multimodal.py` | Multimodal input: text + image / PDF / audio parts via `TextPart`/`ImagePart`/`DocumentPart`/`AudioPart`. | — |
+| `23_sandbox.py` | `SubprocessExecutor`: run untrusted/model-generated code in an isolated subprocess (no network, rlimits, timeout). | — (POSIX) |
+| `24_suspend_resume.py` | Durable human-in-the-loop: `suspend_on_confirm` pauses for approval, persists, and `resume(decisions=…)` continues (even in a new process). | — |
 
 To run the Anthropic example:
 

{agentix_toolkit-0.2.1 → agentix_toolkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentix-toolkit"
-version = "0.2.1"
+version = "0.3.0"
 description = "A generic, batteries-included agent toolkit: configure the loop, tools, guards, and observability instead of rewriting them."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -27,6 +27,11 @@ dependencies = []
 # Runtime extras (installed on demand): the optional provider/integration deps.
 [project.optional-dependencies]
 anthropic = ["anthropic>=0.40"]
+openai = ["openai>=1.0"]
+gemini = ["google-genai>=0.3"]
+bedrock = ["boto3>=1.34"]
+ollama = ["ollama>=0.3"]
+litellm = ["litellm>=1.40"]
 mcp = ["mcp>=1.0"]
 otel = ["opentelemetry-api>=1.20"]
 
@@ -65,5 +70,12 @@ files = ["src"]
 
 # Optional, lazily-imported deps — don't require their stubs to type-check.
 [[tool.mypy.overrides]]
-module = ["opentelemetry.*"]
+module = [
+    "opentelemetry.*",
+    "openai.*",
+    "google.*",
+    "boto3.*",
+    "ollama.*",
+    "litellm.*",
+]
 ignore_missing_imports = true