hyperagents 1.2.3rc5.post3__py3-none-any.whl

core/hyperstate/schema.py

@@ -0,0 +1,160 @@
+"""
+HyperState Schema — Pydantic v2 data models for HyperClaw state management.
+"""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+# ── Enums ─────────────────────────────────────────────────────────────────────
+
+Domain = Literal["personal", "business", "scientific", "creative", "recursive"]
+
+TaskType = Literal[
+    "code", "research", "analysis", "synthesis",
+    "planning", "health", "finance", "scientific",
+    "routing", "classification", "quick_lookup",
+    "summarization", "draft", "triage", "status_check",
+]
+
+
+# ── Sub-models ─────────────────────────────────────────────────────────────────
+
+class Task(BaseModel):
+    goal: str
+    constraints: list[str] = Field(default_factory=list)
+    priority: int = Field(default=5, ge=0, le=10)
+    task_type: TaskType = "research"
+
+
+class Hypothesis(BaseModel):
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    statement: str
+    confidence: float = Field(default=0.5, ge=0.0, le=1.0)
+
+
+class ExperimentEntry(BaseModel):
+    method: str
+    model_used: str
+    result: str = ""
+    certified: bool = False
+    test_trace: str = ""
+    cost_usd: float = 0.0
+    latency_ms: float = 0.0
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class AgentScore(BaseModel):
+    attempts: int = 0
+    successes: int = 0
+    task_type: str = "general"
+
+    @property
+    def win_rate(self) -> float:
+        return self.successes / self.attempts if self.attempts > 0 else 0.0
+
+
+class ModelScore(BaseModel):
+    attempts: int = 0
+    successes: int = 0
+
+    @property
+    def win_rate(self) -> float:
+        return self.successes / self.attempts if self.attempts > 0 else 0.0
+
+
+class CertifiedMethod(BaseModel):
+    method_id: str
+    validated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    performance: dict[str, Any] = Field(default_factory=dict)
+    model_used: str = ""
+
+
+class RecursiveResearch(BaseModel):
+    active: bool = False
+    domains_monitored: list[str] = Field(default_factory=list)
+    last_sweep: datetime | None = None
+    discoveries_this_week: int = 0
+
+
+# ── HyperState ─────────────────────────────────────────────────────────────────
+
+class HyperState(BaseModel):
+    state_id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    domain: Domain = "business"
+    task: Task = Field(default_factory=lambda: Task(goal=""))
+    hypotheses: list[Hypothesis] = Field(default_factory=list)
+    experiment_log: list[ExperimentEntry] = Field(default_factory=list)
+    agent_scores: dict[str, AgentScore] = Field(default_factory=dict)
+    model_scores: dict[str, dict[str, ModelScore]] = Field(default_factory=dict)
+    certified_methods: list[CertifiedMethod] = Field(default_factory=list)
+    routing_weights: dict[str, float] = Field(default_factory=dict)
+    recursive_research: RecursiveResearch = Field(default_factory=RecursiveResearch)
+    state_version: int = 0
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    last_updated: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def _bump_version(self) -> None:
+        self.state_version += 1
+        self.last_updated = datetime.now(timezone.utc)
+
+    def certify_method(
+        self,
+        method_id: str,
+        test_trace: str,
+        result: str,
+        model_used: str,
+    ) -> CertifiedMethod:
+        """
+        Certify a method if test_trace and result are non-empty.
+        Raises CertificationError if validation fails.
+        """
+        # Import here to avoid circular at module level
+        from .certifier import CertificationError
+
+        if not test_trace or not test_trace.strip():
+            raise CertificationError(
+                f"Certification failed for '{method_id}': test_trace is empty. "
+                "A non-empty test trace is required for certification."
+            )
+        if not result or not result.strip():
+            raise CertificationError(
+                f"Certification failed for '{method_id}': result is empty. "
+                "A non-empty result is required for certification."
+            )
+
+        cm = CertifiedMethod(
+            method_id=method_id,
+            model_used=model_used,
+            performance={"test_trace_length": len(test_trace), "result_length": len(result)},
+        )
+        self.certified_methods.append(cm)
+        self._bump_version()
+        return cm
+
+    def get_best_model(self, task_type: str) -> str:
+        """
+        Return the model_id with the highest successes/attempts ratio for
+        the given task_type. Returns 'claude-sonnet-5' if no data exists.
+        """
+        best_model = "claude-sonnet-5"
+        best_rate = -1.0
+
+        for model_id, task_scores in self.model_scores.items():
+            score = task_scores.get(task_type)
+            if score is None:
+                continue
+            if score.attempts == 0:
+                continue
+            rate = score.successes / score.attempts
+            if rate > best_rate:
+                best_rate = rate
+                best_model = model_id
+
+        return best_model

