roboz 0.1.2.dev10__tar.gz → 0.1.2.dev11__tar.gz

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

@@ -2,6 +2,12 @@
 
 ## 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roboz
-Version: 0.1.2.dev10
+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.
@@ -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.
 
 
 
@@ -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.dev10 → 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.
@@ -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.
 
 
 
@@ -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.dev10 → roboz-0.1.2.dev11}/pyproject.toml

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

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.",
+]