cli.py

"""GraphAnything CLI — turn anything into a knowledge graph from your terminal.

Two modes share one Session core (`GraphAnything.session`):

  - **Sub-command mode** (`graphanything new / propose / sample / review / run`):
    one-shot operations, suitable for scripts and CI. Every sub-command
    operates on the "current session" — the most recently opened or
    explicitly switched-to session. State lives in ``graphanything-out/sessions/``.

  - **REPL mode** (``graphanything repl <inputs...>``): an interactive shell
    over the same Session. Useful when the schema needs back-and-forth
    discussion with the user.

Both modes are thin wrappers over `Session.<verb>()`. The CLI never
re-implements extraction or normalisation — every command boils down to
one or two Session method calls.

Optional dependencies:
  - prompt_toolkit (extras=`graphanything[repl]`): nicer REPL with history +
    completion. Falls back to bare ``input()`` if missing.

Environment variables (only consulted when LLM-based commands are invoked):
  - GA_API_BASE / OPENAI_API_BASE / API_BASE — chat-completions URL
    (default `http://localhost:8000/v1`).
  - GA_MODEL    / OPENAI_MODEL    / SUMMARY_MODEL_NAME — model name.
  - GA_API_KEY  / OPENAI_API_KEY  / API_KEY — optional bearer token.
  See `llm_client.py` for the full list.
"""
from __future__ import annotations

import argparse
import json
import os
import sys
import time
from pathlib import Path
from typing import Any, Iterable

from . import (
    list_extractors,
    list_presets,
    load_session,
    open_session,
    render,
)
from .session import DEFAULT_SESSIONS_DIR, Session


# ---------------------------------------------------------------------------
# Current-session pointer
# ---------------------------------------------------------------------------


def _sessions_dir(custom: str | None = None) -> Path:
    return Path(custom) if custom else DEFAULT_SESSIONS_DIR


def _current_pointer(sessions_dir: Path) -> Path:
    return sessions_dir / ".current"


def _read_current(sessions_dir: Path) -> str | None:
    p = _current_pointer(sessions_dir)
    if not p.exists():
        return None
    sid = p.read_text().strip()
    return sid or None


def _write_current(sessions_dir: Path, sid: str) -> None:
    sessions_dir.mkdir(parents=True, exist_ok=True)
    _current_pointer(sessions_dir).write_text(sid)


def _resolve_session(args, *, required: bool = True) -> Session:
    sd = _sessions_dir(args.sessions_dir)
    sid = args.session or _read_current(sd)
    if not sid:
        if not required:
            raise SystemExit(
                "No active session. Run `graphanything new <inputs>` first, or pass --session ID."
            )
        raise SystemExit("No active session. Run `graphanything new <inputs>` first.")
    return load_session(sid, sessions_dir=sd)


def _save_and_announce(sess: Session, action: str, *, quiet: bool = False) -> None:
    sess.save()
    if not quiet:
        print(f"[{sess.id}] {action}  status={sess.status}", file=sys.stderr)


# ---------------------------------------------------------------------------
# Lazy LLM client
# ---------------------------------------------------------------------------


def _make_llm():
    """Return GraphAnything's built-in OpenAI-compatible client.

    All LLM calls go through `GraphAnything.llm_client` — a thin HTTP
    wrapper around `chat.completions` that works against any compatible
    endpoint (vLLM serve, llama.cpp, Ollama, LM Studio, OpenAI, …).

    Configure via env vars (legacy names also accepted):
      GA_API_BASE  / OPENAI_API_BASE / OPENAI_BASE_URL / API_BASE
      GA_API_KEY   / OPENAI_API_KEY  / API_KEY
      GA_MODEL     / OPENAI_MODEL    / SUMMARY_MODEL_NAME
    """
    from .llm_client import make_client

    return make_client()


def _maybe_llm(needs_llm: bool):
    if not needs_llm:
        return None
    try:
        return _make_llm()
    except Exception as e:
        print(
            f"⚠ LLM not configured ({e.__class__.__name__}: {e}). "
            "Set GA_API_BASE + GA_MODEL (and optional GA_API_KEY) to point at "
            "any chat.completions-compatible endpoint, or add --no-llm.",
            file=sys.stderr,
        )
        return None


# ---------------------------------------------------------------------------
# Sub-command bodies
# ---------------------------------------------------------------------------


