uro-cli 0.2.0__tar.gz

uro_cli-0.2.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.python-version.local
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Deployment config holds credential references — commit uro.example.toml instead (docs/14)
+uro.toml
+.env
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Stray local data dumps — never commit (a PII file named `data` was found here once)
+/data

uro_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cupskeee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uro_cli-0.2.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: uro-cli
+Version: 0.2.0
+Summary: Uro Engine reference client — play, dry-run, and dev tools against the engine
+Project-URL: Homepage, https://github.com/cupskeee/uro
+Project-URL: Repository, https://github.com/cupskeee/uro
+Project-URL: Issues, https://github.com/cupskeee/uro/issues
+Author: cupskeee
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: rich>=13.9
+Requires-Dist: typer>=0.15
+Requires-Dist: uro-core[llm,postgres]==0.2.0
+Requires-Dist: uro-server==0.2.0
+Requires-Dist: websockets>=16.1
+Description-Content-Type: text/markdown
+
+# uro-cli
+
+**The Uro Engine reference client — play, dry-run, and dev tools against the engine.**
+
+`uro-cli` installs the `uro` command: create worlds, play campaigns (offline with a
+deterministic stub or against a real model), fork timelines, run mechanics, and drive every
+engine subsystem from the terminal. It is the reference consumer of
+[`uro-core`](https://pypi.org/project/uro-core/) — the only "frontend" the project ships.
+
+## Install
+
+```sh
+pip install uro-cli
+```
+
+This pulls `uro-core` with its `postgres` and `llm` extras — the client wires the Postgres
+store and the LLM providers for you.
+
+## Quickstart
+
+Uro's only store is **PostgreSQL 17 + pgvector**. Start it (the reference setup uses Docker on
+host port 5433), then:
+
+```sh
+docker compose up -d --wait     # from the project repository
+uro db migrate
+uro world new "Ashfall"         # prints a campaign id
+uro play <campaign>             # offline, deterministic stub
+uro play <campaign> --provider anthropic   # or a real model (needs ANTHROPIC_API_KEY)
+```
+
+If the database isn't reachable, `uro` tells you exactly how to start it. Point at a different
+database with `URO_DATABASE_URL`.
+
+## Links
+
+- Source and docs: https://github.com/cupskeee/uro
+- License: MIT

uro_cli-0.2.0/README.md

@@ -0,0 +1,38 @@
+# uro-cli
+
+**The Uro Engine reference client — play, dry-run, and dev tools against the engine.**
+
+`uro-cli` installs the `uro` command: create worlds, play campaigns (offline with a
+deterministic stub or against a real model), fork timelines, run mechanics, and drive every
+engine subsystem from the terminal. It is the reference consumer of
+[`uro-core`](https://pypi.org/project/uro-core/) — the only "frontend" the project ships.
+
+## Install
+
+```sh
+pip install uro-cli
+```
+
+This pulls `uro-core` with its `postgres` and `llm` extras — the client wires the Postgres
+store and the LLM providers for you.
+
+## Quickstart
+
+Uro's only store is **PostgreSQL 17 + pgvector**. Start it (the reference setup uses Docker on
+host port 5433), then:
+
+```sh
+docker compose up -d --wait     # from the project repository
+uro db migrate
+uro world new "Ashfall"         # prints a campaign id
+uro play <campaign>             # offline, deterministic stub
+uro play <campaign> --provider anthropic   # or a real model (needs ANTHROPIC_API_KEY)
+```
+
+If the database isn't reachable, `uro` tells you exactly how to start it. Point at a different
+database with `URO_DATABASE_URL`.
+
+## Links
+
+- Source and docs: https://github.com/cupskeee/uro
+- License: MIT

