halyn 0.2.0__py3-none-any.whl

halyn/intent.py

@@ -0,0 +1,240 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Intent Chain — Structured provenance for every executed action.
+
+Every action has a chain:
+  HUMAN REQUEST → AI REASONING → PLAN → ACTION → RESULT
+
+Structured provenance with persistent storage.
+
+
+
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger("halyn.intent")
+
+
+@dataclass(slots=True)
+class IntentStep:
+    """One step in the intent chain."""
+    step_type: str       # "request", "reasoning", "plan", "action", "result", "shield_check"
+    content: str         # Human-readable description
+    timestamp: float = field(default_factory=time.time)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "step_type": self.step_type,
+            "content": self.content,
+            "timestamp": self.timestamp,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass(slots=True)
+class IntentChain:
+    """Complete chain for one action — from human request to result."""
+    chain_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    user_id: str = ""
+    llm_model: str = ""
+    node: str = ""
+    domain: str = ""
+    autonomy_level: int = -1
+    steps: list[IntentStep] = field(default_factory=list)
+    created_at: float = field(default_factory=time.time)
+    completed_at: float = 0.0
+    status: str = "in_progress"  # in_progress, completed, failed, blocked
+
+    def add(self, step_type: str, content: str, **metadata: Any) -> IntentStep:
+        step = IntentStep(step_type=step_type, content=content, metadata=metadata)
+        self.steps.append(step)
+        return step
+
+    def request(self, content: str, **meta: Any) -> IntentStep:
+        return self.add("request", content, **meta)
+
+    def reasoning(self, content: str, **meta: Any) -> IntentStep:
+        return self.add("reasoning", content, **meta)
+
+    def plan(self, content: str, **meta: Any) -> IntentStep:
+        return self.add("plan", content, **meta)
+
+    def shield_check(self, content: str, passed: bool = True, **meta: Any) -> IntentStep:
+        return self.add("shield_check", content, passed=passed, **meta)
+
+    def action(self, content: str, tool: str = "", **meta: Any) -> IntentStep:
+        return self.add("action", content, tool=tool, **meta)
+
+    def result(self, content: str, success: bool = True, **meta: Any) -> IntentStep:
+        self.completed_at = time.time()
+        self.status = "completed" if success else "failed"
+        return self.add("result", content, success=success, **meta)
+
+    def blocked(self, content: str, **meta: Any) -> IntentStep:
+        self.completed_at = time.time()
+        self.status = "blocked"
+        return self.add("blocked", content, **meta)
+
+    @property
+    def duration_ms(self) -> float:
+        if self.completed_at:
+            return (self.completed_at - self.created_at) * 1000
+        return (time.time() - self.created_at) * 1000
+
+    def summary(self) -> str:
+        """One-line summary for logs."""
+        req = next((s.content for s in self.steps if s.step_type == "request"), "?")
+        res = next((s.content for s in reversed(self.steps) if s.step_type == "result"), "?")
+        return f"[{self.status}] {req[:60]} → {res[:60]}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "chain_id": self.chain_id,
+            "user_id": self.user_id,
+            "llm_model": self.llm_model,
+            "node": self.node,
+            "domain": self.domain,
+            "autonomy_level": self.autonomy_level,
+            "steps": [s.to_dict() for s in self.steps],
+            "created_at": self.created_at,
+            "completed_at": self.completed_at,
+            "status": self.status,
+            "duration_ms": round(self.duration_ms, 2),
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, default=str)
+
+    def to_readable(self) -> str:
+        """Human-readable chain for display."""
+        lines = [
+            f"Intent Chain: {self.chain_id}",
+            f"  Status: {self.status} ({self.duration_ms:.0f}ms)",
+            f"  Node: {self.node}",
+            f"  Domain: {self.domain} (level {self.autonomy_level})",
+            f"  LLM: {self.llm_model}",
+            f"  User: {self.user_id}",
+            "",
+        ]
+        for i, step in enumerate(self.steps):
+            icon = {
+                "request": "📋", "reasoning": "🧠", "plan": "📝",
+                "shield_check": "🛡", "action": "⚡", "result": "✅",
+                "blocked": "🚫",
+            }.get(step.step_type, "•")
+            lines.append(f"  {icon} [{step.step_type}] {step.content}")
+            if step.metadata:
+                for k, v in step.metadata.items():
+                    lines.append(f"      {k}: {v}")
+        return "\n".join(lines)
+
+
+_CHAIN_SCHEMA = """
+CREATE TABLE IF NOT EXISTS intent_chains (
+    chain_id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL DEFAULT '',
+    llm_model TEXT NOT NULL DEFAULT '',
+    node TEXT NOT NULL DEFAULT '',
+    domain TEXT NOT NULL DEFAULT '',
+    autonomy_level INTEGER NOT NULL DEFAULT -1,
+    steps TEXT NOT NULL DEFAULT '[]',
+    created_at REAL NOT NULL,
+    completed_at REAL NOT NULL DEFAULT 0,
+    status TEXT NOT NULL DEFAULT 'in_progress'
+);
+CREATE INDEX IF NOT EXISTS idx_intent_node ON intent_chains(node);
+CREATE INDEX IF NOT EXISTS idx_intent_status ON intent_chains(status);
+CREATE INDEX IF NOT EXISTS idx_intent_created ON intent_chains(created_at);
+"""
+
+
+class IntentStore:
+    """Persistent storage for intent chains."""
+
+    def __init__(self, db_path: str = "") -> None:
+        if not db_path:
+            data_dir = Path.home() / ".halyn"
+            data_dir.mkdir(parents=True, exist_ok=True)
+            db_path = str(data_dir / "intent.db")
+        self._lock = threading.Lock()
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.executescript(_CHAIN_SCHEMA)
+        self._conn.commit()
+
+    def save(self, chain: IntentChain) -> None:
+        with self._lock:
+            self._conn.execute(
+                "INSERT OR REPLACE INTO intent_chains "
+                "(chain_id, user_id, llm_model, node, domain, autonomy_level, "
+                "steps, created_at, completed_at, status) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (chain.chain_id, chain.user_id, chain.llm_model,
+                 chain.node, chain.domain, chain.autonomy_level,
+                 json.dumps([s.to_dict() for s in chain.steps], default=str),
+                 chain.created_at, chain.completed_at, chain.status),
+            )
+            self._conn.commit()
+
+    def get(self, chain_id: str) -> IntentChain | None:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT * FROM intent_chains WHERE chain_id = ?", (chain_id,)
+            ).fetchone()
+        if not row:
+            return None
+        return self._row_to_chain(row)
+
+    def query(self, node: str = "", status: str = "", limit: int = 50) -> list[IntentChain]:
+        conditions, params = [], []
+        if node:
+            conditions.append("node LIKE ?")
+            params.append(f"%{node}%")
+        if status:
+            conditions.append("status = ?")
+            params.append(status)
+        where = " AND ".join(conditions) if conditions else "1=1"
+        params.append(limit)
+        with self._lock:
+            rows = self._conn.execute(
+                f"SELECT * FROM intent_chains WHERE {where} ORDER BY created_at DESC LIMIT ?",
+                params,
+            ).fetchall()
+        return [self._row_to_chain(r) for r in rows]
+
+    def export_jsonl(self, path: str) -> int:
+        chains = self.query(limit=100_000)
+        with open(path, "w") as f:
+            for c in reversed(chains):
+                f.write(c.to_json() + "\n")
+        return len(chains)
+
+    def _row_to_chain(self, row: tuple) -> IntentChain:
+        steps_data = json.loads(row[6]) if row[6] else []
+        steps = [IntentStep(
+            step_type=s["step_type"], content=s["content"],
+            timestamp=s.get("timestamp", 0),
+            metadata=s.get("metadata", {}),
+        ) for s in steps_data]
+        return IntentChain(
+            chain_id=row[0], user_id=row[1], llm_model=row[2],
+            node=row[3], domain=row[4], autonomy_level=row[5],
+            steps=steps, created_at=row[7], completed_at=row[8], status=row[9],
+        )
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()

