urirun-reasoner 0.1.0__tar.gz

urirun_reasoner-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: urirun-reasoner
+Version: 0.1.0
+Summary: Intent → need → capability → URI plan, headless-first. Model the goal not the app: a missing GUI editor is one blocked method, not the end. Deterministic core, LLM only as fallback.
+Author: Tom Sapletta
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# urirun-reasoner
+
+Intent → need → capability → URI plan, **headless-first**. Model the GOAL, not the app.
+
+A missing GUI editor is one blocked method in a graph — not the end of the road. Asked to
+"test office on lenovo", the reasoner does not stop at "no LibreOffice"; it reframes to
+"produce a document artifact and verify it exists" and resolves it through the cheapest
+feasible URI path.
+
+## The resolution ladder (kernel decides, cheapest/safest first)
+
+1. **direct** — a capability is already served on the node (headless)
+2. **host_fallback** — a headless capability runs host-side + sync (no node change)
+3. **install_then_run** — a connector provides it and the node can manage (install → rebuild → restart → smoke → use)
+4. **gui** — a GUI capability, only as a last resort
+5. **blocked** — nothing feasible → honest, with what was tried
+
+GUI is never chosen when a headless path exists; connectors are never installed blindly.
+
+## Layers
+
+| module | role |
+|---|---|
+| `needs.py` | `NeedSpec` — the intent contract (goal, required outputs, preferred/acceptable capabilities, requires_gui) + a catalog |
+| `capabilities.py` | `CapabilityMap` — capability → URI route templates + connectors (the layer between language and URIs) |
+| `intent.py` | prompt → NeedSpec (rules first; LLM only names the intent, never invents URIs) |
+| `planner.py` | the deterministic ladder + `resolve(need, ctx)` with a postcondition |
+
+## Use
+
+```python
+from urirun_reasoner import Context, resolve_prompt
+ctx = Context(node="lenovo", node_served=[...], host_served=["fs://host/file/command/write"],
+              installable={"sheet"}, can_manage=True)
+plan = resolve_prompt("przetestuj biuro na lenovo", ctx)
+# → {"strategy": "host_fallback", "steps": [...], "postcondition": {...}}
+```
+
+Pairs with `urirun-fleet` (node readiness + execution) and the dispatch `_meta` provenance
+(so the reasoner knows what is actually served). Part of the ifURI solution · Apache-2.0

urirun_reasoner-0.1.0/README.md

@@ -0,0 +1,40 @@
+# urirun-reasoner
+
+Intent → need → capability → URI plan, **headless-first**. Model the GOAL, not the app.
+
+A missing GUI editor is one blocked method in a graph — not the end of the road. Asked to
+"test office on lenovo", the reasoner does not stop at "no LibreOffice"; it reframes to
+"produce a document artifact and verify it exists" and resolves it through the cheapest
+feasible URI path.
+
+## The resolution ladder (kernel decides, cheapest/safest first)
+
+1. **direct** — a capability is already served on the node (headless)
+2. **host_fallback** — a headless capability runs host-side + sync (no node change)
+3. **install_then_run** — a connector provides it and the node can manage (install → rebuild → restart → smoke → use)
+4. **gui** — a GUI capability, only as a last resort
+5. **blocked** — nothing feasible → honest, with what was tried
+
+GUI is never chosen when a headless path exists; connectors are never installed blindly.
+
+## Layers
+
+| module | role |
+|---|---|
+| `needs.py` | `NeedSpec` — the intent contract (goal, required outputs, preferred/acceptable capabilities, requires_gui) + a catalog |
+| `capabilities.py` | `CapabilityMap` — capability → URI route templates + connectors (the layer between language and URIs) |
+| `intent.py` | prompt → NeedSpec (rules first; LLM only names the intent, never invents URIs) |
+| `planner.py` | the deterministic ladder + `resolve(need, ctx)` with a postcondition |
+
+## Use
+
+```python
+from urirun_reasoner import Context, resolve_prompt
+ctx = Context(node="lenovo", node_served=[...], host_served=["fs://host/file/command/write"],
+              installable={"sheet"}, can_manage=True)
+plan = resolve_prompt("przetestuj biuro na lenovo", ctx)
+# → {"strategy": "host_fallback", "steps": [...], "postcondition": {...}}
+```
+
+Pairs with `urirun-fleet` (node readiness + execution) and the dispatch `_meta` provenance
+(so the reasoner knows what is actually served). Part of the ifURI solution · Apache-2.0

urirun_reasoner-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "urirun-reasoner"
+version = "0.1.0"
+description = "Intent → need → capability → URI plan, headless-first. Model the goal not the app: a missing GUI editor is one blocked method, not the end. Deterministic core, LLM only as fallback."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Tom Sapletta" }]
+dependencies = []
+
+[project.scripts]
+urirun-reasoner = "urirun_reasoner.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["urirun_reasoner*"]

urirun_reasoner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

urirun_reasoner-0.1.0/tests/test_reasoner.py