uro_cli-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "uro-cli"
+version = "0.2.0"
+description = "Uro Engine reference client — play, dry-run, and dev tools against the engine"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [{ name = "cupskeee" }]
+requires-python = ">=3.12"
+# The reference client drives the whole engine: it wires the Postgres store and the LLM
+# providers, so it pulls both uro-core extras (D-43). The internal deps are pinned to the exact
+# lockstep version (the workspace is single-versioned) so a partial `pip install --upgrade` can't
+# pair a new uro-cli with an old uro-core; `just release` bumps all three together, and the
+# `{workspace = true}` sources make a drifted pin fail `uv sync` locally.
+dependencies = [
+    "uro-core[postgres,llm]==0.2.0",
+    "uro-server==0.2.0",
+    "typer>=0.15",
+    "rich>=13.9",
+    "websockets>=16.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/cupskeee/uro"
+Repository = "https://github.com/cupskeee/uro"
+Issues = "https://github.com/cupskeee/uro/issues"
+
+[project.scripts]
+uro = "uro_cli.main:app"
+
+[tool.uv.sources]
+uro-core = { workspace = true }
+uro-server = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["uro_cli"]

uro_cli-0.2.0/tests/test_cli_scaffold.py

@@ -0,0 +1,8 @@
+from typer.testing import CliRunner
+from uro_cli.main import app
+
+
+def test_cli_version_runs() -> None:
+    result = CliRunner().invoke(app, ["version"])
+    assert result.exit_code == 0
+    assert "uro-core" in result.output

uro_cli-0.2.0/tests/test_wiring.py

@@ -0,0 +1,119 @@
+"""CLI wiring: embedder role, multi-role provider specs, and role config."""
+
+from pathlib import Path
+
+import pytest
+from uro_cli.wiring import build_embedder, build_router, load_role_specs, provider_from_spec
+from uro_core.providers.adapters.anthropic import AnthropicProvider
+from uro_core.providers.adapters.stub import StubProvider
+
+
+def test_stub_needs_no_separate_embedder() -> None:
+    assert build_embedder("stub") is None  # StubProvider.embed works
+
+
+def test_real_providers_bind_a_separate_embedder() -> None:
+    # Real providers distinguish chat vs embedding endpoints — a separate binding is
+    # required so the embedder role does not POST a chat model to /embeddings (review 1.3).
+    local = build_embedder("local")
+    assert local is not None and "embedder" in build_router("local", None)._bindings
+
+
+async def test_stub_router_embeds_via_default() -> None:
+    router = build_router("stub", None)
+    vectors = await router.embed("embedder", ["hello world"])
+    assert len(vectors) == 1 and len(vectors[0]) == 256
+
+
+def test_provider_from_spec_parses_kind_and_model(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")
+    assert isinstance(provider_from_spec("stub"), StubProvider)
+    anthropic = provider_from_spec("anthropic:claude-sonnet-5")
+    assert isinstance(anthropic, AnthropicProvider)
+
+
+def test_role_specs_load_from_config(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    cfg = tmp_path / "uro.toml"
+    cfg.write_text('[llm.roles]\nnarrator = "anthropic:claude-sonnet-5"\nextractor = "stub"\n')
+    monkeypatch.setenv("URO_CONFIG", str(cfg))
+    assert load_role_specs() == {"narrator": "anthropic:claude-sonnet-5", "extractor": "stub"}
+
+
+def test_role_config_binds_roles(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")
+    cfg = tmp_path / "uro.toml"
+    cfg.write_text('[llm.roles]\nnarrator = "anthropic:claude-sonnet-5"\n')
+    monkeypatch.setenv("URO_CONFIG", str(cfg))
+    router = build_router("stub", None)
+    assert isinstance(router._bindings["narrator"], AnthropicProvider)  # role override applied
+
+
+def test_build_router_tolerates_an_unbuildable_role(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    # A pinned role whose key is missing must be skipped (fall back to default), not
+    # crash the whole router — else an unused/optional role bricks play (review inc 4).
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    cfg = tmp_path / "uro.toml"
+    cfg.write_text('[llm.roles]\nextractor = "openai:gpt-4o-mini"\n')
+    monkeypatch.setenv("URO_CONFIG", str(cfg))
+    router = build_router("stub", None)  # no OpenAI key → extractor binding skipped
+    assert "extractor" not in router._bindings  # fell back to the default provider
+
+
+def test_config_errors_loudly_on_a_missing_explicit_path(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("URO_CONFIG", "/no/such/uro.toml")
+    with pytest.raises(RuntimeError):
+        load_role_specs()
+
+
+def test_parse_role_models_parses_and_rejects_malformed() -> None:
+    from uro_cli.wiring import parse_role_models
+
+    assert parse_role_models(["planner=openai:gpt-4o", "extractor=gpt-4o-mini"]) == {
+        "planner": "openai:gpt-4o",
+        "extractor": "gpt-4o-mini",
+    }
+    assert parse_role_models(None) == {}
+    for bad in ["planner", "=gpt-4o", "planner="]:
+        with pytest.raises(ValueError):
+            parse_role_models([bad])
+
+
+def test_cli_role_model_override_full_spec(monkeypatch: pytest.MonkeyPatch) -> None:
+    # --role-model narrator=local:llama3.1 binds that role to a distinct provider (no key needed).
+    from uro_core.providers.adapters.openai_compat import OpenAICompatProvider
+
+    router = build_router("stub", None, {"narrator": "local:llama3.1"})
+    assert isinstance(router._bindings["narrator"], OpenAICompatProvider)  # override applied
+    assert isinstance(router._default, StubProvider)  # other roles still use the default
+
+
+def test_cli_role_model_bare_model_uses_default_kind() -> None:
+    # A bare 'model' (no 'kind:') reuses the default provider kind — the common "cheap default,
+    # strong planner" case: planner=<model> stays on the same provider.
+    from uro_core.providers.adapters.openai_compat import OpenAICompatProvider
+
+    router = build_router("local", None, {"planner": "some-big-model"})
+    planner = router._bindings["planner"]
+    assert isinstance(planner, OpenAICompatProvider) and planner._model == "some-big-model"
+
+
+def test_cli_override_wins_over_config(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    from uro_core.providers.adapters.openai_compat import OpenAICompatProvider
+
+    cfg = tmp_path / "uro.toml"
+    cfg.write_text('[llm.roles]\nnarrator = "stub"\n')
+    monkeypatch.setenv("URO_CONFIG", str(cfg))
+    router = build_router("stub", None, {"narrator": "local:llama3.1"})
+    assert isinstance(router._bindings["narrator"], OpenAICompatProvider)  # CLI beats uro.toml
+
+
+def test_cli_override_fails_loudly_unlike_config(monkeypatch: pytest.MonkeyPatch) -> None:
+    # A config role missing its key is skipped with a warning; an explicit CLI override is intent,
+    # so it raises rather than silently falling back.
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    with pytest.raises(RuntimeError):
+        build_router("stub", None, {"planner": "openai:gpt-4o"})

uro_cli-0.2.0/uro_cli/__init__.py

@@ -0,0 +1,8 @@
+"""Uro Engine CLI reference client. Command surface: docs/08."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("uro-cli")
+except PackageNotFoundError:  # pragma: no cover - source checkout without an install
+    __version__ = "0.0.0+unknown"