halyn/llm.py

@@ -0,0 +1,178 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+LLM Connector — Plug any brain into Jarvis.
+
+Supports: Claude API, OpenAI API, Ollama (local), HuggingFace (local),
+          vLLM (self-hosted), any OpenAI-compatible endpoint.
+
+The LLM is NOT in the control plane. It connects FROM OUTSIDE via MCP.
+This module is for the REVERSE: when Jarvis needs to ASK the LLM
+(e.g. for autonomous reasoning, incident analysis, summarization).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from abc import ABC, abstractmethod
+from typing import Any
+
+log = logging.getLogger("jarvis.llm")
+
+
+class LLMConnector(ABC):
+    """Base class for LLM connections."""
+
+    @abstractmethod
+    async def complete(self, prompt: str, system: str = "", max_tokens: int = 1000) -> str:
+        """Send prompt, get response."""
+
+    @abstractmethod
+    async def is_available(self) -> bool:
+        """Check if LLM is reachable."""
+
+
+class ClaudeConnector(LLMConnector):
+    """Anthropic Claude API."""
+
+    def __init__(self, api_key: str = "", model: str = "claude-sonnet-4-20250514") -> None:
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY", "")
+        self.model = model
+        self.endpoint = "https://api.anthropic.com/v1/messages"
+
+    async def complete(self, prompt: str, system: str = "", max_tokens: int = 1000) -> str:
+        import aiohttp
+        headers = {
+            "x-api-key": self.api_key,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+        }
+        body: dict[str, Any] = {
+            "model": self.model,
+            "max_tokens": max_tokens,
+            "messages": [{"role": "user", "content": prompt}],
+        }
+        if system:
+            body["system"] = system
+        async with aiohttp.ClientSession() as session:
+            async with session.post(self.endpoint, json=body, headers=headers) as resp:
+                data = await resp.json()
+                return data.get("content", [{}])[0].get("text", "")
+
+    async def is_available(self) -> bool:
+        return bool(self.api_key)
+
+
+class OpenAIConnector(LLMConnector):
+    """OpenAI or any OpenAI-compatible API (vLLM, LiteLLM, etc.)."""
+
+    def __init__(self, api_key: str = "", model: str = "gpt-4o",
+                 endpoint: str = "https://api.openai.com/v1") -> None:
+        self.api_key = api_key or os.environ.get("OPENAI_API_KEY", "")
+        self.model = model
+        self.endpoint = endpoint
+
+    async def complete(self, prompt: str, system: str = "", max_tokens: int = 1000) -> str:
+        import aiohttp
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        body = {"model": self.model, "max_tokens": max_tokens, "messages": messages}
+        async with aiohttp.ClientSession() as session:
+            async with session.post(f"{self.endpoint}/chat/completions",
+                                    json=body, headers=headers) as resp:
+                data = await resp.json()
+                return data.get("choices", [{}])[0].get("message", {}).get("content", "")
+
+    async def is_available(self) -> bool:
+        return bool(self.api_key)
+
+
+class OllamaConnector(LLMConnector):
+    """Ollama local inference. Zero cost, zero internet."""
+
+    def __init__(self, model: str = "llama3.2", host: str = "http://localhost:11434") -> None:
+        self.model = model
+        self.host = host
+
+    async def complete(self, prompt: str, system: str = "", max_tokens: int = 1000) -> str:
+        import aiohttp
+        body: dict[str, Any] = {
+            "model": self.model,
+            "prompt": prompt,
+            "stream": False,
+        }
+        if system:
+            body["system"] = system
+        async with aiohttp.ClientSession() as session:
+            async with session.post(f"{self.host}/api/generate", json=body) as resp:
+                data = await resp.json()
+                return data.get("response", "")
+
+    async def is_available(self) -> bool:
+        try:
+            import aiohttp
+            async with aiohttp.ClientSession() as session:
+                async with session.get(f"{self.host}/api/tags", timeout=aiohttp.ClientTimeout(total=3)) as resp:
+                    return resp.status == 200
+        except Exception:
+            return False
+
+
+class HuggingFaceConnector(LLMConnector):
+    """Run any HuggingFace model locally. Zero cloud."""
+
+    def __init__(self, model: str = "mistralai/Mistral-7B-Instruct-v0.3") -> None:
+        self.model_name = model
+        self._pipeline: Any = None
+
+    async def complete(self, prompt: str, system: str = "", max_tokens: int = 1000) -> str:
+        if self._pipeline is None:
+            self._load()
+        full_prompt = f"{system}
+
+{prompt}" if system else prompt
+        result = self._pipeline(full_prompt, max_new_tokens=max_tokens, do_sample=True, temperature=0.7)
+        return result[0]["generated_text"][len(full_prompt):]
+
+    async def is_available(self) -> bool:
+        try:
+            import transformers  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def _load(self) -> None:
+        from transformers import pipeline
+        log.info("llm.loading model=%s (this may take a while...)", self.model_name)
+        self._pipeline = pipeline("text-generation", model=self.model_name, device_map="auto")
+        log.info("llm.loaded model=%s", self.model_name)
+
+
+# ─── Factory ────────────────────────────────────────
+
+def create_connector(provider: str, **kwargs: Any) -> LLMConnector:
+    """Create an LLM connector by name."""
+    connectors: dict[str, type[LLMConnector]] = {
+        "claude": ClaudeConnector,
+        "anthropic": ClaudeConnector,
+        "openai": OpenAIConnector,
+        "gpt": OpenAIConnector,
+        "ollama": OllamaConnector,
+        "huggingface": HuggingFaceConnector,
+        "hf": HuggingFaceConnector,
+        "vllm": OpenAIConnector,  # vLLM is OpenAI-compatible
+        "litellm": OpenAIConnector,
+    }
+    cls = connectors.get(provider.lower())
+    if cls is None:
+        raise ValueError(f"Unknown LLM provider: {provider}. Available: {list(connectors.keys())}")
+    return cls(**kwargs)
+