@@ -0,0 +1,119 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""The reasoner contract: model the goal not the app, and walk the ladder cheapest-first.
+GUI is the LAST resort; a missing editor never ends the process."""
+from urirun_reasoner import Context, intent, needs, planner, resolve, resolve_prompt
+
+
+def test_intent_maps_office_words_to_document_need():
+    assert intent.classify("napisz artykuł w edytorze tekstu").id == "office.document.create"
+    assert intent.classify("przetestuj biuro na lenovo").id == "office.document.create"
+    assert intent.classify("stwórz arkusz z danymi").id == "office.spreadsheet.create"
+    assert intent.classify("zupełnie coś innego") is None
+
+
+def test_direct_when_capability_already_served():
+    ctx = Context(node="laptop", node_served=["sheet://laptop/workbook/command/write"])
+    p = planner.resolve(needs.OFFICE_DOCUMENT, ctx)
+    assert p["resolved"] and p["strategy"] == "direct" and p["capability"] == "sheet.write"
+    assert p["steps"][0]["uri"] == "sheet://laptop/workbook/command/write"
+
+
+def test_host_fallback_before_install_when_node_lacks_it():
+    # node serves nothing useful; host can write files → host_fallback beats installing
+    ctx = Context(node="laptop", node_served=["kvm://laptop/screen/query/capture"],
+                  host_served=["fs://host/file/command/write"],
+                  installable={"sheet"}, can_manage=True)
+    p = planner.resolve(needs.OFFICE_DOCUMENT, ctx)
+    assert p["strategy"] == "host_fallback" and p["capability"] == "markdown.write"
+    assert p["steps"][0]["uri"] == "fs://host/file/command/write"
+
+
+def test_install_when_no_direct_and_no_host_fallback():
+    # nothing served anywhere, but a connector is installable and the node can manage
+    ctx = Context(node="laptop", node_served=[], host_served=[],
+                  installable={"sheet"}, can_manage=True)
+    p = planner.resolve(needs.OFFICE_DOCUMENT, ctx)
+    assert p["strategy"] == "install_then_run" and p["connector"] == "sheet"
+    uris = [s["uri"] for s in p["steps"]]
+    assert uris[0] == "node://laptop/connector/command/install"
+    assert "node://laptop/runtime/command/restart" in uris  # drop stale workers
+    assert uris[-1].startswith("sheet://laptop/")            # then actually use it
+
+
+def test_gui_is_last_resort_only_when_allowed_and_nothing_else():
+    ctx = Context(node="laptop", node_served=["browser://laptop/page/command/navigate"],
+                  host_served=[], installable=set(), can_manage=False, allow_gui=True)
+    p = planner.resolve(needs.OFFICE_DOCUMENT, ctx)
+    assert p["strategy"] == "gui" and p["capability"] == "browser.document_edit"
+
+
+def test_gui_not_chosen_when_headless_exists():
+    # both a served browser (gui) AND a served sheet (headless) → headless wins
+    ctx = Context(node="laptop",
+                  node_served=["browser://laptop/page/command/navigate",
+                               "sheet://laptop/workbook/command/write"],
+                  allow_gui=True)
+    p = planner.resolve(needs.OFFICE_DOCUMENT, ctx)
+    assert p["strategy"] == "direct" and p["capability"] == "sheet.write"
+
+
+def test_blocked_is_honest_with_what_was_tried():
+    ctx = Context(node="laptop", node_served=[], host_served=[], installable=set(),
+                  can_manage=False, allow_gui=False)
+    p = planner.resolve(needs.OFFICE_DOCUMENT, ctx)
+    assert p["resolved"] is False and set(p["tried"]) >= {"direct", "host_fallback", "install", "gui"}
+
+
+def test_plan_carries_postcondition():
+    ctx = Context(node="laptop", node_served=["sheet://laptop/workbook/command/write"])
+    p = planner.resolve(needs.OFFICE_DOCUMENT, ctx)
+    assert p["postcondition"] and p["postcondition"]["check"] == "exists"
+
+
+def test_resolve_prompt_office_on_lenovo_reframes_to_headless():
+    # THE flagship case: "test office on lenovo" with no GUI → headless host fallback
+    ctx = Context(node="lenovo", node_served=["kvm://lenovo/screen/query/capture"],
+                  host_served=["fs://host/file/command/write"], installable={"sheet"},
+                  can_manage=True, allow_gui=True)
+    p = resolve_prompt("przetestuj biuro na lenovo", ctx)
+    assert p["resolved"] and p["strategy"] == "host_fallback"
+    assert p["need"] == "office.document.create" and not p["strategy"] == "gui"
+
+
+# --- gates: risky actions are never ungated -------------------------------------
+def test_gate_classifies_risky_verbs():
+    from urirun_reasoner import gates
+    assert gates.gate_for("linkedin://user/post/command/publish")
+    assert gates.gate_for("fiverr://user/order/command/pay")
+    assert gates.gate_for("email://user/message/command/send")
+    assert gates.gate_for("fs://host/file/command/write") is None      # autonomous
+    assert gates.gate_for("sheet://host/workbook/command/write") is None
+
+
+def test_gate_inserts_approval_before_publish():
+    from urirun_reasoner import gates
+    steps = [{"uri": "llm://host/social/command/write-linkedin-post"},
+             {"uri": "linkedin://user/post/command/publish"}]
+    out = gates.apply(steps)
+    assert out[0]["uri"].endswith("social/command/write-linkedin-post")   # autonomous kept
+    assert out[1]["uri"].startswith("approval://human/")                  # gate inserted
+    assert out[2]["gate"] == "required"
+    assert gates.has_ungated_risk(out) == []                              # audit clean
+
+
+def test_audit_catches_bare_payment():
+    from urirun_reasoner import gates
+    risky = gates.has_ungated_risk([{"uri": "fiverr://user/order/command/pay"}])
+    assert risky == ["fiverr://user/order/command/pay"]
+
+
+def test_generator_scaffolds_a_valid_connector(tmp_path):
+    from urirun_reasoner import generator
+    spec = {"id": "demo", "scheme": "demo", "summary": "x",
+            "handlers": [{"route": "thing/query/list", "params": "", "body": 'return _ok(action="x")'}]}
+    r = generator.generate(spec, tmp_path)
+    assert r["ok"] and r["routes"] == ["thing/query/list"]
+    core = (tmp_path / "urirun-connector-demo" / "urirun_connector_demo" / "core.py").read_text()
+    assert 'scheme="demo"' in core and "def thing_query_list" in core
+    assert (tmp_path / "urirun-connector-demo" / "pyproject.toml").is_file()
+    assert (tmp_path / "urirun-connector-demo" / "tests" / "test_demo.py").is_file()

urirun_reasoner-0.1.0/urirun_reasoner/__init__.py

@@ -0,0 +1,26 @@
+# Author: Tom Sapletta · https://tom.sapletta.com
+# Part of the ifURI solution.
+"""urirun-reasoner — intent → need → capability → URI plan, headless-first.
+
+Model the GOAL, not the app. A missing GUI editor is one blocked method in a graph, not
+the end of the road: the reasoner reframes "test office" into "produce a document
+artifact" and resolves it through the cheapest feasible URI path (served route → host
+fallback → install connector → GUI last). Deterministic core; LLM only where rules can't.
+"""
+from __future__ import annotations
+
+from . import capabilities, intent, needs, planner
+from .needs import NeedSpec
+from .planner import Context, resolve
+
+__all__ = ["capabilities", "intent", "needs", "planner", "NeedSpec", "Context", "resolve"]
+
+
+def resolve_prompt(prompt: str, ctx: "Context", *, llm=None) -> dict:
+    """One call: classify the prompt to a need, then resolve it to a URI plan."""
+    need = intent.classify(prompt, llm=llm)
+    if not need:
+        return {"resolved": False, "reason": f"could not classify intent: {prompt!r}"}
+    plan = resolve(need, ctx)
+    plan["goal"] = need.goal
+    return plan

urirun_reasoner-0.1.0/urirun_reasoner/capabilities.py

@@ -0,0 +1,83 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""CapabilityMap — the missing layer between a NEED and concrete URIs/connectors.
+
+A capability (e.g. ``document.create``) maps to the routes that provide it and the
+connectors that install it. This is what turns "I need to author a document" into
+"call sheet://… , or install urirun-connector-sheet". Route templates use ``{node}``.
+"""
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Capability:
+    id: str
+    routes: tuple[str, ...]        # URI templates ({node} placeholder)
+    connectors: tuple[str, ...] = ()  # connector ids that provide this capability
+    gui: bool = False
+    host_ok: bool = True           # can this run host-side as a fallback?
+
+
+MAP: dict[str, Capability] = {
+    "document.create": Capability("document.create",
+        ("document://{node}/document/command/create", "odt://{node}/document/command/create"),
+        ("document", "office"), host_ok=True),
+    "sheet.write": Capability("sheet.write",
+        ("sheet://{node}/workbook/command/write", "sheet://{node}/rows/command/write",
+         "xlsx://{node}/workbook/command/write"),
+        ("sheet",), host_ok=True),
+    "invoice.render": Capability("invoice.render",
+        ("invoice://{node}/invoice/command/render", "invoice://{node}/document/command/build"),
+        ("invoice",), host_ok=True),
+    "markdown.write": Capability("markdown.write",
+        ("fs://{node}/file/command/write",), ("fs",), host_ok=True),
+    "html.write": Capability("html.write",
+        ("fs://{node}/file/command/write",), ("fs",), host_ok=True),
+    "browser.document_edit": Capability("browser.document_edit",
+        ("browser://{node}/page/command/navigate", "cdp://{node}/page/command/navigate"),
+        ("browser", "cdp"), gui=True, host_ok=False),
+    "screen.capture": Capability("screen.capture",
+        ("screen://{node}/screen/query/capture", "kvm://{node}/screen/query/capture",
+         "view://{node}/screenshot/query/capture"),
+        ("kvm",), host_ok=False),
+}
+
+
+def get(cap_id: str) -> Capability | None:
+    return MAP.get(cap_id)
+
+
+def _served(route_tmpl: str, node: str, served: list[str]) -> str | None:
+    """Return the concrete served route matching this template for ``node``, else None."""
+    want = route_tmpl.replace("{node}", node)
+    tail = want.split("://", 1)[-1]
+    for r in served:
+        if r == want or fnmatch.fnmatch(r.split("://", 1)[-1], tail) or \
+           fnmatch.fnmatch(r.split("://", 1)[-1], route_tmpl.split("://", 1)[-1].replace("{node}", "*")):
+            return r
+    return None
+
+
+def served_route(cap_id: str, node: str, served: list[str]) -> str | None:
+    """Is this capability already served on the node? Return the concrete route or None."""
+    cap = MAP.get(cap_id)
+    if not cap:
+        return None
+    for tmpl in cap.routes:
+        hit = _served(tmpl, node, served)
+        if hit:
+            return hit
+    return None
+
+
+def install_route(cap_id: str, node: str) -> str:
+    """The concrete route to call once the capability's connector is installed."""
+    cap = MAP.get(cap_id)
+    return cap.routes[0].replace("{node}", node) if cap else ""
+
+
+def providers(cap_id: str) -> tuple[str, ...]:
+    cap = MAP.get(cap_id)
+    return cap.connectors if cap else ()