def cmd_new(args: argparse.Namespace) -> int:
    sd = _sessions_dir(args.sessions_dir)
    inputs = list(_expand_inputs(args.inputs))
    if not inputs:
        print("No inputs match the given paths.", file=sys.stderr)
        return 2

    budget = _budget_from_args(args)
    sess = open_session(
        inputs,
        preset=args.preset,
        extractor=args.extractor,
        sessions_dir=sd,
        budget=budget,
    )
    _write_current(sd, sess.id)

    if args.auto:
        # End-to-end: propose (if no preset) → run (no review).
        if sess.schema.is_empty():
            llm = _maybe_llm(False)   # propose works without LLM (generic schema)
            sess.propose(auto_accept=True, llm=llm)
        result = sess.run(out_dir=args.out)
        print(json.dumps({
            "session": sess.id,
            "n_inputs": len(sess.inputs),
            "n_nodes": result["n_nodes"],
            "n_edges": result["n_edges"],
            "out_path": result["out_path"],
            "extractor": sess.extractor,
            "schema": sess.schema.name,
        }, indent=2, ensure_ascii=False))
        return 0

    print(json.dumps({
        "session": sess.id,
        "inputs": len(sess.inputs),
        "preset": args.preset,
        "extractor": sess.extractor,
        "schema_entities": [e.name for e in sess.schema.entities],
        "next": "graphanything sample 5  (or `graphanything propose` first)",
    }, indent=2, ensure_ascii=False))
    return 0


def cmd_propose(args: argparse.Namespace) -> int:
    sess = _resolve_session(args)
    llm = _maybe_llm(needs_llm=args.llm)
    schema = sess.propose(n_samples=args.n, auto_accept=True, llm=llm)
    _save_and_announce(sess, f"propose → {len(schema.entities)} entities, {len(schema.relations)} relations")
    print(json.dumps(schema.to_dict(), indent=2, ensure_ascii=False))
    return 0


def cmd_refine(args: argparse.Namespace) -> int:
    sess = _resolve_session(args)
    llm = _maybe_llm(needs_llm=args.llm)
    sess.refine(args.instruction, llm=llm)
    _save_and_announce(sess, f"refine → schema v{sess.schema.version}")
    print(json.dumps(sess.schema.to_dict(), indent=2, ensure_ascii=False))
    return 0


def cmd_sample(args: argparse.Namespace) -> int:
    sess = _resolve_session(args)
    llm = _maybe_llm(needs_llm=_extractor_needs_llm(sess.extractor))
    summary = sess.sample(n=args.n, extractor=args.extractor, llm=llm)
    _save_and_announce(sess, f"sample({summary['n']}) → {summary['n_nodes']} nodes, {summary['n_edges']} edges")
    print(json.dumps(summary, indent=2, ensure_ascii=False))
    return 0


def cmd_review(args: argparse.Namespace) -> int:
    sess = _resolve_session(args)
    actions: list[dict[str, Any]] = []
    if args.accept_all:
        actions.append({"op": "accept_all"})
    if args.accept:
        actions.append({"op": "accept", "node_ids": args.accept})
    if args.reject:
        actions.append({"op": "reject", "node_ids": args.reject, "reason": args.reason or ""})
    if args.merge:
        ids = [s.strip() for s in args.merge.split(",") if s.strip()]
        if len(ids) >= 2:
            actions.append({"op": "merge", "node_ids": ids, "into": ids[0]})
    if not actions:
        print(
            "Nothing to review. Use --accept-all / --accept ID... / --reject ID... / "
            "--merge a,b[,c]",
            file=sys.stderr,
        )
        return 2
    sess.review(actions)
    _save_and_announce(sess, f"review × {len(actions)}")
    print(json.dumps({
        "accepted": {"nodes": len(sess.accepted["nodes"]), "edges": len(sess.accepted["edges"])},
        "pending": {"nodes": len(sess.pending["nodes"]), "edges": len(sess.pending["edges"])},
        "rejected": {"nodes": len(sess.rejected["nodes"])},
    }, indent=2, ensure_ascii=False))
    return 0


def cmd_run(args: argparse.Namespace) -> int:
    sess = _resolve_session(args)
    llm = _maybe_llm(needs_llm=_extractor_needs_llm(sess.extractor))
    result = sess.run(extractor=args.extractor, llm=llm, out_dir=args.out)
    _save_and_announce(sess, f"run → {result['n_nodes']} nodes, {result['n_edges']} edges")
    print(json.dumps(result, indent=2, ensure_ascii=False))
    return 0


