"""Generate docs/CYPHER.md from the queries the tools actually execute.

    cd backend && python ../scripts/gen_cypher_doc.py

Every tool is run once with representative arguments; the Cypher it reports
(`out["cypher"]`) is written verbatim, so the catalog cannot drift from the code.
"""
from __future__ import annotations

import json
import pathlib
import re

from bidbrain.graph.client import Graph
from bidbrain.ingest.load_graph import PROJECTION_SIG, PROJECTIONS, TENDER_STATUS
from bidbrain.tools import TOOLS, call

ROOT = pathlib.Path(__file__).resolve().parents[1]

SAMPLES = {
    "resolve_entity": {"text": "phed odisha", "kind": "client"},
    "get_entity": {"key": "Ring Road — Uttar Pradesh Pkg-113", "kind": "work"},
    "find_portfolio": {"via_work": "Pkg-107", "exclude_categories": ["irrigation"]},
    "aggregate": {"work_keys": ["ringroaduttarpradeshpkg113"], "op": "sum"},
    "credential_timeline": {"person": "Sunita Joshi"},
    "date_span": {"work": "ROB — Jharkhand Pkg-29", "credential_kind": "pmp"},
    "receivables": {"client": "Arunodaya Infrastructure", "measure": "outstanding"},
    "collection_rate": {"work": "Ring Road — West Bengal Pkg-128"},
    "awarded_vs_billed": {"client": "Jal Nigam, Jharkhand"},
    "prove_absence": {"evidence": "reference_letter", "client": "Trishakti Power Generation Corporation"},
    "qualify_clause": {"kind": "similar_works", "params": {"categories": ["expressways"], "estimated_cost": 2500000000}},
    "key_people": {},
    "who_knows": {"client": "National Expressway Development Authority"},
    "explain_path": {"a": "Sunita Joshi", "a_kind": "person", "b": "Rahul Menon", "b_kind": "person"},
    "isolated_entities": {"scope": "corpus"},
    "communities": {},
    "trace_from_credential": {"person": "Sunita Joshi", "credential": "Six Sigma", "work": "Pkg-107"},
    "compliance_check": {"tender": "RFP-132000970"},
    "depends_on": {"doc_id": "DOC-CERT-001"},
    "fact_history": {"key": "Pkg-113", "kind": "work"},
    "change_impact": {"doc_id": "DOC-CC-151"},
    "fact_as_of": {"key": "anganwadicentregujaratpkg151", "predicate": "value", "as_of": "2026-10-17"},
    "vector_search": {"text": "client praised the safety record", "k": 3},
    "fulltext_search": {"text": "Anganwadi"},
    "graph_schema": {},
    "cypher_readonly": {"query": "MATCH (w:Work) RETURN count(w) AS works"},
    "precedents": {"category": "expressways"},
    "audit_bid": {},
    "blast_radius": {"label": "Person", "key": "rahulmenon", "rerun": False},
    "case_get": None,
}

