hyperagents 1.2.3rc5.post3__py3-none-any.whl

core/hyperrouter/__init__.py

@@ -0,0 +1,23 @@
+from .bandit import (
+    HyperRouter,
+    ucb1_score,
+    select_agent,
+    select_model,
+    update_scores,
+    MODEL_COSTS,
+    MODEL_LATENCY_MS,
+    CHATJIMMY_TASK_TYPES,
+)
+from .fast_loop import FastLoop
+
+__all__ = [
+    "HyperRouter",
+    "ucb1_score",
+    "select_agent",
+    "select_model",
+    "update_scores",
+    "MODEL_COSTS",
+    "MODEL_LATENCY_MS",
+    "CHATJIMMY_TASK_TYPES",
+    "FastLoop",
+]

core/hyperrouter/bandit.py

@@ -0,0 +1,218 @@
+"""
+HyperRouter UCB1 Bandit — multi-armed bandit model and agent routing.
+Uses Upper Confidence Bound 1 (UCB1) algorithm for exploration/exploitation.
+"""
+from __future__ import annotations
+
+import copy
+import math
+from dataclasses import dataclass, field
+from typing import Optional
+
+from core.hyperstate.schema import AgentScore, ModelScore
+
+
+# ── Cost and latency tables ───────────────────────────────────────────────────
+
+MODEL_COSTS: dict[str, float] = {
+    "chatjimmy": 0.000001,
+    "claude-opus-5": 0.005,
+    "claude-sonnet-5": 0.002,
+    "claude-code": 0.003,
+    "nim-local": 0.0,
+}
+
+MODEL_LATENCY_MS: dict[str, float] = {
+    "chatjimmy": 50.0,
+    "claude-opus-5": 4000.0,
+    "claude-sonnet-5": 2000.0,
+    "claude-code": 3000.0,
+    "nim-local": 500.0,
+}
+
+# Tasks ChatJimmy handles well (fast, cheap, low-stakes)
+CHATJIMMY_TASK_TYPES: frozenset[str] = frozenset([
+    "routing", "classification", "quick_lookup",
+    "summarization", "draft", "triage", "status_check",
+])
+
+
+# ── Core UCB1 functions ───────────────────────────────────────────────────────
+
+def ucb1_score(
+    successes: int,
+    attempts: int,
+    total_attempts: int,
+    c: float = 2.0,
+) -> float:
+    """
+    Compute UCB1 score for a single arm.
+
+    Returns float('inf') if attempts == 0 (unexplored arm always gets tried first).
+    Formula: mean_reward + c * sqrt(ln(total_attempts) / attempts)
+    """
+    if attempts == 0:
+        return float("inf")
+    mean_reward = successes / attempts
+    exploration = c * math.sqrt(math.log(max(total_attempts, 1)) / attempts)
+    return mean_reward + exploration
+
+
+def select_agent(
+    agents: dict[str, AgentScore],
+    task_type: str,
+    total_attempts: int,
+) -> str:
+    """
+    Select the best agent for a task_type using UCB1.
+    Prefers agents whose task_type matches, falls back to all agents.
+    Returns the agent_id with the highest UCB1 score.
+    """
+    if not agents:
+        return "default_agent"
+
+    # Filter to agents matching task_type if possible
+    matching = {
+        aid: score for aid, score in agents.items()
+        if score.task_type == task_type
+    }
+    pool = matching if matching else agents
+
+    best_id = max(
+        pool,
+        key=lambda aid: ucb1_score(
+            pool[aid].successes,
+            pool[aid].attempts,
+            total_attempts,
+        ),
+    )
+    return best_id
+
+
+def select_model(
+    model_scores: dict[str, dict[str, ModelScore]],
+    task_type: str,
+    total_attempts: int,
+    cost_budget_usd: Optional[float] = None,
+    latency_budget_ms: Optional[float] = None,
+) -> str:
+    """
+    Select the best model for a task_type using UCB1, with optional budget filters.
+
+    ChatJimmy is the default for CHATJIMMY_TASK_TYPES if it passes budget checks.
+    Budget filters are applied before scoring — models exceeding either budget are excluded.
+    Falls back to 'claude-opus-5' if no scored models available.
+    """
+    # ChatJimmy fast-path for cheap/quick tasks
+    if task_type in CHATJIMMY_TASK_TYPES:
+        cj_cost = MODEL_COSTS.get("chatjimmy", 0.0)
+        cj_latency = MODEL_LATENCY_MS.get("chatjimmy", 50.0)
+        cost_ok = cost_budget_usd is None or cj_cost <= cost_budget_usd
+        latency_ok = latency_budget_ms is None or cj_latency <= latency_budget_ms
+        if cost_ok and latency_ok:
+            return "chatjimmy"
+
+    # Build candidate pool with budget filtering
+    candidates: dict[str, ModelScore] = {}
+    for model_id, task_map in model_scores.items():
+        score = task_map.get(task_type, ModelScore())
+
+        cost = MODEL_COSTS.get(model_id, 0.001)
+        latency = MODEL_LATENCY_MS.get(model_id, 2000.0)
+
+        if cost_budget_usd is not None and cost > cost_budget_usd:
+            continue
+        if latency_budget_ms is not None and latency > latency_budget_ms:
+            continue
+
+        candidates[model_id] = score
+
+    if not candidates:
+        # Fallback: try any model within budget ignoring task_type filter
+        for model_id in MODEL_COSTS:
+            cost = MODEL_COSTS.get(model_id, 0.001)
+            latency = MODEL_LATENCY_MS.get(model_id, 2000.0)
+            if cost_budget_usd is not None and cost > cost_budget_usd:
+                continue
+            if latency_budget_ms is not None and latency > latency_budget_ms:
+                continue
+            candidates[model_id] = ModelScore()
+
+    if not candidates:
+        return "claude-opus-5"
+
+    best_model = max(
+        candidates,
+        key=lambda mid: ucb1_score(
+            candidates[mid].successes,
+            candidates[mid].attempts,
+            total_attempts,
+        ),
+    )
+    return best_model
+
+
+def update_scores(
+    scores: dict[str, dict[str, ModelScore]],
+    model_id: str,
+    task_type: str,
+    success: bool,
+) -> dict[str, dict[str, ModelScore]]:
+    """
+    Immutably update model scores. Returns a new dict — original is unchanged.
+    """
+    new_scores = copy.deepcopy(scores)
+    if model_id not in new_scores:
+        new_scores[model_id] = {}
+    if task_type not in new_scores[model_id]:
+        new_scores[model_id][task_type] = ModelScore()
+
+    entry = new_scores[model_id][task_type]
+    entry.attempts += 1
+    if success:
+        entry.successes += 1
+
+    return new_scores
+
+
+# ── HyperRouter dataclass ──────────────────────────────────────────────────────
+
+@dataclass
+class HyperRouter:
+    """
+    Stateful router that holds live UCB1 scores and routes tasks to
+    (agent_id, model_id) pairs.
+    """
+    agent_scores: dict[str, AgentScore] = field(default_factory=dict)
+    model_scores: dict[str, dict[str, ModelScore]] = field(default_factory=dict)
+    total_attempts: int = 0
+
+    def route(
+        self,
+        task_type: str,
+        cost_budget: Optional[float] = None,
+        latency_budget: Optional[float] = None,
+    ) -> tuple[str, str]:
+        """
+        Route a task to the best (agent_id, model_id) pair.
+        Uses UCB1 for both selections.
+        """
+        agent_id = select_agent(self.agent_scores, task_type, self.total_attempts)
+        model_id = select_model(
+            self.model_scores,
+            task_type,
+            self.total_attempts,
+            cost_budget_usd=cost_budget,
+            latency_budget_ms=latency_budget,
+        )
+        return agent_id, model_id
+
+    def record(self, agent_id: str, model_id: str, task_type: str, success: bool) -> None:
+        """Record the outcome of a routing decision and update scores."""
+        self.total_attempts += 1
+        self.model_scores = update_scores(self.model_scores, model_id, task_type, success)
+        if agent_id not in self.agent_scores:
+            self.agent_scores[agent_id] = AgentScore(task_type=task_type)
+        self.agent_scores[agent_id].attempts += 1
+        if success:
+            self.agent_scores[agent_id].successes += 1