def cmd_render(args: argparse.Namespace) -> int:
    if args.graph:
        # Render an existing graph.json (no Session needed).
        import networkx as nx
        from networkx.readwrite import json_graph

        data = json.loads(Path(args.graph).read_text())
        if "nodes" in data and ("edges" in data or "links" in data):
            edges = data.get("edges") or data.get("links") or []
            G = nx.DiGraph()
            for n in data["nodes"]:
                G.add_node(n["id"], **n)
            for e in edges:
                G.add_edge(e["source"], e["target"], **e)
        else:
            G = json_graph.node_link_graph(data, edges="edges")
    else:
        sess = _resolve_session(args)
        G = sess.to_viz_graph()

    out = render(G, fmt=args.fmt, out_path=args.out, budget_tokens=args.budget_tokens)
    if isinstance(out, Path):
        print(str(out))
    else:
        print(out)
    return 0


def cmd_explain(args: argparse.Namespace) -> int:
    sess = _resolve_session(args)
    target = args.target
    G = sess.to_viz_graph()
    if "→" in target or "->" in target:
        # Edge: "src → relation → tgt"  (also accept "->" form)
        sep = "→" if "→" in target else "->"
        parts = [p.strip() for p in target.split(sep)]
        if len(parts) != 3:
            print(f"Edge form must be 'src {sep} relation {sep} tgt'", file=sys.stderr)
            return 2
        src, relation, tgt = parts
        if not G.has_edge(src, tgt):
            print(f"No edge {src} -> {tgt}", file=sys.stderr)
            return 1
        edge_data = G.get_edge_data(src, tgt)
        print(json.dumps({"src": src, "tgt": tgt, "relation": relation, **edge_data}, indent=2, ensure_ascii=False))
        return 0

    # Node id
    if target not in G.nodes:
        # try fuzzy match by label
        cand = [n for n in G.nodes if str(G.nodes[n].get("label", "")).lower() == target.lower()]
        if not cand:
            print(f"No node matches {target!r}.", file=sys.stderr)
            return 1
        target = cand[0]
    info = {
        "id": target,
        **G.nodes[target],
        "in_edges": [
            {"from": u, "relation": G[u][v].get("relation"), **{k: v2 for k, v2 in G[u][v].items() if k not in {"relation"}}}
            for u, v in G.in_edges(target)
        ][:10],
        "out_edges": [
            {"to": v, "relation": G[u][v].get("relation"), **{k: v2 for k, v2 in G[u][v].items() if k not in {"relation"}}}
            for u, v in G.out_edges(target)
        ][:10],
    }
    print(json.dumps(info, indent=2, ensure_ascii=False))
    return 0


def cmd_ask(args: argparse.Namespace) -> int:
    from .ask import ask
    sess = _resolve_session(args)
    G = sess.to_viz_graph()
    llm = _maybe_llm(needs_llm=args.llm)
    result = ask(
        G, args.question,
        llm=llm,
        schema_entities=[e.name for e in sess.schema.entities],
        schema_relations=[r.name for r in sess.schema.relations],
    )
    print(json.dumps(result, indent=2, ensure_ascii=False))
    return 0


def cmd_update(args: argparse.Namespace) -> int:
    sess = _resolve_session(args)
    llm = _maybe_llm(needs_llm=_extractor_needs_llm(sess.extractor))
    result = sess.update(extractor=args.extractor, llm=llm, out_dir=args.out)
    _save_and_announce(
        sess,
        f"update v{result['version']} → {result['n_nodes']} nodes "
        f"(re-extracted {result['n_changed_inputs']}/{result['n_changed_inputs'] + result['n_kept_inputs']})",
    )
    print(json.dumps(result, indent=2, ensure_ascii=False))
    return 0


def cmd_versions(args: argparse.Namespace) -> int:
    from .temporal import list_versions
    out_root = Path(args.out_root) if args.out_root else _sessions_dir(args.sessions_dir).parent
    versions = list_versions(out_root)
    if not versions:
        print(f"(no versions in {out_root})")
        return 0
    for v in versions:
        ts = time.strftime("%Y-%m-%d %H:%M", time.localtime(v.created_at))
        print(f"  v{v.version}  {ts}  nodes={v.n_nodes:<6} edges={v.n_edges:<6} schema=v{v.schema_version}  {v.notes}")
    return 0


