tools.py

"""Hermes tools for nse-orchestrator — the cross-pillar coordination layer.

The orchestrator detects available pillars by importing them at runtime.
For Hermes use, pillars are surfaced via their own HA plugins; this
plugin's tools focus on health, coherence checks, and status."""

from __future__ import annotations

from dataclasses import asdict, is_dataclass
from typing import Any, Optional

from nse_orchestrator import SovereignEntity

from tools.registry import tool_error, tool_result

_entity: Optional[SovereignEntity] = None


def _require_entity() -> SovereignEntity:
    if _entity is None:
        raise RuntimeError("NSE not initialized. Call nse_init first.")
    return _entity


def _serialize(obj: Any) -> Any:
    import enum
    if isinstance(obj, enum.Enum):
        return obj.value
    if is_dataclass(obj):
        return _serialize(asdict(obj))
    if isinstance(obj, (list, tuple)):
        return [_serialize(x) for x in obj]
    if isinstance(obj, dict):
        return {k: _serialize(v) for k, v in obj.items()}
    return obj


# -----------------------------
# nse_init
# -----------------------------

NSE_INIT_SCHEMA = {
    "type": "function",
    "function": {
        "name": "nse_init",
        "description": "Initialize the NSE entity. Auto-detects pillar libraries available in the Python environment.",
        "parameters": {
            "type": "object",
            "properties": {
                "owner_npub":  {"type": "string"},
                "owner_name":  {"type": "string"},
                "entity_name": {"type": "string"},
            },
            "required": [],
        },
    },
}


def handle_nse_init(args: dict[str, Any], **kw) -> str:
    global _entity
    try:
        _entity = SovereignEntity.create(
            owner_npub=args.get("owner_npub") or "",
            owner_name=args.get("owner_name") or "",
            entity_name=args.get("entity_name") or "",
        )
        return tool_result({
            "available_pillars": [_serialize(p) for p in _entity.available_pillars],
            "active_pillars":    [_serialize(p) for p in _entity.active_pillars],
        })
    except Exception as e:
        return tool_error(f"nse_init failed: {type(e).__name__}: {e}")


# -----------------------------
# nse_check
# -----------------------------

NSE_CHECK_SCHEMA = {
    "type": "function",
    "function": {
        "name": "nse_check",
        "description": (
            "Run cross-pillar coherence checks on a proposed action. Returns "
            "verdicts and whether escalation to the human is warranted. Use "
            "this BEFORE any significant action."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "description":            {"type": "string", "description": "Human-readable description of the action."},
                "involves_money":         {"type": "boolean", "default": False},
                "money_amount_sats":      {"type": "integer", "default": 0},
                "recipient_id":           {"type": "string"},
                "social_known":           {"type": "boolean", "default": False, "description": "Is the recipient/counterparty known to the social graph?"},
                "social_tier":            {"type": "string", "enum": ["intimate", "close", "familiar", "known"]},
                "involves_secrets":       {"type": "boolean", "default": False},
                "involves_scheduling":    {"type": "boolean", "default": False},
                "is_reversible":          {"type": "boolean", "default": True},
                "owner_recently_active":  {"type": "boolean", "default": False},
                "owner_absent_hours":     {"type": "number",  "default": 0.0},
            },
            "required": ["description"],
        },
    },
}


def handle_nse_check(args: dict[str, Any], **kw) -> str:
    try:
        entity = _require_entity()
        kwargs = {
            "description":           args["description"],
            "involves_money":        bool(args.get("involves_money", False)),
            "money_amount_sats":     int(args.get("money_amount_sats", 0)),
            "recipient_id":          args.get("recipient_id") or "",
            "social_known":          bool(args.get("social_known", False)),
            "social_tier":           args.get("social_tier"),
            "involves_secrets":      bool(args.get("involves_secrets", False)),
            "involves_scheduling":   bool(args.get("involves_scheduling", False)),
            "is_reversible":         bool(args.get("is_reversible", True)),
            "owner_recently_active": bool(args.get("owner_recently_active", False)),
            "owner_absent_hours":    float(args.get("owner_absent_hours", 0.0)),
        }
        verdicts = entity.check(**kwargs)
        escalate = entity.should_escalate(verdicts)
        return tool_result({
            "should_escalate": escalate,
            "verdicts": [_serialize(v) for v in verdicts],
        })
    except Exception as e:
        return tool_error(f"nse_check failed: {type(e).__name__}: {e}")


# -----------------------------
# nse_health
# -----------------------------

NSE_HEALTH_SCHEMA = {
    "type": "function",
    "function": {
        "name": "nse_health",
        "description": "Return the status of each pillar (active, available, missing).",
        "parameters": {"type": "object", "properties": {}, "required": []},
    },
}


def handle_nse_health(args: dict[str, Any], **kw) -> str:
    try:
        entity = _require_entity()
        return tool_result(entity.health)
    except Exception as e:
        return tool_error(f"nse_health failed: {type(e).__name__}: {e}")


# -----------------------------
# nse_status
# -----------------------------

NSE_STATUS_SCHEMA = {
    "type": "function",
    "function": {
        "name": "nse_status",
        "description": "Full entity status — pillars, models, recent signals.",
        "parameters": {"type": "object", "properties": {}, "required": []},
    },
}


def handle_nse_status(args: dict[str, Any], **kw) -> str:
    try:
        entity = _require_entity()
        return tool_result(_serialize(entity.status))
    except Exception as e:
        return tool_error(f"nse_status failed: {type(e).__name__}: {e}")