core/hyperstate/state_manager.py

@@ -0,0 +1,103 @@
+"""
+StateManager — lifecycle management for HyperState objects.
+Wraps store operations with business logic.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+from uuid import UUID
+
+from .certifier import Certifier
+from .schema import (
+    Domain,
+    ExperimentEntry,
+    HyperState,
+    Task,
+    TaskType,
+)
+from .store import HyperStateStore
+
+
+class StateManager:
+    """
+    High-level API for creating, updating, and managing HyperState lifecycles.
+    Uses asyncpg pool internally via HyperStateStore.
+    """
+
+    def __init__(self, store: HyperStateStore) -> None:
+        self._store = store
+        self._certifier = Certifier()
+
+    async def create_state(
+        self,
+        goal: str,
+        domain: Domain,
+        task_type: TaskType,
+        constraints: Optional[list[str]] = None,
+    ) -> HyperState:
+        """Create and persist a new HyperState."""
+        state = HyperState(
+            domain=domain,
+            task=Task(
+                goal=goal,
+                task_type=task_type,
+                constraints=constraints or [],
+            ),
+        )
+        await self._store.save_state(state)
+        return state
+
+    async def update_state(
+        self,
+        state_id: UUID,
+        updates: dict[str, Any],
+    ) -> HyperState:
+        """Apply a dict of field updates to a HyperState and persist it."""
+        state = await self._store.load_state(state_id)
+        for key, value in updates.items():
+            if hasattr(state, key):
+                setattr(state, key, value)
+        state._bump_version()
+        await self._store.save_state(state)
+        return state
+
+    async def add_experiment(
+        self,
+        state_id: UUID,
+        entry: ExperimentEntry,
+    ) -> HyperState:
+        """Append an ExperimentEntry to a HyperState's experiment log."""
+        state = await self._store.load_state(state_id)
+        state.experiment_log.append(entry)
+        state._bump_version()
+        await self._store.save_state(state)
+        return state
+
+    async def certify_method(
+        self,
+        state_id: UUID,
+        method_id: str,
+        test_trace: str,
+        result: str,
+        model_used: str,
+    ) -> HyperState:
+        """
+        Certify a method on a HyperState. Validates via Certifier then
+        calls HyperState.certify_method() to record the CertifiedMethod.
+        Raises CertificationError if validation fails.
+        """
+        state = await self._store.load_state(state_id)
+        # Will raise CertificationError if validation fails
+        state.certify_method(
+            method_id=method_id,
+            test_trace=test_trace,
+            result=result,
+            model_used=model_used,
+        )
+        await self._store.save_state(state)
+        return state
+
+    async def archive_state(self, state_id: UUID) -> None:
+        """Archive a HyperState (soft delete)."""
+        await self._store.archive_state(state_id)

core/hyperstate/store.py