urirun_reasoner-0.1.0/urirun_reasoner/cli.py

@@ -0,0 +1,25 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""urirun-reasoner CLI: resolve a prompt to a headless-first URI plan."""
+from __future__ import annotations
+import argparse, json
+from . import Context, resolve_prompt
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="urirun-reasoner")
+    ap.add_argument("prompt")
+    ap.add_argument("--node", default="host")
+    ap.add_argument("--node-served", nargs="*", default=[])
+    ap.add_argument("--host-served", nargs="*", default=[])
+    ap.add_argument("--installable", nargs="*", default=[])
+    ap.add_argument("--can-manage", action="store_true")
+    ap.add_argument("--allow-gui", action="store_true")
+    a = ap.parse_args(argv)
+    ctx = Context(node=a.node, node_served=a.node_served, host_served=a.host_served,
+                  installable=set(a.installable), can_manage=a.can_manage, allow_gui=a.allow_gui)
+    print(json.dumps(resolve_prompt(a.prompt, ctx), indent=1, default=str))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

urirun_reasoner-0.1.0/urirun_reasoner/gates.py

@@ -0,0 +1,64 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""Gates — the hard rules on what the system may NEVER do without a human.
+
+A plan step is classified by its URI: publishing, paying, messaging a vendor, ordering,
+or sending private files are ALWAYS human-gated; searching, drafting, packaging,
+comparing, generating a document are autonomous. The planner inserts an
+``approval://human/...`` gate before any gated step, or downgrades it to draft mode.
+"""
+from __future__ import annotations
+
+# (matcher substring, gate reason) — a step whose URI contains the substring is gated
+_GATED: list[tuple[str, str]] = [
+    ("/command/publish", "public publication requires human approval"),
+    ("/command/pay", "payment always requires human approval"),
+    ("/command/schedule", "scheduling a public post requires human approval"),
+    ("/message/command/send", "sending a message to a vendor requires human approval"),
+    ("/email/command/send", "sending email requires human approval"),
+    ("/order/command", "placing/ordering a service requires human approval"),
+    ("/command/confirm", "confirmation of a paid/committed action requires a human"),
+]
+
+# autonomous-safe verbs (never gated) — for documentation / assertion
+AUTONOMOUS = ("query/", "command/write", "command/draft", "command/package",
+              "command/render", "command/create", "command/summarize", "command/extract",
+              "command/compare", "command/search", "command/build")
+
+
+def gate_for(uri: str) -> str | None:
+    """Return the human-gate reason for a URI, or None if it is autonomous-safe."""
+    u = str(uri)
+    for needle, reason in _GATED:
+        if needle in u:
+            return reason
+    return None
+
+
+def apply(steps: list[dict], *, node_for_approval: str = "human") -> list[dict]:
+    """Insert an approval:// gate before each gated step; leave autonomous steps as-is.
+
+    Returns a new step list. A gated step also gets ``gate: "required"`` so an executor
+    refuses to run it until the preceding approval is granted (draft-then-approve)."""
+    out: list[dict] = []
+    for step in steps:
+        reason = gate_for(step.get("uri", ""))
+        if reason:
+            out.append({"uri": f"approval://{node_for_approval}/action/command/review",
+                        "for": "gate", "reason": reason, "reviews": step.get("uri")})
+            out.append({**step, "gate": "required"})
+        else:
+            out.append(step)
+    return out
+
+
+def has_ungated_risk(steps: list[dict]) -> list[str]:
+    """Audit: return URIs of any gated step NOT immediately preceded by an approval.
+    A safety net — the plan must never carry a bare publish/pay/send."""
+    risky: list[str] = []
+    prev_is_gate = False
+    for step in steps:
+        uri = step.get("uri", "")
+        if gate_for(uri) and not prev_is_gate:
+            risky.append(uri)
+        prev_is_gate = uri.startswith("approval://")
+    return risky

