roboz 0.1.2.dev9__tar.gz → 0.1.2.dev10__tar.gz

{roboz-0.1.2.dev9 → roboz-0.1.2.dev10}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.1.2.dev10 - 2026-09-21
+
+- Define default tools as scheduler-owned chain roots: downstream tools can now
+  reference a default-only parent with `chained_to`, while defaults that are
+  themselves chained downstream are rejected during agent construction.
+
 ## 0.1.2.dev9 - 2026-09-20
 
 - Remove the leftover `proton-bridge-beta` installation extra. Install

{roboz-0.1.2.dev9 → roboz-0.1.2.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roboz
-Version: 0.1.2.dev9
+Version: 0.1.2.dev10
 Import-Name: roboz
 Summary: Typed primitives for composable agentic workflows
 Project-URL: Homepage, https://github.com/Tachion-Oy/roboz
@@ -122,7 +122,7 @@ An agent is a loop that calls tools. Everything is defined as a tool: Skills,  b
 **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).
+- **As default tools**. Defaults are ordered chain roots owned by the scheduler. When no chained successor exists, they run in configuration order; a default may feed downstream tools, and the sequence resumes with the next default after that branch ends. A default cannot itself be downstream, so it cannot declare `chained_to`.
 
 RoboZ then collapses to the traditional agentic approach as a special case if one just has the `prompt_agent` as the default with no chaining. An `AgentMode.DETERMINISTIC` agent has no `prompt_agent`; its default tools perform tasks directly, allowing deterministic branching through chaining. This is useful for a background agent that performs periodic maintenance work. `AgentMode.STEERABLE` agents may ask the user for input, while `AgentMode.AUTONOMOUS` agents cannot.
 
@@ -145,7 +145,7 @@ To see the above in practice see the [complex example](https://github.com/Tachio
 
 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 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.
+**Tool chaining** is usually introduced via the decorator argument `chained_to`, which points from a downstream tool to the upstream tool whose output becomes its input (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 scheduling resumes with the next configured default. Defaults may be referenced as upstream parents without also appearing in `tools`, but cannot declare `chained_to` themselves. `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.
 

{roboz-0.1.2.dev9 → roboz-0.1.2.dev10}/README.md

@@ -95,7 +95,7 @@ An agent is a loop that calls tools. Everything is defined as a tool: Skills,  b
 **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).
+- **As default tools**. Defaults are ordered chain roots owned by the scheduler. When no chained successor exists, they run in configuration order; a default may feed downstream tools, and the sequence resumes with the next default after that branch ends. A default cannot itself be downstream, so it cannot declare `chained_to`.
 
 RoboZ then collapses to the traditional agentic approach as a special case if one just has the `prompt_agent` as the default with no chaining. An `AgentMode.DETERMINISTIC` agent has no `prompt_agent`; its default tools perform tasks directly, allowing deterministic branching through chaining. This is useful for a background agent that performs periodic maintenance work. `AgentMode.STEERABLE` agents may ask the user for input, while `AgentMode.AUTONOMOUS` agents cannot.
 
@@ -118,7 +118,7 @@ To see the above in practice see the [complex example](https://github.com/Tachio
 
 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 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.
+**Tool chaining** is usually introduced via the decorator argument `chained_to`, which points from a downstream tool to the upstream tool whose output becomes its input (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 scheduling resumes with the next configured default. Defaults may be referenced as upstream parents without also appearing in `tools`, but cannot declare `chained_to` themselves. `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.
 

{roboz-0.1.2.dev9 → roboz-0.1.2.dev10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roboz"
-version = "0.1.2.dev9"
+version = "0.1.2.dev10"
 description = "Typed primitives for composable agentic workflows"
 readme = "README.md"
 authors = [{ name = "Tachion Oy" }]

{roboz-0.1.2.dev9 → roboz-0.1.2.dev10}/src/roboz/agent/core.py

@@ -83,6 +83,14 @@ class Agent(HasExternalDependencies):
     list of callbacks attached to a newly created pipe. Hosts compose CLI,
     run-scoped, process-scoped, or agent-specific callbacks before creating the
     agent; Agent does not construct or distinguish those scopes.
+
+    ``default_tools`` are scheduler-owned chain roots. The scheduler runs them in
+    configuration order whenever the current tool has no chained successor, then
+    repeats that sequence in the next cycle. A downstream tool may declare
+    ``chained_to=default_tool``; when that branch ends, scheduling resumes with the
+    next configured default. A default tool cannot itself declare ``chained_to``
+    because defaults cannot be downstream tools. Default-only tools remain hidden
+    from the model-facing active and passive registries.
     """
 
     def __init__(
@@ -280,23 +288,27 @@ class Agent(HasExternalDependencies):
 
     def _init_tools(self, *, tools: Sequence[Tool], skill: Skill | None):
         for t in self.default_tools:
+            if t.chained_to:
+                raise ValueError(
+                    f"Default tool '{t.name}' cannot declare chained_to"
+                )
             if any(
                 issubclass(output_type, Invoke)
                 for output_type in get_constituent_types(t.OutputModel)
             ):
                 raise ValueError(f"Default tool '{t.name}' cannot return Invoke")
 
-        all_tools = set(tools)
+        registered_tools = set(tools)
         if skill:
-            all_tools |= set(skill.tools)
+            registered_tools |= set(skill.tools)
 
-        for t in all_tools:
+        for t in registered_tools:
             if t.chained_to:
                 self.passive_tools[t.id] = t
                 continue
             self.active_tools[t.id] = t
         self._init_prompt_agent_tool()
-        self._validate_tool_chains(all_tools)
+        self._validate_tool_chains(registered_tools | set(self.default_tools))
 
     def external_dependencies(
         self,

{roboz-0.1.2.dev9 → roboz-0.1.2.dev10}/src/roboz/deployment.py

@@ -41,8 +41,12 @@ class AgentCapability(Protocol):
 class Capability(AgentCapability):
     """Already-bound tools and skills that provide an agent feature.
 
-    Tools shared between a chain and default execution retain their identity.
-    Supplied objects remain caller-owned and require no owner configuration.
+    ``default_tools`` are ordered, repeatedly scheduled chain roots. A tool in
+    ``tools`` may declare ``chained_to`` with one of those defaults as its parent,
+    and scheduling resumes with the next default when the downstream branch ends.
+    Defaults cannot themselves declare ``chained_to``. Tools shared between
+    ``tools`` and ``default_tools`` retain their identity. Supplied objects remain
+    caller-owned and require no owner configuration.
     """
 
     tools: tuple[Tool | Sequence[Tool], ...] = ()