def cmd_diff(args: argparse.Namespace) -> int:
    from .temporal import diff_graphs, load_version
    out_root = Path(args.out_root) if args.out_root else _sessions_dir(args.sessions_dir).parent
    old = load_version(out_root, args.v_old)
    new = load_version(out_root, args.v_new)
    out = diff_graphs(old, new)
    print(json.dumps({
        "summary": out["summary"],
        "nodes_added":   [n["id"] for n in out["nodes"]["added"]][:50],
        "nodes_removed": [n["id"] for n in out["nodes"]["removed"]][:50],
        "nodes_modified": [m["id"] for m in out["nodes"]["modified"]][:50],
        "edges_added":   [[e["source"], e["target"], e.get("relation")] for e in out["edges"]["added"]][:50],
        "edges_removed": [[e["source"], e["target"], e.get("relation")] for e in out["edges"]["removed"]][:50],
        "n_nodes_modified": len(out["nodes"]["modified"]),
        "n_edges_modified": len(out["edges"]["modified"]),
    }, indent=2, ensure_ascii=False))
    return 0


def cmd_federate(args: argparse.Namespace) -> int:
    from .federate import federate_files
    llm = _maybe_llm(needs_llm=args.llm)
    out = federate_files(
        args.graphs, fuzzy=args.fuzzy,
        fuzzy_threshold=args.fuzzy_threshold,
        llm_tiebreak=llm if args.llm else None,
        out_path=args.out,
    )
    summary = out["linking_report"]
    print(json.dumps({
        "out_path": args.out,
        **summary,
    }, indent=2, ensure_ascii=False))
    return 0


def cmd_eval(args: argparse.Namespace) -> int:
    from .quality import write_report

    if args.graph:
        graph = json.loads(Path(args.graph).read_text())
        schema = None
    else:
        sess = _resolve_session(args)
        # Use the accepted graph (mirrors what `run` writes to disk).
        graph = sess.accepted
        schema = sess.schema

    llm = _maybe_llm(needs_llm=args.llm)
    paths = write_report(
        graph,
        out_dir=args.out_dir,
        schema=schema,
        llm=llm,
        judge_n=args.judge_n,
    )
    print(json.dumps({k: str(v) for k, v in paths.items()}, indent=2, ensure_ascii=False))
    return 0


def cmd_presets(args: argparse.Namespace) -> int:
    rows = list_presets()
    if not rows:
        print("(no built-in presets)")
        return 0
    width = max(len(r["name"]) for r in rows)
    for r in rows:
        desc = r["description"][:120]
        print(f"  {r['name']:<{width}}  {desc}")
    return 0


def cmd_extractors(args: argparse.Namespace) -> int:
    rows = list_extractors()
    width = max(len(m.name) for m in rows)
    for m in rows:
        flag = "[LLM] " if m.needs_llm else "      "
        handles = ",".join(sorted(set(m.handles)))[:40]
        print(f"  {flag}{m.name:<{width}}  v{m.version}  ({handles})  {m.description}")
    return 0


def cmd_sessions(args: argparse.Namespace) -> int:
    sd = _sessions_dir(args.sessions_dir)
    if not sd.exists():
        print(f"No sessions dir at {sd}.")
        return 0
    current = _read_current(sd)
    files = sorted(sd.glob("sess_*.json"))
    if not files:
        print(f"(no sessions in {sd})")
        return 0
    for p in files:
        try:
            data = json.loads(p.read_text())
        except Exception:
            continue
        sid = data.get("id", p.stem)
        marker = "*" if sid == current else " "
        n_inputs = len(data.get("inputs") or [])
        status = data.get("status", "?")
        schema_name = (data.get("schema") or {}).get("name", "?")
        print(f"  {marker} {sid}  inputs={n_inputs:<4} status={status:<10} schema={schema_name}")
    return 0


def cmd_use(args: argparse.Namespace) -> int:
    sd = _sessions_dir(args.sessions_dir)
    sid = args.session_id
    if not (sd / f"{sid}.json").exists():
        print(f"Session {sid} not found in {sd}", file=sys.stderr)
        return 1
    _write_current(sd, sid)
    print(f"Active session: {sid}")
    return 0


