roboz 0.1.2.dev9__tar.gz → 0.1.2.dev11__tar.gz

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

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.1.2.dev11 - 2026-09-21
+
+- Ship the simple and complex examples in `roboz.examples`, so installed users
+  can run the credential-free agent demo with `python -m roboz.examples.simple`
+  without cloning the repository.
+
+## 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.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roboz
-Version: 0.1.2.dev9
+Version: 0.1.2.dev11
 Import-Name: roboz
 Summary: Typed primitives for composable agentic workflows
 Project-URL: Homepage, https://github.com/Tachion-Oy/roboz
@@ -69,9 +69,8 @@ Chaining not only reduces the llm calls, but it also provides a useful way of in
 ```python
 from random import choice
 
-from simpsons_quotes import QUOTES
-
 from roboz import Agent, tool
+from roboz.examples.simpsons_quotes import QUOTES
 from roboz.llm.endpoints import MockLLMEndpoint
 from roboz.models import Empty, Message, Stop
 
@@ -97,12 +96,12 @@ output, messages_ = agent.invoke()
 print(f'"{output.value}"')
 ```
 
-The above [simple example](https://github.com/Tachion-Oy/roboz/blob/main/examples/simple.py) uses the accompanying
-[quote file](https://github.com/Tachion-Oy/roboz/blob/main/examples/simpsons_quotes.py) in this repository. Run it from the
-repository root with
+The above [simple example](https://github.com/Tachion-Oy/roboz/blob/main/src/roboz/examples/simple.py) uses the accompanying
+[quote file](https://github.com/Tachion-Oy/roboz/blob/main/src/roboz/examples/simpsons_quotes.py). First add RoboZ to your
+environment as shown in [Try it out](#try-it-out), then run it with
 
 ```bash
-uv run python examples/simple.py
+uv run python -m roboz.examples.simple
 ```
 It creates an agent that returns a random
 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.
@@ -122,7 +121,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.
 
@@ -136,7 +135,7 @@ The contract in RoboZ is that every action in the agentic loop is a tool call an
 ### 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.
 
-To see the above in practice see the [complex example](https://github.com/Tachion-Oy/roboz/blob/main/examples/complex.py) example below.
+To see the above in practice see the [complex example](https://github.com/Tachion-Oy/roboz/blob/main/src/roboz/examples/complex.py) below.
 
 
 
@@ -145,7 +144,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.
 
@@ -226,23 +225,29 @@ agent.invoke()
 
 ```
 
-The above [complex example](https://github.com/Tachion-Oy/roboz/blob/main/examples/complex.py) can be run from the root with
+The above [complex example](https://github.com/Tachion-Oy/roboz/blob/main/src/roboz/examples/complex.py) is also bundled with
+RoboZ. First add the library to your environment as shown in
+[Try it out](#try-it-out), then run it with
 
 ```bash
-uv run python examples/complex.py
+uv run python -m roboz.examples.complex
 ```
 
 
 ## Try it out
 
+Add RoboZ to a uv project and run the same bundled example:
+
 ```bash
 uv add roboz
+uv run python -m roboz.examples.simple
 ```
 
-Or with pip:
+or with pip, install RoboZ into the active environment first:
 
 ```bash
 python -m pip install roboz
+python -m roboz.examples.simple
 ```
 
 ## Packages

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

@@ -42,9 +42,8 @@ Chaining not only reduces the llm calls, but it also provides a useful way of in
 ```python
 from random import choice
 
-from simpsons_quotes import QUOTES
-
 from roboz import Agent, tool
+from roboz.examples.simpsons_quotes import QUOTES
 from roboz.llm.endpoints import MockLLMEndpoint
 from roboz.models import Empty, Message, Stop
 
@@ -70,12 +69,12 @@ output, messages_ = agent.invoke()
 print(f'"{output.value}"')
 ```
 
-The above [simple example](https://github.com/Tachion-Oy/roboz/blob/main/examples/simple.py) uses the accompanying
-[quote file](https://github.com/Tachion-Oy/roboz/blob/main/examples/simpsons_quotes.py) in this repository. Run it from the
-repository root with
+The above [simple example](https://github.com/Tachion-Oy/roboz/blob/main/src/roboz/examples/simple.py) uses the accompanying
+[quote file](https://github.com/Tachion-Oy/roboz/blob/main/src/roboz/examples/simpsons_quotes.py). First add RoboZ to your
+environment as shown in [Try it out](#try-it-out), then run it with
 
 ```bash
-uv run python examples/simple.py
+uv run python -m roboz.examples.simple
 ```
 It creates an agent that returns a random
 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.
@@ -95,7 +94,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.
 
@@ -109,7 +108,7 @@ The contract in RoboZ is that every action in the agentic loop is a tool call an
 ### 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.
 
-To see the above in practice see the [complex example](https://github.com/Tachion-Oy/roboz/blob/main/examples/complex.py) example below.
+To see the above in practice see the [complex example](https://github.com/Tachion-Oy/roboz/blob/main/src/roboz/examples/complex.py) below.
 
 
 
@@ -118,7 +117,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.
 
@@ -199,23 +198,29 @@ agent.invoke()
 
 ```
 
-The above [complex example](https://github.com/Tachion-Oy/roboz/blob/main/examples/complex.py) can be run from the root with
+The above [complex example](https://github.com/Tachion-Oy/roboz/blob/main/src/roboz/examples/complex.py) is also bundled with
+RoboZ. First add the library to your environment as shown in
+[Try it out](#try-it-out), then run it with
 
 ```bash
-uv run python examples/complex.py
+uv run python -m roboz.examples.complex
 ```
 
 
 ## Try it out
 
+Add RoboZ to a uv project and run the same bundled example:
+
 ```bash
 uv add roboz
+uv run python -m roboz.examples.simple
 ```
 
-Or with pip:
+or with pip, install RoboZ into the active environment first:
 
 ```bash
 python -m pip install roboz
+python -m roboz.examples.simple
 ```
 
 ## Packages

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

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

{roboz-0.1.2.dev9 → roboz-0.1.2.dev11}/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.dev11}/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], ...] = ()

roboz-0.1.2.dev11/src/roboz/examples/__init__.py

@@ -0,0 +1 @@
+"""Runnable examples shipped with Roboz."""

roboz-0.1.2.dev11/src/roboz/examples/complex.py

@@ -0,0 +1,72 @@
+"""Run an interactive example of chains, factories, and truncation."""
+
+from builtins import input as read_input
+
+from roboz import Agent, factory, tool
+from roboz.llm import EndpointLike, MockLLMEndpoint, get_completion
+from roboz.models import Empty, Int, Message, Role, Stop, Str, filter_messages
+from roboz.models.truncation import Severity, Truncation
+from roboz.runtime.io import interact_with_user
+from roboz.runtime.sinks import CliSink
+from roboz.tools import stop
+
+
+@tool
+def ask_number(input: Empty, messages: list[Message]) -> Int:
+    """Ask the user for an integer, repeating until the response is valid."""
+    while True:
+        reply = read_input("Enter an integer: ")
+        try:
+            return Int(value=int(reply))
+        except ValueError:
+            print("Please enter an integer :)")
+
+
+@factory(chained_to=ask_number, chain_condition=lambda x: x.value % 2 == 0)
+def escalate(input: Int, messages: list[Message], ctx: EndpointLike) -> Stop | Str:
+    """An even number?! Need to check this with HR!"""
+    interact_with_user("Careful now, that is pretty spicy!", with_reply=False)
+    prompt = f"The user chose {input.value}. Is this too hot to handle?! (y/n)?"
+    verdict = get_completion(
+        endpoint=ctx, messages=[Message(role=Role.SYSTEM, content=prompt)]
+    )
+    is_first_escalation = (
+        len(filter_messages(caller="escalate", messages=messages)) == 0
+    )
+    if verdict == "y" and not is_first_escalation:
+        return Stop(value="Too much spiciness, need to quit!")
+    return Str(
+        value="HR gave a pass, but still, let's show this to the agent only once.",
+        truncation=Truncation(threshold=1, severity=Severity.REMOVE),
+    )
+
+
+@tool(chained_to=ask_number, chain_condition=lambda x: x.value % 2 != 0)
+def give_praise(input: Int, messages: list[Message]) -> Str:
+    """We need to give praise for such an erudite approach to the problem."""
+    interact_with_user(f"{input.value} a fine and bold choice!", with_reply=False)
+    return Str(value=f"{input.value} is good, no biggie.")
+
+
+def main() -> None:
+    """Build and run the interactive example agent."""
+    agent_endpoint = MockLLMEndpoint(
+        responses=[
+            *(10 * [{"action": "ask_number", "rationale": "This is my only job"}]),
+            {"action": "stop", "rationale": "Enough numbers!", "value": ""},
+        ]
+    )
+    guard_endpoint = MockLLMEndpoint(responses=10 * ["y"])
+
+    agent = Agent(
+        name="demo",
+        system_prompt=f"Without exception, use the {ask_number.name} tool.",
+        event_sinks=[CliSink.default()],
+        agent_endpoint=agent_endpoint,
+        tools=[ask_number, escalate(guard_endpoint), give_praise, stop],
+    )
+    agent.invoke()
+
+
+if __name__ == "__main__":
+    main()

roboz-0.1.2.dev11/src/roboz/examples/simple.py

@@ -0,0 +1,36 @@
+"""Run a credential-free agent that returns a random Simpsons quote."""
+
+from random import choice
+
+from roboz import Agent, tool
+from roboz.llm.endpoints import MockLLMEndpoint
+from roboz.models import Empty, Message, Stop
+
+from .simpsons_quotes import QUOTES
+
+
+@tool
+def get_quote(input: Empty, messages: list[Message]) -> Stop:
+    """Return a random Simpsons quote and then stop."""
+    return Stop(value=choice(QUOTES))
+
+
+def main() -> None:
+    """Build and run the credential-free example agent."""
+    mock = MockLLMEndpoint(
+        responses=[{"action": "get_quote", "rationale": "Need Simpsons quote!"}]
+    )
+
+    agent = Agent(
+        name="demo",
+        system_prompt="You are a Simpsons quote generator",
+        agent_endpoint=mock,
+        tools=[get_quote],
+    )
+
+    output, messages_ = agent.invoke()
+    print(f'"{output.value}"')
+
+
+if __name__ == "__main__":
+    main()

roboz-0.1.2.dev11/src/roboz/examples/simpsons_quotes.py

@@ -0,0 +1,44 @@
+"""Provide short Simpsons quotes collected from Reddit discussions.
+
+Sources are fan recollections; punctuation and capitalization are normalized.
+"""
+
+from typing import Final
+
+QUOTES: Final[list[str]] = [
+    "Little bit of column A, little bit of column B.",
+    "At first I was just full of vinegar!",
+    "Haha, nobody ever says Italy.",
+    "Some people say evasion, I say avoision.",
+    "Trying is the first step toward failure.",
+    "Kids, you tried your best and you failed miserably. The lesson is, never try.",
+    'Maybe for once, someone will call me "sir" without adding, "You\'re making a scene."',
+    "Please refrain from tasting the knob!",
+    "Money can be exchanged for goods and services.",
+    "Whoa, whoa, slow down, egghead!",
+    "It's my first day.",
+    "It takes two to lie. One to lie and one to listen.",
+    "It's a boy, and what a boy!",
+    "I told you, my baby beat me up!",
+    "We've tried nothing and we're all out of ideas.",
+    "You don't get rich by writing a lot of checks.",
+    "Good evening, sir. Would you please leave without a fuss right now?",
+    "Save me Jebus!",
+    "To alcohol, the cause of, and solution to, all of life's problems.",
+    "Purple's a fruit.",
+    "That's a paddlin'.",
+    "Bake 'em away, toys!",
+    "Meh. M-E-H. Meh.",
+    "My boy's a box! Damn you! A box!",
+    "Care to join me in a belt of scotch?",
+    "I'm all hopped up on goofballs.",
+    "D'oh!",
+    "Yoink!",
+    "Ha-ha!",
+    "Smell ya later!",
+    "Now with vitamin R!",
+    "Me fail English? Unpossible!",
+    "The goggles! They do nothing!",
+    "If you don't like your job, you don't go on strike; you go in every day and do it really half assed",
+    "I don't want to look like a weirdo, I'll just wear a muumuu.",
+]