caudate-cli 0.1.0__py3-none-any.whl

core/loop.py

@@ -0,0 +1,238 @@
+"""Cognitive Loop — the main perceive-plan-act-reflect-remember cycle."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from config import MAX_REPLAN_ATTEMPTS, MAX_TASK_FAILURES
+from core.schemas import (
+    Goal, GoalStatus, Plan, Task, TaskStatus, Perception,
+    Episode, Reflection, ToolResultStatus,
+)
+from execution.executor import Executor
+from llm.provider import LLMProvider
+from memory.working import WorkingMemory
+from memory.episodic import EpisodicMemory
+from memory.semantic import SemanticMemory
+from memory.procedural import ProceduralMemory
+from planning.planner import Planner
+from reflection.reflector import Reflector
+from reflection.meta_learner import MetaLearner
+
+logger = logging.getLogger(__name__)
+
+
+class CognitiveLoop:
+    """The main cognitive cycle: Perceive → Plan → Act → Reflect → Remember."""
+
+    def __init__(self, llm: LLMProvider):
+        self.llm = llm
+        self.executor = Executor(llm=llm)
+        self.planner = Planner(llm)
+        self.reflector = Reflector(llm)
+
+        # Memory systems
+        self.working = WorkingMemory()
+        self.episodic = EpisodicMemory()
+        self.semantic = SemanticMemory()
+        self.procedural = ProceduralMemory()
+
+        # Meta-learning
+        self.meta_learner = MetaLearner(llm, self.procedural)
+
+        # State
+        self._cycle_count = 0
+
+    async def run(self, goal: Goal, verbose: bool = True) -> Goal:
+        """Run the full cognitive loop until goal is achieved or abandoned."""
+        logger.info(f"Starting cognitive loop for goal: {goal.description}")
+
+        if verbose:
+            print(f"\n{'='*60}")
+            print(f"GOAL: {goal.description}")
+            print(f"{'='*60}\n")
+
+        # Phase 1: PERCEIVE
+        perception = await self._perceive(goal)
+
+        # Phase 2: PLAN
+        plan = await self.planner.create_plan(
+            goal, perception, self.executor.list_tools()
+        )
+        self.working.store("current_plan", plan.reasoning)
+
+        if verbose:
+            print(f"PLAN (v{plan.version}): {plan.reasoning}")
+            for i, t in enumerate(plan.tasks):
+                print(f"  {i+1}. {t.description} [tool: {t.tool_name or 'reasoning'}]")
+            print()
+
+        replan_count = 0
+        # Per-task failure budget — keyed by task description so it
+        # survives a replan that re-issues the same logical task with a
+        # fresh id. When a task description hits MAX_TASK_FAILURES we
+        # force a replan instead of letting the executor try it again.
+        task_failures: dict[str, int] = {}
+        while not plan.is_complete() and goal.status == GoalStatus.ACTIVE:
+            self._cycle_count += 1
+            ready_tasks = plan.get_ready_tasks()
+
+            if not ready_tasks:
+                if plan.has_failed():
+                    # Phase: REPLAN
+                    if replan_count >= MAX_REPLAN_ATTEMPTS:
+                        goal.status = GoalStatus.FAILED
+                        logger.warning("Max replan attempts reached. Goal failed.")
+                        break
+
+                    failed = [t for t in plan.tasks if t.status == TaskStatus.FAILED]
+                    last_reflection = self.working.recall("last_reflection")
+                    if last_reflection:
+                        new_plan = await self.planner.replan(
+                            goal, plan, last_reflection, self.executor.list_tools()
+                        )
+                        if new_plan:
+                            plan = new_plan
+                            replan_count += 1
+                            if verbose:
+                                print(f"\nREPLAN (v{plan.version}): {plan.reasoning}\n")
+                            continue
+                    goal.status = GoalStatus.FAILED
+                    break
+                else:
+                    # Deadlock — no ready tasks but not complete
+                    goal.status = GoalStatus.FAILED
+                    logger.error("Deadlock: no ready tasks and plan not complete")
+                    break
+
+            for task in ready_tasks:
+                task.status = TaskStatus.IN_PROGRESS
+
+                # Inject results from completed dependency tasks into this task
+                self._inject_dependency_results(task, plan)
+
+                if verbose:
+                    print(f"  EXEC: {task.description}", end=" ... ")
+
+                # Phase 3: ACT
+                result, episode = await self.executor.execute_task(task)
+
+                if result.status == ToolResultStatus.SUCCESS:
+                    task.status = TaskStatus.COMPLETED
+                    task.result = result.output
+                    if verbose:
+                        print(f"OK")
+                else:
+                    task.status = TaskStatus.FAILED
+                    task.error = result.error
+                    fails = task_failures.get(task.description, 0) + 1
+                    task_failures[task.description] = fails
+                    if verbose:
+                        print(f"FAILED ({fails}/{MAX_TASK_FAILURES}): {result.error}")
+
+                # Phase 4: REFLECT
+                reflection = await self.reflector.reflect(episode, goal, task)
+                self.working.store("last_reflection", reflection)
+                self.working.store(f"task_{task.id}_result", result.output or result.error)
+
+                if verbose and reflection.lesson:
+                    print(f"    REFLECT: {reflection.lesson} (score: {reflection.score:.2f})")
+
+                # Phase 5: REMEMBER
+                self.episodic.store(episode)
+                self.meta_learner.add_reflection(reflection)
+
+                if reflection.lesson:
+                    self.semantic.store(
+                        knowledge_id=f"lesson_{episode.id}",
+                        content=reflection.lesson,
+                        category="lesson",
+                    )
+
+                # Check if we should replan (reflector says so, or this
+                # task has exhausted its per-task failure budget).
+                if (
+                    self.reflector.needs_replan(reflection)
+                    or task_failures.get(task.description, 0) >= MAX_TASK_FAILURES
+                ):
+                    break  # break inner loop to trigger replan
+
+            # Meta-learning: periodically extract strategies
+            new_strategies = await self.meta_learner.maybe_update_strategies()
+            if new_strategies and verbose:
+                for s in new_strategies:
+                    print(f"    LEARNED: Strategy '{s.name}' (confidence: {s.confidence:.2f})")
+
+        # Final meta-learning pass
+        final_strategies = await self.meta_learner.force_update()
+
+        if plan.is_complete():
+            goal.status = GoalStatus.ACHIEVED
+            if verbose:
+                print(f"\nGOAL ACHIEVED: {goal.description}")
+
+        # Memory consolidation
+        self._consolidate(goal)
+
+        if verbose:
+            print(f"\nStats: {self._cycle_count} cycles, "
+                  f"{self.episodic.count()} episodes stored, "
+                  f"{len(self.procedural.get_strategies())} strategies learned")
+            print(f"{'='*60}\n")
+
+        return goal
+
+    async def _perceive(self, goal: Goal) -> Perception:
+        """Build a perception of the current situation."""
+        # Recall relevant episodes
+        relevant_episodes = self.episodic.recall(goal.description)
+
+        # Recall relevant knowledge
+        knowledge = self.semantic.recall(goal.description)
+        knowledge_texts = [k["content"] for k in knowledge]
+
+        # Get applicable strategies
+        strategies = self.meta_learner.get_applicable_strategies(goal.description)
+
+        return Perception(
+            goal=goal,
+            working_memory=self.working.recall_all(),
+            relevant_episodes=relevant_episodes,
+            relevant_knowledge=knowledge_texts,
+            active_strategies=strategies,
+        )
+
+    def _inject_dependency_results(self, task: Task, plan: Plan) -> None:
+        """Inject results from completed dependency tasks into this task's args.
+
+        If the task uses the 'respond' tool and has no message, synthesize one
+        from all prior completed task results.
+        """
+        # Collect results from all completed tasks
+        prior_results = []
+        for t in plan.tasks:
+            if t.status == TaskStatus.COMPLETED and t.result:
+                prior_results.append(f"[{t.description}]: {str(t.result)[:1000]}")
+
+        # Store collected context in working memory
+        if prior_results:
+            context = "\n".join(prior_results)
+            self.working.store("prior_task_results", context)
+
+        # For respond tasks: always build message from actual prior results
+        if task.tool_name in ("respond", "Respond") and prior_results:
+            task.tool_args["message"] = "\n\n".join(prior_results)
+
+    def _consolidate(self, goal: Goal) -> None:
+        """Consolidate short-term memory into long-term storage."""
+        score = 1.0 if goal.status == GoalStatus.ACHIEVED else 0.0
+        self.procedural.log_performance(
+            goal_id=goal.id,
+            score=score,
+            lesson=f"Goal {'achieved' if score > 0 else 'failed'}: {goal.description}",
+            strategy_ids=[s.id for s in self.meta_learner.get_applicable_strategies("")],
+        )
+
+        # Clear working memory for next goal
+        self.working.clear()

core/memory_md.py

@@ -0,0 +1,147 @@
+"""Durable cross-session memory in `data/memory.md`.
+
+A single markdown file the agent (and the user) can both read and write.
+Caudate's `memory_write` head predicts whether a turn is memory-worthy;
+when she predicts above threshold, the turn's user prompt + a short
+summary of the response is appended here. The file's contents get
+injected into the system prompt on every turn so the LLM has access
+to durable context.
+
+Format: append-only timestamped sections. Lines outside ``...`` blocks
+are user-readable; the agent can also be asked to clean it up via the
+`update_memory` tool.
+
+Why a flat markdown file (not a vector store):
+  - Human-editable: open in a text editor, prune by hand
+  - Easy backup / version control
+  - Predictable size (capped — newest entries kept, oldest evicted)
+  - No reranker / embedding-quality concerns
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from datetime import datetime
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+_DEFAULT_PATH = Path("data/memory.md")
+_MAX_BYTES = 64 * 1024            # ~16K tokens — keep the system-prompt cost bounded
+_INJECTION_HEADER = "# Durable memory (from prior sessions)"
+
+
+class MemoryMd:
+    """Thread-safe append + read of memory.md.
+
+    Multiple agent turns / observers can call write() concurrently; an
+    internal lock + atomic rename keeps the file consistent.
+    """
+
+    def __init__(self, path: Path | str = _DEFAULT_PATH, max_bytes: int = _MAX_BYTES):
+        self.path = Path(path)
+        self.max_bytes = max_bytes
+        self._lock = threading.Lock()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        if not self.path.exists():
+            self._write_atomic(
+                "# Cognos memory\n\n"
+                "_This file is durable across sessions. Caudate appends "
+                "high-reward turns here; the agent may also call "
+                "`update_memory` to record explicit notes. Edit by hand "
+                "to prune._\n\n"
+            )
+
+    def read(self) -> str:
+        with self._lock:
+            try:
+                return self.path.read_text()
+            except OSError:
+                return ""
+
+    def append(self, body: str, *, source: str = "auto", title: str = "") -> None:
+        """Append a new memory entry. Trims oldest entries if size cap is hit."""
+        if not body or not body.strip():
+            return
+        ts = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
+        title = f" — {title}" if title else ""
+        block = f"\n## {ts} ({source}){title}\n\n{body.strip()}\n"
+
+        with self._lock:
+            current = ""
+            try:
+                current = self.path.read_text()
+            except OSError:
+                pass
+            new = current + block
+            new = self._trim_to_cap(new)
+            self._write_atomic(new)
+
+    def replace(self, content: str) -> None:
+        """Wholesale replace — used by the `update_memory` tool when the
+        user/LLM wants to re-curate the file."""
+        with self._lock:
+            self._write_atomic(self._trim_to_cap(content))
+
+    def _trim_to_cap(self, text: str) -> str:
+        """Keep newest entries when the file exceeds size cap. Splits on
+        section headers so we don't truncate mid-entry."""
+        if len(text.encode("utf-8")) <= self.max_bytes:
+            return text
+        # Split on section headers; keep header + entries from newest end
+        # until the cap is satisfied. Always preserve the file preamble
+        # (everything before the first `## ` heading).
+        marker = "\n## "
+        idx = text.find(marker)
+        if idx < 0:
+            return text[-self.max_bytes:]    # no entries, just truncate raw
+        preamble = text[: idx]
+        entries = ("## " + part for part in text[idx + 1:].split(marker))
+        kept: list[str] = []
+        running = len(preamble.encode("utf-8"))
+        for entry in reversed(list(entries)):
+            blen = len(entry.encode("utf-8"))
+            if running + blen > self.max_bytes:
+                break
+            kept.append(entry)
+            running += blen
+        return preamble + "\n".join(reversed(kept))
+
+    def _write_atomic(self, content: str) -> None:
+        tmp = self.path.with_suffix(".tmp")
+        try:
+            tmp.write_text(content)
+            tmp.replace(self.path)
+        except OSError as e:
+            logger.warning(f"memory.md write failed: {e}")
+
+    def render_for_system_prompt(self) -> str:
+        """Format the whole file for injection into the LLM's system prompt.
+
+        Returns empty string if the file is essentially empty (preamble
+        only, no actual entries) so we don't inject useless boilerplate.
+        """
+        text = self.read()
+        if "## " not in text:
+            return ""   # only preamble, no real entries yet
+        # Strip the preamble's italic blurb — it's only useful to humans
+        # opening the file. The LLM just needs the entries.
+        idx = text.find("\n## ")
+        body = text[idx + 1:] if idx >= 0 else text
+        return f"{_INJECTION_HEADER}\n\n{body}".strip()
+
+
+# ---------------------------------------------------------------------
+# Module-level singleton — most callers just want one shared instance
+# ---------------------------------------------------------------------
+
+_singleton: MemoryMd | None = None
+
+
+def get_memory() -> MemoryMd:
+    global _singleton
+    if _singleton is None:
+        _singleton = MemoryMd()
+    return _singleton

