"""
VOVINA ZEDEC PRO - XERO Terminal Assistant (built-in user help)
================================================================
Author:  Michael Laurence Curzi
Company: ZEDEC AI / 36N9 Genetics LLC
License: MIT (Attribution Required)

The help desk lives inside the model. Whenever an operator is unsure, they
ask in plain English and XERO answers with: a direct answer, the exact
terminal commands to run, the matching preconfig, and a runnable tutorial —
no external docs needed.

    from xero_assistant import assist, print_help, menu
    print_help("how do I make it talk to customers")
    print_help("I'm stuck")           # shows the full menu of options

It blends a structured HOW-TO base (deterministic, always correct commands)
with the organism's own voice for a natural framing.
"""
from __future__ import annotations

from typing import Optional

# (topic, keywords, summary, commands[], tutorial, see_also)
HOWTO: dict[str, dict] = {
    "getting_started": {
        "kw": "start begin first new setup install init how do i use",
        "summary": "Initialise XERO and meet it. Easiest path for anyone.",
        "commands": ["python xero.py --setup            # guided wizard (easy/advanced)",
                     "python xero.py --init             # awaken the organism",
                     "python xero.py --help-me          # this assistant, any time"],
        "tutorial": "quickstart"},
    "talk": {
        "kw": "talk chat speak converse ask question message conversation",
        "summary": "Hold a conversation with the organism (five tongues).",
        "commands": ["python xero.py --talk \"who are you?\"   # one-shot",
                     "python xero.py --chat                    # web chat on :8883"],
        "tutorial": "talk"},
    "create": {
        "kw": "create make generate art image picture video music song draw paint compose",
        "summary": "Make images, video, music, and speech with the limbs.",
        "commands": ["python xero.py --chat   # then click a limb (image/video/music/voice)",
                     "# or in code:  from organism_limbs import mind; mind().act('image', {'prompt':'a mandala'})"],
        "tutorial": "create"},
    "code": {
        "kw": "code program function script developer api sdk integrate build",
        "summary": "Generate code and use the Python API / SDK.",
        "commands": ["python xero.py --preset developer",
                     "python -c \"from organism_limbs import mind; print(mind().act('code', {'spec':'a fibonacci function'})['code'])\""],
        "tutorial": "create"},
    "languages": {
        "kw": "language translate enochian sanskrit hebrew aramaic gematria numerology tongue meaning",
        "summary": "Translate across tongues and read the gematria/numerology.",
        "commands": ["python xero.py --talk \"translate truth\"",
                     "python -c \"from numerology_metadata import compact_signature; print(compact_signature('truth'))\""],
        "tutorial": "languages"},
    "configure": {
        "kw": "config configure preset purpose use case corporate government intelligence enterprise retail industrial setup mode",
        "summary": "Pick a fusion-grade preconfig for your exact use case.",
        "commands": ["python xero.py --list-presets",
                     "python xero.py --preset <name>          # e.g. intelligence, retail_frontend",
                     "python xero.py --setup                  # guided"],
        "tutorial": "configure"},
    "deploy": {
        "kw": "deploy serve server host run web interface port public",
        "summary": "Run the chat/API server (the public interface).",
        "commands": ["python serve/xero_chat_server.py --host 0.0.0.0 --port 8883",
                     "XERO_CHAT_TOKEN=secret python serve/xero_chat_server.py   # require auth"],
        "tutorial": "configure"},
    "selfheal": {
        "kw": "heal health doctor fix error crash broken diagnose repair stuck problem",
        "summary": "Diagnose system health and let XERO self-correct.",
        "commands": ["python xero.py --doctor",
                     "# in code: from xero_self_healing import healer; healer('easy').safe(fn, fallback=None)"],
        "tutorial": "selfheal"},
    "lab": {
        "kw": "lab derive derivative breed mutate dna offspring descendant model train ancestor",
        "summary": "Draw out digital DNA and breed derivative models.",
        "commands": ["python xero.py --lab",
                     "python -c \"from xero_lab import lab; print(lab().derive('mymodel', purpose='an analyst').lineage_id)\""],
        "tutorial": "lab"},
    "publish": {
        "kw": "publish huggingface hf upload share release distribute package",
        "summary": "Package and publish to Hugging Face (hardened).",
        "commands": ["python xero.py --status          # confirm health first",
                     "# see docs/PUBLISHING.md for the secret-scanned, atomic upload flow"],
        "tutorial": "configure"},
}

