caudate-cli 0.1.0__py3-none-any.whl

memory/episodic.py

@@ -0,0 +1,99 @@
+"""Episodic Memory — stores and retrieves past experiences using vector similarity."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import chromadb
+
+from config import CHROMA_DIR, EPISODIC_RECALL_LIMIT
+from core.schemas import Episode
+
+logger = logging.getLogger(__name__)
+
+
+class EpisodicMemory:
+    """Vector-based store of past episodes (experiences).
+
+    Each episode records what the agent did, what happened, and in what context.
+    Retrieval is by semantic similarity to a query.
+    """
+
+    def __init__(self, persist_dir: str | None = None):
+        path = persist_dir or str(CHROMA_DIR)
+        self._client = chromadb.PersistentClient(path=path)
+        self._collection = self._client.get_or_create_collection(
+            name="episodic_memory",
+            metadata={"hnsw:space": "cosine"},
+        )
+
+    def store(self, episode: Episode) -> None:
+        """Store an episode."""
+        text = self._episode_to_text(episode)
+        metadata = {
+            "goal_id": episode.goal_id,
+            "task_id": episode.task_id,
+            "tool_name": episode.tool_name or "",
+            "timestamp": episode.timestamp.isoformat(),
+        }
+        if episode.result:
+            metadata["result_status"] = episode.result.status.value
+
+        self._collection.add(
+            ids=[episode.id],
+            documents=[text],
+            metadatas=[metadata],
+        )
+        logger.debug(f"Stored episode {episode.id}")
+
+    def recall(
+        self,
+        query: str,
+        limit: int = EPISODIC_RECALL_LIMIT,
+        goal_id: str | None = None,
+    ) -> list[Episode]:
+        """Retrieve similar episodes."""
+        where = {"goal_id": goal_id} if goal_id else None
+        results = self._collection.query(
+            query_texts=[query],
+            n_results=limit,
+            where=where,
+        )
+
+        episodes = []
+        if results["documents"]:
+            for i, doc in enumerate(results["documents"][0]):
+                meta = results["metadatas"][0][i] if results["metadatas"] else {}
+                kwargs = {
+                    "id": results["ids"][0][i],
+                    "goal_id": meta.get("goal_id", ""),
+                    "task_id": meta.get("task_id", ""),
+                    "action": doc,
+                    "tool_name": meta.get("tool_name") or None,
+                }
+                ts = meta.get("timestamp")
+                if ts:
+                    kwargs["timestamp"] = ts
+                episode = Episode(**kwargs)
+                episodes.append(episode)
+        return episodes
+
+    def count(self) -> int:
+        return self._collection.count()
+
+    def _episode_to_text(self, episode: Episode) -> str:
+        """Convert episode to searchable text."""
+        parts = [f"Action: {episode.action}"]
+        if episode.tool_name:
+            parts.append(f"Tool: {episode.tool_name}")
+        if episode.tool_args:
+            parts.append(f"Args: {json.dumps(episode.tool_args)}")
+        if episode.result:
+            parts.append(f"Result: {episode.result.status.value}")
+            if episode.result.output:
+                parts.append(f"Output: {str(episode.result.output)[:500]}")
+            if episode.result.error:
+                parts.append(f"Error: {episode.result.error}")
+        return " | ".join(parts)

memory/procedural.py

@@ -0,0 +1,145 @@
+"""Procedural Memory — stores learned strategies and heuristics in SQLite."""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+
+import sqlalchemy as sa
+from sqlalchemy import create_engine, Column, String, Float, Integer, DateTime, Text
+from sqlalchemy.orm import declarative_base, Session
+
+from config import SQLITE_PATH
+from core.schemas import Strategy
+
+logger = logging.getLogger(__name__)
+
+Base = declarative_base()
+
+
+class StrategyRow(Base):
+    __tablename__ = "strategies"
+
+    id = Column(String, primary_key=True)
+    name = Column(String, nullable=False)
+    description = Column(Text, nullable=False)
+    conditions = Column(Text, nullable=False)
+    actions = Column(Text, nullable=False)
+    confidence = Column(Float, default=0.5)
+    times_used = Column(Integer, default=0)
+    times_succeeded = Column(Integer, default=0)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow)
+
+
+class PerformanceLogRow(Base):
+    __tablename__ = "performance_log"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    goal_id = Column(String, nullable=False)
+    score = Column(Float, nullable=False)
+    lesson = Column(Text, default="")
+    strategy_ids = Column(Text, default="[]")  # JSON list
+    timestamp = Column(DateTime, default=datetime.utcnow)
+
+
+class ProceduralMemory:
+    """SQLite-backed store for learned strategies and performance history."""
+
+    def __init__(self, db_path: str | None = None):
+        path = db_path or str(SQLITE_PATH)
+        self._engine = create_engine(f"sqlite:///{path}")
+        Base.metadata.create_all(self._engine)
+
+    def store_strategy(self, strategy: Strategy) -> None:
+        """Store or update a strategy."""
+        with Session(self._engine) as session:
+            row = session.get(StrategyRow, strategy.id)
+            if row:
+                row.name = strategy.name
+                row.description = strategy.description
+                row.conditions = strategy.conditions
+                row.actions = strategy.actions
+                row.confidence = strategy.confidence
+                row.times_used = strategy.times_used
+                row.times_succeeded = strategy.times_succeeded
+                row.updated_at = datetime.utcnow()
+            else:
+                row = StrategyRow(
+                    id=strategy.id,
+                    name=strategy.name,
+                    description=strategy.description,
+                    conditions=strategy.conditions,
+                    actions=strategy.actions,
+                    confidence=strategy.confidence,
+                    times_used=strategy.times_used,
+                    times_succeeded=strategy.times_succeeded,
+                )
+                session.add(row)
+            session.commit()
+
+    def get_strategies(self, min_confidence: float = 0.0) -> list[Strategy]:
+        """Retrieve all strategies above a confidence threshold."""
+        with Session(self._engine) as session:
+            rows = session.query(StrategyRow).filter(
+                StrategyRow.confidence >= min_confidence
+            ).order_by(StrategyRow.confidence.desc()).all()
+
+            return [
+                Strategy(
+                    id=r.id,
+                    name=r.name,
+                    description=r.description,
+                    conditions=r.conditions,
+                    actions=r.actions,
+                    confidence=r.confidence,
+                    times_used=r.times_used,
+                    times_succeeded=r.times_succeeded,
+                    created_at=r.created_at,
+                    updated_at=r.updated_at,
+                )
+                for r in rows
+            ]
+
+    def update_strategy_stats(self, strategy_id: str, succeeded: bool) -> None:
+        """Update usage stats for a strategy after it's been applied."""
+        with Session(self._engine) as session:
+            row = session.get(StrategyRow, strategy_id)
+            if row:
+                row.times_used += 1
+                if succeeded:
+                    row.times_succeeded += 1
+                # Recalculate confidence as success rate with Bayesian smoothing
+                row.confidence = (row.times_succeeded + 1) / (row.times_used + 2)
+                row.updated_at = datetime.utcnow()
+                session.commit()
+
+    def log_performance(self, goal_id: str, score: float, lesson: str, strategy_ids: list[str]) -> None:
+        """Log a performance entry."""
+        with Session(self._engine) as session:
+            session.add(PerformanceLogRow(
+                goal_id=goal_id,
+                score=score,
+                lesson=lesson,
+                strategy_ids=json.dumps(strategy_ids),
+            ))
+            session.commit()
+
+    def get_performance_history(self, limit: int = 20) -> list[dict]:
+        """Get recent performance entries."""
+        with Session(self._engine) as session:
+            rows = session.query(PerformanceLogRow).order_by(
+                PerformanceLogRow.timestamp.desc()
+            ).limit(limit).all()
+
+            return [
+                {
+                    "goal_id": r.goal_id,
+                    "score": r.score,
+                    "lesson": r.lesson,
+                    "strategy_ids": json.loads(r.strategy_ids),
+                    "timestamp": r.timestamp.isoformat(),
+                }
+                for r in rows
+            ]