halyn/mcp.py

@@ -0,0 +1,239 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+MCP Server — Expose Halyn tools to Claude.ai natively.
+
+When connected via MCP, Claude sees all NRP nodes as tools.
+Observe, act, shield, scan — directly in the conversation.
+
+MCP JSON-RPC spec: https://spec.modelcontextprotocol.io
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+log = logging.getLogger("halyn.mcp")
+
+try:
+    from aiohttp import web
+    HAS_AIOHTTP = True
+except ImportError:
+    HAS_AIOHTTP = False
+
+
+class MCPServer:
+    """
+    MCP JSON-RPC endpoint.
+
+    Generates tools dynamically from ControlPlane state:
+    - Every NRP node creates observe/act/info tools
+    - System tools: scan, emergency_stop, resume, status
+    - Consent tools: approve, deny, list_pending
+    """
+
+    def __init__(self, control_plane: Any) -> None:
+        self.cp = control_plane
+
+    def get_tools(self) -> list[dict[str, Any]]:
+        """Generate MCP tool definitions from current NRP nodes."""
+        tools: list[dict[str, Any]] = []
+
+        # System tools
+        tools.append({
+            "name": "halyn_status",
+            "description": "Get system status: nodes, tools, audit, watchdog health.",
+            "inputSchema": {"type": "object", "properties": {}},
+        })
+        tools.append({
+            "name": "halyn_scan",
+            "description": "Discover devices on the network. Returns found nodes with suggested NRP IDs.",
+            "inputSchema": {"type": "object", "properties": {
+                "ssh_hosts": {"type": "string", "description": "Comma-separated SSH hosts to probe"},
+                "http_urls": {"type": "string", "description": "Comma-separated HTTP URLs to check"},
+            }},
+        })
+        tools.append({
+            "name": "halyn_emergency_stop",
+            "description": "STOP ALL NODES IMMEDIATELY. Use only in emergencies.",
+            "inputSchema": {"type": "object", "properties": {}},
+        })
+        tools.append({
+            "name": "halyn_resume",
+            "description": "Resume operations after emergency stop.",
+            "inputSchema": {"type": "object", "properties": {}},
+        })
+        tools.append({
+            "name": "halyn_audit",
+            "description": "Query the audit trail. Returns recent actions with hash chain verification.",
+            "inputSchema": {"type": "object", "properties": {
+                "tool": {"type": "string", "description": "Filter by tool name"},
+                "node": {"type": "string", "description": "Filter by node"},
+                "limit": {"type": "integer", "description": "Max entries (default 20)"},
+            }},
+        })
+        tools.append({
+            "name": "halyn_consent_pending",
+            "description": "List nodes waiting for operator approval.",
+            "inputSchema": {"type": "object", "properties": {}},
+        })
+
+        # Node-specific tools from registry
+        for tool_name in sorted(self.cp.engine.registry.tool_names):
+            spec = self.cp.engine.registry.get_spec(tool_name)
+            if not spec:
+                continue
+
+            props: dict[str, Any] = {}
+            required: list[str] = []
+
+            if ".observe" in tool_name:
+                props["channels"] = {
+                    "type": "string",
+                    "description": "Comma-separated channel names to read (empty = all)",
+                }
+            elif ".act" in tool_name or ".shell" in tool_name:
+                props["command"] = {"type": "string", "description": "Command to execute"}
+                required.append("command")
+            elif any(tool_name.endswith(f".{a}") for a in (
+                "file_read", "file_write", "file_list", "log_tail",
+                "git_status", "service_restart", "process_list",
+                "calibrate", "set_threshold", "walk", "pick", "stand",
+            )):
+                # Action-specific tools get generic args
+                props["args"] = {
+                    "type": "object",
+                    "description": "Action arguments",
+                    "additionalProperties": True,
+                }
+
+            tools.append({
+                "name": tool_name.replace("/", "__").replace(".", "_"),
+                "description": spec.description or tool_name,
+                "inputSchema": {
+                    "type": "object",
+                    "properties": props,
+                    "required": required,
+                },
+            })
+
+        return tools
+
+    async def handle_jsonrpc(self, request: "web.Request") -> "web.Response":
+        """Handle MCP JSON-RPC requests."""
+        try:
+            body = await request.json()
+        except Exception:
+            return _mcp_error(-32700, "Parse error", None)
+
+        method = body.get("method", "")
+        params = body.get("params", {})
+        req_id = body.get("id")
+
+        if method == "initialize":
+            return _mcp_result(req_id, {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {"tools": {"listChanged": True}},
+                "serverInfo": {"name": "halyn", "version": "0.1.0"},
+            })
+
+        if method == "tools/list":
+            return _mcp_result(req_id, {"tools": self.get_tools()})
+
+        if method == "tools/call":
+            tool_name = params.get("name", "")
+            arguments = params.get("arguments", {})
+            result = await self._dispatch(tool_name, arguments)
+            return _mcp_result(req_id, {
+                "content": [{"type": "text", "text": json.dumps(result, default=str)}],
+            })
+
+        if method == "notifications/initialized":
+            return web.Response(status=204)
+
+        return _mcp_error(-32601, f"Method not found: {method}", req_id)
+
+    async def _dispatch(self, mcp_name: str, args: dict[str, Any]) -> Any:
+        """Route MCP tool call to ControlPlane."""
+        # System tools
+        if mcp_name == "halyn_status":
+            return self.cp.status()
+
+        if mcp_name == "halyn_scan":
+            config = {}
+            if args.get("ssh_hosts"):
+                config["ssh_hosts"] = [h.strip() for h in args["ssh_hosts"].split(",")]
+            if args.get("http_urls"):
+                config["http_urls"] = [u.strip() for u in args["http_urls"].split(",")]
+            nodes = await self.cp.scan(config or None)
+            return [{"address": n.address, "port": n.port, "protocol": n.protocol,
+                      "name": n.name, "nrp_id": n.suggested_nrp_id} for n in nodes]
+
+        if mcp_name == "halyn_emergency_stop":
+            await self.cp.emergency_stop()
+            return {"status": "stopped"}
+
+        if mcp_name == "halyn_resume":
+            await self.cp.resume()
+            return {"status": "resumed"}
+
+        if mcp_name == "halyn_audit":
+            entries = self.cp.audit.query(
+                tool=args.get("tool", ""),
+                node=args.get("node", ""),
+                limit=int(args.get("limit", 20)),
+            )
+            valid, count, msg = self.cp.audit.verify_chain()
+            return {
+                "entries": [e.to_dict() for e in entries],
+                "chain_valid": valid,
+                "total": count,
+            }
+
+        if mcp_name == "halyn_consent_pending":
+            from .consent import ConsentLevel
+            pending = self.cp.consent.list_all(level=ConsentLevel.PENDING)
+            return [r.to_dict() for r in pending]
+
+        # Node tools: convert MCP name back to engine tool name
+        engine_name = mcp_name.replace("__", "/").replace("_", ".", 1)
+        # Try direct lookup first
+        if engine_name not in self.cp.engine.registry.tool_names:
+            # Try more aggressive conversion
+            parts = mcp_name.split("__")
+            if len(parts) == 2:
+                engine_name = parts[0] + "/" + parts[1].replace("_", ".", 1)
+
+        if engine_name in self.cp.engine.registry.tool_names:
+            result = await self.cp.execute(
+                engine_name, args,
+                llm_model="mcp",
+                intent_text=f"MCP call: {mcp_name}",
+            )
+            return {"ok": result.ok, "data": result.data, "error": result.error}
+
+        return {"error": f"unknown tool: {mcp_name}", "available": sorted(self.cp.engine.registry.tool_names)[:20]}
+
+
+def _mcp_result(req_id: Any, result: Any) -> "web.Response":
+    return web.Response(
+        text=json.dumps({"jsonrpc": "2.0", "id": req_id, "result": result}, default=str),
+        content_type="application/json",
+    )
+
+
+def _mcp_error(code: int, message: str, req_id: Any) -> "web.Response":
+    return web.Response(
+        text=json.dumps({"jsonrpc": "2.0", "id": req_id,
+                         "error": {"code": code, "message": message}}),
+        content_type="application/json",
+    )
+
+
+def mount_mcp(app: "web.Application", control_plane: Any) -> None:
+    """Mount the MCP endpoint on an existing aiohttp app."""
+    mcp = MCPServer(control_plane)
+    app.router.add_post("/mcp", mcp.handle_jsonrpc)
+    log.info("mcp.mounted path=/mcp")