hyperagents 1.2.3rc5.post3__py3-none-any.whl

civilization/versioning/version_manager.py

@@ -0,0 +1,293 @@
+"""
+Version management for Civilization nodes.
+Tracks changes, maintains history, and supports rollback.
+"""
+from __future__ import annotations
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+from uuid import UUID, uuid4
+import json
+import hashlib
+
+from ..schema import CivilizationNode
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class NodeVersion:
+    """Represents a specific version of a node."""
+    version_id: UUID = field(default_factory=uuid4)
+    node_id: UUID = field(default_factory=uuid4)
+    version_number: str = "1.0.0"
+    content_hash: str = ""
+    snapshot: dict = field(default_factory=dict)
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    created_by: str | None = None
+    change_summary: str | None = None
+    metadata: dict = field(default_factory=dict)
+
+    @property
+    def major(self) -> int:
+        parts = self.version_number.split(".")
+        return int(parts[0]) if parts else 1
+
+    @property
+    def minor(self) -> int:
+        parts = self.version_number.split(".")
+        return int(parts[1]) if len(parts) > 1 else 0
+
+    @property
+    def patch(self) -> int:
+        parts = self.version_number.split(".")
+        return int(parts[2]) if len(parts) > 2 else 0
+
+
+@dataclass
+class VersionHistory:
+    """Complete version history for a node."""
+    node_id: UUID
+    current_version: str = "1.0.0"
+    versions: list[NodeVersion] = field(default_factory=list)
+
+    @property
+    def version_count(self) -> int:
+        return len(self.versions)
+
+    def get_version(self, version_number: str) -> NodeVersion | None:
+        """Get a specific version by version number."""
+        for v in self.versions:
+            if v.version_number == version_number:
+                return v
+        return None
+
+    def get_latest(self) -> NodeVersion | None:
+        """Get the most recent version."""
+        if not self.versions:
+            return None
+        return max(self.versions, key=lambda v: v.created_at)
+
+
+class VersionManager:
+    """
+    Manages versions of civilization nodes.
+    Supports semantic versioning, history tracking, and rollback.
+    """
+
+    def __init__(self, org_id: str, store=None):
+        self.org_id = org_id
+        self.store = store
+        self._histories: dict[UUID, VersionHistory] = {}
+
+    def _compute_hash(self, node: CivilizationNode) -> str:
+        """Compute content hash for a node."""
+        # Exclude volatile fields from hash
+        data = node.model_dump(mode="json", exclude={"updated_at", "embedding"})
+        content = json.dumps(data, sort_keys=True)
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+
+    def _parse_version(self, version: str) -> tuple[int, int, int]:
+        """Parse version string into (major, minor, patch)."""
+        parts = version.split(".")
+        return (
+            int(parts[0]) if parts else 1,
+            int(parts[1]) if len(parts) > 1 else 0,
+            int(parts[2]) if len(parts) > 2 else 0,
+        )
+
+    def _increment_version(
+        self,
+        current: str,
+        bump_type: str = "patch",
+    ) -> str:
+        """Increment version number."""
+        major, minor, patch = self._parse_version(current)
+
+        if bump_type == "major":
+            return f"{major + 1}.0.0"
+        elif bump_type == "minor":
+            return f"{major}.{minor + 1}.0"
+        else:  # patch
+            return f"{major}.{minor}.{patch + 1}"
+
+    def create_version(
+        self,
+        node: CivilizationNode,
+        bump_type: str = "patch",
+        change_summary: str | None = None,
+        created_by: str | None = None,
+    ) -> NodeVersion:
+        """
+        Create a new version of a node.
+
+        Args:
+            node: The node to version
+            bump_type: "major", "minor", or "patch"
+            change_summary: Description of changes
+            created_by: ID of user making the change
+
+        Returns:
+            The new NodeVersion
+        """
+        history = self._histories.get(node.id)
+
+        if history:
+            new_version_num = self._increment_version(history.current_version, bump_type)
+        else:
+            new_version_num = "1.0.0"
+            history = VersionHistory(node_id=node.id)
+            self._histories[node.id] = history
+
+        version = NodeVersion(
+            node_id=node.id,
+            version_number=new_version_num,
+            content_hash=self._compute_hash(node),
+            snapshot=node.model_dump(mode="json"),
+            created_by=created_by,
+            change_summary=change_summary,
+        )
+
+        history.versions.append(version)
+        history.current_version = new_version_num
+
+        logger.info(f"Created version {new_version_num} for node {node.id}")
+        return version
+
+    def get_history(self, node_id: UUID) -> VersionHistory | None:
+        """Get the version history for a node."""
+        return self._histories.get(node_id)
+
+    def get_version(self, node_id: UUID, version_number: str) -> NodeVersion | None:
+        """Get a specific version of a node."""
+        history = self._histories.get(node_id)
+        if history:
+            return history.get_version(version_number)
+        return None
+
+    def get_current_version(self, node_id: UUID) -> str:
+        """Get the current version number for a node."""
+        history = self._histories.get(node_id)
+        return history.current_version if history else "1.0.0"
+
+    def has_changes(self, node: CivilizationNode) -> bool:
+        """Check if a node has uncommitted changes."""
+        history = self._histories.get(node.id)
+        if not history or not history.versions:
+            return True
+
+        current_hash = self._compute_hash(node)
+        latest = history.get_latest()
+        return latest is None or latest.content_hash != current_hash
+
+    def restore_version(
+        self,
+        node_id: UUID,
+        version_number: str,
+    ) -> CivilizationNode | None:
+        """
+        Restore a node to a previous version.
+        Returns the restored node or None if version not found.
+        """
+        version = self.get_version(node_id, version_number)
+        if not version:
+            return None
+
+        # Reconstruct node from snapshot
+        return CivilizationNode(**version.snapshot)
+
+    def compare_versions(
+        self,
+        node_id: UUID,
+        version1: str,
+        version2: str,
+    ) -> dict | None:
+        """
+        Compare two versions of a node.
+        Returns a dict with added, removed, and changed fields.
+        """
+        v1 = self.get_version(node_id, version1)
+        v2 = self.get_version(node_id, version2)
+
+        if not v1 or not v2:
+            return None
+
+        changes = {
+            "added": {},
+            "removed": {},
+            "changed": {},
+        }
+
+        s1 = v1.snapshot
+        s2 = v2.snapshot
+
+        # Find added and changed
+        for key, val in s2.items():
+            if key not in s1:
+                changes["added"][key] = val
+            elif s1[key] != val:
+                changes["changed"][key] = {"old": s1[key], "new": val}
+
+        # Find removed
+        for key in s1:
+            if key not in s2:
+                changes["removed"][key] = s1[key]
+
+        return changes
+
+    def get_version_timeline(self, node_id: UUID) -> list[dict]:
+        """Get a timeline of all versions for a node."""
+        history = self._histories.get(node_id)
+        if not history:
+            return []
+
+        return [
+            {
+                "version": v.version_number,
+                "created_at": v.created_at.isoformat(),
+                "created_by": v.created_by,
+                "change_summary": v.change_summary,
+                "content_hash": v.content_hash,
+            }
+            for v in sorted(history.versions, key=lambda x: x.created_at)
+        ]
+
+    def cleanup_old_versions(
+        self,
+        node_id: UUID,
+        keep_count: int = 10,
+    ) -> int:
+        """
+        Remove old versions, keeping the most recent N.
+        Returns count of removed versions.
+        """
+        history = self._histories.get(node_id)
+        if not history or len(history.versions) <= keep_count:
+            return 0
+
+        sorted_versions = sorted(history.versions, key=lambda v: v.created_at, reverse=True)
+        to_remove = sorted_versions[keep_count:]
+
+        for v in to_remove:
+            history.versions.remove(v)
+
+        return len(to_remove)
+
+    def export_version(self, node_id: UUID, version_number: str) -> dict | None:
+        """Export a version as a portable dict."""
+        version = self.get_version(node_id, version_number)
+        if not version:
+            return None
+
+        return {
+            "version_id": str(version.version_id),
+            "node_id": str(version.node_id),
+            "version_number": version.version_number,
+            "content_hash": version.content_hash,
+            "snapshot": version.snapshot,
+            "created_at": version.created_at.isoformat(),
+            "created_by": version.created_by,
+            "change_summary": version.change_summary,
+            "metadata": version.metadata,
+        }