def cmd_repl(args: argparse.Namespace) -> int:
    sd = _sessions_dir(args.sessions_dir)
    inputs = list(_expand_inputs(args.inputs)) if args.inputs else []
    if inputs:
        budget = _budget_from_args(args)
        sess = open_session(
            inputs,
            preset=args.preset,
            extractor=args.extractor,
            sessions_dir=sd,
            budget=budget,
        )
        _write_current(sd, sess.id)
    else:
        sess = _resolve_session(args)

    return _run_repl(sess, sessions_dir=sd)


# ---------------------------------------------------------------------------
# REPL
# ---------------------------------------------------------------------------


_REPL_HELP = """\
Commands (each maps to one Session verb):
  schema                 print current schema
  propose [N]            ask LLM (or rule pick) for an initial schema
  refine "<text>"        edit schema (regex first, LLM fallback)
  sample [N]             extract from first N inputs into pending
  review accept-all      promote all pending to accepted
  review accept ID...    accept specific nodes
  review reject ID ...   reject specific nodes
  review merge a,b[,c]   merge nodes
  run [DIR]              full run, write graph.json
  render FMT [PATH]      render current graph (html/svg/mermaid/ascii/json)
  explain TARGET         node id, label, or "src → rel → tgt"
  status                 show session status + counts
  presets / extractors   list built-ins
  cost                   show running cost log
  llm on|off             toggle LLM use for this REPL turn
  help / ?               show this help
  quit / exit            leave the REPL
"""


def _run_repl(sess: Session, *, sessions_dir: Path) -> int:
    print(f"graphanything REPL — session {sess.id}  (type 'help')")
    use_llm = bool(
        os.environ.get("GA_API_KEY")
        or os.environ.get("OPENAI_API_KEY")
        or os.environ.get("API_KEY")
    )

    try:
        from prompt_toolkit import PromptSession
        from prompt_toolkit.history import InMemoryHistory
        ptk_sess: Any = PromptSession(history=InMemoryHistory())
        def _readline(prompt: str) -> str:
            return ptk_sess.prompt(prompt)
    except ImportError:
        def _readline(prompt: str) -> str:
            return input(prompt)

    while True:
        prompt_str = f"[{sess.status}] {sess.id} > "
        try:
            line = _readline(prompt_str).strip()
        except (EOFError, KeyboardInterrupt):
            print()
            break
        if not line:
            continue

        try:
            cont = _repl_dispatch(line, sess, use_llm)
        except SystemExit:
            raise
        except Exception as e:
            print(f"!! {type(e).__name__}: {e}")
            continue

        if cont is False:
            break

        # Reload state on disk so any sub-tool that touched the file (rare)
        # doesn't desync; cheap because save() is idempotent JSON write.
        sess.save()

    sess.save()
    return 0


