urirun-mind 0.1.0__tar.gz

urirun_mind-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: urirun-mind
+Version: 0.1.0
+Summary: Cognitive layer over connectors: episode memory, skill cards, antipatterns, capability graph, autonomy levels, strategy selection, reflection. Learn procedures not answers.
+Author: Tom Sapletta
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# urirun-mind
+
+The cognitive layer over connectors — **operational self-awareness**. Not human
+consciousness: an operating model of self. *I know what I want, what I have, what worked
+before, what I can't do, when to build/repair a capability, when to ask a human, and how
+to measure real success.*
+
+**Learn procedures, not answers.** Store *"for office tasks on a stale node, go headless
+first"* — never *"LibreOffice missing on lenovo"*. Procedures transfer across nodes and tasks.
+
+| module | role |
+|---|---|
+| `episode_store` | record every task as an episode, keyed by an **environment fingerprint**; retrieve similar (known-good first) |
+| `skill_cards` | promote a working flow to a reusable **procedure**; search by intent; track success stats |
+| `antipatterns` | learn from counter-examples — routes to **avoid** for an intent/node-status, and what to prefer |
+| `capability_graph` | capability → required sub-capabilities + **fallback chains** (no youtube:// ≠ dead end) |
+| `autonomy_policy` | **L0 observe → L5 commit**; gate each action; never auto for pay/publish/send/delete/credentials |
+| `strategy_selector` | **known-good replay BEFORE the LLM** — skill → episode → fresh, minus antipattern routes, under the autonomy gate |
+| `reflection` | after a run: silent-failure check, promote skill, record antipattern, emit **koru tickets** |
+
+## The loop it closes
+```
+run → reflect → learn → ticket → koru → connector/code → smoke → publish → use
+```
+Round 1 of a task plans fresh; the failure teaches an antipattern + a procedure lesson.
+Round 2 of the same task replays the known-good skill and avoids the failed path — cheaper,
+less flaky, and honestly gated by autonomy level.
+
+Part of the ifURI solution · Author: Tom Sapletta · Apache-2.0

urirun_mind-0.1.0/README.md

@@ -0,0 +1,29 @@
+# urirun-mind
+
+The cognitive layer over connectors — **operational self-awareness**. Not human
+consciousness: an operating model of self. *I know what I want, what I have, what worked
+before, what I can't do, when to build/repair a capability, when to ask a human, and how
+to measure real success.*
+
+**Learn procedures, not answers.** Store *"for office tasks on a stale node, go headless
+first"* — never *"LibreOffice missing on lenovo"*. Procedures transfer across nodes and tasks.
+
+| module | role |
+|---|---|
+| `episode_store` | record every task as an episode, keyed by an **environment fingerprint**; retrieve similar (known-good first) |
+| `skill_cards` | promote a working flow to a reusable **procedure**; search by intent; track success stats |
+| `antipatterns` | learn from counter-examples — routes to **avoid** for an intent/node-status, and what to prefer |
+| `capability_graph` | capability → required sub-capabilities + **fallback chains** (no youtube:// ≠ dead end) |
+| `autonomy_policy` | **L0 observe → L5 commit**; gate each action; never auto for pay/publish/send/delete/credentials |
+| `strategy_selector` | **known-good replay BEFORE the LLM** — skill → episode → fresh, minus antipattern routes, under the autonomy gate |
+| `reflection` | after a run: silent-failure check, promote skill, record antipattern, emit **koru tickets** |
+
+## The loop it closes
+```
+run → reflect → learn → ticket → koru → connector/code → smoke → publish → use
+```
+Round 1 of a task plans fresh; the failure teaches an antipattern + a procedure lesson.
+Round 2 of the same task replays the known-good skill and avoids the failed path — cheaper,
+less flaky, and honestly gated by autonomy level.
+
+Part of the ifURI solution · Author: Tom Sapletta · Apache-2.0

urirun_mind-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "urirun-mind"
+version = "0.1.0"
+description = "Cognitive layer over connectors: episode memory, skill cards, antipatterns, capability graph, autonomy levels, strategy selection, reflection. Learn procedures not answers."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Tom Sapletta" }]
+dependencies = []
+[project.scripts]
+urirun-mind = "urirun_mind.cli:main"
+[tool.setuptools.packages.find]
+include = ["urirun_mind*"]
+
+[tool.wellmanifest]
+standard = "0.20.35"
+revision = "cfaa0bf0ea6b0e7349fed0bb62b5ce15792d687d"
+gate = "project/governance-check.sh"
+
+[tool.pytest.ini_options]
+addopts = "-p wellmanifest_governance"

urirun_mind-0.1.0/setup.cfg

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

urirun_mind-0.1.0/tests/test_mind.py

@@ -0,0 +1,114 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""The cognitive layer: episodes remember, skills replay, antipatterns steer away, the
+policy gates by autonomy level, and reflection turns a run into learning + tickets."""
+import pytest
+
+from urirun_mind import (antipatterns, autonomy_policy, capability_graph,
+                         episode_store, reflection, skill_cards, strategy_selector)
+
+
+@pytest.fixture(autouse=True)
+def isolate(tmp_path, monkeypatch):
+    monkeypatch.setenv("URIRUN_MIND_DIR", str(tmp_path))
+
+
+# --- episode store + fingerprint ---
+def test_fingerprint_stable_and_env_sensitive():
+    a = episode_store.env_fingerprint({"node": "lenovo", "os": "linux", "connectors": {"kvm": "stale"}})
+    b = episode_store.env_fingerprint({"node": "lenovo", "os": "linux", "connectors": {"kvm": "stale"}})
+    c = episode_store.env_fingerprint({"node": "lenovo", "os": "linux", "connectors": {"kvm": "fresh"}})
+    assert a == b and a != c and a.startswith("lenovo:")
+
+
+def test_record_and_similar_prefers_matching_env():
+    env = {"node": "host", "os": "linux"}
+    episode_store.record({"intent": "office.document.create", "environment": env,
+                          "flow": ["fs://host/file/command/write"], "result": "ok"})
+    fp = episode_store.env_fingerprint(env)
+    sim = episode_store.similar("office.document.create", fp, result="ok")
+    assert sim and sim[0]["fingerprint"] == fp and sim[0]["flow"]
+
+
+# --- autonomy levels ---
+def test_autonomy_gates_by_level():
+    assert autonomy_policy.decide("fs://host/file/command/write", level=2)["allowed"]      # local artifact @L2
+    assert not autonomy_policy.decide("node://x/connector/command/install", level=2)["allowed"]  # needs L3
+    assert autonomy_policy.decide("node://x/connector/command/install", level=3)["allowed"]
+
+
+def test_autonomy_never_auto_and_approval():
+    assert autonomy_policy.decide("email://x/message/command/send", level=5)["needs_approval"]
+    assert autonomy_policy.decide("fiverr://x/order/command/pay", level=5)["needs_approval"]
+    d = autonomy_policy.decide("secret://x/credential/command/export", level=5)
+    assert d["allowed"] is False and "never" in d["reason"]
+
+
+# --- antipatterns steer away ---
+def test_antipattern_avoids_gui_on_stale_node():
+    antipatterns.add({"id": "gui-first-office-stale",
+                      "trigger": {"intent": "office.document.create", "node_status": "stale"},
+                      "avoid": ["app://*/desktop/command/launch"], "prefer": ["fs://host/file/command/write"]})
+    matched = antipatterns.match("office.document.create", "stale")
+    assert antipatterns.is_avoided("app://lenovo/desktop/command/launch", matched) == "gui-first-office-stale"
+    assert antipatterns.is_avoided("fs://host/file/command/write", matched) is None
+
+
+# --- capability graph fallbacks ---
+def test_capability_graph_walks_fallbacks():
+    r = capability_graph.resolve("office.document.create", available={"markdown.write"})
+    assert r["complete"] and r["satisfied"]["document.write"]["method"] == "markdown.write"
+    r2 = capability_graph.resolve("content.linkedin.from_youtube", available={"media.audio.transcribe"})
+    assert not r2["complete"]   # only transcript satisfied; others unmet
+    assert r2["satisfied"]["transcript.extract"]["method"] == "media.audio.transcribe"
+
+
+# --- strategy selector: known-good before LLM ---
+def test_selector_replays_skill_before_fresh():
+    skill_cards.create({"id": "office.document.create.headless",
+                        "intent_patterns": ["testuj biuro", "utwórz dokument"],
+                        "preferred_flow": ["fs://host/file/command/write", "fs://host/file/query/stat"]})
+    sel = strategy_selector.select("office.document.create", prompt="testuj biuro na lenovo",
+                                   environment={"node": "lenovo", "node_status": "stale"}, level=3)
+    assert sel["source"] == "skill" and sel["flow"] and sel["runnable"]
+
+
+def test_selector_fresh_when_no_memory():
+    sel = strategy_selector.select("brand.new.intent", environment={"node": "host"})
+    assert sel["source"] == "fresh" and sel["flow"] == []
+
+
+# --- reflection closes the loop ---
+def test_reflection_promotes_skill_and_records_episode():
+    run = {"intent": "office.document.create", "prompt": "testuj biuro", "strategy": "headless",
+           "environment": {"node": "host"}, "flow": [{"uri": "fs://host/file/command/write"}],
+           "result": "ok", "postcondition_ok": True, "postcondition": {"check": "artifact_exists"}}
+    out = reflection.evaluate(run)
+    assert out["goal_achieved"] and out["new_skill_candidate"] == "office.document.create.headless"
+    assert skill_cards.show("office.document.create.headless")
+
+
+def test_reflection_detects_silent_failure_and_tickets():
+    run = {"intent": "office.document.create", "strategy": "gui_editor", "result": "ok",
+           "postcondition_ok": False, "flow": [{"uri": "app://lenovo/desktop/command/launch"}]}
+    out = reflection.evaluate(run)
+    assert out["silent_failure_detected"] is True
+    assert any("Harden postcondition" in t["title"] for t in out["tickets"])
+
+
+def test_reflection_records_antipattern_and_connector_ticket():
+    run = {"intent": "content.linkedin.from_youtube", "strategy": "youtube_direct",
+           "result": "failed", "failure_class": "missing_connector", "missing_scheme": "youtube",
+           "working_fallback": "media.audio.transcribe",
+           "environment": {"node": "host", "node_status": "ready"},
+           "flow": [{"uri": "youtube://host/video/query/transcript"}]}
+    out = reflection.evaluate(run)
+    assert out["antipattern_recorded"] and any("youtube" in t["title"] for t in out["tickets"])
+
+
+def test_reflection_silent_failure_lesson_is_honest():
+    out = reflection.evaluate({"intent":"office.document.create","strategy":"host_fallback",
+      "result":"ok","postcondition_ok":False,"flow":[{"uri":"fs://host/file/command/write"}]})
+    assert out["silent_failure_detected"] and not out["goal_achieved"]
+    assert "FAILED" in out["lesson"] and "works" not in out["lesson"]   # never claims it works
+    assert out["new_skill_candidate"] is None                           # no skill on silent failure
+    assert out["what_worked"] == []                                     # nothing 'worked'

urirun_mind-0.1.0/urirun_mind/__init__.py

@@ -0,0 +1,22 @@
+# Author: Tom Sapletta · https://tom.sapletta.com
+# Part of the ifURI solution.
+"""urirun-mind — the cognitive layer over connectors. Operational self-awareness.
+
+Not human consciousness — an operating model of self: I know what I want, what I have,
+what worked before, what I can't do, when to build/repair a capability, when to ask a
+human, and how to measure real success. Episode memory + skill cards + antipatterns +
+capability graph + autonomy levels + strategy selection + reflection — so koru and
+connectorgen become elements of a continuous self-improvement loop, not just tools.
+
+Learn PROCEDURES, not answers: store "for office tasks on a stale node, go headless
+first", never "LibreOffice missing on lenovo".
+"""
+from __future__ import annotations
+
+from . import (
+    antipatterns, autonomy_policy, capability_graph, episode_store,
+    reflection, skill_cards, strategy_selector,
+)
+
+__all__ = ["antipatterns", "autonomy_policy", "capability_graph", "episode_store",
+           "reflection", "skill_cards", "strategy_selector"]

urirun_mind-0.1.0/urirun_mind/antipatterns.py

@@ -0,0 +1,62 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""Antipatterns — learning from counter-examples, not just successes.
+
+"For office tasks on a stale/blocked node, do NOT reach for the GUI editor; prefer
+headless." An antipattern has a trigger (intent + node status) and lists routes to AVOID
+and routes to PREFER. The strategy selector consults these so the system does not walk
+into the same failed path three times.
+"""
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+
+def _path() -> Path:
+    d = Path(os.environ.get("URIRUN_MIND_DIR") or "~/.urirun/mind").expanduser()
+    d.mkdir(parents=True, exist_ok=True)
+    return d / "antipatterns.json"
+
+
+def _load() -> dict[str, dict]:
+    p = _path()
+    return json.loads(p.read_text(encoding="utf-8")) if p.is_file() else {}
+
+
+def add(rule: dict) -> dict[str, Any]:
+    """Add/replace an antipattern. Needs id + trigger; avoid/prefer are route globs."""
+    rid = rule.get("id")
+    if not rid or not rule.get("trigger"):
+        raise ValueError("antipattern needs 'id' and 'trigger'")
+    rules = _load()
+    rules[rid] = {"id": rid, "trigger": rule["trigger"],
+                  "avoid": rule.get("avoid") or [], "prefer": rule.get("prefer") or []}
+    _path().write_text(json.dumps(rules, indent=1), encoding="utf-8")
+    return rules[rid]
+
+
+def match(intent: str, node_status: str | None = None) -> list[dict]:
+    """Antipatterns whose trigger matches this intent (+ optional node status)."""
+    out = []
+    for r in _load().values():
+        t = r.get("trigger") or {}
+        if t.get("intent") and t["intent"] != intent:
+            continue
+        if t.get("node_status") and node_status and t["node_status"] != node_status:
+            continue
+        out.append(r)
+    return out
+
+
+def is_avoided(uri: str, matched: list[dict]) -> str | None:
+    """If ``uri`` matches an AVOID glob of any matched antipattern, return that rule id."""
+    path = uri.split("://", 1)[-1]
+    for r in matched:
+        for glob in r.get("avoid", []):
+            g = glob.split("://", 1)[-1]
+            if fnmatch.fnmatch(uri, glob) or fnmatch.fnmatch(path, g):
+                return r["id"]
+    return None

urirun_mind-0.1.0/urirun_mind/autonomy_policy.py

@@ -0,0 +1,85 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""Autonomy levels — self-directed, not uncontrolled. L0 observe … L5 commit.
+
+Each action class needs a minimum autonomy level; the current level gates what runs
+without human approval. External/committing actions (send, publish, pay, delete) never
+run automatically; credential export and destructive-without-backup are never auto at any
+level. This is what makes the system autonomous AND safe.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+LEVELS = {
+    0: "observe",     # only observe/report
+    1: "propose",     # propose a plan, execute nothing
+    2: "safe-run",    # read-only + local artifacts
+    3: "repair",      # install connectors, reconcile/repair a node, rebuild registry
+    4: "external",    # create drafts of messages/orders/posts (not sent)
+    5: "commit",      # send/publish/pay — only with human approval
+}
+
+# action class → minimum level that MAY perform it automatically
+_MIN_LEVEL = {
+    "query": 0, "propose": 1,
+    "local_artifact_create": 2, "connector_smoke": 2, "read_only": 2,
+    "connector_generate": 3, "connector_install": 3, "fleet_reconcile_safe": 3,
+    "node_restart": 3, "registry_rebuild": 3,
+    "mailbox_mutate": 4,   # move-to-Junk etc. — reversible mailbox write, auto at L4
+    "draft_message": 4, "draft_order": 4, "repo_publish_public": 4,
+}
+# always require explicit human approval regardless of level
+_APPROVAL_REQUIRED = {"email.send", "linkedin.publish", "fiverr.order", "payment.confirm",
+                      "file.delete", "message.send", "post.publish"}
+# never automatic at any level
+_NEVER_AUTO = {"credential_export", "destructive_without_backup"}
+
+# map a URI verb → action class (for classifying a step)
+_VERB_CLASS = [
+    ("credential", "credential_export"), ("/command/delete", "file.delete"),
+    ("/command/pay", "payment.confirm"), ("/command/publish", "post.publish"),
+    ("/command/send", "message.send"), ("/order/command", "fiverr.order"),
+    ("/command/move", "mailbox_mutate"),
+    ("connector/command/generate", "connector_generate"),
+    ("connector/command/install", "connector_install"),
+    ("runtime/command/restart", "node_restart"), ("registry/command/rebuild", "registry_rebuild"),
+    ("repo/command/publish", "repo_publish_public"),
+    ("/command/draft", "draft_message"), ("/command/write", "local_artifact_create"),
+    ("/command/create", "local_artifact_create"), ("/query/", "query"),
+]
+
+
+def classify_action(uri: str) -> str:
+    u = str(uri)
+    for needle, cls in _VERB_CLASS:
+        if needle in u:
+            return cls
+    return "propose"
+
+
+def decide(uri: str, *, level: int = 3) -> dict[str, Any]:
+    """Can this URI run automatically at ``level``? Returns {allowed, needs_approval, reason}."""
+    cls = classify_action(uri)
+    if cls in _NEVER_AUTO:
+        return {"allowed": False, "needs_approval": False, "class": cls,
+                "reason": "never automatic (blocked at every level)"}
+    if cls in _APPROVAL_REQUIRED:
+        return {"allowed": False, "needs_approval": True, "class": cls,
+                "reason": "requires explicit human approval"}
+    need = _MIN_LEVEL.get(cls, 1)
+    if level >= need:
+        return {"allowed": True, "needs_approval": False, "class": cls, "reason": f"level {level} >= {need}"}
+    return {"allowed": False, "needs_approval": True, "class": cls,
+            "reason": f"needs autonomy level {need} ({LEVELS.get(need)}), current {level}"}
+
+
+def gate_plan(steps: list[dict], *, level: int = 3) -> dict[str, Any]:
+    """Classify every step; return which run auto, which need approval, which are forbidden."""
+    auto, approval, forbidden = [], [], []
+    for s in steps:
+        d = decide(s.get("uri", ""), level=level)
+        (auto if d["allowed"] else (forbidden if not d["needs_approval"] and not d["allowed"]
+                                    and "never" in d["reason"] else approval)).append(
+            {"uri": s.get("uri"), **d})
+    return {"level": level, "auto": auto, "approval": approval, "forbidden": forbidden,
+            "runnable": not forbidden}

urirun_mind-0.1.0/urirun_mind/capability_graph.py

@@ -0,0 +1,65 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""Capability graph — not a flat list of connectors, but requires + fallbacks.
+
+A high-level capability (``content.linkedin.from_youtube``) requires sub-capabilities,
+each with an ordered fallback chain (youtube.transcript → media.audio.transcribe →
+browser.copy_transcript). So "no youtube connector" never stops the system — it walks the
+fallback chain. resolve() returns, for a capability, which sub-capabilities are satisfiable
+given what's available and the fallback that satisfies each.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+# capability → {requires: [sub-cap], fallbacks: {sub-cap: [ordered alternatives]}}
+GRAPH: dict[str, dict] = {
+    "content.linkedin.from_youtube": {
+        "requires": ["video.source", "transcript.extract", "clip.create", "post.write", "linkedin.draft"],
+        "fallbacks": {
+            "transcript.extract": ["youtube.transcript", "media.audio.transcribe", "browser.copy_transcript"],
+            "linkedin.draft": ["linkedin.api", "browser.linkedin", "artifact.markdown"],
+            "clip.create": ["media.video.clip", "artifact.timestamp_list"],
+        },
+    },
+    "office.document.create": {
+        "requires": ["document.write"],
+        "fallbacks": {"document.write": ["document.create", "sheet.write", "markdown.write",
+                                         "host.generate_and_sync", "browser.document_edit", "gui.editor"]},
+    },
+    "procurement.fiverr.pcb": {
+        "requires": ["project.find", "brief.write", "vendor.search", "order.draft"],
+        "fallbacks": {
+            "vendor.search": ["fiverr.search", "browser.fiverr", "artifact.vendor_list"],
+            "order.draft": ["fiverr.order.draft", "artifact.order_brief"],
+        },
+    },
+}
+
+
+def resolve(capability: str, available: set[str]) -> dict[str, Any]:
+    """For a capability, resolve each required sub-capability to the first available
+    fallback. Returns satisfiable subs (+ chosen method) and the unmet ones."""
+    node = GRAPH.get(capability)
+    if not node:
+        return {"known": False, "capability": capability}
+    satisfied, unmet = {}, []
+    for sub in node["requires"]:
+        chain = node.get("fallbacks", {}).get(sub, [sub])
+        pick = next((m for m in chain if m in available), None)
+        if pick:
+            satisfied[sub] = {"method": pick, "chain": chain}
+        else:
+            unmet.append({"sub": sub, "chain": chain})
+    return {"known": True, "capability": capability, "satisfied": satisfied,
+            "unmet": unmet, "complete": not unmet}
+
+
+def fallbacks(capability: str, sub: str) -> list[str]:
+    return (GRAPH.get(capability, {}).get("fallbacks", {}) or {}).get(sub, [sub])
+
+
+def update(capability: str, spec: dict) -> dict:
+    """Add/extend a capability node in the graph (learning new decompositions)."""
+    GRAPH[capability] = {"requires": spec.get("requires") or [],
+                         "fallbacks": spec.get("fallbacks") or {}}
+    return GRAPH[capability]

urirun_mind-0.1.0/urirun_mind/cli.py

@@ -0,0 +1,29 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""urirun-mind CLI: assess / reflect / skills / gaps over the cognitive memory."""
+from __future__ import annotations
+import argparse, json
+from . import episode_store, skill_cards, strategy_selector, reflection
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="urirun-mind")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    a = sub.add_parser("assess"); a.add_argument("prompt"); a.add_argument("--intent", default="")
+    a.add_argument("--node", default="host"); a.add_argument("--node-status", default="")
+    a.add_argument("--level", type=int, default=3)
+    sub.add_parser("skills")
+    g = sub.add_parser("reflect"); g.add_argument("--run-json", required=True)
+    args = ap.parse_args(argv)
+    if args.cmd == "assess":
+        env = {"node": args.node, "node_status": args.node_status or None}
+        sel = strategy_selector.select(args.intent or args.prompt, prompt=args.prompt, environment=env, level=args.level)
+        print(json.dumps(sel, indent=1, default=str)); return 0
+    if args.cmd == "skills":
+        print(json.dumps(skill_cards.search(""), indent=1, default=str)); return 0
+    if args.cmd == "reflect":
+        print(json.dumps(reflection.evaluate(json.loads(args.run_json)), indent=1, default=str)); return 0
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

urirun_mind-0.1.0/urirun_mind/episode_store.py

@@ -0,0 +1,81 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""Episode memory — the basis of learning. Every task records a full episode.
+
+    intent → context → strategy → URI flow → trace → artifacts → postconditions → result → lesson
+
+Learning here is NOT weight training — it is building a library of proven paths and
+antipatterns, keyed by an ENVIRONMENT FINGERPRINT so a lesson only applies where the
+environment matches. The lesson is a PROCEDURE ("for office tasks on a stale/blocked node,
+go headless first"), never a fact ("LibreOffice missing on lenovo").
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+
+def _dir() -> Path:
+    d = Path(os.environ.get("URIRUN_MIND_DIR") or "~/.urirun/mind").expanduser()
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _path() -> Path:
+    return _dir() / "episodes.jsonl"
+
+
+def env_fingerprint(env: dict) -> str:
+    """A stable signature of the RELEVANT environment — os/session/node + connector state —
+    so a known-good path is only reused when the environment actually matches."""
+    keys = ("node", "os", "session", "display", "runtime", "node_status")
+    base = {k: env.get(k) for k in keys if env.get(k) is not None}
+    conns = env.get("connectors") or {}
+    base["connectors"] = {k: conns[k] for k in sorted(conns)} if isinstance(conns, dict) else conns
+    blob = json.dumps(base, sort_keys=True, default=str)
+    return env.get("node", "host") + ":" + hashlib.sha256(blob.encode()).hexdigest()[:12]
+
+
+def record(episode: dict, *, clock: float | None = None) -> dict[str, Any]:
+    """Append one episode. Stamps id + fingerprint; returns the stored record."""
+    ts = clock if clock is not None else time.time()
+    rec = {
+        "id": "ep-" + hashlib.sha256(f"{episode.get('intent')}{ts}".encode()).hexdigest()[:10],
+        "ts": ts,
+        "intent": episode.get("intent"),
+        "prompt": episode.get("prompt"),
+        "node": (episode.get("environment") or {}).get("node") or episode.get("node"),
+        "fingerprint": env_fingerprint(episode.get("environment") or {}),
+        "strategy": episode.get("strategy"),
+        "flow": episode.get("flow") or [],
+        "artifacts": episode.get("artifacts") or [],
+        "result": episode.get("result"),                 # ok | failed | degraded | blocked
+        "failure_class": episode.get("failure_class"),
+        "working_fallback": episode.get("working_fallback"),
+        "lesson": episode.get("lesson"),
+        "promote_to_skill": bool(episode.get("promote_to_skill")),
+    }
+    with _path().open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(rec, default=str) + "\n")
+    return rec
+
+
+def all_episodes(limit: int = 500) -> list[dict]:
+    p = _path()
+    if not p.is_file():
+        return []
+    rows = p.read_text(encoding="utf-8").strip().splitlines()[-limit:]
+    return [json.loads(r) for r in rows if r]
+
+
+def similar(intent: str, fingerprint: str | None = None, *, result: str | None = None) -> list[dict]:
+    """Episodes for the same intent, best-first: exact-fingerprint matches (same env) rank
+    above others. This is the known-good retrieval a strategy selector consults before an LLM."""
+    eps = [e for e in all_episodes() if e.get("intent") == intent]
+    if result:
+        eps = [e for e in eps if e.get("result") == result]
+    eps.sort(key=lambda e: (e.get("fingerprint") == fingerprint, e.get("ts") or 0), reverse=True)
+    return eps

urirun_mind-0.1.0/urirun_mind/reflection.py

@@ -0,0 +1,103 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""Reflection — after every run, evaluate honestly and turn lessons into action.
+
+Did the goal REALLY hold (postconditions), or was it a silent failure? What worked, what
+failed, is there a better strategy next time? Reflection records the episode, promotes a
+working fallback to a skill card, records the failed path as an antipattern, and emits
+ticket candidates (missing connector, repeated blocker) for koru — closing the loop:
+
+    run → reflect → learn → ticket → koru → connector/code → smoke → publish → use
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from . import antipatterns, episode_store, skill_cards
+
+
+def evaluate(run: dict) -> dict[str, Any]:
+    """Assess a run record. ``run`` = {intent, prompt, environment, strategy, flow,
+    artifacts, result, postcondition_ok, failure_class, working_fallback}."""
+    intent = run.get("intent")
+    ok = run.get("result") == "ok"
+    post_ok = run.get("postcondition_ok")
+    silent = bool(ok and post_ok is False)   # claimed success but postcondition failed
+    goal_achieved = bool(ok and post_ok is not False)
+
+    # 1. record the episode (with the lesson as a PROCEDURE, not a fact)
+    lesson = run.get("lesson") or _derive_lesson(run)
+    ep = episode_store.record({**run, "lesson": lesson,
+                               "promote_to_skill": goal_achieved and bool(run.get("flow"))})
+
+    out: dict[str, Any] = {
+        "episode": ep["id"], "goal_achieved": goal_achieved,
+        "silent_failure_detected": silent, "lesson": lesson,
+        "what_worked": _worked(run), "what_failed": _failed(run),
+        "new_skill_candidate": None, "antipattern_recorded": None, "tickets": [],
+    }
+
+    # 2. promote a good flow to a skill card
+    if goal_achieved and run.get("flow"):
+        skill_id = f"{intent}.{run.get('strategy', 'flow')}"
+        skill_cards.create({"id": skill_id, "intent_patterns": [run.get("prompt") or intent],
+                            "preferred_flow": [s.get("uri") if isinstance(s, dict) else s for s in run["flow"]],
+                            "postconditions": [run.get("postcondition", {}).get("check", "artifact_exists")],
+                            "risk": {"level": run.get("risk", "low"), "requires_human_approval": False}})
+        out["new_skill_candidate"] = skill_id
+
+    # 3. record the failed GUI/whatever path as an antipattern
+    if not goal_achieved and run.get("working_fallback") and run.get("strategy"):
+        failed_uris = [s.get("uri") for s in (run.get("flow") or []) if isinstance(s, dict)]
+        if failed_uris:
+            rid = f"avoid-{run.get('strategy')}-on-{run.get('failure_class', 'fail')}"
+            antipatterns.add({"id": rid,
+                              "trigger": {"intent": intent,
+                                          "node_status": (run.get("environment") or {}).get("node_status")},
+                              "avoid": failed_uris, "prefer": [run["working_fallback"]]})
+            out["antipattern_recorded"] = rid
+
+    # 4. ticket candidates for koru (missing capability / repeated blocker)
+    out["tickets"] = _ticket_candidates(run, silent)
+    return out
+
+
+def _derive_lesson(run: dict) -> str:
+    intent = run.get("intent", "task")
+    # a claimed-ok run whose postcondition failed is a SILENT FAILURE — never call it "works"
+    if run.get("result") == "ok" and run.get("postcondition_ok") is False:
+        return (f"For {intent}, strategy '{run.get('strategy')}' reported ok but the postcondition "
+                f"({run.get('failure_class', 'unmet')}) FAILED — treat as not done; harden the check.")
+    if run.get("result") != "ok" and run.get("working_fallback"):
+        return (f"For {intent}, when strategy '{run.get('strategy')}' fails "
+                f"({run.get('failure_class', 'blocked')}), prefer '{run.get('working_fallback')}' first.")
+    if run.get("result") == "ok" and run.get("postcondition_ok") is not False:
+        return f"For {intent}, strategy '{run.get('strategy')}' works in this environment."
+    return f"{intent}: {run.get('failure_class', 'unresolved')}."
+
+
+def _worked(run: dict) -> list[str]:
+    w = []
+    if run.get("result") == "ok" and run.get("postcondition_ok") is not False:  # not on silent failure
+        w.append(run.get("strategy") or "chosen strategy")
+    if run.get("working_fallback"):
+        w.append(run["working_fallback"])
+    return w
+
+
+def _failed(run: dict) -> list[str]:
+    return [f"{run.get('strategy')}: {run.get('failure_class')}"] if run.get("result") != "ok" else []
+
+
+def _ticket_candidates(run: dict, silent: bool) -> list[dict]:
+    tickets = []
+    fc = run.get("failure_class")
+    if fc in ("missing_connector", "capability_missing") and run.get("missing_scheme"):
+        tickets.append({"title": f"Generate {run['missing_scheme']}:// connector",
+                        "priority": "high", "reason": f"blocked {run.get('intent')}"})
+    if fc in ("node_stale_or_blocked", "node_stale"):
+        tickets.append({"title": "Add fleet auto-reconcile before host ask",
+                        "priority": "critical", "reason": "node stale caused task failure"})
+    if silent:
+        tickets.append({"title": f"Harden postcondition for {run.get('intent')}",
+                        "priority": "high", "reason": "silent failure: claimed ok but postcondition failed"})
+    return tickets

urirun_mind-0.1.0/urirun_mind/skill_cards.py

@@ -0,0 +1,95 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""Skill cards — a learned PROCEDURE promoted from successful episodes, as a reusable resource.
+
+A skill card captures "how to do X here": intent patterns, a preferred URI flow, ranked
+fallbacks, postconditions, risk, and success stats. Before planning from scratch, the
+system searches skills — "I have a known-good path for this; try it, use the LLM only to
+adapt." Cards store PROCEDURES (transferable), never one-off answers.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+
+def _path() -> Path:
+    d = Path(os.environ.get("URIRUN_MIND_DIR") or "~/.urirun/mind").expanduser()
+    d.mkdir(parents=True, exist_ok=True)
+    return d / "skills.json"
+
+
+def _load() -> dict[str, dict]:
+    p = _path()
+    if not p.is_file():
+        return {}
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+def _save(cards: dict) -> None:
+    _path().write_text(json.dumps(cards, indent=1, default=str), encoding="utf-8")
+
+
+def create(card: dict) -> dict[str, Any]:
+    """Create/replace a skill card. Requires id + preferred_flow."""
+    cid = card.get("id")
+    if not cid or not card.get("preferred_flow"):
+        raise ValueError("skill card needs 'id' and 'preferred_flow'")
+    cards = _load()
+    existing = cards.get(cid, {})
+    cards[cid] = {
+        "id": cid,
+        "intent_patterns": card.get("intent_patterns") or existing.get("intent_patterns") or [],
+        "preconditions": card.get("preconditions") or [],
+        "preferred_flow": card["preferred_flow"],
+        "fallbacks": card.get("fallbacks") or [],
+        "postconditions": card.get("postconditions") or [],
+        "risk": card.get("risk") or {"level": "low", "requires_human_approval": False},
+        "stats": existing.get("stats") or {"success_count": 0, "failure_count": 0, "last_success": None},
+    }
+    _save(cards)
+    return cards[cid]
+
+
+def search(intent_or_prompt: str) -> list[dict]:
+    """Cards whose id or intent patterns match the intent/prompt, best (most successful) first."""
+    q = (intent_or_prompt or "").lower()
+    hits = []
+    for card in _load().values():
+        if card["id"] in q or q in card["id"] or \
+           any(p.lower() in q or q in p.lower() for p in card.get("intent_patterns", [])):
+            hits.append(card)
+    hits.sort(key=lambda c: c["stats"]["success_count"] - c["stats"]["failure_count"], reverse=True)
+    return hits
+
+
+def show(card_id: str) -> dict | None:
+    return _load().get(card_id)
+
+
+def record_outcome(card_id: str, ok: bool, *, clock: float | None = None) -> dict | None:
+    """Update a card's success/failure stats after a run (feeds ranking + trust)."""
+    cards = _load()
+    card = cards.get(card_id)
+    if not card:
+        return None
+    key = "success_count" if ok else "failure_count"
+    card["stats"][key] = card["stats"].get(key, 0) + 1
+    if ok:
+        card["stats"]["last_success"] = clock if clock is not None else time.time()
+    _save(cards)
+    return card
+
+
+def deprecate(card_id: str) -> bool:
+    cards = _load()
+    if card_id in cards:
+        cards[card_id]["risk"] = {**cards[card_id].get("risk", {}), "deprecated": True}
+        _save(cards)
+        return True
+    return False

urirun_mind-0.1.0/urirun_mind/strategy_selector.py

@@ -0,0 +1,74 @@
+# Author: Tom Sapletta · Part of the ifURI solution.
+"""Strategy selector — known-good replay BEFORE the LLM, gated by autonomy + antipatterns.
+
+Order (cheap → expensive):
+  1. retrieve a known-good SKILL for this intent; if env fingerprint matches, replay it
+  2. filter out routes an ANTIPATTERN says to avoid for this intent/node status
+  3. otherwise fall through to a fresh plan (the reasoner / LLM)
+Every chosen plan is gated by the AUTONOMY policy before it is called runnable. This cuts
+cost and flakiness and stops the system re-walking failed paths.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from . import antipatterns, autonomy_policy, episode_store, skill_cards
+
+
+def select(intent: str, *, prompt: str = "", environment: dict | None = None,
+           level: int = 3) -> dict[str, Any]:
+    """Pick how to satisfy an intent. Returns the source (skill|episode|fresh), the flow,
+    the autonomy gate verdict, and any antipattern warnings — WITHOUT calling an LLM."""
+    env = environment or {}
+    fp = episode_store.env_fingerprint(env)
+    node_status = env.get("node_status")
+    anti = antipatterns.match(intent, node_status)
+
+    # 1. known-good skill for this intent (prefer env match)
+    cards = skill_cards.search(prompt or intent)
+    for card in cards:
+        if card.get("risk", {}).get("deprecated"):
+            continue
+        flow = [{"uri": u} if isinstance(u, str) else u for u in card["preferred_flow"]]
+        flow, warns = _drop_avoided(flow, anti)
+        if flow:
+            gate = autonomy_policy.gate_plan(flow, level=level)
+            return _result("skill", card["id"], flow, gate, anti, warns,
+                           note="known-good skill; adapt with LLM only if env differs")
+
+    # 2. a successful past episode with the same fingerprint → replay its flow
+    for ep in episode_store.similar(intent, fp, result="ok"):
+        if ep.get("flow"):
+            flow = [{"uri": u} if isinstance(u, str) else u for u in ep["flow"]]
+            flow, warns = _drop_avoided(flow, anti)
+            if flow:
+                gate = autonomy_policy.gate_plan(flow, level=level)
+                return _result("episode", ep["id"], flow, gate, anti, warns,
+                               note="replaying a known-good episode (same env fingerprint)")
+
+    # 3. no memory → the caller should plan fresh (reasoner/LLM), still under the gate
+    return {"source": "fresh", "intent": intent, "fingerprint": fp, "flow": [],
+            "antipatterns": [a["id"] for a in anti], "avoid_routes": _avoid_routes(anti),
+            "note": "no known-good path; plan fresh (reasoner/LLM) then gate + record the episode",
+            "autonomy_level": level}
+
+
+def _drop_avoided(flow: list[dict], anti: list[dict]) -> tuple[list[dict], list[str]]:
+    kept, warns = [], []
+    for step in flow:
+        rid = antipatterns.is_avoided(step.get("uri", ""), anti)
+        if rid:
+            warns.append(f"{step.get('uri')} avoided by antipattern {rid}")
+        else:
+            kept.append(step)
+    return kept, warns
+
+
+def _avoid_routes(anti: list[dict]) -> list[str]:
+    return [g for r in anti for g in r.get("avoid", [])]
+
+
+def _result(source, ref, flow, gate, anti, warns, note) -> dict:
+    return {"source": source, "ref": ref, "flow": flow, "gate": gate,
+            "antipatterns": [a["id"] for a in anti], "warnings": warns,
+            "runnable": gate["runnable"], "note": note}

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

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: urirun-mind
+Version: 0.1.0
+Summary: Cognitive layer over connectors: episode memory, skill cards, antipatterns, capability graph, autonomy levels, strategy selection, reflection. Learn procedures not answers.
+Author: Tom Sapletta
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# urirun-mind
+
+The cognitive layer over connectors — **operational self-awareness**. Not human
+consciousness: an operating model of self. *I know what I want, what I have, what worked
+before, what I can't do, when to build/repair a capability, when to ask a human, and how
+to measure real success.*
+
+**Learn procedures, not answers.** Store *"for office tasks on a stale node, go headless
+first"* — never *"LibreOffice missing on lenovo"*. Procedures transfer across nodes and tasks.
+
+| module | role |
+|---|---|
+| `episode_store` | record every task as an episode, keyed by an **environment fingerprint**; retrieve similar (known-good first) |
+| `skill_cards` | promote a working flow to a reusable **procedure**; search by intent; track success stats |
+| `antipatterns` | learn from counter-examples — routes to **avoid** for an intent/node-status, and what to prefer |
+| `capability_graph` | capability → required sub-capabilities + **fallback chains** (no youtube:// ≠ dead end) |
+| `autonomy_policy` | **L0 observe → L5 commit**; gate each action; never auto for pay/publish/send/delete/credentials |
+| `strategy_selector` | **known-good replay BEFORE the LLM** — skill → episode → fresh, minus antipattern routes, under the autonomy gate |
+| `reflection` | after a run: silent-failure check, promote skill, record antipattern, emit **koru tickets** |
+
+## The loop it closes
+```
+run → reflect → learn → ticket → koru → connector/code → smoke → publish → use
+```
+Round 1 of a task plans fresh; the failure teaches an antipattern + a procedure lesson.
+Round 2 of the same task replays the known-good skill and avoids the failed path — cheaper,
+less flaky, and honestly gated by autonomy level.
+
+Part of the ifURI solution · Author: Tom Sapletta · Apache-2.0

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

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+tests/test_mind.py
+urirun_mind/__init__.py
+urirun_mind/antipatterns.py
+urirun_mind/autonomy_policy.py
+urirun_mind/capability_graph.py
+urirun_mind/cli.py
+urirun_mind/episode_store.py
+urirun_mind/reflection.py
+urirun_mind/skill_cards.py
+urirun_mind/strategy_selector.py
+urirun_mind.egg-info/PKG-INFO
+urirun_mind.egg-info/SOURCES.txt
+urirun_mind.egg-info/dependency_links.txt
+urirun_mind.egg-info/entry_points.txt
+urirun_mind.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

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

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

@@ -0,0 +1 @@
+urirun_mind