cli/__init__.py

@@ -0,0 +1 @@
+# HyperClaw CLI

cli/doctor.py

@@ -0,0 +1,334 @@
+"""
+hyperclaw doctor — system health check.
+Verifies API keys, DB connection, pgvector, policy files, and dependencies.
+"""
+from __future__ import annotations
+
+import asyncio
+import importlib
+import os
+import sys
+from pathlib import Path
+from typing import Callable
+
+from rich.console import Console
+from rich.table import Table
+from rich import print as rprint
+
+console = Console()
+
+CHECK_MARK = "[bold green]✓[/bold green]"
+CROSS_MARK = "[bold red]✗[/bold red]"
+WARN_MARK  = "[bold yellow]⚠[/bold yellow]"
+
+
+def _check(label: str, ok: bool, detail: str = "", warn: bool = False) -> dict:
+    status = CHECK_MARK if ok else (WARN_MARK if warn else CROSS_MARK)
+    return {"label": label, "ok": ok, "warn": warn, "detail": detail, "status": status}
+
+
+async def _check_db(db_url: str) -> dict:
+    try:
+        import asyncpg
+        conn = await asyncpg.connect(db_url, timeout=5)
+        await conn.close()
+        return _check("PostgreSQL connection", True, db_url.split("@")[-1] if "@" in db_url else db_url)
+    except Exception as e:
+        return _check("PostgreSQL connection", False, str(e)[:80])
+
+
+async def _check_pgvector(db_url: str) -> dict:
+    try:
+        import asyncpg
+        conn = await asyncpg.connect(db_url, timeout=5)
+        row = await conn.fetchval(
+            "SELECT COUNT(*) FROM pg_extension WHERE extname = 'vector'"
+        )
+        await conn.close()
+        if row:
+            return _check("pgvector extension", True, "installed")
+        else:
+            return _check("pgvector extension", False,
+                         "Not installed — run: CREATE EXTENSION vector; in your DB", warn=True)
+    except Exception as e:
+        return _check("pgvector extension", False, str(e)[:80])
+
+
+async def _check_migrations(db_url: str) -> dict:
+    try:
+        import asyncpg
+        conn = await asyncpg.connect(db_url, timeout=5)
+        exists = await conn.fetchval(
+            "SELECT EXISTS(SELECT 1 FROM information_schema.tables WHERE table_name='_migrations')"
+        )
+        if exists:
+            applied = await conn.fetch("SELECT filename FROM _migrations ORDER BY filename")
+            names = [r["filename"] for r in applied]
+            await conn.close()
+            return _check("DB migrations", True, f"{len(names)} applied: {', '.join(names)}")
+        else:
+            await conn.close()
+            return _check("DB migrations", False,
+                         "Not initialized — run: hyperclaw init", warn=True)
+    except Exception as e:
+        return _check("DB migrations", False, str(e)[:80])
+
+
+def _print_provider_matrix(probe: bool = False) -> None:
+    """Provider/slot matrix per the routing spec; --probe sends one cheap
+    request per live provider and reports latency."""
+    from hyperclaw.providers import registry, SLOTS
+    from hyperclaw.deployment import is_hyper
+    reg = registry()
+    line = "   ".join(f"{n} {'✓' if pr.live else '–'}" for n, pr in reg.providers.items())
+    console.print(f"\n[bold]Providers[/bold]   {line}"
+                  + ("   [dim](Hyper-deployed: allowed models only)[/dim]" if is_hyper() else ""))
+    summary = reg.slot_summary()
+    for i, slot in enumerate(SLOTS):
+        label = "[bold]Slots[/bold]      " if i == 0 else "           "
+        console.print(f"{label} {slot:<11}→ {summary.get(slot, 'not configured')}")
+    if not probe:
+        return
+    import time as _t
+    from hyperclaw.cost_guard import guard_client, max_output   # probes count against the cost cap too
+    console.print("\n[bold]Probe[/bold]")
+    for name, prov in reg.providers.items():
+        if not prov.live:
+            console.print(f"  {name}: skipped (not configured)")
+            continue
+        t0 = _t.time()
+        try:
+            if prov.kind == "anthropic":
+                import anthropic as _an
+                guard_client(_an.Anthropic(api_key=prov.api_key),
+                             getattr(prov, "name", None)).messages.create(
+                    model=prov.model_for("fast") or prov.model_for(),
+                    max_tokens=max_output("doctor", name, prov.model_for("fast") or prov.model_for()),
+                    messages=[{"role": "user", "content": "ping"}])
+            else:
+                import openai as _oa
+                guard_client(_oa.OpenAI(api_key=prov.api_key, base_url=prov.base_url or None),
+                             getattr(prov, "name", None)).chat.completions.create(
+                    model=prov.model_for(),
+                    max_tokens=max_output("doctor", name, prov.model_for()),
+                    messages=[{"role": "user", "content": "ping"}])
+            console.print(f"  {name}: ok ({(_t.time()-t0)*1000:.0f}ms)")
+        except Exception as e:
+            console.print(f"  {name}: FAILED ({type(e).__name__}: {str(e)[:80]})")
+
+
+def run_doctor(probe: bool = False) -> int:
+    """
+    Run all health checks and print results.
+    Returns 0 if all critical checks pass, 1 if any fail.
+    """
+    console.print("\n[bold cyan]⚡ HyperClaw Doctor[/bold cyan]\n")
+    # Load $HYPERCLAW_ROOT/.env (default ~/.hyperclaw) so doctor works without
+    # a sourced shell, before anything reads provider settings.
+    from hyperclaw.providers import reset_registry
+    from hyperclaw.userconfig import load_env_into_process
+    load_env_into_process()
+    reset_registry()
+    _print_provider_matrix(probe=probe)
+
+    checks: list[dict] = []
+    db_url = os.environ.get("DATABASE_URL", "")
+
+    # ── Python version ────────────────────────────────────────────────────────
+    py = sys.version_info
+    checks.append(_check(
+        "Python version",
+        py >= (3, 11),
+        f"{py.major}.{py.minor}.{py.micro}",
+        warn=(py >= (3, 11)),
+    ))
+
+    # ── Required packages ─────────────────────────────────────────────────────
+    required_packages = {
+        "pydantic": "pydantic",
+        "asyncpg": "asyncpg",
+        "anthropic": "anthropic",
+        "httpx": "httpx",
+        "typer": "typer",
+        "rich": "rich",
+        "yaml": "yaml (pyyaml)",
+        "dotenv": "dotenv (python-dotenv)",
+    }
+    for mod, label in required_packages.items():
+        try:
+            importlib.import_module(mod)
+            checks.append(_check(f"Package: {label}", True))
+        except ImportError:
+            checks.append(_check(f"Package: {label}", False, f"pip install {label.split()[0]}"))
+
+    # ── Environment variables ─────────────────────────────────────────────────
+    # (the user's .env was loaded before the provider matrix, above)
+    provider = os.environ.get("LLM_PROVIDER", "")
+    from hyperclaw.deployment import is_hyper
+    from hyperclaw.provider_setup import describe, v2_status
+    hyper = is_hyper()
+    v2 = v2_status()
+    v2_chosen = provider in ("", "hyperspeed") or hyper or v2.get("live")
+    from hyperclaw.model_policy import allowed_display
+    checks.append(_check("Install mode", True,
+                         "Hyper-deployed · allowed models: " + ", ".join(allowed_display())
+                         if hyper else "standard"))
+    checks.append(_check("LLM_PROVIDER", True, provider or "(not set: HyperSpeed V2 default)"))
+
+    if v2.get("present") and v2_chosen:
+        # HyperSpeed V2 is the default: a missing Anthropic (or other
+        # third-party) key is not a failure (spec §11).
+        checks.append(_check("Model provider", True, f"{v2['label']} ({v2['mode']})"))
+        checks.append(_check(
+            "Hyper access key", v2["key_set"],
+            "set (hidden)" if v2["key_set"] else
+            "Not set — run: hyperclaw provider hyper-key"))
+        checks.append(_check("HyperSpeed V2 endpoint", True, v2["base_url"]))
+        checks.append(_check(
+            "HyperSpeed V2 model", True,
+            v2["model"] + (" (placeholder pending adapter confirmation; "
+                           "override with HYPERSPEED_MODEL)" if v2["model_placeholder"] else "")))
+        own = [r for r in describe() if r["origin"] != "hyper"]
+        live_own = [r for r in own if r["live"]]
+        if hyper:
+            from hyperclaw.managed_config import provider_allowed
+            stray = [k for k, p in (("ANTHROPIC_API_KEY", "anthropic"),
+                                    ("OPENAI_API_KEY", "openai"), ("XAI_API_KEY", "xai"))
+                     if os.environ.get(k) and not provider_allowed(p)]
+            checks.append(_check(
+                "Other providers", not stray,
+                "only the models on this install's allowed list"
+                + (f"; ignored keys present: {', '.join(stray)}" if stray else ""),
+                warn=bool(stray)))
+        elif not live_own:
+            checks.append(_check("Your own providers", True, "none added (optional)"))
+        for r in live_own:
+            checks.append(_check(r["label"][:1].upper() + r["label"][1:], True,
+                                 f"configured · {r['model'] or '-'} · {r['mode']}"))
+    elif provider == "openai":
+        oai_key = os.environ.get("OPENAI_API_KEY", "")
+        checks.append(_check("Model provider", True, "your own provider (OpenAI)"))
+        checks.append(_check("OPENAI_API_KEY", bool(oai_key),
+                             "set (hidden)" if oai_key else "Not set — run: hyperclaw provider add openai"))
+    elif provider == "openai_compat":
+        oai_key = os.environ.get("OPENAI_API_KEY", "")
+        checks.append(_check(
+            "OPENAI_API_KEY",
+            bool(oai_key),
+            f"...{oai_key[-6:]}" if oai_key else "Not set — export OPENAI_API_KEY=...",
+        ))
+        oai_url = os.environ.get("OPENAI_BASE_URL", "")
+        checks.append(_check(
+            "OPENAI_BASE_URL",
+            bool(oai_url),
+            oai_url if oai_url else "Not set — export OPENAI_BASE_URL=http://host/v1",
+        ))
+        oai_model = os.environ.get("OPENAI_MODEL", "")
+        checks.append(_check("OPENAI_MODEL", True, oai_model or "(default)"))
+    elif provider == "bedrock":
+        region = os.environ.get("AWS_REGION", "") or os.environ.get("AWS_DEFAULT_REGION", "")
+        checks.append(_check(
+            "AWS_REGION",
+            bool(region),
+            region if region else "Not set — defaulting to us-east-1",
+            warn=not bool(region),
+        ))
+        bedrock_model = os.environ.get("BEDROCK_MODEL", "anthropic.claude-sonnet-5")
+        checks.append(_check("BEDROCK_MODEL", True, bedrock_model))
+    elif provider == "anthropic_compat":
+        anthropic_key = os.environ.get("ANTHROPIC_API_KEY", "")
+        checks.append(_check(
+            "ANTHROPIC_API_KEY",
+            bool(anthropic_key),
+            f"...{anthropic_key[-6:]}" if anthropic_key else "Not set",
+        ))
+        compat_url = os.environ.get("ANTHROPIC_BASE_URL", "")
+        checks.append(_check(
+            "ANTHROPIC_BASE_URL",
+            bool(compat_url),
+            compat_url if compat_url else "Not set — export ANTHROPIC_BASE_URL=http://host",
+        ))
+    else:
+        anthropic_key = os.environ.get("ANTHROPIC_API_KEY", "")
+        checks.append(_check("Model provider", True, "your own provider (Anthropic)"))
+        checks.append(_check(
+            "ANTHROPIC_API_KEY",
+            bool(anthropic_key),
+            f"sk-ant-...{anthropic_key[-6:]}" if anthropic_key else "Not set — export ANTHROPIC_API_KEY=...",
+        ))
+
+    db_url_env = os.environ.get("DATABASE_URL", "")
+    checks.append(_check(
+        "DATABASE_URL",
+        bool(db_url_env),
+        f"...{db_url_env[-30:]}" if db_url_env else "Not set — using config/hyperclaw.yaml fallback",
+        warn=not bool(db_url_env),
+    ))
+
+    chatjimmy_key = os.environ.get("CHATJIMMY_API_KEY", "")
+    checks.append(_check(
+        "CHATJIMMY_API_KEY",
+        bool(chatjimmy_key),
+        "Set" if chatjimmy_key else "Not set — ChatJimmy will be unavailable (optional)",
+        warn=not bool(chatjimmy_key),
+    ))
+
+    # ── Config files ──────────────────────────────────────────────────────────
+    config_files = [
+        "config/hyperclaw.yaml",
+        "config/agents.yaml",
+        "config/models.yaml",
+        "security/policies/default.yaml",
+    ]
+    for cf in config_files:
+        checks.append(_check(f"Config: {cf}", Path(cf).exists(),
+                            "Found" if Path(cf).exists() else f"Missing — run: hyperclaw init"))
+
+    # ── DB checks (async) ─────────────────────────────────────────────────────
+    if db_url_env:
+        loop = asyncio.new_event_loop()
+        try:
+            checks.append(loop.run_until_complete(_check_db(db_url_env)))
+            checks.append(loop.run_until_complete(_check_pgvector(db_url_env)))
+            checks.append(loop.run_until_complete(_check_migrations(db_url_env)))
+        finally:
+            loop.close()
+    else:
+        checks.append(_check("PostgreSQL connection", False,
+                            "Skipped — DATABASE_URL not set", warn=True))
+        checks.append(_check("pgvector extension", False,
+                            "Skipped — DATABASE_URL not set", warn=True))
+        checks.append(_check("DB migrations", False,
+                            "Skipped — DATABASE_URL not set", warn=True))
+
+    # ── Print results ─────────────────────────────────────────────────────────
+    table = Table(show_header=True, header_style="bold cyan", expand=True)
+    table.add_column("Check", style="bold")
+    table.add_column("Status", justify="center", width=4)
+    table.add_column("Detail", style="dim")
+
+    for c in checks:
+        table.add_row(c["label"], c["status"], c["detail"])
+
+    console.print(table)
+
+    failed = [c for c in checks if not c["ok"] and not c.get("warn")]
+    warned = [c for c in checks if not c["ok"] and c.get("warn")]
+    passed = [c for c in checks if c["ok"]]
+
+    console.print(
+        f"\n[green]{len(passed)} passed[/green]  "
+        f"[yellow]{len(warned)} warnings[/yellow]  "
+        f"[red]{len(failed)} failed[/red]"
+    )
+
+    if failed:
+        console.print("\n[red]Fix the failed checks above before running hyperclaw start.[/red]")
+        return 1
+
+    if not warned:
+        console.print("\n[bold green]✓ HyperClaw is healthy and ready to run.[/bold green]")
+    else:
+        console.print("\n[bold yellow]⚠ HyperClaw has warnings — review above before running tasks.[/bold yellow]")
+
+    return 0