def _repl_dispatch(line: str, sess: Session, use_llm: bool) -> bool | None:
    """One REPL command. Returns False to exit; None / True to continue."""
    parts = line.split(None, 1)
    cmd = parts[0].lower()
    rest = parts[1] if len(parts) > 1 else ""

    if cmd in {"quit", "exit", ":q"}:
        return False
    if cmd in {"help", "?"}:
        print(_REPL_HELP)
        return None
    if cmd == "status":
        print(json.dumps({
            "id": sess.id, "status": sess.status,
            "inputs": len(sess.inputs),
            "schema": sess.schema.name,
            "schema_version": sess.schema.version,
            "entities": [e.name for e in sess.schema.entities],
            "relations": [r.name for r in sess.schema.relations],
            "accepted": len(sess.accepted.get("nodes", [])),
            "pending": len(sess.pending.get("nodes", [])),
            "rejected": len(sess.rejected.get("nodes", [])),
        }, indent=2, ensure_ascii=False))
        return None
    if cmd == "schema":
        print(json.dumps(sess.schema.to_dict(), indent=2, ensure_ascii=False))
        return None
    if cmd == "presets":
        for r in list_presets():
            print(f"  {r['name']}  {r['description'][:80]}")
        return None
    if cmd == "extractors":
        for m in list_extractors():
            print(f"  {m.name:<14} v{m.version}  {m.description}")
        return None
    if cmd == "cost":
        from dataclasses import asdict
        print(json.dumps(asdict(sess.cost), indent=2, ensure_ascii=False))
        return None
    if cmd == "llm":
        if rest in {"on", "off"}:
            # NB: the function-local `use_llm` is unused by callers; we mutate
            # the session record so future REPL commands persist the toggle.
            sess.budget = sess.budget or {}
            sess.budget["__llm_enabled"] = (rest == "on")
            print(f"llm = {rest}")
        else:
            print(f"llm = {'on' if (sess.budget or {}).get('__llm_enabled', use_llm) else 'off'}")
        return None
    if cmd == "propose":
        n = int(rest) if rest.isdigit() else 3
        llm = _maybe_llm(use_llm) if (sess.budget or {}).get("__llm_enabled", use_llm) else None
        schema = sess.propose(n_samples=n, auto_accept=True, llm=llm)
        print(f"schema = {schema.name}: {len(schema.entities)} entities, {len(schema.relations)} relations")
        return None
    if cmd == "refine":
        instr = rest.strip().strip('"').strip("'")
        if not instr:
            print("Usage: refine \"<instruction>\"")
            return None
        llm = _maybe_llm(use_llm) if (sess.budget or {}).get("__llm_enabled", use_llm) else None
        sess.refine(instr, llm=llm)
        print(f"schema v{sess.schema.version}: {[e.name for e in sess.schema.entities]}")
        return None
    if cmd == "sample":
        n = int(rest) if rest.isdigit() else 5
        llm = _maybe_llm(_extractor_needs_llm(sess.extractor))
        summary = sess.sample(n=n, llm=llm)
        print(f"sample: {summary['n_nodes']} nodes, {summary['n_edges']} edges, "
              f"{len(summary['suggested_merges'])} suggested merges")
        for note in summary.get("notes") or []:
            print(f"  ! {note}")
        return None
    if cmd == "review":
        return _repl_review(rest, sess)
    if cmd == "run":
        out_dir = rest.strip() or None
        llm = _maybe_llm(_extractor_needs_llm(sess.extractor))
        result = sess.run(llm=llm, out_dir=out_dir)
        print(f"done: {result['n_nodes']} nodes, {result['n_edges']} edges → {result['out_path']}")
        return None
    if cmd == "render":
        toks = rest.split()
        if not toks:
            print("Usage: render <fmt> [out_path]")
            return None
        fmt = toks[0]
        out_path = toks[1] if len(toks) > 1 else None
        out = render(sess.to_viz_graph(), fmt=fmt, out_path=out_path)
        if isinstance(out, Path):
            print(str(out))
        else:
            print(out)
        return None
    if cmd == "explain":
        target = rest.strip()
        if not target:
            print("Usage: explain <node_id|label|src → rel → tgt>")
            return None
        G = sess.to_viz_graph()
        if target in G.nodes:
            print(json.dumps({"id": target, **G.nodes[target]}, indent=2, ensure_ascii=False))
        else:
            print(f"No node {target!r}.")
        return None

    print(f"?? unknown command: {cmd!r} (try 'help')")
    return None


def _repl_review(rest: str, sess: Session) -> bool | None:
    parts = rest.split()
    if not parts:
        print("Usage: review accept-all | accept ID... | reject ID... | merge a,b[,c]")
        return None
    sub = parts[0].lower()
    if sub == "accept-all":
        sess.review([{"op": "accept_all"}])
        print(f"all pending promoted; accepted = {len(sess.accepted['nodes'])} nodes")
        return None
    if sub == "accept":
        ids = parts[1:]
        if not ids:
            print("Usage: review accept ID...")
            return None
        sess.review([{"op": "accept", "node_ids": ids}])
        print(f"accepted = {len(sess.accepted['nodes'])} nodes")
        return None
    if sub == "reject":
        ids = parts[1:]
        if not ids:
            print("Usage: review reject ID...")
            return None
        sess.review([{"op": "reject", "node_ids": ids, "reason": ""}])
        print(f"rejected = {len(sess.rejected['nodes'])} nodes")
        return None
    if sub == "merge":
        if len(parts) < 2:
            print("Usage: review merge a,b[,c]")
            return None
        ids = [s.strip() for s in parts[1].split(",") if s.strip()]
        if len(ids) < 2:
            print("Need at least two ids to merge.")
            return None
        sess.review([{"op": "merge", "node_ids": ids, "into": ids[0]}])
        print(f"merged {len(ids)} → {ids[0]}")
        return None
    print(f"?? unknown review op: {sub!r}")
    return None