urirun_reasoner-0.1.0/urirun_reasoner/generation_policy.py

@@ -0,0 +1,57 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""Generation policy — the rules under which the system may create a NEW connector itself.
+
+Autonomy needs guardrails, not permission prompts. A connector spec is admissible only if
+it introduces a NEW scheme (never silently overwrites a served one), every handler routes
+through the urirun envelope, any destructive/network verb (delete/pay/publish/send) is
+marked gated, no secret is baked inline, and the id/scheme are clean slugs. A generated
+connector must pass its own smoke test before it is installed or published. These checks
+are what let the reasoner call ``connector://.../generate`` without asking a human first.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_SLUG = re.compile(r"^[a-z][a-z0-9-]{1,39}$")
+_GATED_VERBS = ("delete", "pay", "publish", "send", "order", "remove", "drop", "wipe", "purge")
+_SECRET_HINT = re.compile(r"(password|api[_-]?key|secret|token)\s*=\s*['\"][^'\"]+['\"]", re.I)
+
+
+def check(spec: dict, *, served_schemes: set | None = None) -> dict[str, Any]:
+    """Validate a connector spec against the generation policy. Returns
+    {ok, violations, gated_routes}. ``served_schemes`` are schemes already served (must not
+    be overwritten)."""
+    violations: list[str] = []
+    cid = str(spec.get("id", ""))
+    scheme = str(spec.get("scheme", cid))
+    if not _SLUG.match(cid):
+        violations.append(f"id {cid!r} is not a clean slug [a-z][a-z0-9-]{{1,39}}")
+    if not _SLUG.match(scheme):
+        violations.append(f"scheme {scheme!r} is not a clean slug")
+    if served_schemes and scheme in served_schemes:
+        violations.append(f"scheme '{scheme}://' is already served — refuse to overwrite (bump/rename instead)")
+
+    handlers = spec.get("handlers") or []
+    if not handlers:
+        violations.append("spec has no handlers")
+    gated_routes: list[str] = []
+    for h in handlers:
+        route = str(h.get("route", ""))
+        if "/" not in route:
+            violations.append(f"handler route {route!r} must look like 'noun/verb/name'")
+        body = str(h.get("body", ""))
+        if _SECRET_HINT.search(body):
+            violations.append(f"handler {route!r} appears to hardcode a secret — use secret:// references")
+        # a destructive/network verb must be declared gated so an executor requires approval
+        if any(v in route.lower() for v in _GATED_VERBS):
+            if not h.get("gated"):
+                violations.append(f"handler {route!r} uses a destructive/network verb but is not marked gated")
+            gated_routes.append(route)
+
+    return {"ok": not violations, "violations": violations, "gated_routes": gated_routes,
+            "id": cid, "scheme": scheme}
+
+
+def admissible(spec: dict, *, served_schemes: set | None = None) -> bool:
+    return check(spec, served_schemes=served_schemes)["ok"]

