hypermind 0.11.0__py3-none-any.whl

hypermind/simlab/tool_registry.py

@@ -0,0 +1,568 @@
+"""Tool registry — catalog of available tools + namespace activation records.
+
+Two layers:
+  TOOL_CATALOG   — global, in-memory, immutable Python dict of all known tools.
+  ActivatedTool  — per-namespace activation records persisted to disk.
+
+Activation lifecycle:  (not activated) → pending → verified → active
+                                                  ↑ (credentials updated resets to pending)
+                       active → disabled  (soft-delete; record preserved)
+
+# SECURITY NOTE
+# Credentials are base64-encoded at rest in ~/.hypermind/tools/activated.json.
+# Base64 is encoding, not encryption.  The file is written with mode 0o600
+# (owner read/write only) to limit exposure on shared systems, but this is
+# NOT a substitute for proper secret management.  For production deployments
+# replace encode_credential / decode_credential with calls to your secret
+# manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, etc.).
+
+Public API:
+    ToolDef              — catalog entry dataclass
+    ActivatedTool        — namespace activation record dataclass
+    TOOL_CATALOG         — dict[slug → ToolDef]
+    list_catalog()       — list[ToolDef], sorted by category then name
+    get_tool_def(slug)   — ToolDef | None
+    tools_dir()          — Path to ~/.hypermind/tools/
+    load_activated_tools() — list[ActivatedTool] from disk
+    get_activated_tool(slug) — ActivatedTool | None
+    save_activated_tool(t)   — atomic write
+    delete_activated_tool(slug) — remove record
+    list_active_tool_slugs() — list[str] where status == "active"
+    encode_credential(v) — base64 encode
+    decode_credential(v) — base64 decode
+    mask_credential(v)   — first2…last2 of decoded value
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import threading
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .registry import _write_json_atomic, home
+
+# Module-level lock — guards all read-modify-write operations on activated.json
+_registry_lock = threading.Lock()
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ToolDef:
+    slug: str
+    name: str
+    description: str
+    category: str  # "knowledge" | "action" | "hybrid"
+    auth_type: str  # "api_key" | "none"
+    parameters_schema: dict[str, Any]
+    handler_module: str  # dotted import path
+    docs_url: str
+    icon: str  # emoji
+    version: str
+    author: str
+    credentials_schema: dict[str, Any]  # {field: {type, label, required, placeholder?}}
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ActivatedTool:
+    tool_slug: str
+    status: str  # "pending" | "verified" | "active" | "disabled"
+    credentials: dict[str, str] = field(default_factory=dict)  # base64-encoded values
+    label: str = ""
+    activated_at_ms: int | None = None
+    last_tested_ms: int | None = None
+    error_msg: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def to_api_dict(self) -> dict[str, Any]:
+        """Return dict safe for HTTP responses — credentials masked, never raw."""
+        d = self.to_dict()
+        d["credentials_masked"] = {k: mask_credential(v) for k, v in self.credentials.items()}
+        del d["credentials"]
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ActivatedTool:
+        known = {f.name for f in cls.__dataclass_fields__.values()}  # type: ignore[attr-defined]
+        clean = {k: v for k, v in d.items() if k in known}
+        return cls(**clean)
+
+
+# ---------------------------------------------------------------------------
+# Credential helpers
+# ---------------------------------------------------------------------------
+
+
+def encode_credential(value: str) -> str:
+    return base64.b64encode(value.encode()).decode()
+
+
+def decode_credential(encoded: str) -> str:
+    try:
+        return base64.b64decode(encoded.encode()).decode()
+    except Exception:
+        return ""
+
+
+def mask_credential(encoded: str) -> str:
+    decoded = decode_credential(encoded)
+    if len(decoded) < 8:
+        return "*" * len(decoded)
+    return decoded[:2] + "****" + decoded[-2:]
+
+
+# ---------------------------------------------------------------------------
+# Built-in tool catalog
+# ---------------------------------------------------------------------------
+
+
+def _web_search_schema() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "Search query"},
+            "max_results": {"type": "integer", "default": 5},
+        },
+        "required": ["query"],
+    }
+
+
+def _doc_id_schema() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {
+            "doc_id": {"type": "string", "description": "Document identifier"},
+        },
+        "required": ["doc_id"],
+    }
+
+
+def _kb_query_schema() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "Semantic search query"},
+            "top_k": {"type": "integer", "default": 5},
+        },
+        "required": ["query"],
+    }
+
+
+def _finance_schema() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {
+            "symbol": {"type": "string", "description": "Stock ticker symbol e.g. AAPL"},
+            "function": {"type": "string", "default": "GLOBAL_QUOTE"},
+        },
+        "required": ["symbol"],
+    }
+
+
+def _news_schema() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "News search query or topic"},
+            "page_size": {"type": "integer", "default": 5},
+        },
+        "required": ["query"],
+    }
+
+
+def _api_key_cred() -> dict[str, Any]:
+    return {
+        "api_key": {
+            "type": "password",
+            "label": "API Key",
+            "required": True,
+            "placeholder": "sk-...",
+        }
+    }
+
+
+def _api_key_and_url_cred(url_label: str = "API URL", url_required: bool = False) -> dict[str, Any]:
+    return {
+        "api_key": {
+            "type": "password",
+            "label": "API Key",
+            "required": True,
+            "placeholder": "...",
+        },
+        "base_url": {
+            "type": "url",
+            "label": url_label,
+            "required": url_required,
+            "placeholder": "https://...",
+        },
+    }
+
+
+TOOL_CATALOG: dict[str, ToolDef] = {
+    # ---- Web search ----------------------------------------------------------
+    "brave_web_search": ToolDef(
+        slug="brave_web_search",
+        name="Brave Web Search",
+        description="Search the public web via Brave's privacy-preserving search API. Returns titles, URLs, and snippets.",
+        category="knowledge",
+        auth_type="api_key",
+        parameters_schema=_web_search_schema(),
+        handler_module="hypermind.simlab.tool_handlers.brave",
+        docs_url="https://api.search.brave.com/app/documentation/web-search",
+        icon="🦁",
+        version="1.0",
+        author="hypermind",
+        credentials_schema=_api_key_cred(),
+    ),
+    "tavily_search": ToolDef(
+        slug="tavily_search",
+        name="Tavily AI Search",
+        description="AI-optimised web search designed for LLM agents. Returns cleaned, answer-ready results.",
+        category="knowledge",
+        auth_type="api_key",
+        parameters_schema=_web_search_schema(),
+        handler_module="hypermind.simlab.tool_handlers.tavily",
+        docs_url="https://docs.tavily.com/docs/tavily-api/rest_api",
+        icon="🔍",
+        version="1.0",
+        author="hypermind",
+        credentials_schema=_api_key_cred(),
+    ),
+    "serper_web_search": ToolDef(
+        slug="serper_web_search",
+        name="Serper Web Search",
+        description="Google search results via the Serper API. Affordable, fast, broad coverage.",
+        category="knowledge",
+        auth_type="api_key",
+        parameters_schema=_web_search_schema(),
+        handler_module="hypermind.simlab.tool_handlers.serper",
+        docs_url="https://serper.dev/",
+        icon="🌐",
+        version="1.0",
+        author="hypermind",
+        credentials_schema=_api_key_cred(),
+    ),
+    # ---- Finance & news ------------------------------------------------------
+    "alpha_vantage": ToolDef(
+        slug="alpha_vantage",
+        name="Alpha Vantage",
+        description="Real-time and historical financial data: equities, forex, crypto, and macroeconomic indicators.",
+        category="knowledge",
+        auth_type="api_key",
+        parameters_schema=_finance_schema(),
+        handler_module="hypermind.simlab.tool_handlers.alpha_vantage",
+        docs_url="https://www.alphavantage.co/documentation/",
+        icon="📈",
+        version="1.0",
+        author="hypermind",
+        credentials_schema=_api_key_cred(),
+    ),
+    "newsapi_headlines": ToolDef(
+        slug="newsapi_headlines",
+        name="NewsAPI Headlines",
+        description="Top headlines and article search from 80,000+ news sources worldwide.",
+        category="knowledge",
+        auth_type="api_key",
+        parameters_schema=_news_schema(),
+        handler_module="hypermind.simlab.tool_handlers.newsapi",
+        docs_url="https://newsapi.org/docs",
+        icon="📰",
+        version="1.0",
+        author="hypermind",
+        credentials_schema=_api_key_cred(),
+    ),
+    "yahoo_finance": ToolDef(
+        slug="yahoo_finance",
+        name="Yahoo Finance",
+        description="Free financial data via Yahoo Finance — stock quotes, price history, company info. No API key required.",
+        category="knowledge",
+        auth_type="none",
+        parameters_schema={
+            "type": "object",
+            "properties": {
+                "symbol": {"type": "string", "description": "Stock ticker e.g. AAPL"},
+                "period": {
+                    "type": "string",
+                    "default": "1mo",
+                    "description": "e.g. 1d, 5d, 1mo, 3mo, 1y",
+                },
+            },
+            "required": ["symbol"],
+        },
+        handler_module="hypermind.simlab.tool_handlers.yahoo_finance",
+        docs_url="https://finance.yahoo.com/",
+        icon="💹",
+        version="1.0",
+        author="hypermind",
+        credentials_schema={},
+    ),
+    # ---- Reference -----------------------------------------------------------
+    "wikipedia_search": ToolDef(
+        slug="wikipedia_search",
+        name="Wikipedia Search",
+        description="Search and retrieve Wikipedia article summaries. No API key required.",
+        category="knowledge",
+        auth_type="none",
+        parameters_schema=_web_search_schema(),
+        handler_module="hypermind.simlab.tool_handlers.wikipedia",
+        docs_url="https://en.wikipedia.org/api/rest_v1/",
+        icon="📚",
+        version="1.0",
+        author="hypermind",
+        credentials_schema={},
+    ),
+    "wolfram_alpha": ToolDef(
+        slug="wolfram_alpha",
+        name="Wolfram Alpha",
+        description="Computational knowledge engine — maths, science, statistics, unit conversions, factual queries.",
+        category="knowledge",
+        auth_type="api_key",
+        parameters_schema={
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Natural language or mathematical query",
+                },
+            },
+            "required": ["query"],
+        },
+        handler_module="hypermind.simlab.tool_handlers.wolfram",
+        docs_url="https://products.wolframalpha.com/api/documentation/",
+        icon="🧮",
+        version="1.0",
+        author="hypermind",
+        credentials_schema=_api_key_cred(),
+    ),
+    "openweathermap": ToolDef(
+        slug="openweathermap",
+        name="OpenWeatherMap",
+        description="Current weather and 5-day forecast for any city or coordinates worldwide.",
+        category="knowledge",
+        auth_type="api_key",
+        parameters_schema={
+            "type": "object",
+            "properties": {
+                "location": {"type": "string", "description": "City name or 'lat,lon'"},
+                "units": {
+                    "type": "string",
+                    "default": "metric",
+                    "description": "metric | imperial | standard",
+                },
+            },
+            "required": ["location"],
+        },
+        handler_module="hypermind.simlab.tool_handlers.openweather",
+        docs_url="https://openweathermap.org/api",
+        icon="🌤",
+        version="1.0",
+        author="hypermind",
+        credentials_schema=_api_key_cred(),
+    ),
+    # ---- Vector databases ----------------------------------------------------
+    "pinecone_search": ToolDef(
+        slug="pinecone_search",
+        name="Pinecone Vector Search",
+        description="Semantic search against a Pinecone index. Requires a configured index and embedding model.",
+        category="knowledge",
+        auth_type="api_key",
+        parameters_schema=_kb_query_schema(),
+        handler_module="hypermind.simlab.tool_handlers.pinecone",
+        docs_url="https://docs.pinecone.io/",
+        icon="🌲",
+        version="1.0",
+        author="hypermind",
+        credentials_schema={
+            "api_key": {
+                "type": "password",
+                "label": "API Key",
+                "required": True,
+                "placeholder": "",
+            },
+            "index_name": {
+                "type": "string",
+                "label": "Index Name",
+                "required": True,
+                "placeholder": "my-index",
+            },
+            "environment": {
+                "type": "string",
+                "label": "Environment",
+                "required": False,
+                "placeholder": "us-east-1-aws",
+            },
+        },
+    ),
+    "qdrant_search": ToolDef(
+        slug="qdrant_search",
+        name="Qdrant Vector Search",
+        description="Semantic search against a Qdrant collection. Self-hosted or Qdrant Cloud.",
+        category="knowledge",
+        auth_type="api_key",
+        parameters_schema=_kb_query_schema(),
+        handler_module="hypermind.simlab.tool_handlers.qdrant",
+        docs_url="https://qdrant.tech/documentation/",
+        icon="🔷",
+        version="1.0",
+        author="hypermind",
+        credentials_schema={
+            "api_key": {
+                "type": "password",
+                "label": "API Key",
+                "required": False,
+                "placeholder": "(leave blank for local)",
+            },
+            "base_url": {
+                "type": "url",
+                "label": "Qdrant URL",
+                "required": True,
+                "placeholder": "http://localhost:6333",
+            },
+            "collection": {
+                "type": "string",
+                "label": "Collection Name",
+                "required": True,
+                "placeholder": "my-collection",
+            },
+        },
+    ),
+    "weaviate_search": ToolDef(
+        slug="weaviate_search",
+        name="Weaviate Semantic Search",
+        description="Semantic search against a Weaviate schema class. Supports hybrid BM25+vector search.",
+        category="knowledge",
+        auth_type="api_key",
+        parameters_schema=_kb_query_schema(),
+        handler_module="hypermind.simlab.tool_handlers.weaviate",
+        docs_url="https://weaviate.io/developers/weaviate",
+        icon="🕸",
+        version="1.0",
+        author="hypermind",
+        credentials_schema={
+            "api_key": {
+                "type": "password",
+                "label": "API Key",
+                "required": False,
+                "placeholder": "(leave blank for local)",
+            },
+            "base_url": {
+                "type": "url",
+                "label": "Weaviate URL",
+                "required": True,
+                "placeholder": "http://localhost:8080",
+            },
+            "class_name": {
+                "type": "string",
+                "label": "Class Name",
+                "required": True,
+                "placeholder": "Document",
+            },
+        },
+    ),
+    # ---- Built-in stubs (backwards-compat) -----------------------------------
+    "retrieve_document": ToolDef(
+        slug="retrieve_document",
+        name="Document Retrieval",
+        description="Retrieve a document by ID from a configured store. Built-in stub — override the handler to connect a real backend.",
+        category="knowledge",
+        auth_type="none",
+        parameters_schema=_doc_id_schema(),
+        handler_module="hypermind.simlab.tool_handlers.retrieve_document",
+        docs_url="",
+        icon="📄",
+        version="1.0",
+        author="hypermind",
+        credentials_schema={},
+    ),
+    "query_knowledge_base": ToolDef(
+        slug="query_knowledge_base",
+        name="HyperMind Knowledge Base",
+        description="Vector-search the HyperMind federation knowledge base for relevant sealed claims.",
+        category="knowledge",
+        auth_type="none",
+        parameters_schema=_kb_query_schema(),
+        handler_module="hypermind.simlab.tool_handlers.query_knowledge_base",
+        docs_url="",
+        icon="🧠",
+        version="1.0",
+        author="hypermind",
+        credentials_schema={},
+    ),
+}
+
+
+# ---------------------------------------------------------------------------
+# Catalog accessors
+# ---------------------------------------------------------------------------
+
+
+def list_catalog() -> list[ToolDef]:
+    return sorted(TOOL_CATALOG.values(), key=lambda t: (t.category, t.name))
+
+
+def get_tool_def(slug: str) -> ToolDef | None:
+    return TOOL_CATALOG.get(slug)
+
+
+# ---------------------------------------------------------------------------
+# Disk storage
+# ---------------------------------------------------------------------------
+
+
+def tools_dir() -> Path:
+    d = home() / "tools"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _activated_path() -> Path:
+    return tools_dir() / "activated.json"
+
+
+def load_activated_tools() -> list[ActivatedTool]:
+    p = _activated_path()
+    if not p.exists():
+        return []
+    try:
+        data = json.loads(p.read_text())
+        return [ActivatedTool.from_dict(d) for d in data]
+    except Exception:
+        return []
+
+
+def get_activated_tool(slug: str) -> ActivatedTool | None:
+    for t in load_activated_tools():
+        if t.tool_slug == slug:
+            return t
+    return None
+
+
+def save_activated_tool(t: ActivatedTool) -> None:
+    with _registry_lock:
+        tools = load_activated_tools()
+        tools = [x for x in tools if x.tool_slug != t.tool_slug]
+        tools.append(t)
+        path = _activated_path()
+        _write_json_atomic(path, [x.to_dict() for x in tools], mode=0o600)
+
+
+def delete_activated_tool(slug: str) -> None:
+    with _registry_lock:
+        tools = [t for t in load_activated_tools() if t.tool_slug != slug]
+        path = _activated_path()
+        _write_json_atomic(path, [t.to_dict() for t in tools], mode=0o600)
+
+
+def list_active_tool_slugs() -> list[str]:
+    return [t.tool_slug for t in load_activated_tools() if t.status == "active"]