memory/semantic.py

@@ -0,0 +1,71 @@
+"""Semantic Memory — long-term knowledge base using vector similarity."""
+
+from __future__ import annotations
+
+import logging
+
+import chromadb
+
+from config import CHROMA_DIR, SEMANTIC_RECALL_LIMIT
+
+logger = logging.getLogger(__name__)
+
+
+class SemanticMemory:
+    """Vector-based knowledge store.
+
+    Stores facts, concepts, and learned information that persists across goals.
+    Unlike episodic memory (what happened), semantic memory stores what is known.
+    """
+
+    def __init__(self, persist_dir: str | None = None):
+        path = persist_dir or str(CHROMA_DIR)
+        self._client = chromadb.PersistentClient(path=path)
+        self._collection = self._client.get_or_create_collection(
+            name="semantic_memory",
+            metadata={"hnsw:space": "cosine"},
+        )
+
+    def store(self, knowledge_id: str, content: str, category: str = "general") -> None:
+        """Store a piece of knowledge."""
+        self._collection.upsert(
+            ids=[knowledge_id],
+            documents=[content],
+            metadatas=[{"category": category}],
+        )
+        logger.debug(f"Stored knowledge: {knowledge_id}")
+
+    def recall(
+        self,
+        query: str,
+        limit: int = SEMANTIC_RECALL_LIMIT,
+        category: str | None = None,
+    ) -> list[dict[str, str]]:
+        """Retrieve relevant knowledge."""
+        where = {"category": category} if category else None
+        results = self._collection.query(
+            query_texts=[query],
+            n_results=limit,
+            where=where,
+        )
+
+        knowledge = []
+        if results["documents"]:
+            for i, doc in enumerate(results["documents"][0]):
+                meta = results["metadatas"][0][i] if results["metadatas"] else {}
+                knowledge.append({
+                    "id": results["ids"][0][i],
+                    "content": doc,
+                    "category": meta.get("category", "general"),
+                })
+        return knowledge
+
+    def forget(self, knowledge_id: str) -> None:
+        """Remove a piece of knowledge."""
+        try:
+            self._collection.delete(ids=[knowledge_id])
+        except Exception:
+            pass
+
+    def count(self) -> int:
+        return self._collection.count()

