zonix 0.2.2__tar.gz → 0.3.2__tar.gz

{zonix-0.2.2 → zonix-0.3.2}/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.3.2
+
+- Kept approved tool input overrides in sync with `ToolContext.call.input`.
+- Stored workflow scratch outputs by node name instead of class name to avoid
+  overwriting repeated agent steps.
+- Treated typed first parameters such as `ctx: str` as normal tool inputs while
+  preserving untyped `ctx`/`context` as framework context parameters.
+
+## 0.3.0
+
+- Added model call inspection on `RunResult`, including raw upstream requests,
+  raw upstream responses, provider status, finish reasons, and per-call usage.
+- Expanded usage accounting with cached, cache creation, cache read, reasoning,
+  and thinking token fields.
+- Added chainable OpenAI Responses API controls for reasoning effort, reasoning
+  summaries, verbosity, output limits, previous responses, and includes.
+- Added Anthropic thinking, adaptive effort, service tier, metadata, native
+  thinking stream handling, and richer usage details.
+- Added a Gemini adapter with thinking budget, thought summaries, JSON output,
+  safety settings, tool config, and cached-content controls.
+- Added workflow and team graph exports as Mermaid, DOT, SVG, PNG, or PDF.
+- Updated documentation around Zonix's simple-first, chainable, traceable
+  design style and OpenAI-compatible providers such as DeepSeek.
+
 ## 0.2.2
 
 - Added first-class manually supplied `message_history` for agents, workflows,