core/hyperrouter/fast_loop.py

@@ -0,0 +1,68 @@
+"""
+FastLoop — high-frequency routing loop. Routes tasks in <100ms using cached UCB1 scores.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from core.hyperstate.schema import ExperimentEntry, HyperState
+from .bandit import HyperRouter
+
+
+class FastLoop:
+    """
+    Fast routing path. Reads live UCB1 scores from HyperState.model_scores
+    and routes to the optimal (agent_id, model_id) pair in microseconds.
+    """
+
+    def __init__(self) -> None:
+        self._router = HyperRouter()
+
+    async def route(
+        self,
+        state: HyperState,
+        task_type: str,
+        cost_budget: Optional[float] = None,
+        latency_budget: Optional[float] = None,
+    ) -> tuple[str, str]:
+        """
+        Route a task using live UCB1 scores from the HyperState.
+
+        Syncs the router's model_scores from state, routes the task,
+        then appends a routing entry to state.experiment_log.
+
+        Returns:
+            (agent_id, model_id)
+        """
+        # Sync router from state's live scores
+        self._router.agent_scores = dict(state.agent_scores)
+        self._router.model_scores = {
+            model_id: dict(task_map)
+            for model_id, task_map in state.model_scores.items()
+        }
+        self._router.total_attempts = sum(
+            score.attempts for score in state.agent_scores.values()
+        ) or 1
+
+        agent_id, model_id = self._router.route(
+            task_type=task_type,
+            cost_budget=cost_budget,
+            latency_budget=latency_budget,
+        )
+
+        # Log routing decision to state experiment log
+        routing_entry = ExperimentEntry(
+            method=f"fast_loop_route:{task_type}",
+            model_used=model_id,
+            result=f"routed to agent={agent_id} model={model_id}",
+            certified=False,
+            test_trace="",
+            cost_usd=0.0,
+            latency_ms=0.0,
+            timestamp=datetime.now(timezone.utc),
+        )
+        state.experiment_log.append(routing_entry)
+        state._bump_version()
+
+        return agent_id, model_id

core/hyperrouter/slow_loop.py

@@ -0,0 +1,143 @@
+"""
+SlowLoop — background optimization loop. Periodically re-reads SwarmMessage history
+from the DB, rebalances UCB1 scores, and writes routing performance summaries to CausalGraph.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+import asyncpg
+
+from .bandit import HyperRouter, update_scores
+from core.hyperstate.schema import AgentScore, ModelScore
+
+if TYPE_CHECKING:
+    from memory.causal_graph import CausalGraph
+
+log = logging.getLogger("hyperclaw.slow_loop")
+
+
+class SlowLoop:
+    """
+    Background optimization loop.
+
+    Every interval_hours:
+    1. Reads all SwarmMessages from DB since last run
+    2. Recalculates UCB1 scores per agent/model per task_type
+    3. Updates HyperRouter in-place
+    4. Writes routing performance summary to CausalGraph (node_type='outcome')
+    5. Returns summary dict
+    """
+
+    def __init__(
+        self,
+        hyper_router: HyperRouter,
+        pool: asyncpg.Pool,
+        causal_graph: "CausalGraph",
+    ) -> None:
+        self._router = hyper_router
+        self._pool = pool
+        self._causal_graph = causal_graph
+        self._last_run: datetime | None = None
+
+    async def run_once(self) -> dict:
+        """
+        Process SwarmMessages since last run, update router scores.
+        Returns summary: {messages_processed, agents_updated, models_updated, timestamp}
+        """
+        since = self._last_run or datetime(2020, 1, 1, tzinfo=timezone.utc)
+
+        async with self._pool.acquire() as conn:
+            rows = await conn.fetch(
+                """
+                SELECT agent_id, model_used, task_type, certified
+                FROM swarm_messages
+                WHERE created_at > $1
+                ORDER BY created_at ASC
+                """,
+                since,
+            )
+
+        agents_seen: set[str] = set()
+        models_seen: set[str] = set()
+        messages_processed = 0
+
+        new_agent_scores: dict = dict(self._router.agent_scores)
+        new_model_scores: dict = dict(self._router.model_scores)
+        new_total = self._router.total_attempts
+
+        for row in rows:
+            agent_id = row["agent_id"]
+            model_id = row["model_used"]
+            task_type = row["task_type"]
+            # Treat certified=True as success; False as failure
+            success = bool(row["certified"])
+
+            # Update agent scores
+            if agent_id not in new_agent_scores:
+                new_agent_scores[agent_id] = AgentScore(task_type=task_type)
+            new_agent_scores[agent_id].attempts += 1
+            if success:
+                new_agent_scores[agent_id].successes += 1
+            agents_seen.add(agent_id)
+
+            # Update model scores (immutable pattern)
+            new_model_scores = update_scores(new_model_scores, model_id, task_type, success)
+            models_seen.add(model_id)
+            new_total += 1
+            messages_processed += 1
+
+        # Apply updated scores to router
+        self._router.agent_scores = new_agent_scores
+        self._router.model_scores = new_model_scores
+        self._router.total_attempts = new_total
+
+        now = datetime.now(timezone.utc)
+        self._last_run = now
+
+        summary = {
+            "messages_processed": messages_processed,
+            "agents_updated": len(agents_seen),
+            "models_updated": len(models_seen),
+            "timestamp": now.isoformat(),
+        }
+
+        # Write routing performance summary to CausalGraph
+        if messages_processed > 0:
+            try:
+                await self._causal_graph.add_node(
+                    label=f"routing_optimization: processed {messages_processed} messages",
+                    node_type="outcome",
+                    domain="recursive",
+                    metadata={
+                        "slow_loop_summary": summary,
+                        "agents_updated": list(agents_seen),
+                        "models_updated": list(models_seen),
+                    },
+                )
+            except Exception as e:
+                log.warning(f"SlowLoop: failed to write CausalGraph summary: {e}")
+
+        log.info(
+            f"SlowLoop run_once: {messages_processed} messages, "
+            f"{len(agents_seen)} agents, {len(models_seen)} models updated"
+        )
+        return summary
+
+    async def run_forever(self, interval_hours: float = 6.0) -> None:
+        """
+        Infinite loop — runs run_once() then sleeps interval_hours.
+        Catches all exceptions, logs, continues.
+        """
+        log.info(f"SlowLoop started — interval={interval_hours}h")
+        while True:
+            try:
+                summary = await self.run_once()
+                log.info(f"SlowLoop cycle complete: {summary}")
+            except Exception as e:
+                log.error(f"SlowLoop error (continuing): {e}")
+            await asyncio.sleep(interval_hours * 3600)