@@ -0,0 +1,163 @@
+"""
+HyperState Store — asyncpg-backed persistence for HyperState objects.
+Connection string loaded from DATABASE_URL env var or config/hyperclaw.yaml.
+"""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from typing import Optional
+from uuid import UUID
+
+import asyncpg
+import yaml
+
+from .schema import HyperState
+
+
+def _load_db_url() -> str:
+    """Load DATABASE_URL from env or config/hyperclaw.yaml."""
+    url = os.environ.get("DATABASE_URL")
+    if url:
+        return url
+    config_path = os.path.join(os.path.dirname(__file__), "../../../config/hyperclaw.yaml")
+    config_path = os.path.normpath(config_path)
+    if os.path.exists(config_path):
+        with open(config_path) as f:
+            cfg = yaml.safe_load(f) or {}
+        db_url = cfg.get("database", {}).get("url")
+        if db_url:
+            return db_url
+    return "postgresql://localhost/hyperclaw"
+
+
+class HyperStateStore:
+    """
+    Async persistence layer for HyperState. Uses asyncpg + PostgreSQL.
+    pgvector extension assumed available for future vector fields.
+    """
+
+    def __init__(self, db_url: str | None = None) -> None:
+        self._db_url = db_url or _load_db_url()
+        self._pool: asyncpg.Pool | None = None
+
+    async def connect(self) -> None:
+        self._pool = await asyncpg.create_pool(self._db_url, min_size=1, max_size=10)
+
+    async def close(self) -> None:
+        if self._pool:
+            await self._pool.close()
+
+    async def create_tables(self) -> None:
+        """Create hyperstates and hyperstate_history tables if they don't exist."""
+        assert self._pool, "Call connect() first"
+        async with self._pool.acquire() as conn:
+            await conn.execute("""
+                CREATE TABLE IF NOT EXISTS hyperstates (
+                    state_id        UUID PRIMARY KEY,
+                    domain          TEXT NOT NULL,
+                    data            JSONB NOT NULL,
+                    state_version   INTEGER NOT NULL DEFAULT 0,
+                    created_at      TIMESTAMPTZ NOT NULL,
+                    updated_at      TIMESTAMPTZ NOT NULL,
+                    archived_at     TIMESTAMPTZ
+                );
+
+                CREATE TABLE IF NOT EXISTS hyperstate_history (
+                    id              BIGSERIAL PRIMARY KEY,
+                    state_id        UUID NOT NULL REFERENCES hyperstates(state_id),
+                    state_version   INTEGER NOT NULL,
+                    data            JSONB NOT NULL,
+                    recorded_at     TIMESTAMPTZ NOT NULL DEFAULT NOW()
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_hyperstates_domain
+                    ON hyperstates(domain);
+                CREATE INDEX IF NOT EXISTS idx_hyperstate_history_state_id
+                    ON hyperstate_history(state_id);
+            """)
+
+    async def save_state(self, state: HyperState) -> None:
+        """Upsert a HyperState by state_id. Writes a history snapshot on each save."""
+        assert self._pool, "Call connect() first"
+        data = state.model_dump_json()
+        async with self._pool.acquire() as conn:
+            async with conn.transaction():
+                await conn.execute("""
+                    INSERT INTO hyperstates (state_id, domain, data, state_version, created_at, updated_at)
+                    VALUES ($1, $2, $3::jsonb, $4, $5, $6)
+                    ON CONFLICT (state_id) DO UPDATE SET
+                        domain        = EXCLUDED.domain,
+                        data            = EXCLUDED.data,
+                        state_version = EXCLUDED.state_version,
+                        updated_at    = EXCLUDED.updated_at
+                """,
+                    state.state_id,
+                    state.domain,
+                    data,
+                    state.state_version,
+                    state.created_at,
+                    state.last_updated,
+                )
+                await conn.execute("""
+                    INSERT INTO hyperstate_history (state_id, state_version, snapshot)
+                    VALUES ($1, $2, $3::jsonb)
+                """, state.state_id, state.state_version, data)
+
+    async def load_state(self, state_id: UUID) -> HyperState:
+        """Load a HyperState by state_id. Raises KeyError if not found."""
+        assert self._pool, "Call connect() first"
+        async with self._pool.acquire() as conn:
+            row = await conn.fetchrow(
+                "SELECT data FROM hyperstates WHERE state_id = $1", state_id
+            )
+        if row is None:
+            raise KeyError(f"HyperState {state_id} not found")
+        return HyperState.model_validate_json(row["data"])
+
+    async def list_states(
+        self,
+        domain: Optional[str] = None,
+        limit: int = 50,
+    ) -> list[HyperState]:
+        """List active (non-archived) HyperStates, optionally filtered by domain."""
+        assert self._pool, "Call connect() first"
+        if domain:
+            rows = await self._pool.fetch(
+                "SELECT data FROM hyperstates WHERE domain = $1 AND archived_at IS NULL "
+                "ORDER BY updated_at DESC LIMIT $2",
+                domain, limit,
+            )
+        else:
+            rows = await self._pool.fetch(
+                "SELECT data FROM hyperstates WHERE archived_at IS NULL "
+                "ORDER BY updated_at DESC LIMIT $1",
+                limit,
+            )
+        return [HyperState.model_validate_json(r["data"]) for r in rows]
+
+    async def archive_state(self, state_id: UUID) -> None:
+        """Set archived_at timestamp on a HyperState."""
+        assert self._pool, "Call connect() first"
+        await self._pool.execute(
+            "UPDATE hyperstates SET archived_at = $1 WHERE state_id = $2",
+            datetime.now(timezone.utc), state_id,
+        )
+
+    async def get_state_history(self, state_id: UUID) -> list[dict]:
+        """Return all version snapshots for a HyperState."""
+        assert self._pool, "Call connect() first"
+        rows = await self._pool.fetch(
+            "SELECT state_version, snapshot, created_at as recorded_at FROM hyperstate_history "
+            "WHERE state_id = $1 ORDER BY state_version ASC",
+            state_id,
+        )
+        return [
+            {
+                "state_version": r["state_version"],
+                "recorded_at": r["recorded_at"].isoformat(),
+                "state_data": json.loads(r["snapshot"]),
+            }
+            for r in rows
+        ]

