roboz 0.1.2.dev10__tar.gz → 0.1.2.dev12__tar.gz

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

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.1.2.dev12 - 2026-09-21
+
+- Breaking: consolidate core, Shed, and Endpoints into the `roboz`
+  distribution. Replace `roboshed` imports with `roboz.shed` and
+  `roboz_endpoints` imports with `roboz.endpoints`; no compatibility packages
+  or forwarding namespaces are provided.
+- Install the OpenAI SDK as a required dependency while retaining deferred
+  endpoint client construction and credential-free imports. Remove package
+  extras and the `roboz-endpoints` executable; manage catalogues with
+  `python -m roboz.endpoints inventory`.
+- Exclude Proton Bridge from the consolidated distribution. Its pre-migration
+  implementation and development setup remain preserved on the
+  `wip/proton-bridge` branch.
+- Consolidate package documentation into the main README and move the detailed
+  project catalogue guide to `docs/catalogues.md`.
+
+## 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
@@ -166,7 +188,7 @@
 
 - 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.
+  it installs core automatically.
 
 - Breaking: move dependency primitives from `roboz.tooling.dependencies` and
   `roboz.tooling` to `roboz.dependencies`. Update those imports; the existing

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

@@ -1,8 +1,8 @@
 Metadata-Version: 2.5
 Name: roboz
-Version: 0.1.2.dev10
+Version: 0.1.2.dev12
 Import-Name: roboz
-Summary: Typed primitives for composable agentic workflows
+Summary: Typed agents, reusable capabilities, and model catalogues
 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
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
+Requires-Dist: openai<3,>=2.8.1
 Requires-Dist: pydantic>=2.12.4
 Requires-Dist: python-dotenv>=1.2.1
 Requires-Dist: rich>=14.2.0
@@ -69,9 +70,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 +97,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 +136,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,40 +226,106 @@ 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. The one dependency
+includes the core framework, Shed, Endpoints, and the OpenAI SDK:
+
 ```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
+```
+
+## Shed
+
+`roboz.shed` provides reusable components built on the core primitives. Use an
+individual guarded file or email tool, add a capability to a
+`DeployableAgent`, start from the orchestrator and Librarian definitions, or use
+the RoboSprawl recipe to assemble a persistent project agent. Applications own
+the model endpoints, event sinks, lifecycle, and filesystem layout.
+
+- `roboz.shed.agents` contains the orchestrator and Librarian definitions.
+- `roboz.shed.capabilities` binds reusable behavior to agent configuration.
+- `roboz.shed.tools` contains guarded file commands, patching, email contracts,
+  conversation compaction, snapshots, memory consolidation, and retention.
+- `roboz.shed.skills` supplies the agent instructions for those tools.
+- `roboz.shed.sandbox` defines filesystem scopes and tool permission policies.
+- `roboz.shed.dependency_health` checks configured external resources.
+
+Shed permission policies guard Shed tools. They are not an operating-system
+sandbox.
+
+## Endpoints and model catalogues
+
+`roboz.endpoints` builds concrete `LLMEndpoint` and `TranscriptionEndpoint`
+objects for OpenAI-compatible APIs. The OpenAI SDK is installed with RoboZ, but
+client construction and credential lookup remain deferred until an endpoint is
+materialized or used. Importing and inspecting the bundled catalogue needs no
+credentials:
+
+```python
+from roboz.endpoints.inventory import openrouter
+
+endpoint = openrouter.z_ai__glm_5_3
+print(endpoint.model_name)
+print(endpoint.max_context_tokens)
 ```
 
-## Packages
+The bundled OpenRouter, Cerebras, and Groq entries are examples. Export them to
+an editable project catalogue, change `models.json`, then generate the Python
+snapshot:
 
-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.
+```bash
+uv run python -m roboz.endpoints inventory export
+# Edit model_catalogue/models.json.
+uv run python -m roboz.endpoints inventory import
+```
 
