roboz 0.1.2.dev11__tar.gz → 0.1.2.dev12__tar.gz

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

@@ -2,6 +2,22 @@
 
 ## 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
@@ -172,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.dev11 → roboz-0.1.2.dev12}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.5
 Name: roboz
-Version: 0.1.2.dev11
+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
@@ -236,7 +237,8 @@ uv run python -m roboz.examples.complex
 
 ## Try it out
 
-Add RoboZ to a uv project and run the same bundled example:
+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
@@ -250,21 +252,80 @@ python -m pip install roboz
 python -m roboz.examples.simple
 ```
 
-## Packages
+## Shed
 
-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.
+`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.
 
-| 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. |
+- `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.
 
-The companion packages build on `roboz`; `roboz-proton-bridge` also uses
-`roboshed`.
+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)
+```
+
+The bundled OpenRouter, Cerebras, and Groq entries are examples. Export them to
+an editable project catalogue, change `models.json`, then generate the Python
+snapshot:
+
+```bash
+uv run python -m roboz.endpoints inventory export
+# Edit model_catalogue/models.json.
+uv run python -m roboz.endpoints inventory import
+```
+
+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
+```
+
+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.dev11 → roboz-0.1.2.dev12}/README.md

@@ -209,7 +209,8 @@ uv run python -m roboz.examples.complex
 
 ## Try it out
 
-Add RoboZ to a uv project and run the same bundled example:
+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
@@ -223,21 +224,80 @@ python -m pip install roboz
 python -m roboz.examples.simple
 ```
 
-## Packages
+## Shed
 
-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.
+`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.
 
-| 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. |
+- `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.
 
-The companion packages build on `roboz`; `roboz-proton-bridge` also uses
-`roboshed`.
+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)
+```
+
+The bundled OpenRouter, Cerebras, and Groq entries are examples. Export them to
+an editable project catalogue, change `models.json`, then generate the Python
+snapshot:
+
+```bash
+uv run python -m roboz.endpoints inventory export
+# Edit model_catalogue/models.json.
+uv run python -m roboz.endpoints inventory import
+```
+
+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
+```
+
+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.dev11 → roboz-0.1.2.dev12}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "roboz"
-version = "0.1.2.dev11"
-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())