MENU = [
    ("talk",      "Just talk to it",            "python xero.py --talk \"hello\"  ·  --chat"),
    ("create",    "Make image / video / music", "python xero.py --chat  (pick a limb)"),
    ("configure", "Configure for my purpose",   "python xero.py --setup  ·  --list-presets"),
    ("code",      "Use the code / API",         "python xero.py --preset developer"),
    ("lab",       "Breed a derivative model",   "python xero.py --lab"),
    ("selfheal",  "Something's wrong",          "python xero.py --doctor"),
    ("getting_started", "I'm brand new",        "python xero.py --setup"),
]


def _match(query: str) -> Optional[str]:
    q = set(query.lower().replace("?", " ").split())
    best, score = None, 0
    for topic, d in HOWTO.items():
        s = len(q & set(d["kw"].split()))
        if s > score:
            best, score = topic, s
    return best if score > 0 else None


def assist(query: str) -> dict:
    """Return structured guidance for a plain-English question."""
    topic = _match(query)
    out: dict = {"query": query}
    # a use-case → recommended preset
    try:
        from xero_presets import recommend
        rec = recommend(query)
        out["recommended_preset"] = {"key": rec.key, "title": rec.title}
    except Exception:
        out["recommended_preset"] = None
    # the organism's own framing
    try:
        from enochian_llm_integration import brain
        out["organism"] = brain().respond(query)["reply"]
    except Exception:
        out["organism"] = ""
    if topic:
        d = HOWTO[topic]
        out.update({"topic": topic, "summary": d["summary"],
                    "commands": d["commands"], "tutorial": d.get("tutorial")})
    else:
        out.update({"topic": None,
                    "summary": "Here are all the things I can help you do.",
                    "menu": [{"do": m[1], "run": m[2]} for m in MENU]})
    return out


def menu() -> list[dict]:
    return [{"topic": t, "do": label, "run": cmd} for t, label, cmd in MENU]


def print_help(query: str = "", printer=print) -> None:
    printer("\n" + "═" * 64)
    printer("  XERO ASSISTANT  ·  ask me anything; I'll show you how")
    printer("═" * 64)
    if not query:
        printer("\n  What would you like to do?\n")
        for i, (_, label, cmd) in enumerate(MENU, 1):
            printer(f"   {i}. {label:<28} → {cmd}")
        printer("\n  Or just ask, e.g.:  python xero.py --help-me \"make it talk to customers\"")
        printer("═" * 64 + "\n")
        return
    a = assist(query)
    if a.get("organism"):
        printer(f"\n  XERO: {a['organism'][:240]}")
    if a.get("topic"):
        printer(f"\n  ▸ {a['summary']}")
        printer("\n  Run:")
        for c in a["commands"]:
            printer(f"     $ {c}")
        if a.get("tutorial"):
            printer(f"\n  Tutorial:  python xero.py --tutorial {a['tutorial']}")
    else:
        printer(f"\n  {a['summary']}\n")
        for i, m in enumerate(a.get("menu", []), 1):
            printer(f"   {i}. {m['do']:<28} → {m['run']}")
    if a.get("recommended_preset"):
        rp = a["recommended_preset"]
        printer(f"\n  Suggested preset for this: {rp['key']}  "
                f"(python xero.py --preset {rp['key']})")
    printer("═" * 64 + "\n")


if __name__ == "__main__":
    print_help("")
    print_help("how do I make it talk to customers safely")
    print_help("I want to breed a new model from its dna")