urirun_reasoner-0.1.0/urirun_reasoner/generator.py

@@ -0,0 +1,149 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""Connector generator — the autonomy that CLOSES the loop instead of waiting for a human.
+
+When the reasoner reports a capability blocked because a scheme has no connector, this
+generator scaffolds a complete, installable urirun connector from a spec (id, scheme,
+handlers). Handler bodies come from the spec (deterministic) or an LLM (for novel logic);
+the structure — pyproject, entry point, envelope, manifest, __init__, a smoke test — is
+templated and always valid. The result is a package a node can pip-install.
+
+    spec = {"id": "document", "scheme": "document", "summary": "...",
+            "handlers": [{"route": "document/command/create", "label": "...",
+                          "params": "path: str = '', text: str = ''", "body": "..."}]}
+    generate(spec, dest) -> writes urirun-connector-<id>/…
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+_PYPROJECT = '''[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "urirun-connector-{id}"
+version = "0.1.0"
+description = "{summary}"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {{ text = "Apache-2.0" }}
+authors = [{{ name = "Tom Sapletta" }}]
+dependencies = ["urirun>=0.4.14"{extra_deps}]
+
+[project.entry-points."urirun.bindings"]
+{id} = "urirun_connector_{mod}.core:urirun_bindings"
+
+[tool.setuptools.packages.find]
+include = ["urirun_connector_{mod}*"]
+'''
+
+_CORE_HEADER = '''# Author: Tom Sapletta · Part of the ifURI solution — GENERATED by urirun-reasoner.
+"""urirun-connector-{id} — {summary}
+
+Generated autonomously to satisfy a capability the reasoner found blocked (no connector
+served the {scheme}:// scheme). Built to URI_NATIVE_CONNECTOR_CHECKLIST: lazy imports,
+handlers never raise (urirun envelope), queries in-process.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import urirun
+
+CONNECTOR_ID = "{id}"
+conn = urirun.connector(CONNECTOR_ID, scheme="{scheme}")
+
+
+def _ok(**kw: Any) -> dict[str, Any]:
+    return urirun.ok(connector=CONNECTOR_ID, **kw)
+
+
+def _fail(msg: str, action: str, **extra: Any) -> dict[str, Any]:
+    return urirun.fail(msg, connector=CONNECTOR_ID, action=action, **extra)
+
+'''
+
+_HANDLER = '''
+@conn.handler("{route}", isolated={isolated},
+              meta={{"label": "{label}"}})
+def {fn}({params}) -> dict[str, Any]:
+    """{doc}"""
+    try:
+{body}
+    except Exception as exc:  # noqa: BLE001
+        return _fail(str(exc), "{action}")
+
+'''
+
+_CORE_FOOTER = '''
+def urirun_bindings() -> dict[str, Any]:
+    return conn.bindings()
+
+
+def connector_manifest() -> dict[str, Any]:
+    return urirun.load_manifest(__package__) or {"id": CONNECTOR_ID}
+
+
+def main(argv: list[str] | None = None) -> int:
+    return conn.cli(argv, manifest_prose=urirun.load_manifest(__package__))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+'''
+
+
+def _fn_name(route: str) -> str:
+    return route.replace("/", "_").replace("-", "_")
+
+
+def _core(spec: dict) -> str:
+    parts = [_CORE_HEADER.format(id=spec["id"], scheme=spec.get("scheme", spec["id"]),
+                                 summary=spec.get("summary", ""))]
+    for h in spec.get("handlers", []):
+        body = "\n".join("        " + ln for ln in (h.get("body") or 'return _ok(action="todo")').splitlines())
+        parts.append(_HANDLER.format(
+            route=h["route"], isolated=str(bool(h.get("isolated", "/command/" in h["route"]))),
+            label=h.get("label", h["route"]), fn=_fn_name(h["route"]),
+            params=h.get("params", ""), doc=h.get("doc", h.get("label", h["route"])),
+            body=body, action=h.get("action", spec["id"] + "-" + _fn_name(h["route"]))))
+    parts.append(_CORE_FOOTER)
+    return "".join(parts)
+
+
+def _smoke_test(spec: dict) -> str:
+    mod = spec["id"].replace("-", "_")
+    lines = ["# GENERATED smoke test — every handler returns a well-formed urirun envelope.",
+             f"from urirun_connector_{mod} import core\n\n",
+             "def test_bindings_expose_all_routes():",
+             f"    text = str(core.urirun_bindings())"]
+    for h in spec.get("handlers", []):
+        lines.append(f'    assert {h["route"]!r} in text')
+    return "\n".join(lines) + "\n"
+
+
+def generate(spec: dict, dest: str | Path) -> dict[str, Any]:
+    """Write a complete connector package under ``dest/urirun-connector-<id>/``."""
+    cid = spec["id"]
+    mod = cid.replace("-", "_")
+    root = Path(dest) / f"urirun-connector-{cid}"
+    pkg = root / f"urirun_connector_{mod}"
+    (pkg / "").mkdir(parents=True, exist_ok=True)
+    (root / "tests").mkdir(parents=True, exist_ok=True)
+
+    extra = "".join(f', "{d}"' for d in spec.get("deps", []))
+    (root / "pyproject.toml").write_text(
+        _PYPROJECT.format(id=cid, mod=mod, summary=spec.get("summary", ""), extra_deps=extra),
+        encoding="utf-8")
+    (pkg / "core.py").write_text(_core(spec), encoding="utf-8")
+    (pkg / "__init__.py").write_text(
+        f"from .core import CONNECTOR_ID, connector_manifest, main, urirun_bindings\n"
+        f'__all__ = ["CONNECTOR_ID", "connector_manifest", "main", "urirun_bindings"]\n',
+        encoding="utf-8")
+    (root / "tests" / f"test_{mod}.py").write_text(_smoke_test(spec), encoding="utf-8")
+    (root / "README.md").write_text(
+        f"# urirun-connector-{cid}\n\n{spec.get('summary','')}\n\n"
+        f"Generated by urirun-reasoner to serve the `{spec.get('scheme', cid)}://` scheme.\n"
+        f"Part of the ifURI solution · Apache-2.0\n", encoding="utf-8")
+    return {"ok": True, "path": str(root), "routes": [h["route"] for h in spec.get("handlers", [])]}