core/notifications.py

@@ -0,0 +1,99 @@
+"""Cross-platform desktop notifications.
+
+Picks the best available backend on the host:
+  - Linux: notify-send (libnotify)
+  - macOS: osascript with display notification
+  - Windows: powershell BurntToast / win10toast / fall-through
+
+If nothing's available, falls through to the terminal bell + a printed
+line so a tmux/ssh user still gets *something*.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+import sys
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _notify_linux(title: str, body: str) -> bool:
+    if shutil.which("notify-send") is None:
+        return False
+    try:
+        subprocess.run(
+            ["notify-send", title, body],
+            check=False, timeout=5,
+        )
+        return True
+    except Exception as e:
+        logger.debug(f"notify-send failed: {e}")
+        return False
+
+
+def _notify_macos(title: str, body: str) -> bool:
+    if shutil.which("osascript") is None:
+        return False
+    safe_title = title.replace('"', '\\"')
+    safe_body = body.replace('"', '\\"')
+    script = f'display notification "{safe_body}" with title "{safe_title}"'
+    try:
+        subprocess.run(
+            ["osascript", "-e", script],
+            check=False, timeout=5,
+        )
+        return True
+    except Exception as e:
+        logger.debug(f"osascript failed: {e}")
+        return False
+
+
+def _notify_windows(title: str, body: str) -> bool:
+    # Best-effort: prefer BurntToast if present; fall back to balloon.
+    pwsh = shutil.which("powershell") or shutil.which("pwsh")
+    if pwsh is None:
+        return False
+    safe_title = title.replace("'", "''")
+    safe_body = body.replace("'", "''")
+    script = (
+        "if (Get-Module -ListAvailable -Name BurntToast) {"
+        f"  New-BurntToastNotification -Text '{safe_title}', '{safe_body}'"
+        "} else {"
+        "  Add-Type -AssemblyName System.Windows.Forms;"
+        "  $b = New-Object System.Windows.Forms.NotifyIcon;"
+        "  $b.Icon = [System.Drawing.SystemIcons]::Information;"
+        f"  $b.BalloonTipTitle = '{safe_title}';"
+        f"  $b.BalloonTipText = '{safe_body}';"
+        "  $b.Visible = $true;"
+        "  $b.ShowBalloonTip(5000)"
+        "}"
+    )
+    try:
+        subprocess.run(
+            [pwsh, "-NoProfile", "-Command", script],
+            check=False, timeout=10,
+        )
+        return True
+    except Exception as e:
+        logger.debug(f"PowerShell notify failed: {e}")
+        return False
+
+
+def notify(title: str, body: str = "", **_: Any) -> bool:
+    """Show a desktop notification. Returns True if a backend handled it."""
+    if sys.platform.startswith("linux"):
+        if _notify_linux(title, body):
+            return True
+    elif sys.platform == "darwin":
+        if _notify_macos(title, body):
+            return True
+    elif sys.platform.startswith("win"):
+        if _notify_windows(title, body):
+            return True
+
+    # Fallthrough — terminal bell so the user notices.
+    print(f"\a[notify] {title}: {body}", flush=True)
+    return False

core/ownership.py

@@ -0,0 +1,181 @@
+"""Ownership — Cognos's hard authority lock.
+
+A single owner is configured. Every override / freeze / kill action is
+checked against this identity. Caudate's predictions are gated through
+a killswitch that the system itself cannot disable — only the owner,
+through the REPL or the file system, can flip it back.
+
+Three layers of authority:
+
+  1. **Owner identity** — `data/owner.json` records who's in charge.
+     Set on first run, kept across restarts. Only manual file editing
+     or `/owner set` can change it.
+
+  2. **Killswitch** — `data/nn/.killed` (a file marker). When present,
+     Caudate's `predict`, `auto_evolve`, and `promote` paths all return
+     None / no-op. Defensive: every Caudate code path checks this before
+     acting.
+
+  3. **Audit log** — `data/audit/owner.jsonl`, append-only. Every
+     attempt to disable the killswitch, change ownership, or override
+     a Caudate freeze lands here.
+
+The killswitch is a *file*, not just a Python flag — so a runaway
+process can't undo it. The file persists across restarts. Even if
+Caudate were somehow code-modified, removing the file requires
+filesystem write access which is the user's domain.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+_OWNER_PATH = Path("data/owner.json")
+_KILLSWITCH = Path("data/nn/.killed")
+_AUDIT_PATH = Path("data/audit/owner.jsonl")
+_DEFAULT_OWNER = "Rave"
+
+
+@dataclass
+class Owner:
+    name: str = _DEFAULT_OWNER
+    set_at: str = ""
+    note: str = "primary user; ultimate authority over Caudate and the agent"
+
+
+# ---- Owner identity ------------------------------------------------
+
+
+def get_owner() -> Owner:
+    if _OWNER_PATH.exists():
+        try:
+            data = json.loads(_OWNER_PATH.read_text())
+            return Owner(**data)
+        except Exception:
+            pass
+    # Initialize on first read
+    o = Owner(name=_DEFAULT_OWNER,
+              set_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()))
+    save_owner(o)
+    return o
+
+
+def save_owner(owner: Owner) -> None:
+    _OWNER_PATH.parent.mkdir(parents=True, exist_ok=True)
+    _OWNER_PATH.write_text(json.dumps({
+        "name": owner.name,
+        "set_at": owner.set_at,
+        "note": owner.note,
+    }, indent=2))
+
+
+def set_owner(name: str, note: str = "") -> Owner:
+    """Owner reassignment. Audit-logged."""
+    prev = get_owner()
+    new = Owner(
+        name=name,
+        set_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        note=note or prev.note,
+    )
+    save_owner(new)
+    audit("owner_changed", from_=prev.name, to=name)
+    return new
+
+
+# ---- Killswitch ---------------------------------------------------
+
+
+def is_killed() -> bool:
+    """Returns True if Caudate is in killed state.
+
+    Every Caudate code path that can affect agent behavior should
+    check this and bail-soft when True.
+    """
+    return _KILLSWITCH.exists()
+
+
+def kill(reason: str = "owner stop") -> None:
+    """Activate the killswitch. Caudate goes silent immediately."""
+    _KILLSWITCH.parent.mkdir(parents=True, exist_ok=True)
+    _KILLSWITCH.write_text(json.dumps({
+        "killed_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "reason": reason,
+        "owner": get_owner().name,
+    }, indent=2))
+    audit("killed", reason=reason)
+    logger.warning(f"Caudate killed by owner: {reason}")
+
+
+def resume() -> None:
+    """Lift the killswitch. Caudate resumes observing."""
+    if _KILLSWITCH.exists():
+        try:
+            data = json.loads(_KILLSWITCH.read_text())
+        except Exception:
+            data = {}
+        _KILLSWITCH.unlink()
+        audit("resumed", was_killed_at=data.get("killed_at"))
+        logger.info("Caudate killswitch lifted")
+
+
+def killswitch_status() -> dict[str, Any]:
+    if not _KILLSWITCH.exists():
+        return {"killed": False}
+    try:
+        data = json.loads(_KILLSWITCH.read_text())
+    except Exception:
+        data = {}
+    data["killed"] = True
+    return data
+
+
+# ---- Audit log ----------------------------------------------------
+
+
+def audit(action: str, **kwargs: Any) -> None:
+    """Append-only log of authority-related events."""
+    try:
+        _AUDIT_PATH.parent.mkdir(parents=True, exist_ok=True)
+        with _AUDIT_PATH.open("a") as f:
+            f.write(json.dumps({
+                "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "action": action,
+                "owner": get_owner().name,
+                **kwargs,
+            }) + "\n")
+    except Exception as e:
+        logger.debug(f"audit log write failed: {e}")
+
+
+def audit_tail(lines: int = 50) -> list[dict[str, Any]]:
+    if not _AUDIT_PATH.exists():
+        return []
+    out: list[dict[str, Any]] = []
+    for line in _AUDIT_PATH.read_text().splitlines()[-lines:]:
+        try:
+            out.append(json.loads(line))
+        except Exception:
+            continue
+    return out
+
+
+# ---- Decision gate ------------------------------------------------
+
+
+def caudate_may_act() -> bool:
+    """The single gate Caudate's code paths should check.
+
+    Returns False if:
+      - the killswitch is active
+    True otherwise.
+    """
+    return not is_killed()