-| Distribution | Import | Provides |
-| --- | --- | --- |
-| `roboz` | `roboz` | Core agent, tool, workflow, endpoint, and runtime primitives. |
-| [`roboshed`](https://pypi.org/project/roboshed/) | `roboshed` | Reusable capabilities, guarded system tools, memory, agents, and deployment building blocks. |
-| [`roboz-endpoints`](https://pypi.org/project/roboz-endpoints/) | `roboz_endpoints` | Model catalogues and optional provider adapters. |
-| [`roboz-proton-bridge`](https://pypi.org/project/roboz-proton-bridge/) | `roboz_proton_bridge` | Proton Bridge email integration. |
+For a src-layout project named `my-app`, the commands create
+`src/my_app/model_catalogue/models.json` and
+`src/my_app/model_catalogue/providers.py`. Import the generated catalogue from
+your application package:
+
+```python
+from my_app.model_catalogue.providers import my_service
+
+endpoint = my_service.chat
+```
 
-The companion packages build on `roboz`; `roboz-proton-bridge` also uses
-`roboshed`.
+Only OpenAI-compatible API protocols are supported. An inventory entry records
+a provider URL, the name of its credential environment variable, and its model
+routes; it never stores the credential itself. See the
+[project catalogue guide](docs/catalogues.md) for custom paths, inventory
+format, reset, and recovery.
+
+## Module map
+
+| Module | Provides |
+| --- | --- |
+| `roboz` | Agent, tool, factory, and skill authoring facade. |
+| `roboz.agent` | Agent implementations, subagents, and background agents. |
+| `roboz.deployment` | Reusable agent definitions and capabilities. |
+| `roboz.llm` | Endpoint contracts, selection, calls, and request policies. |
+| `roboz.models` | Typed messages and tool input/output models. |
+| `roboz.runtime` | Events, pipes, sinks, persistence, and observability. |
+| `roboz.shed` | Reusable capabilities, guarded tools, agents, and recipes. |
+| `roboz.endpoints` | OpenAI-compatible adapters and typed model catalogues. |
 
 ## Development
 

{roboz-0.1.2.dev10 → roboz-0.1.2.dev12}/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,40 +198,106 @@ 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. The one dependency
+includes the core framework, Shed, Endpoints, and the OpenAI SDK:
+
 ```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
+```
+
+## Shed
+
+`roboz.shed` provides reusable components built on the core primitives. Use an
+individual guarded file or email tool, add a capability to a
+`DeployableAgent`, start from the orchestrator and Librarian definitions, or use
+the RoboSprawl recipe to assemble a persistent project agent. Applications own
+the model endpoints, event sinks, lifecycle, and filesystem layout.
+
+- `roboz.shed.agents` contains the orchestrator and Librarian definitions.
+- `roboz.shed.capabilities` binds reusable behavior to agent configuration.
+- `roboz.shed.tools` contains guarded file commands, patching, email contracts,
+  conversation compaction, snapshots, memory consolidation, and retention.
+- `roboz.shed.skills` supplies the agent instructions for those tools.
+- `roboz.shed.sandbox` defines filesystem scopes and tool permission policies.
+- `roboz.shed.dependency_health` checks configured external resources.
+
+Shed permission policies guard Shed tools. They are not an operating-system
+sandbox.
+
+## Endpoints and model catalogues
+
+`roboz.endpoints` builds concrete `LLMEndpoint` and `TranscriptionEndpoint`
+objects for OpenAI-compatible APIs. The OpenAI SDK is installed with RoboZ, but
+client construction and credential lookup remain deferred until an endpoint is
+materialized or used. Importing and inspecting the bundled catalogue needs no
+credentials:
+
+```python
+from roboz.endpoints.inventory import openrouter
+
+endpoint = openrouter.z_ai__glm_5_3
+print(endpoint.model_name)
+print(endpoint.max_context_tokens)
 ```
 
-## Packages
+The bundled OpenRouter, Cerebras, and Groq entries are examples. Export them to
+an editable project catalogue, change `models.json`, then generate the Python
+snapshot:
 
-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.
+```bash
+uv run python -m roboz.endpoints inventory export
+# Edit model_catalogue/models.json.
+uv run python -m roboz.endpoints inventory import
+```
 
-| Distribution | Import | Provides |
-| --- | --- | --- |
-| `roboz` | `roboz` | Core agent, tool, workflow, endpoint, and runtime primitives. |
-| [`roboshed`](https://pypi.org/project/roboshed/) | `roboshed` | Reusable capabilities, guarded system tools, memory, agents, and deployment building blocks. |
-| [`roboz-endpoints`](https://pypi.org/project/roboz-endpoints/) | `roboz_endpoints` | Model catalogues and optional provider adapters. |
-| [`roboz-proton-bridge`](https://pypi.org/project/roboz-proton-bridge/) | `roboz_proton_bridge` | Proton Bridge email integration. |
+For a src-layout project named `my-app`, the commands create
+`src/my_app/model_catalogue/models.json` and
+`src/my_app/model_catalogue/providers.py`. Import the generated catalogue from
+your application package:
+
+```python
+from my_app.model_catalogue.providers import my_service
+
+endpoint = my_service.chat
+```
 
-The companion packages build on `roboz`; `roboz-proton-bridge` also uses
-`roboshed`.
+Only OpenAI-compatible API protocols are supported. An inventory entry records
+a provider URL, the name of its credential environment variable, and its model
+routes; it never stores the credential itself. See the
+[project catalogue guide](docs/catalogues.md) for custom paths, inventory
+format, reset, and recovery.
+
+## Module map
+
+| Module | Provides |
+| --- | --- |
+| `roboz` | Agent, tool, factory, and skill authoring facade. |
+| `roboz.agent` | Agent implementations, subagents, and background agents. |
+| `roboz.deployment` | Reusable agent definitions and capabilities. |
+| `roboz.llm` | Endpoint contracts, selection, calls, and request policies. |
+| `roboz.models` | Typed messages and tool input/output models. |
+| `roboz.runtime` | Events, pipes, sinks, persistence, and observability. |
+| `roboz.shed` | Reusable capabilities, guarded tools, agents, and recipes. |
+| `roboz.endpoints` | OpenAI-compatible adapters and typed model catalogues. |
 
 ## Development
 

roboz-0.1.2.dev12/docs/catalogues.md

@@ -0,0 +1,156 @@
+# Project catalogues
+
+A project catalogue is an editable JSON inventory plus a generated Python
+module. It lets an application define its own OpenAI-compatible providers and
+models without modifying RoboZ.
+
+## Standard workflow
+
+Run these commands from the application project root:
+
+```bash
+uv run python -m roboz.endpoints inventory export
+# Edit the generated models.json.
+uv run python -m roboz.endpoints inventory import
+```
+
+The export command creates a `model_catalogue` package. The import command reads
+`models.json` and generates `providers.py` beside it. Edit and retain the JSON;
+do not edit the generated Python module.
+
+For a project with `name = "my-app"` in `pyproject.toml`, the default location
+follows the existing package layout:
+
+- `src/my_app/__init__.py` → `src/my_app/model_catalogue/`
+- `my_app/__init__.py` → `my_app/model_catalogue/`
+
+If neither package exists, the CLI uses `model_catalogue/` in the project root.
+For reliable imports from every application module, use `--path` to place the
+catalogue inside the actual application package when automatic detection fails.
+
+The generated package contains:
+
+```text
+model_catalogue/
+├── __init__.py
+├── models.json       # editable source
+└── providers.py      # generated snapshot
+```
+
+Import through the application's package path:
+
+```python
+from my_app.model_catalogue.providers import my_service
+```
+
+## Choose another name or location
+
+`--path` selects the JSON file. Unless `--output` is provided, import generates
+`providers.py` beside that JSON file. For example, to call the package
+`endpoints`:
+
+```bash
+mkdir -p src/my_app/endpoints
+touch src/my_app/endpoints/__init__.py
+
+uv run python -m roboz.endpoints inventory export \
+    --path src/my_app/endpoints/models.json
+
+uv run python -m roboz.endpoints inventory import \
+    --path src/my_app/endpoints/models.json
+```
+
+Then import it from any application module:
+
+```python
+from my_app.endpoints.providers import my_service
+```
+
+To choose the generated module name as well:
+
+```bash
+uv run python -m roboz.endpoints inventory import \
+    --path src/my_app/endpoints/models.json \
+    --output src/my_app/endpoints/catalogue.py
+```
+
+That module is imported as:
+
+```python
+from my_app.endpoints.catalogue import my_service
+```
+
+For custom paths, create the parent package and its `__init__.py` first. Paths
+are relative to the directory in which the command runs.
+
+## Inventory format
+
+The exported file is the complete starting inventory. A provider entry has its
+service URL, the name of its credential environment variable, and one or more
+models:
+
+```json
+{
+  "schema_version": 1,
+  "providers": {
+    "my_service": {
+      "base_url": "https://models.example.com/v1",
+      "api_key_env": "MY_SERVICE_API_KEY",
+      "models": {
+        "chat": {
+          "model_id": "my-chat-model",
+          "endpoint_type": "llm",
+          "max_context_tokens": 128000
+        },
+        "voice": {
+          "model_id": "my-transcription-model",
+          "endpoint_type": "transcription"
+        }
+      }
+    }
+  }
+}
+```
+
+Provider and model keys become Python names, so they must be valid public Python
+identifiers. `model_id` is the identifier sent to the provider. A chat model
+requires `max_context_tokens`; a transcription model does not accept it.
+
+Only OpenAI-compatible APIs are currently supported. Store the environment
+variable name in `api_key_env`, never the credential itself.
+
+## Regenerate after editing
+
+Once `providers.py` exists, regenerate it with `--force`:
+
+```bash
+uv run python -m roboz.endpoints inventory import --force
+```
+
+For a custom location, pass the same `--path` and, if used originally,
+`--output`. Restart the application so it imports the new snapshot. Package
+upgrades do not replace a project catalogue.
+
+## Reset or recover
+
+Reset restores the bundled examples after confirmation and discards catalogue
+customizations:
+
+```bash
+uv run python -m roboz.endpoints inventory reset
+```
+
+For a custom catalogue, pass its `--path` and `--output`. Copy anything that
+must be retained before confirming the reset.
+
+If `models.json` was lost but the generated module remains, recover JSON without
+executing the module:
+
+```bash
+uv run python -m roboz.endpoints inventory export \
+    --from-module src/my_app/model_catalogue/providers.py \
+    --path recovered-models.json
+```
+
+Use `uv run python -m roboz.endpoints inventory <command> --help` for the full
+options of `export`, `import`, or `reset`.

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

@@ -1,7 +1,7 @@
 [project]
 name = "roboz"
-version = "0.1.2.dev10"
-description = "Typed primitives for composable agentic workflows"
+version = "0.1.2.dev12"
+description = "Typed agents, reusable capabilities, and model catalogues"
 readme = "README.md"
 authors = [{ name = "Tachion Oy" }]
 license = "Apache-2.0"
@@ -20,6 +20,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
+    "openai>=2.8.1,<3",
     "pydantic>=2.12.4",
     "python-dotenv>=1.2.1",
     "rich>=14.2.0",
@@ -29,20 +30,18 @@ dependencies = [
 requires = ["hatchling>=1.32"]
 build-backend = "hatchling.build"
 
-[tool.uv.workspace]
-members = ["packages/*"]
-
-[tool.uv.sources]
-roboz = { workspace = true }
-roboshed = { workspace = true }
-roboz-endpoints = { workspace = true }
-roboz-proton-bridge = { workspace = true }
-
 [tool.hatch.build.targets.wheel]
 packages = ["src/roboz"]
 
 [tool.hatch.build.targets.sdist]
-include = ["/src/roboz", "/README.md", "/CHANGELOG.md", "/LICENSE", "/pyproject.toml"]
+include = [
+    "/src/roboz",
+    "/docs/catalogues.md",
+    "/README.md",
+    "/CHANGELOG.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]
 
 [project.urls]
 Homepage = "https://github.com/Tachion-Oy/roboz"
@@ -53,7 +52,7 @@ Documentation = "https://github.com/Tachion-Oy/roboz#readme"
 [tool.pytest.ini_options]
 addopts = "--cov=roboz --cov-report=term-missing --ignore=tests/type_tests"
 python_files = ["test_*.py", "tests_*.py"]
-testpaths = ["tests", "packages/shed/tests", "packages/endpoints/tests", "packages/proton-bridge/tests"]
+testpaths = ["tests"]
 
 [tool.ruff.lint]
 select = ["D", "E4", "E7", "E9", "F"]
@@ -63,16 +62,12 @@ convention = "google"
 
 [tool.ruff.lint.per-file-ignores]
 "examples/**/*.py" = ["D"]
-"packages/*/tests/**/*.py" = ["D"]
 "scripts/**/*.py" = ["D"]
 "tests/**/*.py" = ["D"]
 
 [dependency-groups]
 dev = [
     "check-wheel-contents>=0.6",
-    "roboshed",
-    "roboz-endpoints[openai]",
-    "roboz-proton-bridge",
     "pyright>=1.1.411",
     "pytest>=7.0",
     "pytest-cov>=4.0",

roboz-0.1.2.dev12/src/roboz/endpoints/__init__.py

@@ -0,0 +1 @@
+"""Typed model catalogues and OpenAI-compatible endpoint adapters."""

roboz-0.1.2.dev12/src/roboz/endpoints/__main__.py

@@ -0,0 +1,7 @@
+"""Run catalogue management with ``python -m roboz.endpoints``."""
+
+from roboz.endpoints.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())