EXTRA = {
    "Conflict detection & resolution (bidbrain/conflicts/engine.py)": [
        ("Claims about the same fact", "MATCH (c:Claim)-[:ABOUT]->(s) WHERE c.status <> 'superseded' AND c.status <> 'rejected'\n"
         "  AND ($keys IS NULL OR c.subject_key IN $keys)\nRETURN c.id, c.subject_key, c.predicate, c.value, c.source_kind, c.authority, c.issuer, c.observed_day"),
        ("Record a contradiction", "MATCH (a:Claim {id:$a}), (b:Claim {id:$b}) WHERE NOT (a)-[:CONTRADICTS]-(b)\n"
         "CREATE (a)-[:CONTRADICTS {rule:'value_mismatch', detected_at:$t}]->(b)"),
        ("Write a Decision (actor label is Agent or User)", "MERGE (a:Agent {key:$actor}) ON CREATE SET a.name = $actor\n"
         "CREATE (d:Decision {id:$id, key:$id, conflict_id:$cid, subject_key:$sk, predicate:$pred,\n"
         "                    policy:$policy, rationale:$why, at:timestamp(), chosen_value:$val})\n"
         "CREATE (d)-[:DECIDED_BY]->(a)\nWITH d MATCH (w:Claim {id:$win}) CREATE (d)-[:SELECTS]->(w)\n"
         "WITH d UNWIND $ids AS cid MATCH (c:Claim {id:cid}) CREATE (d)-[:BASED_ON]->(c)"),
        ("A newer decision supersedes older ones on the same fact", "MATCH (old:Decision {subject_key:$sk, predicate:$pred}) WHERE old.id <> $d\n"
         "  AND NOT ()-[:SUPERSEDES]->(old)\nWITH old MATCH (d:Decision {id:$d}) CREATE (d)-[:SUPERSEDES]->(old)"),
        ("Learn a rule from a human decision (procedural memory)", "MERGE (r:PolicyRule {id:$id}) SET r.predicate = $p, r.prefer_kind = $pk, r.over_kind = $ok\n"
         "WITH r MATCH (d:Decision {id:$d}) MERGE (r)-[:LEARNED_FROM]->(d)"),
    ],
    "Accountable actions (bidbrain/company/actions.py)": [
        ("Create an action idempotently (MERGE on a hash of kind, case, trigger, target)",
         "MERGE (a:Action {idem:$idem})\n"
         "ON CREATE SET a.id = $id, a.kind = $kind, a.status = 'pending', a.title = $title, a.detail = $detail,\n"
         "              a.owner = $owner, a.case_id = $case, a.target = $target, a.payload = $payload,\n"
         "              a.created_at = timestamp(), a.updated_at = timestamp(), a._new = true\n"
         "WITH a, coalesce(a._new, false) AS created SET a._new = null\nRETURN a.id AS id, a.status AS status, created"),
        ("Link the action to its case, trigger, evidence and owner",
         "MATCH (a:Action {id:$a}), (c:Case {id:$c}) MERGE (a)-[:FOR_CASE]->(c)\n"
         "MATCH (a:Action {id:$a}), (t:Decision {id:$t}) MERGE (a)-[:TRIGGERED_BY]->(t)      -- or (t:Finding)\n"
         "MATCH (a:Action {id:$a}), (d:Document {doc_id:$d}) MERGE (a)-[:CITES]->(d)\n"
         "MATCH (a:Action {id:$a}), (p:Person {key:$p}) MERGE (a)-[:ASSIGNED_TO]->(p)"),
        ("Lifecycle transition as compare-and-set (no row back = stale click, HTTP 409)",
         "MATCH (a:Action {id:$a}) WHERE a.status IN $frm\n"
         "SET a.status = $to, a.updated_at = timestamp(), a.decided_by = $by RETURN a.id AS id"),
        ("Audit trail", "MATCH (a:Action {id:$a})\n"
         "CREATE (a)-[:HAS_EVENT]->(:ActionEvent {at:timestamp(), from:$f, to:$t, by:$by, note:$n})"),
        ("Executor: internal document request (nothing is emailed)",
         "MERGE (r:DocumentRequest {id:$id}) ON CREATE SET r.kind = 'reference_letter', r.status = 'requested',\n"
         "    r.requested_at = timestamp(), r.requested_by = $by, r.channel = 'internal'\n"
         "WITH r MATCH (w:Work {key:$w}) MERGE (r)-[:FOR_WORK]->(w)\n"
         "WITH r MATCH (a:Action {id:$a}) MERGE (a)-[:CREATED]->(r)"),
    ],
    "Company record (bidbrain/company/record.py, graph bidbrain_org)": [
        ("Publish a decided fact (idempotent per claim)",
         "MERGE (f:OrgFact {id:$id})\n"
         "ON CREATE SET f.subject_label = $sl, f.subject_key = $sk, f.predicate = $p, f.value = $v, f.claim = $claim,\n"
         "              f.document = $doc, f.source_decision = $d, f.policy = $policy, f.source_session = $sess,\n"
         "              f.approved_by = $by, f.published_at = timestamp(), f.status = 'active'"),
        ("A newer value supersedes, never deletes",
         "MATCH (old:OrgFact {subject_key:$sk, predicate:$p, status:'active'}) WHERE old.id <> $id\n"
         "SET old.status = 'superseded', old.superseded_by = $id, old.superseded_at = timestamp()"),
        ("Apply in a workspace: write the claim, then the conflict engine settles it (policy company_record)",
         "MATCH (s:Work {key:$sk})\nMERGE (c:Claim {id:$id})\n"
         "ON CREATE SET c += $props, c.status = 'active', c.company_record = $f, c.recorded_at = timestamp()\n"
         "MERGE (c)-[:ABOUT]->(s)\nWITH c MATCH (d:Document {doc_id:$doc}) MERGE (c)-[:FROM]->(d)\n"
         "MERGE (r:CompanyRecordRef {id:$f}) SET r.applied_at = timestamp()      -- applied once per workspace"),
    ],
    "Tenancy & memory (bidbrain/api/sessions.py)": [
        ("Per-visitor graph", "GRAPH.COPY bidbrain_base session_<id>      -- Redis command, one isolated graph per visitor"),
        ("Conversation turn", "MERGE (c:Conversation {id:'main'}) WITH c OPTIONAL MATCH (c)-[:HAS_TURN]->(t:Turn)\n"
         "WITH c, count(t) AS n CREATE (c)-[:HAS_TURN]->(:Turn {i:n, role:$r, text:$t, at:timestamp()})"),
    ],
    "Analysis projections (bidbrain/ingest/load_graph.py)": [
        ("Person <-> client projection for centrality", "MATCH (p:Person)<-[:LED_BY]-(w:Work)-[:FOR_CLIENT]->(c:Client)\n"
         "WITH p, c, count(w) AS n, sum(w.value) AS v\nCREATE (p)-[:WORKED_FOR {works:n, value:v}]->(c), (c)-[:ENGAGED {works:n, value:v}]->(p)"),
        *[(f"{name} projection (communities: shared clients >= 1.5x the configuration-model expectation)",
           "\n".join(l.strip() for l in q.strip().splitlines())) for name, q in PROJECTIONS.items()],
        ("Projection freshness: OVERLAPS_CLIENTS / WORKED_FOR are rebuilt in a session whenever their inputs change "
         "(ensure_projections, called by key_people, who_knows, explain_path and communities; the base graph stores "
         "the signature at load, so a current projection is never rewritten)",
         PROJECTION_SIG.strip() + "\n-- sha1 of the list != Meta.projection_sig  ->  project(g): delete and rebuild the projections"),
        ("Tender status as of the corpus snapshot (tender_status; case_open sets 'open' in a session with a live case)",
         "\n".join(l.strip() for l in TENDER_STATUS.strip().splitlines())),
        ("Workbook provenance (found by isolated_entities scope='corpus')",
         "UNWIND $rows AS r MATCH (n:Asset {key:r.key}), (d:Document {doc_id:r.doc})\n"
         "CREATE (n)-[:EVIDENCED_BY {kind:'asset_register'}]->(d)      -- also TBLine, BOQItem, Measurement"),
        ("When each compliance claim was made", "UNWIND $rows AS r MATCH (t:Tender {key:r.tender})\n"
         "SET t.bid_date = r.bid_date, t.bid_date_basis = r.basis, t.bid_value = r.bid_value, t.matrix_doc = r.doc"),
        ("Indexes", "CREATE INDEX FOR (n:Work) ON (n.key)            -- range index on every entity key\n"
         "CALL db.idx.fulltext.createNodeIndex('Chunk', 'ft')\n"
         "CREATE VECTOR INDEX FOR (c:Chunk) ON (c.embedding) OPTIONS {dimension:384, similarityFunction:'cosine'}"),
    ],
}


