fableforge-agent 0.1.0__py3-none-any.whl

fableforge_agent/__init__.py

@@ -0,0 +1,63 @@
+"""
+FableForge Agent — Self-improving AI agent framework with behavioral
+observability and trust protocols.
+
+Built on Hermes Agent (NousResearch) with Tiers 3-4: Agent Control Plane,
+Behavioral Observability, and Bidirectional Trust Protocols.
+
+Author: KingLabsA
+  - GitHub: https://github.com/KingLabsA
+  - Twitter: https://x.com/KingLabsA
+  - Email: kinglabsa@users.noreply.github.com
+"""
+
+__version__ = "0.1.0"
+__author__ = "KingLabsA"
+
+# ── Re-exported Hermes symbols ──────────────────────────────────────────────
+try:
+    from hermes_agent import AIAgent  # noqa: F401
+except ImportError:
+    try:
+        from run_agent import AIAgent  # noqa: F401
+    except ImportError:
+        AIAgent = None  # graceful fallback for partial installs
+
+try:
+    from hermes_agent import ConversationLoop  # noqa: F401
+except ImportError:
+    try:
+        from agent.conversation_loop import ConversationLoop  # noqa: F401
+    except ImportError:
+        ConversationLoop = None
+
+try:
+    from hermes_agent import ToolRegistry  # noqa: F401
+except ImportError:
+    try:
+        from tools.registry import ToolRegistry, registry  # noqa: F401
+    except ImportError:
+        ToolRegistry = None
+
+try:
+    from hermes_agent import SessionDB  # noqa: F401
+except ImportError:
+    try:
+        from hermes_state import SessionDB  # noqa: F401
+    except ImportError:
+        SessionDB = None
+
+# ── FableForge additions ────────────────────────────────────────────────────
+from fableforge_agent.control_plane.core import ControlPlane
+from fableforge_agent.observability.core import BehavioralObservability
+from fableforge_agent.trust.core import TrustProtocol
+
+__all__ = [
+    "AIAgent",
+    "ConversationLoop",
+    "ToolRegistry",
+    "SessionDB",
+    "ControlPlane",
+    "BehavioralObservability",
+    "TrustProtocol",
+]