# ---------------------------------------------------------------------------
# Misc helpers
# ---------------------------------------------------------------------------


def _expand_inputs(patterns: Iterable[str]) -> Iterable[str]:
    """Expand globs and walk directories shallowly into individual files."""
    seen: set[str] = set()
    for p in patterns:
        path = Path(p)
        if any(ch in p for ch in "*?[]"):
            # Glob support
            from glob import glob as _glob
            for hit in _glob(p, recursive=True):
                if hit not in seen:
                    seen.add(hit)
                    yield hit
            continue
        if path.is_dir():
            # For directories, callers usually want the dir itself (fstree) or
            # all contained files (markdown / openapi / etc). Disambiguate by
            # passing the dir; the fstree extractor handles dirs specially,
            # other extractors will be given each file individually.
            if str(path) not in seen:
                seen.add(str(path))
                yield str(path)
            continue
        if path.exists():
            if str(path) not in seen:
                seen.add(str(path))
                yield str(path)


def _extractor_needs_llm(name: str | None) -> bool:
    if not name:
        return False
    try:
        from .extractors import get_extractor
        return get_extractor(name).needs_llm
    except Exception:
        return False


def _budget_from_args(args) -> dict[str, Any] | None:
    out: dict[str, Any] = {}
    if getattr(args, "max_tokens", None):
        out["max_tokens"] = int(args.max_tokens)
    if getattr(args, "max_dollars", None):
        out["max_dollars"] = float(args.max_dollars)
    if getattr(args, "max_api_calls", None):
        out["max_api_calls"] = int(args.max_api_calls)
    return out or None


# ---------------------------------------------------------------------------
# argparse wiring
# ---------------------------------------------------------------------------