{zonix-0.2.2 → zonix-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zonix
-Version: 0.2.2
+Version: 0.3.2
 Summary: Explicit, serializable AI workflow primitives inspired by pydantic-ai.
 Project-URL: Homepage, https://github.com/zongxi1115/zonix
 Project-URL: Repository, https://github.com/zongxi1115/zonix
@@ -23,18 +23,39 @@ Requires-Dist: anthropic>=0.45; extra == 'anthropic'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.13; extra == 'dev'
 Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0; extra == 'gemini'
 Provides-Extra: openai
 Requires-Dist: openai>=1.68; extra == 'openai'
+Provides-Extra: viz
+Requires-Dist: graphviz>=0.20; extra == 'viz'
 Description-Content-Type: text/markdown
 
 # Zonix
 
 ![Zonix logo](https://raw.githubusercontent.com/zongxi1115/zonix/main/logo.png)
 
+<p align="center"><strong>Call simply. Chain deeply. Trace everything.</strong></p>
+
 Zonix is a Python AI workflow framework with explicit agents and a serializable
 run engine. It borrows the clarity of pydantic-ai's `Agent`, then adds first
 class `workflow`, `team`, and `router` primitives on top of one execution model.
 
+The taste is deliberately practical: a beginner should be able to call one
+object and get a useful answer, while an advanced user can turn on reasoning,
+usage accounting, raw provider responses, graph export, and frontend streaming
+without changing the shape of their business code.
+
+Zonix has a few deliberately personal design choices:
+
+- Simple first: `await agent(task)` is the happy path.
+- Chainable when needed: reasoning, thinking budgets, output limits, and
+  provider quirks are small method calls instead of scattered dictionaries.
+- Inspectable by default: `.run()` keeps trace, usage, model calls, messages,
+  raw upstream payloads, and checkpoint state together.
+- Flow should be visible: workflow and team graphs can be exported as Mermaid,
+  DOT, SVG, PNG, or PDF.
+
 The core idea:
 
 ```python
@@ -46,8 +67,9 @@ async for event in planner.stream("add captcha to the login page", ctx=ctx):
 ```
 
 `__call__` returns the structured output. `.run()` returns the full trace, usage,
-messages, and checkpoint metadata. `.stream()` returns typed events that can be
-mapped to frontend protocols such as the Vercel AI SDK data stream.
+messages, model calls, raw upstream responses, and checkpoint metadata.
+`.stream()` returns typed events that can be mapped to frontend protocols such
+as the Vercel AI SDK data stream.
 
 ## Install
 
@@ -66,6 +88,8 @@ Optional model providers:
 ```bash
 pip install "zonix[openai]"
 pip install "zonix[anthropic]"
+pip install "zonix[gemini]"
+pip install "zonix[viz]"
 ```
 
 ## OpenAI-compatible and Anthropic-compatible endpoints
@@ -91,6 +115,50 @@ anthropic_model = Anthropic(
 )
 ```
 
+For OpenAI-compatible providers such as DeepSeek, keep the same adapter and only
+change the endpoint and model:
+
+```python
+deepseek_model = OpenAI(
+    model="deepseek-v4-flash",
+    api_key=os.environ["DEEPSEEK_API_KEY"],
+    base_url="https://api.deepseek.com/v1",
+)
+```
+
+Newer model-specific controls stay chainable, so the common path remains
+readable:
+
+```python
+from zonix.models import Anthropic, Gemini, OpenAI
+
+planner_model = (
+    OpenAI("gpt-5.5")
+    .responses()
+    .reasoning("low", summary="auto")
+    .verbosity("low")
+    .max_output(8000)
+)
+
+claude_model = (
+    Anthropic("claude-sonnet-4-6")
+    .thinking("adaptive")
+    .effort("medium")
+    .max_output(16000)
+)
+
+gemini_model = (
+    Gemini("gemini-3-pro")
+    .thinking_budget(4096)
+    .include_thoughts()
+    .max_output(8000)
+)
+```
+
+OpenAI's Responses API is opt-in with `.responses()` so existing
+OpenAI-compatible gateways that only implement Chat Completions can keep using
+the default adapter path.
+
 Run the real provider example:
 
 ```bash
@@ -120,7 +188,7 @@ planner = (
     agent(
         "planner",
         role="Plan code work",
-        model=OpenAI("gpt-5.2", temperature=0.2),
+        model=OpenAI("gpt-5.5", temperature=0.2).responses().reasoning("low"),
         output=Plan,
     )
     .use(read_tree, search_code)
@@ -159,6 +227,25 @@ async def write_file(ctx, path: str, content: str) -> bool:
 If a tool takes `ctx` as its first parameter, Zonix passes a `ToolContext` with
 `deps`, shared usage, the current run state, and the owning agent.
 
+Tools can require approval before execution. Register the approval handler with
+the tools that share the same approval flow, so the run loop does not need a
+large central router.
+
+```python
+def review_tool_call(pending):
+    print(pending.tool, pending.input)
+    return True
+
+
+assistant = agent("assistant").use(send_email, approval=review_tool_call)
+run = await assistant.run("send the draft")
+```
+
+Middleware is for more involved interception, such as blocking a call, rewriting
+parsed input, or requiring approval only under specific runtime conditions.
+Without a registered approval handler, `run()` returns a paused `RunResult` that
+can be resumed later from a UI, queue, or separate process.
+
 ## Three call levels
 
 ```python
@@ -173,6 +260,34 @@ All three calls use the same run engine. The engine owns prompt assembly, model
 calls, tool execution, output validation, usage aggregation, spans, checkpoints,
 and event emission.
 
+Synchronous callers can use the explicit blocking facade:
+
+```python
+output = planner.call_sync(task, ctx=ctx)
+run = planner.run_sync(task, ctx=ctx)
+
+for event in planner.stream_sync(task, ctx=ctx):
+    print(event)
+```
+
+The async engine remains the source of truth; the sync facade bridges it for
+scripts, CLIs, notebooks, and other non-async entry points.
+
+`.run()` is the inspection layer:
+
+```python
+run = await planner.run(task, ctx=ctx)
+
+print(run.output)
+print(run.usage.reasoning_tokens)
+print(run.model_calls[-1].raw_request)
+print(run.model_calls[-1].raw_response)
+```
+
+That raw-response escape hatch is intentional. Zonix keeps the beginner API
+small, but it should never hide the provider payload when you need to debug a
+token spike, a refusal, a tool-call mismatch, or a gateway quirk.
+
 ## Manual message history
 
 You can pass an explicit prior transcript when you want to replay or continue
@@ -237,6 +352,14 @@ flow = (
 )
 ```
 
+Workflow graphs can be exported for review or documentation:
+
+```python
+flow.graph().save("review.mmd")
+flow.graph().save("review.png")  # requires zonix[viz] and Graphviz
+print(flow.to_mermaid())
+```
+
 ## Team and router
 
 ```python
@@ -263,6 +386,12 @@ answer = await code_team.solve("review the auth changes", ctx=ctx)
 A router can be a rule function, another agent, or any node that returns
 `Route(next=..., done=..., input=...)`.
 
+Teams expose the same graph API:
+
+```python
+code_team.graph().save("code_team.svg")
+```
+
 ## Memory
 
 ```python
@@ -327,6 +456,7 @@ zonix/
   spec.py       agent()/team()/workflow()/router() factories
   engine.py     serializable Run engine and Agent execution
   runtime.py    __call__/run/stream driver shared by every node
+  graph.py      workflow/team graph specs, Mermaid, DOT, and image export
   memory/       Window, Summarize, Vector, Session
   multi/        Workflow, Team, Router nodes
   hitl.py       checkpoint save/load and approval keys

{zonix-0.2.2 → zonix-0.3.2}/README.md

@@ -2,10 +2,27 @@
 
 ![Zonix logo](https://raw.githubusercontent.com/zongxi1115/zonix/main/logo.png)
 
+<p align="center"><strong>Call simply. Chain deeply. Trace everything.</strong></p>
+
 Zonix is a Python AI workflow framework with explicit agents and a serializable
 run engine. It borrows the clarity of pydantic-ai's `Agent`, then adds first
 class `workflow`, `team`, and `router` primitives on top of one execution model.
 
+The taste is deliberately practical: a beginner should be able to call one
+object and get a useful answer, while an advanced user can turn on reasoning,
+usage accounting, raw provider responses, graph export, and frontend streaming
+without changing the shape of their business code.
+
+Zonix has a few deliberately personal design choices:
+
+- Simple first: `await agent(task)` is the happy path.
+- Chainable when needed: reasoning, thinking budgets, output limits, and
+  provider quirks are small method calls instead of scattered dictionaries.
+- Inspectable by default: `.run()` keeps trace, usage, model calls, messages,
+  raw upstream payloads, and checkpoint state together.
+- Flow should be visible: workflow and team graphs can be exported as Mermaid,
+  DOT, SVG, PNG, or PDF.
+
 The core idea:
 
 ```python
@@ -17,8 +34,9 @@ async for event in planner.stream("add captcha to the login page", ctx=ctx):
 ```
 
 `__call__` returns the structured output. `.run()` returns the full trace, usage,
-messages, and checkpoint metadata. `.stream()` returns typed events that can be
-mapped to frontend protocols such as the Vercel AI SDK data stream.
+messages, model calls, raw upstream responses, and checkpoint metadata.
+`.stream()` returns typed events that can be mapped to frontend protocols such
+as the Vercel AI SDK data stream.
 
 ## Install
 
@@ -37,6 +55,8 @@ Optional model providers:
 ```bash
 pip install "zonix[openai]"
 pip install "zonix[anthropic]"
+pip install "zonix[gemini]"
+pip install "zonix[viz]"
 ```
 
 ## OpenAI-compatible and Anthropic-compatible endpoints
@@ -62,6 +82,50 @@ anthropic_model = Anthropic(
 )
 ```
 
+For OpenAI-compatible providers such as DeepSeek, keep the same adapter and only
+change the endpoint and model:
+
+```python
+deepseek_model = OpenAI(
+    model="deepseek-v4-flash",
+    api_key=os.environ["DEEPSEEK_API_KEY"],
+    base_url="https://api.deepseek.com/v1",
+)
+```
+
+Newer model-specific controls stay chainable, so the common path remains
+readable:
+
+```python
+from zonix.models import Anthropic, Gemini, OpenAI
+
+planner_model = (
+    OpenAI("gpt-5.5")
+    .responses()
+    .reasoning("low", summary="auto")
+    .verbosity("low")
+    .max_output(8000)
+)
+
+claude_model = (
+    Anthropic("claude-sonnet-4-6")
+    .thinking("adaptive")
+    .effort("medium")
+    .max_output(16000)
+)
+
+gemini_model = (
+    Gemini("gemini-3-pro")
+    .thinking_budget(4096)
+    .include_thoughts()
+    .max_output(8000)
+)
+```
+
+OpenAI's Responses API is opt-in with `.responses()` so existing
+OpenAI-compatible gateways that only implement Chat Completions can keep using
+the default adapter path.
+
 Run the real provider example:
 
 ```bash
@@ -91,7 +155,7 @@ planner = (
     agent(
         "planner",
         role="Plan code work",
-        model=OpenAI("gpt-5.2", temperature=0.2),
+        model=OpenAI("gpt-5.5", temperature=0.2).responses().reasoning("low"),
         output=Plan,
     )
     .use(read_tree, search_code)
@@ -130,6 +194,25 @@ async def write_file(ctx, path: str, content: str) -> bool:
 If a tool takes `ctx` as its first parameter, Zonix passes a `ToolContext` with
 `deps`, shared usage, the current run state, and the owning agent.
 
+Tools can require approval before execution. Register the approval handler with
+the tools that share the same approval flow, so the run loop does not need a
+large central router.
+
+```python
+def review_tool_call(pending):
+    print(pending.tool, pending.input)
+    return True
+
+
+assistant = agent("assistant").use(send_email, approval=review_tool_call)
+run = await assistant.run("send the draft")
+```
+
+Middleware is for more involved interception, such as blocking a call, rewriting
+parsed input, or requiring approval only under specific runtime conditions.
+Without a registered approval handler, `run()` returns a paused `RunResult` that
+can be resumed later from a UI, queue, or separate process.
+
 ## Three call levels
 
 ```python
@@ -144,6 +227,34 @@ All three calls use the same run engine. The engine owns prompt assembly, model
 calls, tool execution, output validation, usage aggregation, spans, checkpoints,
 and event emission.
 
+Synchronous callers can use the explicit blocking facade:
+
+```python
+output = planner.call_sync(task, ctx=ctx)
+run = planner.run_sync(task, ctx=ctx)
+
+for event in planner.stream_sync(task, ctx=ctx):
+    print(event)
+```
+
+The async engine remains the source of truth; the sync facade bridges it for
+scripts, CLIs, notebooks, and other non-async entry points.
+
+`.run()` is the inspection layer:
+
+```python
+run = await planner.run(task, ctx=ctx)
+
+print(run.output)
+print(run.usage.reasoning_tokens)
+print(run.model_calls[-1].raw_request)
+print(run.model_calls[-1].raw_response)
+```
+
+That raw-response escape hatch is intentional. Zonix keeps the beginner API
+small, but it should never hide the provider payload when you need to debug a
+token spike, a refusal, a tool-call mismatch, or a gateway quirk.
+
 ## Manual message history
 
 You can pass an explicit prior transcript when you want to replay or continue
@@ -208,6 +319,14 @@ flow = (
 )
 ```
 
+Workflow graphs can be exported for review or documentation:
+
+```python
+flow.graph().save("review.mmd")
+flow.graph().save("review.png")  # requires zonix[viz] and Graphviz
+print(flow.to_mermaid())
+```
+
 ## Team and router
 
 ```python
@@ -234,6 +353,12 @@ answer = await code_team.solve("review the auth changes", ctx=ctx)
 A router can be a rule function, another agent, or any node that returns
 `Route(next=..., done=..., input=...)`.
 
+Teams expose the same graph API:
+
+```python
+code_team.graph().save("code_team.svg")
+```
+
 ## Memory
 
 ```python
@@ -298,6 +423,7 @@ zonix/
   spec.py       agent()/team()/workflow()/router() factories
   engine.py     serializable Run engine and Agent execution
   runtime.py    __call__/run/stream driver shared by every node
+  graph.py      workflow/team graph specs, Mermaid, DOT, and image export
   memory/       Window, Summarize, Vector, Session
   multi/        Workflow, Team, Router nodes
   hitl.py       checkpoint save/load and approval keys