roboz 0.1.2.dev3__tar.gz → 0.1.2.dev5__tar.gz

roboz-0.1.2.dev5/CHANGELOG.md

@@ -0,0 +1,166 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.2.dev5 - 2026-09-13
+
+- Add `LLMEndpointRoute`, a typed live-selection layer above concrete chat
+  endpoints. Routes retain a caller-owned endpoint getter, report the current
+  selected resource without initializing clients, and resolve once per model
+  operation so in-flight calls retain their endpoint. Request and OpenRouter
+  policies support routes while keeping fixed endpoint use unchanged.
+
+- Inspect a configured deployment with `DeployableAgent.external_dependencies()`.
+  It builds fresh, unstarted agents without event sinks and delegates to their
+  existing tool inspection, including child agents and skill resources. Capability
+  construction still runs normally; no additional dependency declaration is required.
+
+- Initialize factory contexts lazily on invocation through the optional
+  `Materializable.materialize() -> Self` protocol. Binding, copying, and inspection
+  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).
+
+- Make resource-inspection declarations explicit: aggregate contexts and agents
+  implement the `HasExternalDependencies` protocol, renamed from `Context` with
+  no compatibility alias. Authors can inherit it to require
+  `external_dependencies()`; missing implementations fail type checking and
+  instantiation. Plain contexts remain unrestricted, and direct resources inherit
+  inspection from `ExternalDependency`.
+
+- Breaking: migrate core interaction and agent factories to concrete contexts.
+  Bind interaction factories to strings, `run_subagent` to the child `Agent`,
+  and background/prompt factories to `BackgroundAgentContext`/`PromptAgentContext`
+  from `roboz.agent`. Background constructors own fresh state; rebinding and copies
+  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).
+
+- 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).
+
+- 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).
+
+- Accept any concretely typed factory context, including plain objects and lists.
+  Contexts without resource inspection are passed through unchanged and their
+  tools report no dependencies. Wrong context types remain static binding errors.
+
+- Bind core chat and transcription endpoints directly as typed factory contexts,
+  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).
+- Fix `@factory()` input inference so parenthesized factories retain the same
+  concrete input, output, and context types as bare `@factory` declarations.
+
+- Breaking checkpoint: bind factories directly to concrete typed resources or
+  contexts with optional `external_dependencies()`, preserving the supplied object and
+  inspecting it live. Replace `Ctx` and tool dependency properties with concrete
+  contexts and `tool.external_dependencies()`. Dependency extension primitives
+  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)
+  for the contract, removed APIs, and migration boundary.
+
+## 0.1.2.dev4 - 2026-09-12
+
+- Breaking: make `DeployableAgent` an explicitly configured class. Constructor
+  capabilities are protected defaults; append capabilities and child agents with
+  the add methods, configure endpoints and runtime values separately, and unpack
+  `(agent, background_agents)` from `build()`. `build_graph()` is removed.
+- Breaking: capability builders now declare concrete `required_attributes` and
+  receive `build(agent, pipe)`. Builds validate the complete graph before
+  constructing sinks, pipes, or tools and aggregate missing, `None`, and
+  incorrectly typed owner attributes.
+
+## 0.1.2.dev3 - 2026-09-11
+
+- Breaking: remove the redundant `roboz[shed]` installation extra. Install
+  `roboshed` directly; it installs its compatible core Roboz dependency.
+
+- Add `DeployableAgent.build_graph()` to return the root agent and all background
+  handles for host lifecycle control. `build()` still returns the root alone.
+
+- Breaking: replace `AgentDefinition` and `SubAgentSpec` with recursive
+  `DeployableAgent` definitions. Put child definitions directly in `subagents`
+  or `background_agents`; delegation tools use the child's name and description,
+  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.
+
+## 0.1.2.dev2 - 2026-09-09
+
+- Breaking: remove the `roboz[openai]` extra. Install
+  `roboz-endpoints[openai]` directly for the endpoint catalogue and SDK adapter;
+  it installs core automatically. See `packages/endpoints/README.md` for migration.
+
+- 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`.
+
+- Add `DependencyRoute` for live caller-owned selections. Materialization and discovery delegate to the current target without introducing a separate identity or caching the selection.
+
+- Breaking: capability builders receive `build(pipe, *, default_endpoint)`.
+  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.
+
+- 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.
+
+- 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`.
+
+- 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.
+
+### Added
+
+- Select lazy model endpoints with `ModelSelector` from `roboz.llm` or
+  `roboz.llm.endpoints`, without requiring Shed or constructing clients.
+
+- Bind exact dependency registrations with `roboz.dependencies`, independently
+  of Shed. Registration types, checker callbacks, and contract errors now live
+  alongside dependency discovery and resolution primitives.
+
+- Add `ExternalDependencyReference` for replaceable resources. Endpoint helpers
+  preserve live selection and discovery through contexts, tools, and agents,
+  while lazy resources retain their identity validation and cached clients.
+
+- Inspect resources before binding tools with `Ctx.external_dependencies()`.
+  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`.
+
+### Fixed
+
+- Refresh lifecycle endpoint metadata when invoking an agent again after a live
+  reference switches models, while retaining each lazy dependency's client cache.
+
+### Changed
+
+- **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.
+
+- Define and enforce Google-style source docstrings, and normalize tool
+  docstrings before including them in agent prompts.
+
+## 0.1.1
+
+- Preserve concrete nested model types across in-memory tool handoffs while
+  keeping field projection, excluded fields, validation, and detached inputs.
+- Add optional companion extras and independent package release workflows.
+- Keep the core's runtime dependency set unchanged.

roboz-0.1.2.dev5/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.5
+Name: roboz
+Version: 0.1.2.dev5
+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
+Author: Tachion Oy
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,llm,tool-calling,typing,workflows
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: pydantic>=2.12.4
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: rich>=14.2.0
+Provides-Extra: proton-bridge-beta
+Requires-Dist: roboz-proton-bridge<0.2.0,>=0.1.0b1; extra == 'proton-bridge-beta'
+Description-Content-Type: text/markdown
+
+# RoboZ
+
+**Chain tools. Skip calls.**
+
+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.
+
+[![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/)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+
+> [!WARNING]
+> RoboZ is pre-release software requiring Python 3.13 or newer. APIs may change
+> before 1.0.
+
+## Basic idea
+
+![The usual agent loop sends every lunch-planning step back through the agent. A Roboz chain returns to the agent when Bob wants no lunch, passes any cuisine into one parameterized restaurant search, and retries the plan directly when no seats are available.](docs/assets/tool-chaining.svg)
+
+### Problems in agents: Context bloat and excessive back-and-forth
+Suppose the task we want to achieve is ask our buddy Bob out to lunch and then book a table. For the sake of argument assume that our agent has access to the following MCP servers (Note: this is an example, RoboZ has native Tool primitives):
+
+- Ask Bob what they want
+- 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.
+
+### Deterministic chains
+The philosophy in RoboZ is that the workflow is deterministic an only choosing when to initiate is the agent's job. In RoboZ the agent would trigger the "ask Bob what they want" tool and all subsequent steps come by chaining: each tool is chained to other tools upstream and their output is passed down to the chained tool. Each link/edge may introduce a True/False condition, in this 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. 
+
+### Message truncation
+Lengthy tasks with many tool calls also add many tokens in the context that may not be relevant to the end result. In RoboZ all tools may choose to truncate their message i.e. not show it to the agent in its complete form or only show it in its entirety a few times and then remove it from the agents context entirely, for example.
+
+
+
+
+
+## Code example
+TBD
+
+
+```python
+import roboz as rz
+
+
+class LunchPreference(rz.Empty):
+    cuisine: str | None
+
+
+class Restaurant(rz.Empty):
+    name: str
+    seats_available: bool
+
+
+class Booking(rz.Empty):
+    confirmation: str
+
+
+@rz.tool
+def plan_lunch_with_bob(
+    input: rz.Empty, messages: list[rz.Message]
+) -> LunchPreference:
+    ...
+
+
+@rz.tool
+def retry_plan_lunch_with_bob(
+    input: Restaurant, messages: list[rz.Message]
+) -> LunchPreference:
+    ...
+
+
+@rz.tool(
+    chained_to=[plan_lunch_with_bob, retry_plan_lunch_with_bob],
+    chain_condition=lambda output: (
+        isinstance(output, LunchPreference)
+        and output.cuisine is not None
+    ),
+)
+def find_restaurant(
+    input: LunchPreference, messages: list[rz.Message]
+) -> Restaurant:
+    ...
+
+
+retry_plan_lunch_with_bob.chain(
+    chained_to=find_restaurant,
+    chain_condition=lambda output: (
+        isinstance(output, Restaurant) and not output.seats_available
+    ),
+)
+
+
+@rz.tool(
+    chained_to=find_restaurant,
+    chain_condition=lambda output: (
+        isinstance(output, Restaurant) and output.seats_available
+    ),
+)
+def book_a_table(input: Restaurant, messages: list[rz.Message]) -> Booking:
+    ...
+```
+
+## factory closure, endpoint instance and seeing the entire prompt
+TBD
+
+
+## Try it
+
+```bash
+uv add roboz
+```
+
+Or with pip:
+
+```bash
+python -m pip install roboz
+```
+
+The complete [quick start](examples/quickstart.py) uses a deterministic mock
+endpoint. Bob first chooses sushi; when no seats are available, the typed chain
+retries the planner, routes his second choice to pizza, and books—all from one
+model-selected entry into the chain and without credentials:
+
+```bash
+uv run python examples/quickstart.py
+```
+
+For an unpublished checkout, first run `uv sync --locked --dev`. PyPI commands
+require a published release; see the [build and test guide](docs/build-and-test.md)
+for local wheels.
+
+## Control what reaches the model
+
+Context is a projection, not an ever-growing transcript. Every `Message` can
+carry a lifecycle policy: keep an output intact while it is recent, reduce it
+to a stub later, and remove it from model context when it is stale.
+`NO_MESSAGE` keeps operational chatter out of model context immediately. These
+policies affect only what the model sees; runtime events and persisted messages
+retain the full record.
+
+The prompt is not assembled behind an opaque stack of framework layers. The
+complete generated system prompt is available before invocation:
+
+```python
+print(agent.full_system_prompt)
+```
+
+## One execution abstraction
+
+Roboz uses tools for work and for orchestration instead of adding a separate
+hook mechanism for each new concern.
+
+| Concern | Roboz abstraction |
+| --- | --- |
+| A model-selectable action | Active `@tool` |
+| A deterministic follow-up | Passive chained tool |
+| Runtime configuration or dependencies | `@factory` bound to a concrete typed object |
+| Startup, preflight, and default flow | `default_tools` |
+| Synchronous delegation | A subagent exposed as a named tool |
+| Background work | An idempotent background-start tool in the default flow |
+
+Tools remain independently testable callables with typed inputs and outputs.
+An agent's dependency view is derived from this same tool graph rather than a
+second registry.
+
+## Put models where they belong
+
+Each agent owns its endpoint. A model-backed factory can bind another endpoint
+directly, so a planner, specialist, summarizer, or transcription tool does not
+have to share a model merely because it belongs to the same workflow.
+`LLMEndpointRoute` follows a typed endpoint getter when a tool or agent should
+track live model selection; concrete endpoints keep other uses fixed.
+
+Provider SDKs remain outside core. The `roboz` package supplies the agent,
+tooling, model, runtime, persistence, dependency, and deployment primitives;
+install integrations only where they are needed.
+
+## Core primitives
+
+| Primitive | Role |
+| --- | --- |
+| `rz.Agent` | Owns the active tool surface, prompt, invoke loop, and runtime events. |
+| `@rz.tool` | Defines an action with typed input and output models. |
+| `@rz.factory` | Binds a concrete typed context or resource to a tool. |
+| `rz.Skill` | Packages reusable instructions and optional tools. |
+| `rz.Message` | Carries content and its model-context lifecycle. |
+| `roboz.deployment.DeployableAgent` | Composes capabilities, subagents, and background agents. |
+
+## 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. |
+
+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.
+
+## Documentation
+
+| 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 |
+| [Message truncation example](examples/message_truncation.py) | Sliding model-context visibility |
+| [Testing practices](docs/testing-practices.md) | Deterministic workflow and contract tests |
+
+## Development
+
+```bash
+uv sync --locked --dev
+uv run pytest
+uv run ruff check
+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.
+Roboz is typed and ships a PEP 561 `py.typed` marker.
+
+## License
+
+Roboz is licensed under the [Apache License 2.0](LICENSE). Copyright © 2026 Tachion Oy.