memory/working.py

@@ -0,0 +1,64 @@
+"""Working Memory — short-term scratchpad for the current cognitive cycle."""
+
+from __future__ import annotations
+
+import logging
+from collections import OrderedDict
+from typing import Any
+
+from config import WORKING_MEMORY_CAPACITY
+
+logger = logging.getLogger(__name__)
+
+
+class WorkingMemory:
+    """Fixed-capacity short-term memory. Oldest items are evicted when full."""
+
+    def __init__(self, capacity: int = WORKING_MEMORY_CAPACITY):
+        self.capacity = capacity
+        self._store: OrderedDict[str, Any] = OrderedDict()
+
+    def store(self, key: str, value: Any) -> None:
+        """Store an item. Evicts oldest if at capacity."""
+        if key in self._store:
+            self._store.move_to_end(key)
+        self._store[key] = value
+        while len(self._store) > self.capacity:
+            evicted_key, _ = self._store.popitem(last=False)
+            logger.debug(f"Working memory evicted: {evicted_key}")
+
+    def recall(self, key: str) -> Any | None:
+        """Recall an item by key."""
+        if key in self._store:
+            self._store.move_to_end(key)
+            return self._store[key]
+        return None
+
+    def recall_all(self) -> dict[str, Any]:
+        """Return all items in working memory."""
+        return dict(self._store)
+
+    def remove(self, key: str) -> None:
+        """Remove an item."""
+        self._store.pop(key, None)
+
+    def clear(self) -> None:
+        """Clear all working memory."""
+        self._store.clear()
+
+    def contains(self, key: str) -> bool:
+        return key in self._store
+
+    @property
+    def size(self) -> int:
+        return len(self._store)
+
+    def summary(self) -> str:
+        """Return a text summary of working memory contents."""
+        if not self._store:
+            return "Working memory is empty."
+        lines = [f"Working memory ({self.size}/{self.capacity}):"]
+        for key, value in self._store.items():
+            val_str = str(value)[:100]
+            lines.append(f"  - {key}: {val_str}")
+        return "\n".join(lines)

nn/__init__.py

@@ -0,0 +1,43 @@
+"""Cognos neural-network subsystem — home of Caudate.
+
+Caudate is Cognos's action-selection brain — a small PyTorch transformer
+named for the caudate nucleus, the basal-ganglia structure that learns
+from outcomes to bias which action a real brain takes next. She trains
+on Cognos's own session history to predict, per turn:
+
+    1. which tool to call next
+    2. which routing tier (System 1 / System 2) is appropriate
+    3. whether engaging chain-of-thought helps
+    4. an expected reward / value estimate
+
+Caudate does NOT replace the LLM cortex. She runs alongside as an
+*advisor*: every inference is logged, and (later) optionally biases the
+agent's prompt. Bad predictions don't break the agent.
+
+Module layout:
+
+    nn/config.py        hyperparameters
+    nn/encoder.py       state encoder (text + tool history + mood)
+    nn/caudate.py       Caudate — transformer + 4 output heads
+    nn/data.py          dataset + replay buffer
+    nn/trainer.py       optimizer / loss / eval / checkpointing
+    nn/consolidator.py  offline replay → training pairs
+    nn/runtime.py       inference loader + CaudateAdvisor
+
+Persistent state lives at `data/nn/`.
+"""
+
+from nn.caudate import Caudate, CognosController  # alias kept for compat
+from nn.config import NNConfig
+from nn.encoder import StateEncoder
+from nn.runtime import CaudateAdvisor, NNAdvisor, load_advisor
+
+__all__ = [
+    "NNConfig",
+    "Caudate",
+    "CognosController",
+    "StateEncoder",
+    "CaudateAdvisor",
+    "NNAdvisor",
+    "load_advisor",
+]