core/hyperstate/__init__.py

@@ -0,0 +1,24 @@
+from .schema import (
+    HyperState,
+    Task,
+    Hypothesis,
+    ExperimentEntry,
+    AgentScore,
+    ModelScore,
+    CertifiedMethod,
+    RecursiveResearch,
+    Domain,
+    TaskType,
+)
+from .certifier import Certifier, CertificationError
+from .store import HyperStateStore
+from .state_manager import StateManager
+
+__all__ = [
+    "HyperState", "Task", "Hypothesis", "ExperimentEntry",
+    "AgentScore", "ModelScore", "CertifiedMethod", "RecursiveResearch",
+    "Domain", "TaskType",
+    "Certifier", "CertificationError",
+    "HyperStateStore",
+    "StateManager",
+]

core/hyperstate/certifier.py

@@ -0,0 +1,154 @@
+"""
+HyperClaw Certifier — validates ExperimentEntries before promoting to CertifiedMethod.
+When a CausalGraph is provided, writes cause→effect relationships on every successful certification.
+ChatJimmy outputs must always pass through Claude verification before reaching this stage.
+"""
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from .schema import CertifiedMethod, ExperimentEntry
+
+if TYPE_CHECKING:
+    from memory.causal_graph import CausalGraph
+
+
+class CertificationError(Exception):
+    """Raised when an ExperimentEntry fails certification criteria."""
+    pass
+
+
+class Certifier:
+    """
+    Validates ExperimentEntry objects and produces CertifiedMethod records.
+    Optionally wires to CausalGraph — every certified method auto-writes a causal edge.
+
+    Certification rules:
+    1. test_trace must be non-empty
+    2. result must be non-empty
+    3. certified flag must be True on the entry
+    """
+
+    def __init__(self, causal_graph: "CausalGraph | None" = None) -> None:
+        self._causal_graph = causal_graph
+
+    def certify(
+        self,
+        entry: ExperimentEntry,
+        domain: str = "business",
+    ) -> CertifiedMethod:
+        """
+        Validate an ExperimentEntry and return a CertifiedMethod.
+        If causal_graph was provided at init, schedules a causal edge write.
+
+        Raises:
+            CertificationError: if test_trace is empty, result is empty,
+                                 or certified flag is not set.
+        """
+        if not entry.test_trace or not entry.test_trace.strip():
+            raise CertificationError(
+                f"Certification failed for method '{entry.method}': "
+                "test_trace is empty. A non-empty test trace is required."
+            )
+        if not entry.result or not entry.result.strip():
+            raise CertificationError(
+                f"Certification failed for method '{entry.method}': "
+                "result is empty. A non-empty result is required."
+            )
+        if not entry.certified:
+            raise CertificationError(
+                f"Certification failed for method '{entry.method}': "
+                "entry.certified is False. Entry must be verified before certification."
+            )
+
+        certified_method = CertifiedMethod(
+            method_id=entry.method,
+            model_used=entry.model_used,
+            performance={
+                "cost_usd": entry.cost_usd,
+                "latency_ms": entry.latency_ms,
+                "test_trace_length": len(entry.test_trace),
+                "result_length": len(entry.result),
+            },
+        )
+
+        # Write causal edge if CausalGraph is wired in
+        if self._causal_graph is not None:
+            self._schedule_causal_write(entry, domain, certified_method)
+
+        return certified_method
+
+    def _schedule_causal_write(
+        self,
+        entry: ExperimentEntry,
+        domain: str,
+        certified_method: CertifiedMethod,
+    ) -> None:
+        """
+        Fire-and-forget coroutine to write causal edge.
+        Uses asyncio.ensure_future if an event loop is running,
+        otherwise stores for deferred execution.
+        """
+        import asyncio
+
+        coro = self._write_causal_edge(entry, domain, certified_method)
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(coro)
+        except RuntimeError:
+            # No running event loop — skip (sync context, e.g. unit tests)
+            pass
+
+    async def _write_causal_edge(
+        self,
+        entry: ExperimentEntry,
+        domain: str,
+        certified_method: CertifiedMethod,
+    ) -> None:
+        """Async: write cause→effect to CausalGraph."""
+        try:
+            method_uuid = UUID(certified_method.method_id) if _is_uuid(certified_method.method_id) else uuid.uuid4()
+            await self._causal_graph.write_certified_method(  # type: ignore[union-attr]
+                method_description=entry.method,
+                cause_description=f"method: {entry.method}",
+                effect_description=f"result: {entry.result}",
+                domain=domain,
+                confidence=1.0,
+                method_id=method_uuid,
+            )
+        except Exception as e:
+            import logging
+            logging.getLogger("hyperclaw.certifier").warning(
+                f"CausalGraph write failed for method '{entry.method}': {e}"
+            )
+
+    def validate_batch(
+        self,
+        entries: list[ExperimentEntry],
+        domain: str = "business",
+    ) -> tuple[list[CertifiedMethod], list[CertificationError]]:
+        """
+        Attempt to certify a batch of entries. Returns (certified, errors).
+        Does not raise — all errors are collected and returned.
+        """
+        certified: list[CertifiedMethod] = []
+        errors: list[CertificationError] = []
+
+        for entry in entries:
+            try:
+                cm = self.certify(entry, domain=domain)
+                certified.append(cm)
+            except CertificationError as e:
+                errors.append(e)
+
+        return certified, errors
+
+
+def _is_uuid(value: str) -> bool:
+    try:
+        UUID(value)
+        return True
+    except (ValueError, AttributeError):
+        return False