core/providers/__init__.py

@@ -0,0 +1,121 @@
+"""
+HyperClaw Provider Abstraction Layer.
+Unified interfaces for AI/LLM, voice, image, search, and other providers.
+"""
+
+from .llm import (
+    LLMProvider,
+    AnthropicProvider,
+    OpenAIProvider,
+    GeminiProvider,
+    MistralProvider,
+    GroqProvider,
+    XAIProvider,
+    BedrockProvider,
+    OpenRouterProvider,
+    TogetherProvider,
+    PerplexityProvider,
+    DeepSeekProvider,
+    QwenProvider,
+    CerebrasProvider,
+    HuggingFaceProvider,
+    OllamaProvider,
+    VLLMProvider,
+    LiteLLMProvider,
+    get_llm_provider,
+)
+
+from .voice import (
+    VoiceProvider,
+    STTProvider,
+    TTSProvider,
+    WhisperProvider,
+    DeepgramProvider,
+    AssemblyAIProvider,
+    ElevenLabsProvider,
+    GoogleTTSProvider,
+    OpenAITTSProvider,
+)
+
+from .image import (
+    ImageProvider,
+    DALLEProvider,
+    StabilityProvider,
+    MidjourneyProvider,
+    ReplicateProvider,
+)
+
+from .search import (
+    SearchProvider,
+    GoogleSearchProvider,
+    BingSearchProvider,
+    DuckDuckGoProvider,
+    SerpAPIProvider,
+    PerplexitySearchProvider,
+    ArxivProvider,
+    WikipediaProvider,
+)
+
+from .embeddings import (
+    EmbeddingProvider,
+    OpenAIEmbedder,
+    VoyageEmbedder,
+    GeminiEmbedder,
+    MistralEmbedder,
+    CohereEmbedder,
+)
+
+__all__ = [
+    # LLM
+    "LLMProvider",
+    "AnthropicProvider",
+    "OpenAIProvider",
+    "GeminiProvider",
+    "MistralProvider",
+    "GroqProvider",
+    "XAIProvider",
+    "BedrockProvider",
+    "OpenRouterProvider",
+    "TogetherProvider",
+    "PerplexityProvider",
+    "DeepSeekProvider",
+    "QwenProvider",
+    "CerebrasProvider",
+    "HuggingFaceProvider",
+    "OllamaProvider",
+    "VLLMProvider",
+    "LiteLLMProvider",
+    "get_llm_provider",
+    # Voice
+    "VoiceProvider",
+    "STTProvider",
+    "TTSProvider",
+    "WhisperProvider",
+    "DeepgramProvider",
+    "AssemblyAIProvider",
+    "ElevenLabsProvider",
+    "GoogleTTSProvider",
+    "OpenAITTSProvider",
+    # Image
+    "ImageProvider",
+    "DALLEProvider",
+    "StabilityProvider",
+    "MidjourneyProvider",
+    "ReplicateProvider",
+    # Search
+    "SearchProvider",
+    "GoogleSearchProvider",
+    "BingSearchProvider",
+    "DuckDuckGoProvider",
+    "SerpAPIProvider",
+    "PerplexitySearchProvider",
+    "ArxivProvider",
+    "WikipediaProvider",
+    # Embeddings
+    "EmbeddingProvider",
+    "OpenAIEmbedder",
+    "VoyageEmbedder",
+    "GeminiEmbedder",
+    "MistralEmbedder",
+    "CohereEmbedder",
+]