uro-cli 0.2.0__py3-none-any.whl

uro_cli/wiring.py

@@ -0,0 +1,197 @@
+"""Config resolution + adapter wiring (docs/04, 08, 14).
+
+The CLI is where concrete adapters get instantiated and handed to the core — the
+engine itself only ever sees ports. Roles can be bound to different providers/models
+via uro.toml `[llm.roles]` (e.g. narrator = "anthropic:claude-sonnet-5",
+extractor = "openai:gpt-4o-mini", embedder = "openai:text-embedding-3-small"); the
+`--provider` flag is the default for any role not pinned there. Secrets stay in env
+(references, never values), per docs/14.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+import asyncpg
+from uro_core.adapters.postgres.store import PostgresEventStore
+from uro_core.providers.adapters.anthropic import AnthropicProvider
+from uro_core.providers.adapters.openai_compat import OpenAICompatProvider
+from uro_core.providers.adapters.stub import StubProvider
+from uro_core.providers.base import LLMProvider
+from uro_core.providers.router import ProviderRouter
+from uro_core.rulesets import registry
+from uro_core.rulesets.base import Ruleset
+
+DEFAULT_DSN = "postgresql://uro:uro@localhost:5433/uro"
+
+logger = logging.getLogger(__name__)
+
+
+def db_dsn() -> str:
+    return os.environ.get("URO_DATABASE_URL", DEFAULT_DSN)
+
+
+def build_store() -> PostgresEventStore:
+    return PostgresEventStore(db_dsn())
+
+
+class DatabaseUnavailable(RuntimeError):
+    """The engine's Postgres + pgvector database couldn't be reached. Subclasses RuntimeError
+    so `_run_async` prints its (actionable) message as a clean `error: ...` line — the
+    docker-first quickstart path (docs/14), not a raw asyncpg/OSError traceback."""
+
+
+def _safe_dsn(dsn: str) -> str:
+    """A DSN with any embedded password stripped — safe to print in a user-facing error (a DSN
+    from URO_DATABASE_URL may carry credentials). Keeps user@host:port/db for debuggability."""
+    try:
+        p = urlsplit(dsn)
+    except ValueError:
+        return "the configured database"
+    if not p.hostname:
+        return dsn  # not a URL DSN (e.g. a keyword string) — nothing to strip
+    user = f"{p.username}@" if p.username else ""
+    port = f":{p.port}" if p.port else ""
+    return urlunsplit((p.scheme, f"{user}{p.hostname}{port}", p.path, "", ""))
+
+
+async def connect_store(store: PostgresEventStore) -> None:
+    """Open the store's connection pool, translating a connection failure into an actionable
+    hint. Uro's only store is Postgres + pgvector (D-43): if it isn't up, point the user at
+    the one command that starts it rather than leaking the driver's error."""
+    try:
+        await store.connect()
+    except (OSError, asyncpg.PostgresError) as exc:
+        raise DatabaseUnavailable(
+            f"can't reach the Uro database at {_safe_dsn(store.dsn)}. Start Postgres + pgvector "
+            "with `docker compose up -d --wait` (host port 5433), then `uro db migrate`. "
+            "Point elsewhere with URO_DATABASE_URL. See the README quickstart."
+        ) from exc
+
+
+def build_ruleset(
+    ruleset_id: str = "", version: str = "", config: dict[str, Any] | None = None
+) -> Ruleset:
+    """Resolve a campaign's / world pack's declared ruleset to a bound instance via the registry
+    (docs/06, D-30). Empty id → the default (uro-basic); an unknown id raises. The play/campaign
+    paths pass the campaign's or world's recorded id so a PbtA world binds uro_pbta, not the
+    hard-coded default it used to."""
+    return registry.resolve(ruleset_id, version, config)
+
+
+def _config() -> dict[str, Any]:
+    explicit = os.environ.get("URO_CONFIG")
+    path = Path(explicit) if explicit else Path("uro.toml")
+    if not path.is_file():
+        if explicit:  # explicitly set but not a file → loud, not silently ignored
+            raise RuntimeError(f"URO_CONFIG={path} is not a file")
+        return {}
+    try:
+        return tomllib.loads(path.read_text())
+    except tomllib.TOMLDecodeError as exc:
+        raise RuntimeError(f"malformed config {path}: {exc}") from exc
+
+
+def load_role_specs() -> dict[str, str]:
+    roles = _config().get("llm", {}).get("roles", {})
+    return {str(role): str(spec) for role, spec in roles.items()}
+
+
+def build_provider(kind: str, model: str | None) -> LLMProvider:
+    if kind == "stub":
+        return StubProvider()
+    if kind == "local":
+        return OpenAICompatProvider(
+            model=model or "llama3.1",
+            base_url=os.environ.get("URO_LOCAL_BASE_URL", "http://localhost:11434/v1"),
+        )
+    if kind == "openai":
+        api_key = os.environ.get("OPENAI_API_KEY")
+        if not api_key:
+            raise RuntimeError("OPENAI_API_KEY is not set")
+        return OpenAICompatProvider(model=model or "gpt-4o-mini", api_key=api_key)
+    if kind == "anthropic":
+        api_key = os.environ.get("ANTHROPIC_API_KEY")
+        if not api_key:
+            raise RuntimeError("ANTHROPIC_API_KEY is not set")
+        return AnthropicProvider(model=model or "claude-sonnet-5", api_key=api_key)
+    raise ValueError(
+        f"unknown provider kind {kind!r} (expected: stub | local | openai | anthropic)"
+    )
+
+
+def provider_from_spec(spec: str) -> LLMProvider:
+    """Parse a 'kind:model' (or bare 'kind') role binding into a provider."""
+    kind, _, model = spec.partition(":")
+    return build_provider(kind.strip(), model.strip() or None)
+
+
+def build_embedder(kind: str) -> LLMProvider | None:
+    """A provider bound to an EMBEDDING model for the `embedder` role, or None if the
+    default already embeds (stub) / no embedding provider is available (anthropic w/o
+    OpenAI key → semantic recall degrades gracefully to structured-only)."""
+    if kind == "stub":
+        return None
+    if kind == "local":
+        return OpenAICompatProvider(
+            model=os.environ.get("URO_EMBED_MODEL", "nomic-embed-text"),
+            base_url=os.environ.get("URO_LOCAL_BASE_URL", "http://localhost:11434/v1"),
+        )
+    if kind in ("openai", "anthropic"):
+        api_key = os.environ.get("OPENAI_API_KEY")
+        if not api_key:
+            return None  # no embedding endpoint → semantic recall disabled (best-effort)
+        return OpenAICompatProvider(
+            model=os.environ.get("URO_EMBED_MODEL", "text-embedding-3-small"), api_key=api_key
+        )
+    return None
+
+
+def parse_role_models(overrides: list[str] | None) -> dict[str, str]:
+    """Parse repeatable `--role-model role=spec` CLI overrides into {role: spec}. `spec` is a
+    full provider spec ('openai:gpt-4o') or a bare model ('gpt-4o', bound to the default
+    provider kind). Malformed entries raise — a CLI override is explicit intent (docs/04)."""
+    result: dict[str, str] = {}
+    for item in overrides or []:
+        role, sep, spec = item.partition("=")
+        role, spec = role.strip(), spec.strip()
+        if not sep or not role or not spec:
+            raise ValueError(
+                f"bad --role-model {item!r}; expected role=spec, e.g. planner=openai:gpt-4o"
+            )
+        result[role] = spec
+    return result
+
+
+def build_router(
+    kind: str, model: str | None, role_models: dict[str, str] | None = None
+) -> ProviderRouter:
+    # The default provider is required (it narrates + backs unpinned roles). A *pinned*
+    # role whose provider can't be built (e.g. an unused role missing its key) is skipped
+    # with a warning and falls back to the default, rather than bricking the whole router.
+    default = build_provider(kind, model)
+    bindings: dict[str, LLMProvider] = {}
+    for role, spec in load_role_specs().items():
+        try:
+            bindings[role] = provider_from_spec(spec)
+        except (RuntimeError, ValueError) as exc:
+            logger.warning("role %r (%s) unavailable, using default: %s", role, spec, exc)
+    if "embedder" not in bindings:
+        try:
+            embedder = build_embedder(kind)
+        except (RuntimeError, ValueError):
+            embedder = None
+        if embedder is not None:
+            bindings["embedder"] = embedder
+    # CLI --role-model overrides win over uro.toml (the deployment's explicit last word). A bare
+    # model reuses the default provider kind. Unlike a config role, an explicit override that can't
+    # be built raises — the user asked for it by name; silently ignoring it would mislead.
+    for role, spec in (role_models or {}).items():
+        full = spec if ":" in spec else f"{kind}:{spec}"
+        bindings[role] = provider_from_spec(full)
+    return ProviderRouter(bindings=bindings, default=default)

uro_cli-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+uro_cli/__init__.py,sha256=-sK_hxpyzYOk-6FupyEr5eIKmvDJAEV9BOAfgVqN5UU,290
+uro_cli/main.py,sha256=Q6tyKPuTGv--YEefgUg4BmBLYOve_oT9XOy9aNFQ8gw,45477
+uro_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+uro_cli/wiring.py,sha256=bgvmIbIuY8uXx0PmxX8P9ejmXlDU8k539vKUsvZBBV8,8550
+uro_cli-0.2.0.dist-info/METADATA,sha256=je1X0DvZKjObWauLNHj3RhRS7rr_gVJR0nCS7Hi0VyM,1847
+uro_cli-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+uro_cli-0.2.0.dist-info/entry_points.txt,sha256=za99ldNvXih5o5djjZjfV3tVsvjw_CTc5iH0en64DjI,41
+uro_cli-0.2.0.dist-info/licenses/LICENSE,sha256=EULDR6F7DrDMXRHwkUgLPfsupPZdMj945mS6-DrTXWk,1065
+uro_cli-0.2.0.dist-info/RECORD,,

uro_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

uro_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+uro = uro_cli.main:app

uro_cli-0.2.0.dist-info/licenses/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.