urirun_reasoner-0.1.0/urirun_reasoner/intent.py

@@ -0,0 +1,40 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""Intent classification — prompt → NeedSpec. Rules first, LLM only as a fallback.
+
+Most needs are recognizable by keyword (deterministic, no model call). An injected LLM
+resolves novel prompts to a known need id; it never invents URIs, only names the intent —
+"LLM proposes the need, the kernel maps it to capabilities and decides the method."
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from . import needs as _needs
+
+Completer = Callable[[str], str]
+
+# keyword → need id (rule-based, cheap path)
+_RULES: list[tuple[tuple[str, ...], str]] = [
+    (("arkusz", "spreadsheet", "xlsx", "excel", "tabela"), "office.spreadsheet.create"),
+    (("dokument", "document", "artykuł", "article", "biuro", "office", "notatk", "pismo",
+      "edytor", "editor", "napisz", "write", "libreoffice", "onlyoffice", "faktur", "invoice"),
+     "office.document.create"),
+    (("zrzut", "screenshot", "ekran", "screen capture", "capture"), "desktop.screenshot"),
+]
+
+
+def classify(prompt: str, llm: Completer | None = None) -> _needs.NeedSpec | None:
+    """Return the NeedSpec for a prompt. Rule-based first; LLM fallback names the need id."""
+    low = (prompt or "").lower()
+    for keywords, need_id in _RULES:
+        if any(k in low for k in keywords):
+            return _needs.get(need_id)
+    if llm:
+        try:
+            catalog = ", ".join(_needs.CATALOG)
+            reply = llm(f"Map this request to ONE need id from [{catalog}] or 'none'. "
+                        f"Reply with only the id.\nRequest: {prompt}").strip().strip('"')
+            return _needs.get(reply)
+        except Exception:  # noqa: BLE001 - a bad LLM reply just means 'unclassified'
+            return None
+    return None

urirun_reasoner-0.1.0/urirun_reasoner/needs.py