def norm(q: str) -> str:
    lines = [l.rstrip() for l in q.strip("\n").splitlines()]
    ind = min((len(l) - len(l.lstrip()) for l in lines[1:] if l.strip()), default=0)
    return "\n".join([lines[0].strip()] + [l[ind:] for l in lines[1:]])


def main():
    g = Graph()
    case_id = call(g.copy_to("doc_tmp"), "case_open", {"title": "doc"})  # ensure case tools work on a copy
    Graph("doc_tmp").delete()
    out = ["# Cypher & graph algorithms BidBrain depends on", "",
           "Generated by `scripts/gen_cypher_doc.py`: every tool was executed once against `bidbrain_base` and the",
           "queries it actually ran are listed verbatim. FalkorDB dialect notes: no `EXISTS {}` subqueries (pattern",
           "predicates instead), `shortestPath` only in WITH/RETURN, dates compared as `*_day` integers.", ""]
    algos = set()
    for name in sorted(TOOLS):
        t = TOOLS[name]
        args = SAMPLES.get(name)
        if args is None:
            continue
        res = call(g, name, args)
        qs = []
        for q in res.get("cypher", []):
            q = norm(q)
            if q not in qs:
                qs.append(q)
        algos |= set(re.findall(r"algo\.\w+|db\.idx\.\w+\.\w+", " ".join(qs)))
        out += [f"## `{name}`", "", " ".join(t.description.split()), "",
                f"Example call: `{json.dumps(args, ensure_ascii=False)}` — {res.get('ms', '?')} ms", ""]
        for q in qs:
            out += ["```cypher", q, "```", ""]
    for section, items in EXTRA.items():
        out += [f"## {section}", ""]
        for title, q in items:
            out += [f"**{title}**", "", "```cypher", q, "```", ""]
    out[5:5] = ["", "**Built-in procedures used:** " + ", ".join(f"`{a}`" for a in sorted(algos)) + ", `GRAPH.COPY`, `GRAPH.RO_QUERY`", ""]
    (ROOT / "docs" / "CYPHER.md").write_text("\n".join(out))
    print("wrote docs/CYPHER.md", len(out), "lines; procedures:", sorted(algos))


if __name__ == "__main__":
    main()