roboz-0.1.2.dev5/README.md

@@ -0,0 +1,230 @@
+# RoboZ
+
+**Chain tools. Skip calls.**
+
+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.
+
+[![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/)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+
+> [!WARNING]
+> RoboZ is pre-release software requiring Python 3.13 or newer. APIs may change
+> before 1.0.
+
+## Basic idea
+
+![The usual agent loop sends every lunch-planning step back through the agent. A Roboz chain returns to the agent when Bob wants no lunch, passes any cuisine into one parameterized restaurant search, and retries the plan directly when no seats are available.](docs/assets/tool-chaining.svg)
+
+### Problems in agents: Context bloat and excessive back-and-forth
+Suppose the task we want to achieve is ask our buddy Bob out to lunch and then book a table. For the sake of argument assume that our agent has access to the following MCP servers (Note: this is an example, RoboZ has native Tool primitives):
+
+- Ask Bob what they want
+- 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.
+
+### Deterministic chains
+The philosophy in RoboZ is that the workflow is deterministic an only choosing when to initiate is the agent's job. In RoboZ the agent would trigger the "ask Bob what they want" tool and all subsequent steps come by chaining: each tool is chained to other tools upstream and their output is passed down to the chained tool. Each link/edge may introduce a True/False condition, in this 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. 
+
+### Message truncation
+Lengthy tasks with many tool calls also add many tokens in the context that may not be relevant to the end result. In RoboZ all tools may choose to truncate their message i.e. not show it to the agent in its complete form or only show it in its entirety a few times and then remove it from the agents context entirely, for example.
+
+
+
+
+
+## Code example
+TBD
+
+
+```python
+import roboz as rz
+
+
+class LunchPreference(rz.Empty):
+    cuisine: str | None
+
+
+class Restaurant(rz.Empty):
+    name: str
+    seats_available: bool
+
+
+class Booking(rz.Empty):
+    confirmation: str
+
+
+@rz.tool
+def plan_lunch_with_bob(
+    input: rz.Empty, messages: list[rz.Message]
+) -> LunchPreference:
+    ...
+
+
+@rz.tool
+def retry_plan_lunch_with_bob(
+    input: Restaurant, messages: list[rz.Message]
+) -> LunchPreference:
+    ...
+
+
+@rz.tool(
+    chained_to=[plan_lunch_with_bob, retry_plan_lunch_with_bob],
+    chain_condition=lambda output: (
+        isinstance(output, LunchPreference)
+        and output.cuisine is not None
+    ),
+)
+def find_restaurant(
+    input: LunchPreference, messages: list[rz.Message]
+) -> Restaurant:
+    ...
+
+
+retry_plan_lunch_with_bob.chain(
+    chained_to=find_restaurant,
+    chain_condition=lambda output: (
+        isinstance(output, Restaurant) and not output.seats_available
+    ),
+)
+
+
+@rz.tool(
+    chained_to=find_restaurant,
+    chain_condition=lambda output: (
+        isinstance(output, Restaurant) and output.seats_available
+    ),
+)
+def book_a_table(input: Restaurant, messages: list[rz.Message]) -> Booking:
+    ...
+```
+
+## factory closure, endpoint instance and seeing the entire prompt
+TBD
+
+
+## Try it
+
+```bash
+uv add roboz
+```
+
+Or with pip:
+
+```bash
+python -m pip install roboz
+```
+
+The complete [quick start](examples/quickstart.py) uses a deterministic mock
+endpoint. Bob first chooses sushi; when no seats are available, the typed chain
+retries the planner, routes his second choice to pizza, and books—all from one
+model-selected entry into the chain and without credentials:
+
+```bash
+uv run python examples/quickstart.py
+```
+
+For an unpublished checkout, first run `uv sync --locked --dev`. PyPI commands
+require a published release; see the [build and test guide](docs/build-and-test.md)
+for local wheels.
+
+## Control what reaches the model
+
+Context is a projection, not an ever-growing transcript. Every `Message` can
+carry a lifecycle policy: keep an output intact while it is recent, reduce it
+to a stub later, and remove it from model context when it is stale.
+`NO_MESSAGE` keeps operational chatter out of model context immediately. These
+policies affect only what the model sees; runtime events and persisted messages
+retain the full record.
+
+The prompt is not assembled behind an opaque stack of framework layers. The
+complete generated system prompt is available before invocation:
+
+```python
+print(agent.full_system_prompt)
+```
+
+## One execution abstraction
+
+Roboz uses tools for work and for orchestration instead of adding a separate
+hook mechanism for each new concern.
+
+| Concern | Roboz abstraction |
+| --- | --- |
+| A model-selectable action | Active `@tool` |
+| A deterministic follow-up | Passive chained tool |
+| Runtime configuration or dependencies | `@factory` bound to a concrete typed object |
+| Startup, preflight, and default flow | `default_tools` |
+| Synchronous delegation | A subagent exposed as a named tool |
+| Background work | An idempotent background-start tool in the default flow |
+
+Tools remain independently testable callables with typed inputs and outputs.
+An agent's dependency view is derived from this same tool graph rather than a
+second registry.
+
+## Put models where they belong
+
+Each agent owns its endpoint. A model-backed factory can bind another endpoint
+directly, so a planner, specialist, summarizer, or transcription tool does not
+have to share a model merely because it belongs to the same workflow.
+`LLMEndpointRoute` follows a typed endpoint getter when a tool or agent should
+track live model selection; concrete endpoints keep other uses fixed.
+
+Provider SDKs remain outside core. The `roboz` package supplies the agent,
+tooling, model, runtime, persistence, dependency, and deployment primitives;
+install integrations only where they are needed.
+
+## Core primitives
+
+| Primitive | Role |
+| --- | --- |
+| `rz.Agent` | Owns the active tool surface, prompt, invoke loop, and runtime events. |
+| `@rz.tool` | Defines an action with typed input and output models. |
+| `@rz.factory` | Binds a concrete typed context or resource to a tool. |
+| `rz.Skill` | Packages reusable instructions and optional tools. |
+| `rz.Message` | Carries content and its model-context lifecycle. |
+| `roboz.deployment.DeployableAgent` | Composes capabilities, subagents, and background agents. |
+
+## 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. |
+
+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.
+
+## Documentation
+
+| 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 |
+| [Message truncation example](examples/message_truncation.py) | Sliding model-context visibility |
+| [Testing practices](docs/testing-practices.md) | Deterministic workflow and contract tests |
+
+## Development
+
+```bash
+uv sync --locked --dev
+uv run pytest
+uv run ruff check
+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.
+Roboz is typed and ships a PEP 561 `py.typed` marker.
+
+## License
+
+Roboz is licensed under the [Apache License 2.0](LICENSE). Copyright © 2026 Tachion Oy.

{roboz-0.1.2.dev3 → roboz-0.1.2.dev5}/pyproject.toml

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