@@ -0,0 +1,60 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""NeedSpec — the contract of an INTENT, not a URI. Models the goal, not the app.
+
+"Test office on lenovo" is not "launch ONLYOFFICE" — it is "produce a document artifact
+and verify it exists". Modeling the need (not the means) is what lets the planner reframe
+away from a missing GUI editor to a headless path. Each need lists the capabilities that
+would satisfy it (preferred → acceptable) and whether a GUI is genuinely required.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class NeedSpec:
+    id: str
+    goal: str
+    required_outputs: tuple[str, ...] = ()        # artifact/postcondition globs proving success
+    preferred_capabilities: tuple[str, ...] = ()  # best (headless, verifiable) first
+    acceptable_capabilities: tuple[str, ...] = ()  # fallbacks that still satisfy the goal
+    forbidden_methods: tuple[str, ...] = ()
+    requires_gui: bool = False
+    destructive: bool = False
+
+    def capabilities(self) -> list[str]:
+        return list(self.preferred_capabilities) + list(self.acceptable_capabilities)
+
+
+# --- the needs catalog -----------------------------------------------------------
+OFFICE_DOCUMENT = NeedSpec(
+    id="office.document.create",
+    goal="Create a document-like artifact and verify it exists — no GUI editor required.",
+    required_outputs=("artifact://*/documents/*", "fs://*/file/query/stat"),
+    preferred_capabilities=("document.create", "sheet.write", "invoice.render"),
+    acceptable_capabilities=("markdown.write", "html.write", "browser.document_edit"),
+    requires_gui=False,
+)
+
+SPREADSHEET = NeedSpec(
+    id="office.spreadsheet.create",
+    goal="Create a spreadsheet artifact and read it back.",
+    required_outputs=("artifact://*/documents/*.xlsx", "fs://*/file/query/stat"),
+    preferred_capabilities=("sheet.write",),
+    acceptable_capabilities=("markdown.write",),
+    requires_gui=False,
+)
+
+SCREENSHOT = NeedSpec(
+    id="desktop.screenshot",
+    goal="Capture the screen of a node.",
+    required_outputs=("artifact://*/screenshots/*",),
+    preferred_capabilities=("screen.capture",),
+    requires_gui=False,
+)
+
+CATALOG: dict[str, NeedSpec] = {n.id: n for n in (OFFICE_DOCUMENT, SPREADSHEET, SCREENSHOT)}
+
+
+def get(need_id: str) -> NeedSpec | None:
+    return CATALOG.get(need_id)

urirun_reasoner-0.1.0/urirun_reasoner/planner.py