fableforge_agent/cli.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""
+FableForge Agent CLI — wraps Hermes Agent and adds FableForge commands for
+the control plane, observability, trust, and audit.
+
+Author: KingLabsA
+  - GitHub: https://github.com/KingLabsA
+  - Twitter: https://x.com/KingLabsA
+  - Email: kinglabsa@users.noreply.github.com
+"""
+
+import argparse
+import json
+import os
+import sys
+
+
+def cmd_control_plane(args: argparse.Namespace) -> None:
+    port = args.port
+    host = args.host
+    try:
+        import uvicorn
+        from fastapi import FastAPI
+
+        app = FastAPI(title="FableForge Control Plane")
+
+        @app.get("/health")
+        def health():
+            return {"status": "ok"}
+
+        @app.get("/audit")
+        def get_audit():
+            from fableforge_agent.control_plane import AuditTrail
+            trail = AuditTrail()
+            return {"entries": trail.export("json")}
+
+        @app.post("/sandbox/execute")
+        async def sandbox_execute(body: dict):
+            from fableforge_agent.control_plane import Sandbox
+            sandbox = Sandbox(sandbox_type=body.get("backend", "mock"))
+            result = sandbox.execute(body.get("code", ""), timeout=body.get("timeout", 30))
+            return result.__dict__
+
+        uvicorn.run(app, host=host, port=port, log_level="info")
+    except ImportError as e:
+        print(f"Error: missing dependency — {e}", file=sys.stderr)
+        print("Install with: pip install 'fableforge-agent[server]'", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_audit(args: argparse.Namespace) -> None:
+    from fableforge_agent.control_plane import AuditTrail
+
+    trail = AuditTrail()
+    export_path = args.export
+    fmt = "json" if export_path and export_path.endswith(".json") else "markdown"
+    output = trail.export(fmt=fmt)
+    if export_path:
+        with open(export_path, "w") as f:
+            f.write(output)
+        print(f"Audit exported to {export_path}")
+    else:
+        print(output)
+
+
+def cmd_trust(args: argparse.Namespace) -> None:
+    from fableforge_agent.trust import TrustProtocol
+
+    agent_id = args.agent_id or "cli-agent"
+    trust = TrustProtocol(agent_id=agent_id)
+    action = args.action
+
+    if action == "register":
+        pubkey = args.pubkey
+        if pubkey and os.path.exists(pubkey):
+            with open(pubkey) as f:
+                key_content = f.read().strip()
+        else:
+            key_content = pubkey or trust.public_key
+        trust.registry.register(agent_id, key_content, {"source": "cli"})
+        print(f"Registered agent: {agent_id}")
+        print(f"  Public key fingerprint: {trust.public_key_fingerprint}")
+    elif action == "list":
+        agents = trust.registry.list_agents()
+        print("Registered agents:")
+        for aid in agents:
+            identity = trust.registry.resolve(aid)
+            print(f"  - {aid} (trust level: {identity.trust_level if identity else '?'})")
+    elif action == "verify":
+        challenge = f"challenge-{agent_id}"
+        response = hashlib_response = __import__("hashlib").sha256(
+            f"{agent_id}:{challenge}:{trust.public_key}".encode()
+        ).hexdigest()
+        valid = trust.registry.verify_identity(agent_id, challenge, response)
+        print(f"Identity verification: {'PASS' if valid else 'FAIL'}")
+    else:
+        print(f"Unknown trust action: {action}")
+
+
+def cmd_observe(args: argparse.Namespace) -> None:
+    try:
+        import uvicorn
+        from fastapi import FastAPI, WebSocket
+
+        app = FastAPI(title="FableForge Observability")
+
+        @app.websocket("/ws/observe")
+        async def observe_ws(websocket: WebSocket):
+            await websocket.accept()
+            from fableforge_agent.observability import BehavioralObservability
+            obs = BehavioralObservability(agent_id=args.agent_id or "observed")
+            while True:
+                data = await websocket.receive_json()
+                observation = obs.observe(data.get("action", "unknown"), data)
+                await websocket.send_json(observation.__dict__)
+
+        uvicorn.run(app, host=args.host, port=args.port, log_level="info")
+    except ImportError as e:
+        print(f"Error: missing dependency — {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="fableforge",
+        description="FableForge Agent — self-improving AI agent with behavioral observability and trust",
+        epilog="Author: KingLabsA — https://github.com/KingLabsA",
+    )
+    parser.add_argument("--version", action="version", version="0.1.0")
+
+    subparsers = parser.add_subparsers(dest="command", help="Subcommands")
+
+    # control-plane
+    cp_parser = subparsers.add_parser("control-plane", help="Start the control plane API server")
+    cp_parser.add_argument("--host", default="127.0.0.1")
+    cp_parser.add_argument("--port", type=int, default=8000)
+
+    # audit
+    audit_parser = subparsers.add_parser("audit", help="Export audit trail")
+    audit_parser.add_argument("--export", dest="export_path", help="Export to file (.json or .md)")
+
+    # trust
+    trust_parser = subparsers.add_parser("trust", help="Trust registry management")
+    trust_sub = trust_parser.add_subparsers(dest="action", required=True)
+    reg_parser = trust_sub.add_parser("register", help="Register an agent")
+    reg_parser.add_argument("--agent-id", required=True)
+    reg_parser.add_argument("--pubkey", help="Public key path")
+    list_parser = trust_sub.add_parser("list", help="List registered agents")
+    list_parser.add_argument("--agent-id", default="cli-agent")
+    verify_parser = trust_sub.add_parser("verify", help="Verify identity")
+    verify_parser.add_argument("--agent-id", default="cli-agent")
+
+    # observe
+    obs_parser = subparsers.add_parser("observe", help="Start behavioral observability dashboard")
+    obs_parser.add_argument("--host", default="127.0.0.1")
+    obs_parser.add_argument("--port", type=int, default=8765)
+    obs_parser.add_argument("--agent-id", default="observed")
+
+    args = parser.parse_args()
+
+    if args.command == "control-plane":
+        cmd_control_plane(args)
+    elif args.command == "audit":
+        cmd_audit(args)
+    elif args.command == "trust":
+        cmd_trust(args)
+    elif args.command == "observe":
+        cmd_observe(args)
+    else:
+        # Default: delegate to Hermes CLI
+        try:
+            from hermes_cli.cli import main as hermes_main
+            hermes_main()
+        except ImportError:
+            try:
+                from cli import main as hermes_main
+                hermes_main()
+            except ImportError:
+                print("Hermes Agent not installed. Install with: pip install hermes-agent", file=sys.stderr)
+                sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

fableforge_agent/control_plane/__init__.py

@@ -0,0 +1,37 @@
+"""
+Control Plane — Tier 3 of FableForge Agent.
+
+Sandboxed execution, audit trails, incident response, authentication, and
+credential management for agent workloads.
+
+Author: KingLabsA
+  - GitHub: https://github.com/KingLabsA
+  - Twitter: https://x.com/KingLabsA
+  - Email: kinglabsa@users.noreply.github.com
+"""
+
+from fableforge_agent.control_plane.core import (
+    ControlPlane,
+    Sandbox,
+    SandboxPolicy,
+    SandboxResult,
+    AuditTrail,
+    AuditEntry,
+    IncidentResponse,
+)
+from fableforge_agent.control_plane.auth import (
+    OAuthGate,
+    CredentialBroker,
+)
+
+__all__ = [
+    "ControlPlane",
+    "Sandbox",
+    "SandboxPolicy",
+    "SandboxResult",
+    "AuditTrail",
+    "AuditEntry",
+    "IncidentResponse",
+    "OAuthGate",
+    "CredentialBroker",
+]

fableforge_agent/control_plane/auth.py

@@ -0,0 +1,152 @@
+"""
+Authentication and credential management for the agent control plane.
+
+Author: KingLabsA
+  - GitHub: https://github.com/KingLabsA
+  - Twitter: https://x.com/KingLabsA
+  - Email: kinglabsa@users.noreply.github.com
+"""
+
+import json
+import os
+import time
+import uuid
+from typing import Dict, List, Optional
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# OAuthGate
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class OAuthGate:
+    """Pluggable OAuth authentication and authorization for agent access control."""
+
+    def __init__(self, secrets_path: Optional[str] = None):
+        self._tokens: Dict[str, Dict] = {}
+        self._clients: Dict[str, str] = {}
+        self.secrets_path = secrets_path or os.path.expanduser("~/.fableforge/secrets.json")
+        self._load_secrets()
+
+    def _load_secrets(self) -> None:
+        try:
+            with open(self.secrets_path) as f:
+                data = json.load(f)
+                self._clients = data.get("clients", {})
+        except (FileNotFoundError, json.JSONDecodeError):
+            self._clients = {}
+
+    def _save_secrets(self) -> None:
+        os.makedirs(os.path.dirname(self.secrets_path), exist_ok=True)
+        with open(self.secrets_path, "w") as f:
+            json.dump({"clients": self._clients}, f, indent=2)
+
+    def authenticate(self, credentials: Dict) -> bool:
+        client_id = credentials.get("client_id")
+        client_secret = credentials.get("client_secret")
+        stored = self._clients.get(client_id)
+        if stored and stored == client_secret:
+            return True
+        if not self._clients:
+            return True
+        return False
+
+    def authorize(self, agent_id: str, action: str) -> bool:
+        token = self._tokens.get(agent_id)
+        if not token:
+            return False
+        if token.get("expires_at", 0) < time.time():
+            return False
+        return action in token.get("scopes", [])
+
+    def issue_token(self, agent_id: str, scopes: List[str]) -> str:
+        token = uuid.uuid4().hex
+        self._tokens[agent_id] = {
+            "token": token,
+            "scopes": scopes,
+            "expires_at": time.time() + 3600,
+            "issued_at": time.time(),
+        }
+        return token
+
+    def verify_token(self, token: str) -> Dict:
+        for agent_id, data in self._tokens.items():
+            if data.get("token") == token:
+                if data["expires_at"] > time.time():
+                    return {"agent_id": agent_id, "scopes": data["scopes"], "valid": True}
+                return {"agent_id": agent_id, "valid": False, "reason": "expired"}
+        return {"valid": False, "reason": "unknown_token"}
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# CredentialBroker
+# ═════════════════════════════════════════════════════════════════════════════════
+
+class CredentialBroker:
+    """Secure credential management with encrypted storage."""
+
+    def __init__(self, vault_path: Optional[str] = None):
+        self.vault_path = vault_path or os.path.expanduser("~/.fableforge/vault.json")
+        self._vault: Dict[str, Dict] = {}
+        self._load_vault()
+
+    def _load_vault(self) -> None:
+        try:
+            with open(self.vault_path) as f:
+                raw = f.read()
+                self._vault = json.loads(self._decrypt(raw))
+        except (FileNotFoundError, json.JSONDecodeError, Exception):
+            self._vault = {}
+
+    def _save_vault(self) -> None:
+        os.makedirs(os.path.dirname(self.vault_path), exist_ok=True)
+        with open(self.vault_path, "w") as f:
+            f.write(self._encrypt(json.dumps(self._vault, indent=2)))
+
+    def _encrypt(self, plaintext: str) -> str:
+        try:
+            from cryptography.fernet import Fernet
+            key = self._get_or_create_key()
+            return Fernet(key).encrypt(plaintext.encode()).decode()
+        except ImportError:
+            return plaintext
+
+    def _decrypt(self, ciphertext: str) -> str:
+        try:
+            from cryptography.fernet import Fernet
+            key = self._get_or_create_key()
+            return Fernet(key).decrypt(ciphertext.encode()).decode()
+        except (ImportError, Exception):
+            return ciphertext
+
+    def _get_or_create_key(self) -> bytes:
+        key_path = os.path.expanduser("~/.fableforge/vault.key")
+        try:
+            with open(key_path, "rb") as f:
+                return f.read()
+        except FileNotFoundError:
+            try:
+                from cryptography.fernet import Fernet
+                key = Fernet.generate_key()
+                os.makedirs(os.path.dirname(key_path), exist_ok=True)
+                with open(key_path, "wb") as f:
+                    f.write(key)
+                return key
+            except ImportError:
+                return b"insecure-fallback-key-do-not-use-in-production"
+
+    def store(self, service: str, credential: Dict) -> None:
+        self._vault[service] = credential
+        self._save_vault()
+
+    def retrieve(self, service: str) -> Optional[Dict]:
+        return self._vault.get(service)
+
+    def rotate(self, service: str) -> None:
+        if service in self._vault:
+            old = self._vault[service]
+            rotated = {k: f"{k}-rotated-{uuid.uuid4().hex[:8]}" for k in old}
+            self._vault[service] = rotated
+            self._save_vault()
+
+    def list_services(self) -> List[str]:
+        return list(self._vault.keys())