nn/auto_evolve.py

@@ -0,0 +1,245 @@
+"""Auto-evolve — Caudate fires her own NAS runs.
+
+Wired into `CaudateObserver._kick_auto_train`. After each background
+training cycle, this module decides whether to launch a NAS run:
+
+  1. Was the latest training improvement small? (PlateauScheduler)
+  2. Has the cooldown passed? (default 6h between NAS runs)
+  3. Is there enough VRAM headroom?
+  4. Is no NAS run already in flight?
+
+If all four pass, picks a strategy (rotating through evolutionary →
+random → rl), runs the search asynchronously, and if a new champion
+beats the current Caudate by a margin, promotes it and hot-swaps the
+advisor.
+
+Every decision (fire / skip / promote / reject) lands in
+`data/nn/nas/auto_log.jsonl` for inspection.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+# Strategies cycled through across firings. Evolutionary first because
+# it's most sample-efficient; random as a sanity check; RL once enough
+# trials accumulated to learn from.
+_ROTATION = ["evolutionary", "random", "rl", "evolutionary", "hyperband"]
+
+
+@dataclass
+class AutoEvolveConfig:
+    enabled: bool = True
+    min_vram_gb: float = 3.0           # skip NAS if less than this is free
+    cooldown_seconds: float = 6 * 3600  # don't fire more often than this
+    n_trials_per_run: int = 8
+    train_steps_per_trial: int = 150
+    promote_margin: float = 0.005       # new champion must beat by this much
+    rotation: list[str] = None          # strategies to cycle through
+
+
+def _free_vram_gb() -> float:
+    try:
+        out = subprocess.run(
+            ["nvidia-smi", "--query-gpu=memory.free",
+             "--format=csv,noheader,nounits"],
+            capture_output=True, text=True, timeout=2,
+        ).stdout.strip().splitlines()[0]
+        return float(out) / 1024.0
+    except Exception:
+        return float("inf")  # if we can't check, assume OK
+
+
+class AutoEvolver:
+    """Decides + drives autonomous NAS runs from the observer."""
+
+    def __init__(self, observer: Any, cfg: AutoEvolveConfig | None = None):
+        self.observer = observer
+        self.cfg = cfg or AutoEvolveConfig()
+        if self.cfg.rotation is None:
+            self.cfg.rotation = list(_ROTATION)
+        self._nas_in_flight: asyncio.Task | None = None
+        self._n_fires = 0
+        self._last_fire_at: float = 0.0
+        self._auto_log = Path(self.observer.cfg.data_dir) / "nas" / "auto_log.jsonl"
+        self._auto_log.parent.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------
+
+    def maybe_fire(self) -> None:
+        """Called from CaudateObserver after each auto-train cycle."""
+        if not self.cfg.enabled:
+            return
+        # Owner killswitch — overrides everything else.
+        try:
+            from core.ownership import caudate_may_act
+            if not caudate_may_act():
+                self._log("skip", reason="owner_killswitch_active")
+                return
+        except Exception:
+            pass
+        if self._nas_in_flight is not None and not self._nas_in_flight.done():
+            self._log("skip", reason="already_in_flight")
+            return
+        if time.time() - self._last_fire_at < self.cfg.cooldown_seconds:
+            self._log("skip", reason="cooldown")
+            return
+
+        # Plateau check via the existing scheduler
+        try:
+            from nn.nas.scheduler import PlateauScheduler
+            sched = PlateauScheduler()
+            if not sched.should_fire():
+                self._log("skip", reason="not_plateaued",
+                          stalled_for=sched.status().get("stalled_for"))
+                return
+        except Exception as e:
+            logger.debug(f"plateau check failed: {e}")
+            return
+
+        # VRAM check
+        free_gb = _free_vram_gb()
+        if free_gb < self.cfg.min_vram_gb:
+            self._log("skip", reason="vram_low", free_gb=round(free_gb, 1))
+            return
+
+        # All gates passed — schedule a background NAS run.
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            self._log("skip", reason="no_running_loop")
+            return
+
+        strategy = self.cfg.rotation[self._n_fires % len(self.cfg.rotation)]
+        self._n_fires += 1
+        self._last_fire_at = time.time()
+        self._log("fire", strategy=strategy, n_fire=self._n_fires,
+                  free_vram_gb=round(free_gb, 1))
+        self._nas_in_flight = loop.create_task(
+            self._run_async(strategy)
+        )
+
+    # ------------------------------------------------------------------
+
+    async def _run_async(self, strategy_name: str) -> None:
+        """Run NAS in a thread (heavy CPU/GPU work) and post-process."""
+        try:
+            result = await asyncio.to_thread(self._run_sync, strategy_name)
+            self._log("complete", strategy=strategy_name, result=result)
+            # Hot-swap the advisor in case champion was promoted
+            self.observer.reload_advisor()
+            try:
+                from nn.nas.scheduler import PlateauScheduler
+                PlateauScheduler().mark_fired()
+            except Exception:
+                pass
+        except Exception as e:
+            self._log("error", strategy=strategy_name, error=str(e))
+            logger.warning(f"auto-NAS [{strategy_name}] failed: {e}")
+
+    def _run_sync(self, strategy_name: str) -> dict[str, Any]:
+        from nn.nas import Searcher
+        from nn.nas.searcher import SearcherConfig
+        from nn.nas.strategies import make_strategy
+        from nn.nas.strategies.base import StrategyConfig
+
+        scfg = StrategyConfig(
+            n_trials=self.cfg.n_trials_per_run,
+            train_steps_per_trial=self.cfg.train_steps_per_trial,
+            seed=int(time.time()) % 10000,
+        )
+        if strategy_name == "hyperband":
+            base = make_strategy("random", config=scfg)
+            strategy = make_strategy("hyperband", config=scfg, base=base)
+        elif strategy_name == "darts":
+            strategy = make_strategy("darts", config=scfg, epochs=3, n_layers=4)
+        else:
+            strategy = make_strategy(strategy_name, config=scfg)
+
+        searcher = Searcher(
+            cfg=SearcherConfig(
+                n_trials=self.cfg.n_trials_per_run,
+                train_steps_per_trial=self.cfg.train_steps_per_trial,
+                seed=scfg.seed,
+                cost_cap=8.0,
+                min_corpus_size=64,
+                promote_margin=self.cfg.promote_margin,
+            ),
+            strategy=strategy,
+        )
+        summary = searcher.search()
+
+        # If a new champion exists, promote it over the current Caudate
+        if summary.get("status") == "complete" and summary.get("champion"):
+            self._maybe_promote_to_main()
+
+        return {
+            "status": summary.get("status"),
+            "n_trials": summary.get("n_trials"),
+            "champion": summary.get("champion"),
+        }
+
+    def _maybe_promote_to_main(self) -> None:
+        """Copy NAS champion → main caudate.pt if it beats current."""
+        try:
+            from nn.nas.store import NASStore
+            store = NASStore()
+            champ = store.champion()
+            if not champ:
+                return
+            # Get champion fitness
+            champ_fit = float(champ.get("result", {}).get("fitness", 0.0))
+            # We promote unconditionally — Searcher already gated on the
+            # margin against the previous champion. The Searcher's own
+            # save_champion step already wrote champion.pt. Now copy to
+            # the main slot so the live observer picks it up.
+            ok = store.promote_to_main(self.observer.cfg.checkpoint_path)
+            if ok:
+                logger.info(
+                    f"auto-NAS promoted champion → main caudate "
+                    f"(fitness={champ_fit:.3f})"
+                )
+                self._log("promote", fitness=champ_fit)
+        except Exception as e:
+            logger.debug(f"auto-NAS promotion failed: {e}")
+
+    # ------------------------------------------------------------------
+
+    def status(self) -> dict[str, Any]:
+        return {
+            "enabled": self.cfg.enabled,
+            "n_fires": self._n_fires,
+            "in_flight": (
+                self._nas_in_flight is not None
+                and not self._nas_in_flight.done()
+            ),
+            "seconds_since_last_fire": (
+                int(time.time() - self._last_fire_at)
+                if self._last_fire_at else None
+            ),
+            "cooldown_seconds": self.cfg.cooldown_seconds,
+            "min_vram_gb": self.cfg.min_vram_gb,
+            "rotation": list(self.cfg.rotation),
+        }
+
+    def _log(self, action: str, **kwargs: Any) -> None:
+        try:
+            with self._auto_log.open("a") as f:
+                f.write(json.dumps({
+                    "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                    "action": action,
+                    **kwargs,
+                }) + "\n")
+        except Exception as e:
+            logger.debug(f"auto_log write failed: {e}")