@@ -0,0 +1,119 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""The deterministic resolution ladder — LLM proposes, the kernel decides.
+
+Given a NeedSpec and a context (what the node serves, what the host serves, what is
+installable, whether the node can be managed), pick the FIRST feasible strategy in cost
+order — never install blindly, never reach for a GUI when a headless path exists:
+
+    1. DIRECT        a capability is already served on the node        (cheapest, headless)
+    2. HOST_FALLBACK a headless capability runs host-side + sync       (no node change)
+    3. INSTALL       a connector provides it and the node can manage   (fixes the node)
+    4. GUI           a GUI capability, only as a last resort
+    5. BLOCKED       nothing feasible → honest, with what was tried
+
+Every plan carries a postcondition (from the need's required_outputs) so the verifier
+can confirm the artifact actually exists.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from . import capabilities as _caps
+from . import gates as _gates
+from . import needs as _needs
+
+
+@dataclass
+class Context:
+    node: str
+    node_served: list[str] = field(default_factory=list)
+    host_served: list[str] = field(default_factory=list)
+    installable: set = field(default_factory=set)
+    can_manage: bool = False
+    allow_gui: bool = False
+
+
+def _postcondition(need: _needs.NeedSpec, node: str) -> dict | None:
+    for out in need.required_outputs:
+        if out.startswith("fs://") or out.startswith("artifact://"):
+            return {"uri": out.replace("*", node, 1) if "{node}" not in out else out.replace("{node}", node),
+                    "check": "exists"}
+    return None
+
+
+def _direct(need, ctx) -> dict | None:
+    for cap_id in need.capabilities():
+        cap = _caps.get(cap_id)
+        if not cap or cap.gui:
+            continue
+        route = _caps.served_route(cap_id, ctx.node, ctx.node_served)
+        if route:
+            return {"strategy": "direct", "capability": cap_id,
+                    "steps": [{"uri": route, "for": cap_id}]}
+    return None
+
+
+def _host_fallback(need, ctx) -> dict | None:
+    for cap_id in need.capabilities():
+        cap = _caps.get(cap_id)
+        if not cap or cap.gui or not cap.host_ok:
+            continue
+        route = _caps.served_route(cap_id, "host", ctx.host_served)
+        if route:
+            return {"strategy": "host_fallback", "capability": cap_id,
+                    "steps": [{"uri": route, "for": cap_id, "note": "run on host, then sync to node"}]}
+    return None
+
+
+def _install(need, ctx) -> dict | None:
+    if not ctx.can_manage:
+        return None
+    for cap_id in need.capabilities():
+        cap = _caps.get(cap_id)
+        if not cap or cap.gui:
+            continue
+        for conn in cap.connectors:
+            if conn in ctx.installable:
+                n = ctx.node
+                return {"strategy": "install_then_run", "capability": cap_id, "connector": conn,
+                        "steps": [
+                            {"uri": f"node://{n}/connector/command/install", "payload": {"id": conn}},
+                            {"uri": f"node://{n}/registry/command/rebuild"},
+                            {"uri": f"node://{n}/runtime/command/restart", "note": "drop stale workers"},
+                            {"uri": f"node://{n}/smoke/command/run"},
+                            {"uri": _caps.install_route(cap_id, n), "for": cap_id},
+                        ]}
+    return None
+
+
+def _gui(need, ctx) -> dict | None:
+    if not ctx.allow_gui:
+        return None
+    for cap_id in need.capabilities():
+        cap = _caps.get(cap_id)
+        if cap and cap.gui:
+            route = _caps.served_route(cap_id, ctx.node, ctx.node_served)
+            if route:
+                return {"strategy": "gui", "capability": cap_id, "steps": [{"uri": route, "for": cap_id}]}
+    return None
+
+
+# strategy ladder, cheapest/safest first — GUI last, blind install never
+_LADDER = (_direct, _host_fallback, _install, _gui)
+
+
+def resolve(need: _needs.NeedSpec, ctx: Context) -> dict[str, Any]:
+    """Walk the ladder; return the first feasible plan (+ postcondition), else blocked."""
+    tried = []
+    for strat in _LADDER:
+        plan = strat(need, ctx)
+        if plan:
+            plan["steps"] = _gates.apply(plan["steps"])  # insert approval:// before gated steps
+            plan["need"] = need.id
+            plan["postcondition"] = _postcondition(need, ctx.node)
+            plan["resolved"] = True
+            return plan
+        tried.append(strat.__name__.lstrip("_"))
+    return {"resolved": False, "need": need.id, "tried": tried,
+            "reason": "no served route, no host fallback, no installable connector, GUI not allowed/available"}

urirun_reasoner-0.1.0/urirun_reasoner.egg-info/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: urirun-reasoner
+Version: 0.1.0
+Summary: Intent → need → capability → URI plan, headless-first. Model the goal not the app: a missing GUI editor is one blocked method, not the end. Deterministic core, LLM only as fallback.
+Author: Tom Sapletta
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# urirun-reasoner
+
+Intent → need → capability → URI plan, **headless-first**. Model the GOAL, not the app.
+
+A missing GUI editor is one blocked method in a graph — not the end of the road. Asked to
+"test office on lenovo", the reasoner does not stop at "no LibreOffice"; it reframes to
+"produce a document artifact and verify it exists" and resolves it through the cheapest
+feasible URI path.
+
+## The resolution ladder (kernel decides, cheapest/safest first)
+
+1. **direct** — a capability is already served on the node (headless)
+2. **host_fallback** — a headless capability runs host-side + sync (no node change)
+3. **install_then_run** — a connector provides it and the node can manage (install → rebuild → restart → smoke → use)
+4. **gui** — a GUI capability, only as a last resort
+5. **blocked** — nothing feasible → honest, with what was tried
+
+GUI is never chosen when a headless path exists; connectors are never installed blindly.
+
+## Layers
+
+| module | role |
+|---|---|
+| `needs.py` | `NeedSpec` — the intent contract (goal, required outputs, preferred/acceptable capabilities, requires_gui) + a catalog |
+| `capabilities.py` | `CapabilityMap` — capability → URI route templates + connectors (the layer between language and URIs) |
+| `intent.py` | prompt → NeedSpec (rules first; LLM only names the intent, never invents URIs) |
+| `planner.py` | the deterministic ladder + `resolve(need, ctx)` with a postcondition |
+
+## Use
+
+```python
+from urirun_reasoner import Context, resolve_prompt
+ctx = Context(node="lenovo", node_served=[...], host_served=["fs://host/file/command/write"],
+              installable={"sheet"}, can_manage=True)
+plan = resolve_prompt("przetestuj biuro na lenovo", ctx)
+# → {"strategy": "host_fallback", "steps": [...], "postcondition": {...}}
+```
+
+Pairs with `urirun-fleet` (node readiness + execution) and the dispatch `_meta` provenance
+(so the reasoner knows what is actually served). Part of the ifURI solution · Apache-2.0

urirun_reasoner-0.1.0/urirun_reasoner.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+tests/test_reasoner.py
+urirun_reasoner/__init__.py
+urirun_reasoner/capabilities.py
+urirun_reasoner/cli.py
+urirun_reasoner/gates.py
+urirun_reasoner/generation_policy.py
+urirun_reasoner/generator.py
+urirun_reasoner/intent.py
+urirun_reasoner/needs.py
+urirun_reasoner/planner.py
+urirun_reasoner.egg-info/PKG-INFO
+urirun_reasoner.egg-info/SOURCES.txt
+urirun_reasoner.egg-info/dependency_links.txt
+urirun_reasoner.egg-info/entry_points.txt
+urirun_reasoner.egg-info/top_level.txt

urirun_reasoner-0.1.0/urirun_reasoner.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

urirun_reasoner-0.1.0/urirun_reasoner.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+urirun-reasoner = urirun_reasoner.cli:main

urirun_reasoner-0.1.0/urirun_reasoner.egg-info/top_level.txt

@@ -0,0 +1 @@
+urirun_reasoner