def _build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        prog="graphanything",
        description="Turn anything into a knowledge graph. "
                    "10 schema presets, 8 extractors (rule + LLM + VLM stub), human/Claude review loop.",
    )
    p.add_argument("--version", action="version", version="graphanything 0.1.0")
    p.add_argument("--sessions-dir", default=str(DEFAULT_SESSIONS_DIR),
                   help="Where Session JSONs live (default: graphanything-out/sessions/).")
    p.add_argument("--session", default=None, help="Override the active session id.")

    sub = p.add_subparsers(dest="cmd", required=False)

    # new
    p_new = sub.add_parser("new", help="Open a new session over inputs.")
    p_new.add_argument("inputs", nargs="+")
    p_new.add_argument("--preset", default=None)
    p_new.add_argument("--extractor", default=None)
    p_new.add_argument("--auto", action="store_true",
                       help="propose+run end-to-end; skip interactive review.")
    p_new.add_argument("--out", default=None, help="Write graph.json under here (only with --auto).")
    p_new.add_argument("--max-tokens", type=int, default=None)
    p_new.add_argument("--max-dollars", type=float, default=None)
    p_new.add_argument("--max-api-calls", type=int, default=None)
    p_new.set_defaults(func=cmd_new)

    # propose / refine / sample / review / run
    p_prop = sub.add_parser("propose", help="Suggest an initial schema.")
    p_prop.add_argument("--n", type=int, default=3)
    p_prop.add_argument("--llm", action="store_true", help="Use the LLM to propose (otherwise generic / rule-derived).")
    p_prop.set_defaults(func=cmd_propose)

    p_ref = sub.add_parser("refine", help="Edit the schema with one instruction.")
    p_ref.add_argument("instruction")
    p_ref.add_argument("--llm", action="store_true", help="Allow LLM fallback when regex misses.")
    p_ref.set_defaults(func=cmd_refine)

    p_smp = sub.add_parser("sample", help="Extract from N inputs into pending.")
    p_smp.add_argument("--n", type=int, default=5)
    p_smp.add_argument("--extractor", default=None)
    p_smp.set_defaults(func=cmd_sample)

    p_rev = sub.add_parser("review", help="Promote / reject pending nodes.")
    p_rev.add_argument("--accept-all", action="store_true")
    p_rev.add_argument("--accept", nargs="+", default=None)
    p_rev.add_argument("--reject", nargs="+", default=None)
    p_rev.add_argument("--merge", default=None, help="Comma-separated ids; first becomes target.")
    p_rev.add_argument("--reason", default=None)
    p_rev.set_defaults(func=cmd_review)

    p_run = sub.add_parser("run", help="Full extraction → graph.json.")
    p_run.add_argument("--extractor", default=None)
    p_run.add_argument("--out", default=None)
    p_run.set_defaults(func=cmd_run)

    # render / explain
    p_rnd = sub.add_parser("render", help="Render the current (or saved) graph.")
    p_rnd.add_argument("--fmt", default="html",
                       choices=["html", "svg", "mermaid", "ascii", "json", "canvas",
                                "timeline", "cypher", "graphml"])
    p_rnd.add_argument("--out", default=None)
    p_rnd.add_argument("--graph", default=None, help="Path to a graph.json (skip Session lookup).")
    p_rnd.add_argument("--budget-tokens", type=int, default=None,
                       help="PageRank-prune the graph to roughly this many tokens of output.")
    p_rnd.set_defaults(func=cmd_render)

    p_exp = sub.add_parser("explain", help="Show provenance for a node id / label / edge.")
    p_exp.add_argument("target")
    p_exp.set_defaults(func=cmd_explain)

    p_ask = sub.add_parser("ask", help="Natural-language query over the current graph.")
    p_ask.add_argument("question")
    p_ask.add_argument("--llm", action="store_true", help="Use LLM to translate when regex misses.")
    p_ask.set_defaults(func=cmd_ask)

    p_upd = sub.add_parser("update", help="Re-extract only inputs whose source_hash changed.")
    p_upd.add_argument("--extractor", default=None)
    p_upd.add_argument("--out", default=None)
    p_upd.set_defaults(func=cmd_update)

    p_ver = sub.add_parser("versions", help="List graph snapshots.")
    p_ver.add_argument("--out-root", default=None)
    p_ver.set_defaults(func=cmd_versions)

    p_dif = sub.add_parser("diff", help="Diff two graph versions.")
    p_dif.add_argument("v_old", type=int)
    p_dif.add_argument("v_new", type=int)
    p_dif.add_argument("--out-root", default=None)
    p_dif.set_defaults(func=cmd_diff)

    p_fed = sub.add_parser("federate", help="Combine multiple graph.json files into one universe.")
    p_fed.add_argument("graphs", nargs="+", help="Paths to graph.json files.")
    p_fed.add_argument("--out", required=True, help="Output universe.json path.")
    p_fed.add_argument("--fuzzy", action="store_true", help="Also propose fuzzy same_as edges.")
    p_fed.add_argument("--fuzzy-threshold", type=float, default=0.7)
    p_fed.add_argument("--llm", action="store_true", help="Use LLM to tie-break uncertain fuzzy matches.")
    p_fed.set_defaults(func=cmd_federate)

    p_evl = sub.add_parser("eval", help="Write a QUALITY_REPORT.md for the current session graph.")
    p_evl.add_argument("--out-dir", default="graphanything-out/quality")
    p_evl.add_argument("--graph", default=None, help="Use a graph.json directly (skip Session lookup).")
    p_evl.add_argument("--llm", action="store_true", help="Sample edges + ask LLM whether evidence supports them.")
    p_evl.add_argument("--judge-n", type=int, default=20)
    p_evl.set_defaults(func=cmd_eval)

    # listing
    sub.add_parser("presets", help="List built-in schema presets.").set_defaults(func=cmd_presets)
    sub.add_parser("extractors", help="List registered extractors.").set_defaults(func=cmd_extractors)
    sub.add_parser("sessions", help="List sessions in --sessions-dir.").set_defaults(func=cmd_sessions)

    p_use = sub.add_parser("use", help="Switch active session.")
    p_use.add_argument("session_id")
    p_use.set_defaults(func=cmd_use)

    # repl
    p_repl = sub.add_parser("repl", help="Interactive session shell.")
    p_repl.add_argument("inputs", nargs="*")
    p_repl.add_argument("--preset", default=None)
    p_repl.add_argument("--extractor", default=None)
    p_repl.add_argument("--max-tokens", type=int, default=None)
    p_repl.add_argument("--max-dollars", type=float, default=None)
    p_repl.add_argument("--max-api-calls", type=int, default=None)
    p_repl.set_defaults(func=cmd_repl)

    return p


def main(argv: list[str] | None = None) -> int:
    parser = _build_parser()
    args = parser.parse_args(argv)
    if not getattr(args, "cmd", None):
        parser.print_help()
        return 0
    return args.func(args) or 0


if __name__ == "__main__":  # pragma: no cover
    sys.exit(main())