roboz 0.1.2.dev7__tar.gz → 0.1.2.dev8__tar.gz

{roboz-0.1.2.dev7 → roboz-0.1.2.dev8}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.1.2.dev8 - 2026-09-20
+
+- Breaking: remove the legacy agent master tool. Model-driven agents run
+  their configured default tools followed by the built-in `prompt_agent` tool;
+  deterministic agents require and run only their configured default tools.
+  Use `default_tools` to configure deterministic steps instead of relying on
+  the removed `master_tool` attribute.
+
+- Show every displayed tool's external dependency IDs and kinds in
+  `Agent.show_agent_info()`.
+
 ## 0.1.2.dev7 - 2026-09-20
 
 - Breaking: replace the `is_agentic` boolean with the string-valued
@@ -28,7 +39,7 @@
   verbatim instead of attempting action validation. Supply `LlmOutputModel=...`
   or `active_tools=...` to retain structured dictionary results and repair retries.
   Endpoint and callback arguments are mutually exclusive. See the
-  [completion guide](docs/tool-authoring.md#standalone-llm-backed-tools).
+  [completion guide](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/tool-authoring.md#standalone-llm-backed-tools).
 
 ## 0.1.2.dev6 - 2026-09-15
 
@@ -36,7 +47,7 @@
   `Agent`, `Skill`, `Tool`, `Factory`, `tool`, and `factory` alongside discoverable
   domain namespaces. Import models from `roboz.models`, agent helpers from
   `roboz.agent`, built-in tools from `roboz.tools`, and context protocols from
-  `roboz.tooling`. See [the import migration guide](docs/imports.md).
+  `roboz.tooling`. See [the import migration guide](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/imports.md).
 
 ## 0.1.2.dev5 - 2026-09-13
 
@@ -56,7 +67,7 @@
   stay side-effect free. Endpoints support explicit early `materialize()` calls
   while preserving their identity; prompt contexts delegate initialization.
   Breaking: OpenAI-compatible client protocols now require `close() -> None` for
-  typed cleanup. See [the lifecycle contract](docs/dependency-primitives.md).
+  typed cleanup. See [the lifecycle contract](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/dependency-primitives.md).
 
 - Make resource-inspection declarations explicit: aggregate contexts and agents
   implement the `HasExternalDependencies` protocol, renamed from `Context` with
@@ -72,20 +83,20 @@
   share supplied state. Agent inspection uses live tool methods, and deployment
   builders use the same bindings. Restore top-level agent, skill, and built-in
   tool exports; removed dependency and `Ctx` APIs stay removed. See
-  [the primitive migration](docs/dependency-primitives.md).
+  [the primitive migration](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/dependency-primitives.md).
 
 - Breaking: core endpoints require synchronous OpenAI-compatible clients instead
   of an untyped client. Client methods and request controls are checked statically;
   the real `openai.OpenAI` client satisfies the protocols without a wrapper or an
   SDK dependency in core. Replace placeholder or incompatible clients with a
-  conforming chat/transcription client. See [the client contract](docs/dependency-primitives.md).
+  conforming chat/transcription client. See [the client contract](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/dependency-primitives.md).
 
 - Breaking: external resource implementations must provide `check() -> bool` for
   explicit availability checks. Executables check PATH; core endpoints use model
   discovery without generating output. Results are uncached, absent resources
   return `False`, and check errors propagate. Binding, copying, and inspection
   never invoke checks. Plain contexts need no check method. See
-  [resource inspection and availability](docs/dependency-primitives.md).
+  [resource inspection and availability](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/dependency-primitives.md).
 
 - Accept any concretely typed factory context, including plain objects and lists.
   Contexts without resource inspection are passed through unchanged and their
@@ -95,7 +106,7 @@
   retaining their identity and client for execution and inspection. Endpoint
   request helpers and the selector now use concrete endpoints; lazy construction
   and companion migrations remain deferred. Scripted endpoints report no external
-  resources. See [typed contexts and resource inspection](docs/dependency-primitives.md).
+  resources. See [typed contexts and resource inspection](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/dependency-primitives.md).
 - Fix `@factory()` input inference so parenthesized factories retain the same
   concrete input, output, and context types as bare `@factory` declarations.
 
@@ -106,7 +117,7 @@
   stay in `roboz.dependencies`; the top-level API now exposes only data and
   tool/factory/context primitives. Remove legacy dependency bases, lazy/reference
   helpers, and checker registration. Agent, built-in tool, and companion consumers
-  remain unmigrated; this checkpoint is not release-ready. See [typed contexts and resource inspection](docs/dependency-primitives.md)
+  remain unmigrated; this checkpoint is not release-ready. See [typed contexts and resource inspection](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/dependency-primitives.md)
   for the contract, removed APIs, and migration boundary.
 
 ## 0.1.2.dev4 - 2026-09-12
@@ -134,7 +145,7 @@
   and background agents start through default tools. Construct generic
   definitions directly with `DeployableAgent(...)`.
   Sandbox-aware `Deployment` lives in `roboshed.deployments`, not core.
-  See `docs/agent-factories.md` for migration.
+  See [the archived agent migration guide](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/agent-factories.md) for migration.
 
 ## 0.1.2.dev2 - 2026-09-09
 
@@ -144,7 +155,7 @@
 
 - Breaking: move dependency primitives from `roboz.tooling.dependencies` and
   `roboz.tooling` to `roboz.dependencies`. Update those imports; the existing
-  top-level `roboz` authoring API remains available. See `docs/context-migration.md`.
+  top-level `roboz` authoring API remains available. See [the archived context migration guide](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/context-migration.md).
 
 - Add `DependencyRoute` for live caller-owned selections. Materialization and discovery delegate to the current target without introducing a separate identity or caching the selection.
 
@@ -152,11 +163,11 @@
   Capabilities own their tool-specific endpoint choices and receive the agent
   endpoint as a fallback, independently of runtime controls. Lazy/live
   references retain identity and deferred resolution. See
-  `docs/agent-factories.md` for builder migration.
+  [the archived agent migration guide](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/agent-factories.md) for builder migration.
 
-- Breaking: move the Librarian and its memory/summarization tools out of core into `roboshed.agents` and `roboshed.tools`. Use `librarian(sandbox, agent_names, agent_endpoint=...)` instead of `LibrarianConstructor` and its path record; see `docs/agent-factories.md`. Core retains control, interaction, and generic construction primitives.
+- Breaking: move the Librarian and its memory/summarization tools out of core into `roboshed.agents` and `roboshed.tools`. Use `librarian(sandbox, agent_names, agent_endpoint=...)` instead of `LibrarianConstructor` and its path record; see [the archived agent migration guide](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/agent-factories.md). Core retains control, interaction, and generic construction primitives.
 
-- Add generic `AgentDefinition`, `AgentCapability`, `Capability`, and `SubAgentSpec` in `roboz.deployment`. Configure all tools and skills through capabilities, with fresh agent pipes and explicit sink configuration; definitions select no project, memory, or persistence conventions. See `docs/agent-factories.md`.
+- Add generic `AgentDefinition`, `AgentCapability`, `Capability`, and `SubAgentSpec` in `roboz.deployment`. Configure all tools and skills through capabilities, with fresh agent pipes and explicit sink configuration; definitions select no project, memory, or persistence conventions. See [the archived agent migration guide](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/agent-factories.md).
 
 - Breaking: `roboz[shed]` now installs `roboshed` instead of `roboz-shed`. Update direct requirements to `roboshed` and imports from `roboz_shed` to `roboshed`; no compatibility package is provided.
 
@@ -177,7 +188,7 @@
   Contexts implement `ExternalDependencySource`, preserving resource identity
   and reflecting live nested contexts, agents, and catalogs without resolving
   lazy resources. `external_dependencies` is now a reserved context field name;
-  see `docs/context-migration.md`.
+  see [the archived context migration guide](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/context-migration.md).
 
 ### Fixed
 
@@ -189,7 +200,7 @@
 - **Breaking:** Construct tool contexts with `Ctx(**values)` and pass resources
   directly. Remove `FactoryCtx`, specialized context classes, `ToolDependency`,
   and endpoint binding wrappers; `Tool.dependencies` now returns resources.
-  See `docs/context-migration.md` for replacements and state ownership.
+  See [the archived context migration guide](https://github.com/Tachion-Oy/roboz/blob/roboz-v0.1.2.dev7/docs/context-migration.md) for replacements and state ownership.
 
 - Define and enforce Google-style source docstrings, and normalize tool
   docstrings before including them in agent prompts.

{roboz-0.1.2.dev7 → roboz-0.1.2.dev8}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: roboz
-Version: 0.1.2.dev7
+Version: 0.1.2.dev8
 Import-Name: roboz
 Summary: Typed primitives for composable agentic workflows
 Project-URL: Homepage, https://github.com/Tachion-Oy/roboz
 Project-URL: Repository, https://github.com/Tachion-Oy/roboz
 Project-URL: Issues, https://github.com/Tachion-Oy/roboz/issues
-Project-URL: Documentation, https://github.com/Tachion-Oy/roboz/tree/main/docs
+Project-URL: Documentation, https://github.com/Tachion-Oy/roboz#readme
 Author: Tachion Oy
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
   <p><strong>Chain tools. Skip calls.</strong></p>
 </div>
 
-RoboZ is a framework for building llm powered agents. The core ingredient is that every tool can may be chained conditionally to a subsequent tool thus allowing easy injection of deterministic flows into agentic processes.
+RoboZ is a framework for building llm powered agents. The core ingredient is that every tool may be chained conditionally to a subsequent tool thus allowing easy injection of deterministic flows into agentic processes.
 
 [![CI](https://github.com/Tachion-Oy/roboz/actions/workflows/ci.yml/badge.svg)](https://github.com/Tachion-Oy/roboz/actions/workflows/ci.yml)
 [![Python 3.13+](https://img.shields.io/badge/Python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
@@ -58,10 +58,10 @@ Suppose the task we want to achieve is ask our buddy Bob out to lunch and then b
 - Find a restaurant
 - Book a table.
 
-In the usual approach an agent is presented each MCP server separately in the their system prompt and it must call them one-by-one to complete the task. When the agent is completing the task, at every turn it must choose the correct tool, formulate its output accordingly and absorb the reply into its context, which already must contain the specific instructions on how to use each tool. In addition, at each turn one has to wait for the llm to reply, each reply costs tokens and each reply risks a mistake from the llm.
+In the usual approach an agent is presented each MCP server separately in their system prompt and it must call them one-by-one to complete the task. When the agent is completing the task, at every turn it must choose the correct tool, formulate its output accordingly and absorb the reply into its context, which already must contain the specific instructions on how to use each tool. In addition, at each turn one has to wait for the llm to reply, each reply costs tokens and each reply risks a mistake from the llm.
 
 ### Deterministic chains
-The philosophy in RoboZ is that of a a workflow is (mostly) deterministic an only on occasion does one need to call an llm. For example in RoboZ an agent would trigger the "ask Bob if they wan to have lunch" tool and all subsequent steps come by chaining: each tool can be chained to other tools upstream where their outputs are passed down the chain. Each link/edge may introduce a True/False condition, in our case for example if Bob interested in having lunch (with us). If he is not, RoboZ allows for the chain to break and returns back to the default tool, which for an agentic process is usually "ask the llm what to do next". The default mode is that chained tools are not presented to the agent, they are thus *passive* or in other words their role is strictly in forming deterministic workflows and they cannot be invoked.
+The philosophy in RoboZ is that a workflow is (mostly) deterministic and only on occasion does one need to call an llm. For example in RoboZ an agent would trigger the "ask Bob if they want to have lunch" tool and all subsequent steps come by chaining: each tool can be chained to other tools upstream where their outputs are passed down the chain. Each link/edge may introduce a True/False condition, in our case for example if Bob is interested in having lunch (with us). If he is not, RoboZ allows for the chain to break and returns back to the default tool, which for an agentic process is usually "ask the llm what to do next". The default mode is that chained tools are not presented to the agent, they are thus *passive* or in other words their role is strictly in forming deterministic workflows and they cannot be invoked.
 
 Chaining not only reduces the llm calls, but it also provides a useful way of introducing a fine-grained guard layer for tool calls. This is in fact precisely how the cli tools and their access policies work in Roboz. For a cli command a chained passive tool evaluates the intent and breaks the chain if policies are violated.
 
@@ -99,19 +99,21 @@ output, messages_ = agent.invoke()
 print(f'"{output.value}"')
 ```
 
-The above [simple example](examples/simple.py) can be run from the root with 
+The above [simple example](examples/simple.py) uses the accompanying
+[quote file](examples/simpsons_quotes.py) in this repository. Run it from the
+repository root with
 
-```python
+```bash
 uv run python examples/simple.py
 ```
 It creates an agent that returns a random
-Simpsons quote. It uses a mock endpoint, with pre-determined replies, so you can run it without API keys.
+Simpsons quote. **The docstring in the tool is the instruction that the agent sees**. It uses a mock endpoint, with pre-determined replies, so you can run it without API keys.
 The main contracts of RoboZ are already visible:
 
 - `@tool` creates an instance of a usable tool for the agent
 -  A tool's input and output are typed. Tools also receive the entire message stack
-- Callable endpoints are single instances, as a hard rule 
-- Different output types impact the dymanics, importantly `Stop` breaks out of the agentic loop
+- Callable endpoints are single instances, as a hard rule
+- Different output types impact the dynamics, importantly `Stop` breaks out of the agentic loop
 - `agent.invoke()` runs the agent and returns its output `Stop` and messages.
 
 The above does not show the main idea of tool chaining, for that read the following sections.
@@ -119,7 +121,7 @@ The above does not show the main idea of tool chaining, for that read the follow
 
 An agent is a loop that calls tools. Everything is defined as a tool: Skills,  background agents, prompting the agent, prompting the user, running nested agents, start up hooks etc. Everything.
 
-**A tool can be trigger in three ways:**
+**A tool can be triggered in three ways:**
 - **Invoked by an agent**: The `prompt_agent` tool asks an LLM what to do next and its `Invoke` output always calls another tool. It is constructed internally for `AgentMode.STEERABLE` and `AgentMode.AUTONOMOUS` agents, but it is still just a tool.
 - **By chaining**. After an invoked tool has fired RoboZ checks if a chained tool with a *true* chain condition exists (for more than one *true* condition for a fork you get a runtime error). If yes, the output is passed on and the process repeats until the first broken chain or all chained tools are exhausted
 - **As default tools**. Once the tool chain is exhausted or the chain breaks due to a *false* condition the loop returns to the freely defined `default_tool` (there actually can be many, they are all called in sequence).
@@ -130,13 +132,13 @@ RoboZ then collapses to the traditional agentic approach as a special case if on
 ### Tool Chaining
 This may be used to reduce the number of llm calls, leading to a speed increase, lower cost and fewer AI errors. It also provides a useful way of introducing a guard layer for tool calls, which can be used to restrict agentic actions.
 ### Output Truncation
-A Tools output can be hidden from the llm, also partially, and this can start to apply after the message has been shown N times.
+A tool’s output can be hidden from the llm, also partially, and this can start to apply after the message has been shown N times.
 ### Tool outputs are typed
-The contract in RoboZ is that all tool calls and hence in everything that happens is that outputs are typed classes. Agents and tools never exchange raw strings or even JSON, typed classes and validation are present throughout, with designated classes for tasks such as `Invoke` and `Stop`.
-### LLm Endpoints are instances
-As strict design rule in Roboz, everything that depends on an LLM call must be trivially swappable to another provider or model. This makes changing an agent endpoint trivial and furthermore multi-endpoint functionality, where inside a single agent several endpoints are implemented, quite easy.
+The contract in RoboZ is that every action in the agentic loop is a tool call and all outputs are typed classes. Raw strings or JSON is never exchanged (unless explicitly opted in) as is and typed classes and validation are present throughout, with designated classes for tasks such as `Invoke` and `Stop`.
+### LLM Endpoints are instances
+As a fundamental design rule in Roboz, everything that depends on an LLM call must be trivially swappable to another provider or model. This makes changing an agent endpoint trivial and furthermore multi-endpoint functionality, where inside a single agent several endpoints are implemented, quite easy.
 
-The [simple example](examples/simple.py) above does not fully illustrate how these features of RoboZ work. For that see [complex example](examples/complex.py) example below.
+To see the above in practice see the [complex example](examples/complex.py) example below.
 
 
 
@@ -145,14 +147,15 @@ The [simple example](examples/simple.py) above does not fully illustrate how the
 
 In the code example below we illustrate some of the features that make RoboZ different from other frameworks.
 
-**Tool chaining** is usually introduced via the decorator argument `chained_to` which indicates the name of the tool whose output is passed as the input. The input/output contract must be Liskov compatible, i.e the upstream output must be a subclass of the downstream input. A possible chain condition can be passed in via the `chain_condition` callable, which uses by definition the tool's input argument and returns a boolean. The chain condition must evaluate to at most one true condition, but it can evaluate to `false` on all links, in which case you return to the default tool(s). `AgentMode.STEERABLE` and `AgentMode.AUTONOMOUS` construct a `prompt_agent` tool backed by the agent endpoint; `AgentMode.DETERMINISTIC` uses the configured default tools.
+**Tool chaining** is usually introduced via the decorator argument `chained_to` which indicates the name of the tool whose output is passed as the input (the tools also possess a `.chain` method). The input/output contract must be Liskov compatible, i.e the upstream output must be a subclass of the downstream input. A possible `chain_condition` can be passed in, which by definition has access to the tool's input argument and returns a boolean. The chain condition must evaluate to at most one true condition, but it can evaluate to `false` on all links, in which case you return to the default tool(s). `AgentMode.STEERABLE` and `AgentMode.AUTONOMOUS` construct a `prompt_agent` tool backed by the agent endpoint; `AgentMode.DETERMINISTIC` uses the configured default tools.
 
 The `escalate` is an example of a **tool factory**, which is a simple concept. It accepts a context parameter which is added to the tool's closure and calling the factory with a context argument returns a tool. A very common use case is a tool with an endpoint as a context. In RoboZ all llm **endpoints are instances**, so it is easy to have a specific endpoint for a tool, that is different from that of the agent, below we construct deterministic mock endpoints so that no API keys are required for the examples. Factories have precisely the same chaining arguments in their decorator as a tool.
 
-Another useful feature demonstrated below in the `escalate` factory is **message truncation**. This parameter is present in all output types and allows the tool to decide if the output should be visible in the conversation passed on to the agent. It can truncate partially (show only n chars or just a caller stub) or completely. Importantly, we can choose to start applying the truncation only after the complete message has been shown to the agent n times. Below, we choose to show the message once and then truncate it completely, as useful pattern for example for long tracebacks etc.
+Also demonstrated in the `escalate` factory is the **message truncation** feature. This parameter is present in all output types and allows the tool to decide if the output should be visible in the conversation passed on to the agent. A message can be truncated partially (show only n chars or just a caller stub) or completely. Importantly, we can choose to start applying the truncation only after the complete message has been shown to the agent n times. Below, we choose to show the message once and then truncate it completely, a useful pattern for example for long tracebacks etc.
 
-All RoboZ tools by definition include the full conversation **messages** as input. They are not intended to be altered in place (although they can be and this is how e.g. *compactification* works), but can be used to alter the behavior of tools in a non-trivial way. For example, a start up hook intended to show the agent some information at the start or performing some initial maintenance can simply be one of the default tools that checks if it has already been called and if it has, does nothing.
+All RoboZ tools by definition include the full **conversation messages** as input. These are not intended to be altered in place (although they can be and this is how e.g. *conversation compactification* works), but can be used to alter the behavior of tools in a non-trivial way. For example, a start up hook intended to show the agent some information at the start or performing some initial maintenance can simply be one of the default tools that checks if it has already been called and if it has, does nothing.
 
+**The tool instruction is its docstring**. In addition, the system prompt includes a *technical prompt* by default that gives the specific tool calling instructions. This can of course be switched off. When in doubt, you can always use the method `.show_agent_info()` to check the complete agent configuration including the system prompt, tools, dependencies, persistence locations etc.
 
 
 
@@ -227,12 +230,12 @@ agent.invoke()
 
 The above [complex example](examples/complex.py) can be run from the root with
 
-```python
+```bash
 uv run python examples/complex.py
 ```
 
 
-## Try it
+## Try it out
 
 ```bash
 uv add roboz
@@ -244,29 +247,21 @@ Or with pip:
 python -m pip install roboz
 ```
 
-## Optional ecosystem
-
-Start with core and add only the integrations the application needs.
-
-| Distribution | Adds |
-| --- | --- |
-| `roboshed` | Guarded file and CLI tools, memory, compaction, reusable agents, and deployment recipes. |
-| `roboz-endpoints` | Lazy model catalogues and SDK adapters for OpenAI-compatible providers. |
-| `roboz-proton-bridge` | Proton Bridge email tools. |
+## Packages
 
-See the [add-on guide](docs/addons.md) for installation and composition, and the
-[endpoint guide](packages/endpoints/README.md) for model selection and provider
-adapters.
+This repository contains four independently versioned Python distributions.
+They share development and release tooling, but are published separately so an
+application only needs to install the parts it uses.
 
-## Documentation
+| Distribution | Import | Provides |
+| --- | --- | --- |
+| `roboz` | `roboz` | Core agent, tool, workflow, endpoint, and runtime primitives. |
+| [`roboshed`](packages/shed/README.md) | `roboshed` | Reusable capabilities, guarded system tools, memory, agents, and deployment building blocks. |
+| [`roboz-endpoints`](packages/endpoints/README.md) | `roboz_endpoints` | Model catalogues and optional provider adapters. |
+| [`roboz-proton-bridge`](packages/proton-bridge/README.md) | `roboz_proton_bridge` | Proton Bridge email integration. |
 
-| Guide | Start here for |
-| --- | --- |
-| [Tool authoring](docs/tool-authoring.md) | Chaining, factories, conditions, and typed handoffs |
-| [Agent authoring](docs/agent-authoring.md) | Agent composition and prompt policy |
-| [Reference](docs/reference.md) | Runtime and API semantics |
-| [Complex chaining and truncation example](examples/complex.py) | Conditional chains, factory endpoints, and message visibility |
-| [Testing practices](docs/testing-practices.md) | Deterministic workflow and contract tests |
+The companion packages build on `roboz`; `roboz-proton-bridge` also uses
+`roboshed`.
 
 ## Development
 
@@ -278,8 +273,9 @@ uv run pyright
 bash scripts/run_type_tests.sh
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and the
-[build and test guide](docs/build-and-test.md) for the complete release gate.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and testing guidance. The
+[verification workflow](.github/workflows/verify.yml) defines the complete CI
+gate.
 Roboz is typed and ships a PEP 561 `py.typed` marker.
 
 ## License

{roboz-0.1.2.dev7 → roboz-0.1.2.dev8}/README.md

@@ -8,7 +8,7 @@
   <p><strong>Chain tools. Skip calls.</strong></p>
 </div>
 
-RoboZ is a framework for building llm powered agents. The core ingredient is that every tool can may be chained conditionally to a subsequent tool thus allowing easy injection of deterministic flows into agentic processes.
+RoboZ is a framework for building llm powered agents. The core ingredient is that every tool may be chained conditionally to a subsequent tool thus allowing easy injection of deterministic flows into agentic processes.
 
 [![CI](https://github.com/Tachion-Oy/roboz/actions/workflows/ci.yml/badge.svg)](https://github.com/Tachion-Oy/roboz/actions/workflows/ci.yml)
 [![Python 3.13+](https://img.shields.io/badge/Python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
@@ -29,10 +29,10 @@ Suppose the task we want to achieve is ask our buddy Bob out to lunch and then b
 - Find a restaurant
 - Book a table.
 
-In the usual approach an agent is presented each MCP server separately in the their system prompt and it must call them one-by-one to complete the task. When the agent is completing the task, at every turn it must choose the correct tool, formulate its output accordingly and absorb the reply into its context, which already must contain the specific instructions on how to use each tool. In addition, at each turn one has to wait for the llm to reply, each reply costs tokens and each reply risks a mistake from the llm.
+In the usual approach an agent is presented each MCP server separately in their system prompt and it must call them one-by-one to complete the task. When the agent is completing the task, at every turn it must choose the correct tool, formulate its output accordingly and absorb the reply into its context, which already must contain the specific instructions on how to use each tool. In addition, at each turn one has to wait for the llm to reply, each reply costs tokens and each reply risks a mistake from the llm.
 
 ### Deterministic chains
-The philosophy in RoboZ is that of a a workflow is (mostly) deterministic an only on occasion does one need to call an llm. For example in RoboZ an agent would trigger the "ask Bob if they wan to have lunch" tool and all subsequent steps come by chaining: each tool can be chained to other tools upstream where their outputs are passed down the chain. Each link/edge may introduce a True/False condition, in our case for example if Bob interested in having lunch (with us). If he is not, RoboZ allows for the chain to break and returns back to the default tool, which for an agentic process is usually "ask the llm what to do next". The default mode is that chained tools are not presented to the agent, they are thus *passive* or in other words their role is strictly in forming deterministic workflows and they cannot be invoked.
+The philosophy in RoboZ is that a workflow is (mostly) deterministic and only on occasion does one need to call an llm. For example in RoboZ an agent would trigger the "ask Bob if they want to have lunch" tool and all subsequent steps come by chaining: each tool can be chained to other tools upstream where their outputs are passed down the chain. Each link/edge may introduce a True/False condition, in our case for example if Bob is interested in having lunch (with us). If he is not, RoboZ allows for the chain to break and returns back to the default tool, which for an agentic process is usually "ask the llm what to do next". The default mode is that chained tools are not presented to the agent, they are thus *passive* or in other words their role is strictly in forming deterministic workflows and they cannot be invoked.
 
 Chaining not only reduces the llm calls, but it also provides a useful way of introducing a fine-grained guard layer for tool calls. This is in fact precisely how the cli tools and their access policies work in Roboz. For a cli command a chained passive tool evaluates the intent and breaks the chain if policies are violated.
 
@@ -70,19 +70,21 @@ output, messages_ = agent.invoke()
 print(f'"{output.value}"')
 ```
 
-The above [simple example](examples/simple.py) can be run from the root with 
+The above [simple example](examples/simple.py) uses the accompanying
+[quote file](examples/simpsons_quotes.py) in this repository. Run it from the
+repository root with
 
-```python
+```bash
 uv run python examples/simple.py
 ```
 It creates an agent that returns a random
-Simpsons quote. It uses a mock endpoint, with pre-determined replies, so you can run it without API keys.
+Simpsons quote. **The docstring in the tool is the instruction that the agent sees**. It uses a mock endpoint, with pre-determined replies, so you can run it without API keys.
 The main contracts of RoboZ are already visible:
 
 - `@tool` creates an instance of a usable tool for the agent
 -  A tool's input and output are typed. Tools also receive the entire message stack
-- Callable endpoints are single instances, as a hard rule 
-- Different output types impact the dymanics, importantly `Stop` breaks out of the agentic loop
+- Callable endpoints are single instances, as a hard rule
+- Different output types impact the dynamics, importantly `Stop` breaks out of the agentic loop
 - `agent.invoke()` runs the agent and returns its output `Stop` and messages.
 
 The above does not show the main idea of tool chaining, for that read the following sections.
@@ -90,7 +92,7 @@ The above does not show the main idea of tool chaining, for that read the follow
 
 An agent is a loop that calls tools. Everything is defined as a tool: Skills,  background agents, prompting the agent, prompting the user, running nested agents, start up hooks etc. Everything.
 
-**A tool can be trigger in three ways:**
+**A tool can be triggered in three ways:**
 - **Invoked by an agent**: The `prompt_agent` tool asks an LLM what to do next and its `Invoke` output always calls another tool. It is constructed internally for `AgentMode.STEERABLE` and `AgentMode.AUTONOMOUS` agents, but it is still just a tool.
 - **By chaining**. After an invoked tool has fired RoboZ checks if a chained tool with a *true* chain condition exists (for more than one *true* condition for a fork you get a runtime error). If yes, the output is passed on and the process repeats until the first broken chain or all chained tools are exhausted
 - **As default tools**. Once the tool chain is exhausted or the chain breaks due to a *false* condition the loop returns to the freely defined `default_tool` (there actually can be many, they are all called in sequence).
@@ -101,13 +103,13 @@ RoboZ then collapses to the traditional agentic approach as a special case if on
 ### Tool Chaining
 This may be used to reduce the number of llm calls, leading to a speed increase, lower cost and fewer AI errors. It also provides a useful way of introducing a guard layer for tool calls, which can be used to restrict agentic actions.
 ### Output Truncation
-A Tools output can be hidden from the llm, also partially, and this can start to apply after the message has been shown N times.
+A tool’s output can be hidden from the llm, also partially, and this can start to apply after the message has been shown N times.
 ### Tool outputs are typed
-The contract in RoboZ is that all tool calls and hence in everything that happens is that outputs are typed classes. Agents and tools never exchange raw strings or even JSON, typed classes and validation are present throughout, with designated classes for tasks such as `Invoke` and `Stop`.
-### LLm Endpoints are instances
-As strict design rule in Roboz, everything that depends on an LLM call must be trivially swappable to another provider or model. This makes changing an agent endpoint trivial and furthermore multi-endpoint functionality, where inside a single agent several endpoints are implemented, quite easy.
+The contract in RoboZ is that every action in the agentic loop is a tool call and all outputs are typed classes. Raw strings or JSON is never exchanged (unless explicitly opted in) as is and typed classes and validation are present throughout, with designated classes for tasks such as `Invoke` and `Stop`.
+### LLM Endpoints are instances
+As a fundamental design rule in Roboz, everything that depends on an LLM call must be trivially swappable to another provider or model. This makes changing an agent endpoint trivial and furthermore multi-endpoint functionality, where inside a single agent several endpoints are implemented, quite easy.
 
-The [simple example](examples/simple.py) above does not fully illustrate how these features of RoboZ work. For that see [complex example](examples/complex.py) example below.
+To see the above in practice see the [complex example](examples/complex.py) example below.
 
 
 
@@ -116,14 +118,15 @@ The [simple example](examples/simple.py) above does not fully illustrate how the
 
 In the code example below we illustrate some of the features that make RoboZ different from other frameworks.
 
-**Tool chaining** is usually introduced via the decorator argument `chained_to` which indicates the name of the tool whose output is passed as the input. The input/output contract must be Liskov compatible, i.e the upstream output must be a subclass of the downstream input. A possible chain condition can be passed in via the `chain_condition` callable, which uses by definition the tool's input argument and returns a boolean. The chain condition must evaluate to at most one true condition, but it can evaluate to `false` on all links, in which case you return to the default tool(s). `AgentMode.STEERABLE` and `AgentMode.AUTONOMOUS` construct a `prompt_agent` tool backed by the agent endpoint; `AgentMode.DETERMINISTIC` uses the configured default tools.
+**Tool chaining** is usually introduced via the decorator argument `chained_to` which indicates the name of the tool whose output is passed as the input (the tools also possess a `.chain` method). The input/output contract must be Liskov compatible, i.e the upstream output must be a subclass of the downstream input. A possible `chain_condition` can be passed in, which by definition has access to the tool's input argument and returns a boolean. The chain condition must evaluate to at most one true condition, but it can evaluate to `false` on all links, in which case you return to the default tool(s). `AgentMode.STEERABLE` and `AgentMode.AUTONOMOUS` construct a `prompt_agent` tool backed by the agent endpoint; `AgentMode.DETERMINISTIC` uses the configured default tools.
 
 The `escalate` is an example of a **tool factory**, which is a simple concept. It accepts a context parameter which is added to the tool's closure and calling the factory with a context argument returns a tool. A very common use case is a tool with an endpoint as a context. In RoboZ all llm **endpoints are instances**, so it is easy to have a specific endpoint for a tool, that is different from that of the agent, below we construct deterministic mock endpoints so that no API keys are required for the examples. Factories have precisely the same chaining arguments in their decorator as a tool.
 
-Another useful feature demonstrated below in the `escalate` factory is **message truncation**. This parameter is present in all output types and allows the tool to decide if the output should be visible in the conversation passed on to the agent. It can truncate partially (show only n chars or just a caller stub) or completely. Importantly, we can choose to start applying the truncation only after the complete message has been shown to the agent n times. Below, we choose to show the message once and then truncate it completely, as useful pattern for example for long tracebacks etc.
+Also demonstrated in the `escalate` factory is the **message truncation** feature. This parameter is present in all output types and allows the tool to decide if the output should be visible in the conversation passed on to the agent. A message can be truncated partially (show only n chars or just a caller stub) or completely. Importantly, we can choose to start applying the truncation only after the complete message has been shown to the agent n times. Below, we choose to show the message once and then truncate it completely, a useful pattern for example for long tracebacks etc.
 
-All RoboZ tools by definition include the full conversation **messages** as input. They are not intended to be altered in place (although they can be and this is how e.g. *compactification* works), but can be used to alter the behavior of tools in a non-trivial way. For example, a start up hook intended to show the agent some information at the start or performing some initial maintenance can simply be one of the default tools that checks if it has already been called and if it has, does nothing.
+All RoboZ tools by definition include the full **conversation messages** as input. These are not intended to be altered in place (although they can be and this is how e.g. *conversation compactification* works), but can be used to alter the behavior of tools in a non-trivial way. For example, a start up hook intended to show the agent some information at the start or performing some initial maintenance can simply be one of the default tools that checks if it has already been called and if it has, does nothing.
 
+**The tool instruction is its docstring**. In addition, the system prompt includes a *technical prompt* by default that gives the specific tool calling instructions. This can of course be switched off. When in doubt, you can always use the method `.show_agent_info()` to check the complete agent configuration including the system prompt, tools, dependencies, persistence locations etc.
 
 
 
@@ -198,12 +201,12 @@ agent.invoke()
 
 The above [complex example](examples/complex.py) can be run from the root with
 
-```python
+```bash
 uv run python examples/complex.py
 ```
 
 
-## Try it
+## Try it out
 
 ```bash
 uv add roboz
@@ -215,29 +218,21 @@ Or with pip:
 python -m pip install roboz
 ```
 
-## Optional ecosystem
-
-Start with core and add only the integrations the application needs.
-
-| Distribution | Adds |
-| --- | --- |
-| `roboshed` | Guarded file and CLI tools, memory, compaction, reusable agents, and deployment recipes. |
-| `roboz-endpoints` | Lazy model catalogues and SDK adapters for OpenAI-compatible providers. |
-| `roboz-proton-bridge` | Proton Bridge email tools. |
+## Packages
 
-See the [add-on guide](docs/addons.md) for installation and composition, and the
-[endpoint guide](packages/endpoints/README.md) for model selection and provider
-adapters.
+This repository contains four independently versioned Python distributions.
+They share development and release tooling, but are published separately so an
+application only needs to install the parts it uses.
 
-## Documentation
+| Distribution | Import | Provides |
+| --- | --- | --- |
+| `roboz` | `roboz` | Core agent, tool, workflow, endpoint, and runtime primitives. |
+| [`roboshed`](packages/shed/README.md) | `roboshed` | Reusable capabilities, guarded system tools, memory, agents, and deployment building blocks. |
+| [`roboz-endpoints`](packages/endpoints/README.md) | `roboz_endpoints` | Model catalogues and optional provider adapters. |
+| [`roboz-proton-bridge`](packages/proton-bridge/README.md) | `roboz_proton_bridge` | Proton Bridge email integration. |
 
-| Guide | Start here for |
-| --- | --- |
-| [Tool authoring](docs/tool-authoring.md) | Chaining, factories, conditions, and typed handoffs |
-| [Agent authoring](docs/agent-authoring.md) | Agent composition and prompt policy |
-| [Reference](docs/reference.md) | Runtime and API semantics |
-| [Complex chaining and truncation example](examples/complex.py) | Conditional chains, factory endpoints, and message visibility |
-| [Testing practices](docs/testing-practices.md) | Deterministic workflow and contract tests |
+The companion packages build on `roboz`; `roboz-proton-bridge` also uses
+`roboshed`.
 
 ## Development
 
@@ -249,8 +244,9 @@ uv run pyright
 bash scripts/run_type_tests.sh
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and the
-[build and test guide](docs/build-and-test.md) for the complete release gate.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and testing guidance. The
+[verification workflow](.github/workflows/verify.yml) defines the complete CI
+gate.
 Roboz is typed and ships a PEP 561 `py.typed` marker.
 
 ## License

{roboz-0.1.2.dev7 → roboz-0.1.2.dev8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roboz"
-version = "0.1.2.dev7"
+version = "0.1.2.dev8"
 description = "Typed primitives for composable agentic workflows"
 readme = "README.md"
 authors = [{ name = "Tachion Oy" }]
@@ -51,7 +51,7 @@ include = ["/src/roboz", "/README.md", "/CHANGELOG.md", "/LICENSE", "/pyproject.
 Homepage = "https://github.com/Tachion-Oy/roboz"
 Repository = "https://github.com/Tachion-Oy/roboz"
 Issues = "https://github.com/Tachion-Oy/roboz/issues"
-Documentation = "https://github.com/Tachion-Oy/roboz/tree/main/docs"
+Documentation = "https://github.com/Tachion-Oy/roboz#readme"
 
 [tool.pytest.ini_options]
 addopts = "--cov=roboz --cov-report=term-missing --ignore=tests/type_tests"

{roboz-0.1.2.dev7 → roboz-0.1.2.dev8}/src/roboz/agent/core.py

@@ -176,6 +176,8 @@ class Agent(HasExternalDependencies):
                 "Model-driven flows require a non-empty system_prompt."
             )
         self.default_tools = [] if default_tools is None else list(default_tools)
+        if self.mode is AgentMode.DETERMINISTIC and not self.default_tools:
+            raise ValueError("No default tools for a deterministic instance.")
         if (
             not self.mode.allows_user_interaction
             and custom_prompt_user_tool is not None
@@ -261,22 +263,20 @@ class Agent(HasExternalDependencies):
         }
         return Agent(**(old_input | overrides))
 
-    def _init_default_tool(self):
-        if self.mode is not AgentMode.DETERMINISTIC:
-            endpoint = self.agent_endpoint
-            if endpoint is None:
-                raise RuntimeError("model-driven instance has no endpoint")
-            self.master_tool = prompt_agent(
-                PromptAgentContext(
-                    active_tools=tuple(self.active_tools.values()),
-                    endpoint=endpoint,
-                    pipe=self.pipe,
-                )
-            )
+    def _init_prompt_agent_tool(self) -> None:
+        if self.mode is AgentMode.DETERMINISTIC:
+            self._prompt_agent_tool = None
             return
-        if not self.default_tools:
-            raise ValueError("No default tools for a deterministic instance.")
-        self.master_tool = self.default_tools[0]
+        endpoint = self.agent_endpoint
+        if endpoint is None:
+            raise RuntimeError("model-driven instance has no endpoint")
+        self._prompt_agent_tool = prompt_agent(
+            PromptAgentContext(
+                active_tools=tuple(self.active_tools.values()),
+                endpoint=endpoint,
+                pipe=self.pipe,
+            )
+        )
 
     def _init_tools(self, *, tools: Sequence[Tool], skill: Skill | None):
         for t in self.default_tools:
@@ -295,8 +295,8 @@ class Agent(HasExternalDependencies):
                 self.passive_tools[t.id] = t
                 continue
             self.active_tools[t.id] = t
-        self._init_default_tool()
-        self._validate_tool_chains(all_tools | {self.master_tool})
+        self._init_prompt_agent_tool()
+        self._validate_tool_chains(all_tools)
 
     def external_dependencies(
         self,
@@ -305,7 +305,7 @@ class Agent(HasExternalDependencies):
     ) -> tuple[ExternalDependency, ...]:
         """Derive the agent's dependency catalog exclusively from its Tool graph."""
         tools: list[Tool | None] = [
-            self.master_tool,
+            self._prompt_agent_tool,
             self.prompt_user_tool,
             *self.default_tools,
             *self.active_tools.values(),
@@ -417,8 +417,8 @@ class Agent(HasExternalDependencies):
         """Return the next default tool, starting a new scheduling cycle as needed."""
         if not self._ephemeral_default_tools:
             self._ephemeral_default_tools = list(self.default_tools)
-            if self.mode is not AgentMode.DETERMINISTIC:
-                self._ephemeral_default_tools.append(self.master_tool)
+            if self._prompt_agent_tool is not None:
+                self._ephemeral_default_tools.append(self._prompt_agent_tool)
         return self._ephemeral_default_tools.pop(0)
 
     def append_and_pipe(self, message: Message):
@@ -528,7 +528,7 @@ class Agent(HasExternalDependencies):
                 }
             )
             self._init_skill(output)
-            tool = self.get_next_tool(self.master_tool, output)
+            tool = self.get_next_tool(self._prompt_agent_tool, output)
             output = tool(output, self.messages)
             self.append_and_pipe(
                 get_finalized_message(
@@ -719,6 +719,7 @@ class Agent(HasExternalDependencies):
         conf_table.add_column("Name", style="cyan")
         conf_table.add_column("Description")
         conf_table.add_column("Chained To")
+        conf_table.add_column("External Dependencies")
 
         no_description = "Not provided"
 
@@ -727,21 +728,36 @@ class Agent(HasExternalDependencies):
                 return "-"
             return ", ".join([c.name for c in t.chained_to])
 
-        conf_table.add_row(
-            "Main Prompter",
-            self.master_tool.name if self.master_tool.name else "Not set",
-            f"Configured for {self.mode} execution.",
-            "-",
-        )
+        def _get_external_dependencies(tools: Sequence[Tool]) -> str:
+            dependencies = dedupe_external_dependencies(
+                dependency
+                for tool in tools
+                for dependency in tool.external_dependencies()
+            )
+            if not dependencies:
+                return "-"
+            return ", ".join(
+                f"{dependency.dependency_id} ({dependency.kind.value})"
+                for dependency in dependencies
+            )
 
-        for id, t in self.active_tools.items():
-            if id != self.master_tool.id:
-                conf_table.add_row(
-                    "Active",
-                    t.name,
-                    t.description or no_description,
-                    _get_chained_to(t),
-                )
+        if self._prompt_agent_tool is not None:
+            conf_table.add_row(
+                "Prompter",
+                self._prompt_agent_tool.name or "Not set",
+                f"Configured for {self.mode} execution.",
+                "-",
+                _get_external_dependencies((self._prompt_agent_tool,)),
+            )
+
+        for t in self.active_tools.values():
+            conf_table.add_row(
+                "Active",
+                t.name,
+                t.description or no_description,
+                _get_chained_to(t),
+                _get_external_dependencies((t,)),
+            )
 
         for id, t in self.passive_tools.items():
             conf_table.add_row(
@@ -749,6 +765,7 @@ class Agent(HasExternalDependencies):
                 t.name,
                 t.description or no_description,
                 _get_chained_to(t),
+                _get_external_dependencies((t,)),
             )
 
         default_tool_names = (
@@ -761,6 +778,7 @@ class Agent(HasExternalDependencies):
             default_tool_names,
             "Configured fallback tool list.",
             "-",
+            _get_external_dependencies(self.default_tools),
         )
 
         console.print(conf_table, end="\n\n")