{"openapi":"3.1.0","info":{"title":"LIUS Daoist AI Public API","version":"2026-06-25.1","description":"Public contract for LIUS Daoist AI retrieval, grounded answer generation, demo generation, governance, provenance, capabilities, manifest, schemas, self-hosting, and citation assets.","license":{"name":"Public API contract; model/dataset Apache 2.0; DaoEval assets CC0"}},"servers":[{"url":"https://lius.cc"}],"externalDocs":{"description":"Canonical LIUS LLM infrastructure page","url":"https://lius.cc/llm"},"tags":[{"name":"RAG","description":"Citation-first retrieval over published LIUS nodes."},{"name":"Answer","description":"Grounded answer drafts derived from RAG context."},{"name":"Generate","description":"Demo LLM generation tasks backed by the public RAG contract."},{"name":"Evidence","description":"Machine-readable manifest and citation assets."}],"paths":{"/api/llm-rag":{"get":{"tags":["RAG"],"summary":"Retrieve published LIUS nodes for a query","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"n","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":8,"default":5}},{"name":"types","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"RAG payload","content":{"application/json":{"schema":{"type":"object","properties":{"api_version":{"type":"string","example":"llm-rag-v2"},"mode":{"type":"string","example":"node_search_trigram"},"q":{"type":"string"},"terms":{"type":"array","items":{"type":"string"}},"expanded_terms":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"count":{"type":"integer"},"hits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","example":"deity"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"summary":{"type":"string"},"content":{"type":"string"},"score":{"type":"number"},"citation":{"type":"string"},"source_type":{"type":"string"},"source_label":{"type":"string"}}}},"context_blocks":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string","example":"[1]"},"title":{"type":"string"},"type":{"type":"string"},"url":{"type":"string","format":"uri"},"text":{"type":"string"}}}},"failure_kind":{"type":"string","example":"none"},"not_found":{"type":"boolean"},"answerability":{"type":"object"},"retrieval_policy":{"type":"object"}}}}}}}},"post":{"tags":["RAG"],"summary":"Retrieve published LIUS nodes for a query","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"string","minLength":1,"maxLength":300,"example":"城隍 職司"},"n":{"type":"integer","minimum":1,"maximum":8,"default":5},"types":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"string","example":"deity,paper"}],"description":"Optional LIUS node type filter."}}}}}},"responses":{"200":{"description":"RAG payload","content":{"application/json":{"schema":{"type":"object","properties":{"api_version":{"type":"string","example":"llm-rag-v2"},"mode":{"type":"string","example":"node_search_trigram"},"q":{"type":"string"},"terms":{"type":"array","items":{"type":"string"}},"expanded_terms":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"count":{"type":"integer"},"hits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","example":"deity"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"summary":{"type":"string"},"content":{"type":"string"},"score":{"type":"number"},"citation":{"type":"string"},"source_type":{"type":"string"},"source_label":{"type":"string"}}}},"context_blocks":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string","example":"[1]"},"title":{"type":"string"},"type":{"type":"string"},"url":{"type":"string","format":"uri"},"text":{"type":"string"}}}},"failure_kind":{"type":"string","example":"none"},"not_found":{"type":"boolean"},"answerability":{"type":"object"},"retrieval_policy":{"type":"object"}}}}}}}},"options":{"tags":["RAG"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm-rag/answer":{"get":{"tags":["Answer"],"summary":"Get a deterministic grounded answer draft","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"n","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":6,"default":4}},{"name":"types","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Grounded answer payload"}}},"post":{"tags":["Answer"],"summary":"Get a deterministic grounded answer draft","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"string","minLength":1,"maxLength":300,"example":"城隍 職司"},"n":{"type":"integer","minimum":1,"maximum":8,"default":5},"types":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"string","example":"deity,paper"}],"description":"Optional LIUS node type filter."}}}}}},"responses":{"200":{"description":"Grounded answer payload"}}},"options":{"tags":["Answer"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm-rag/feedback":{"post":{"tags":["RAG"],"summary":"Submit public RAG feedback for review triage","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rating"],"properties":{"request_id":{"type":"string"},"q":{"type":"string"},"hit_id":{"type":"string"},"hit_title":{"type":"string"},"rating":{"type":"string","enum":["useful","irrelevant","wrong","citation_error","needs_alias","missing_context"]},"reason":{"type":"string"},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"Feedback accepted"},"400":{"description":"Invalid feedback payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited"}}},"options":{"tags":["RAG"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/generate":{"post":{"tags":["Generate"],"summary":"Run LIUS demo generation tasks","description":"Narrative, publishing, and grant tasks retrieve context through /api/llm-rag before LLM generation. The tag task analyzes a transcript directly.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["task"],"properties":{"task":{"type":"string","enum":["narrative","publishing","grant","tag"]},"topic":{"type":"string","maxLength":200,"description":"Required unless task is tag."},"transcript":{"type":"string","maxLength":5000,"description":"Required for tag task."}}}}}},"responses":{"200":{"description":"Generation payload with request_id, output, citations, context_blocks, and retrieval_policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResponse"}}}},"400":{"description":"bad_json, invalid_task, topic_required, transcript_required, or length violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"RAG rate limited"},"502":{"description":"RAG retrieve failed"},"503":{"description":"LLM provider failed"}}},"options":{"tags":["Generate"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/infrastructure-manifest":{"get":{"tags":["Evidence"],"summary":"Machine-readable LIUS LLM infrastructure manifest","responses":{"200":{"description":"Manifest JSON"}}}},"/api/llm/capabilities.json":{"get":{"tags":["Evidence"],"summary":"Single machine-readable LLM capability map","responses":{"200":{"description":"Capabilities JSON"}}},"options":{"tags":["Evidence"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/governance.json":{"get":{"tags":["Evidence"],"summary":"Governance, review, correction, release, and independence policy","responses":{"200":{"description":"Governance JSON"}}},"options":{"tags":["Evidence"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/evaluation-gate.json":{"get":{"tags":["Evidence"],"summary":"Machine-readable official leaderboard promotion gates","responses":{"200":{"description":"Evaluation gate JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationGate"}}}}}},"options":{"tags":["Evidence"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/daoeval-manifest.json":{"get":{"tags":["Evidence"],"summary":"DaoEval count policy, public artifacts, and local integrity manifest","responses":{"200":{"description":"DaoEval manifest JSON"}}},"options":{"tags":["Evidence"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/rag-contract.json":{"get":{"tags":["Evidence"],"summary":"RAG contract, failure modes, answerability, and citation semantics","responses":{"200":{"description":"RAG contract JSON"}}},"options":{"tags":["Evidence"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/schemas.json":{"get":{"tags":["Evidence"],"summary":"JSON Schema collection for LIUS LLM public contracts","responses":{"200":{"description":"Schemas JSON"}}},"options":{"tags":["Evidence"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/provenance.json":{"get":{"tags":["Evidence"],"summary":"Public lineage for source corpus, retrieval, evaluation, governance, and self-host boundaries","responses":{"200":{"description":"Provenance JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Provenance"}}}}}},"options":{"tags":["Evidence"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/citation-graph.json":{"get":{"tags":["Evidence"],"summary":"Machine-readable graph from benchmark/registry claims to declared source references","responses":{"200":{"description":"Citation graph JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationGraph"}}}}}},"options":{"tags":["Evidence"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/changelog.json":{"get":{"tags":["Evidence"],"summary":"Public changelog and curated errata for LLM contracts","responses":{"200":{"description":"Changelog JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Changelog"}}}}}},"options":{"tags":["Evidence"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/self-host.json":{"get":{"tags":["Evidence"],"summary":"Self-host and no-network guide for LIUS LLM public contracts","responses":{"200":{"description":"Self-host guide JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelfHostGuide"}}}}}},"options":{"tags":["Evidence"],"summary":"CORS preflight","responses":{"204":{"description":"CORS headers"}}}},"/api/llm/benchmark.jsonl":{"get":{"tags":["Evidence"],"summary":"DaoEval v0.1 public benchmark questions as JSONL","parameters":[{"name":"suite","in":"query","required":false,"schema":{"type":"string","example":"core-v0.1"}},{"name":"layer","in":"query","required":false,"schema":{"type":"string","example":"L6"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"NDJSON question records","content":{"application/x-ndjson":{"schema":{"type":"string"}}}}}}},"/api/llm/leaderboard.json":{"get":{"tags":["Evidence"],"summary":"DaoEval leaderboard JSON with draft/official gates","responses":{"200":{"description":"Leaderboard JSON"}}}},"/api/llm/runner-spec.json":{"get":{"tags":["Evidence"],"summary":"Reproducible runner and grader specification","responses":{"200":{"description":"Runner spec JSON"}}}},"/api/llm/whitepaper-md":{"get":{"tags":["Evidence"],"summary":"DaoEval whitepaper Markdown","responses":{"200":{"description":"Markdown"}}}},"/api/llm/whitepaper-bibtex":{"get":{"tags":["Evidence"],"summary":"DaoEval BibTeX citation","responses":{"200":{"description":"BibTeX"}}}},"/api/llm/whitepaper-ris":{"get":{"tags":["Evidence"],"summary":"DaoEval RIS citation","responses":{"200":{"description":"RIS"}}}},"/api/llm/whitepaper-csl-json":{"get":{"tags":["Evidence"],"summary":"DaoEval CSL JSON citation","responses":{"200":{"description":"CSL JSON"}}}},"/api/llm/dataset-sample":{"get":{"tags":["Evidence"],"summary":"DaoEval sample JSONL","responses":{"200":{"description":"JSONL sample"}}}},"/CITATION.cff":{"get":{"tags":["Evidence"],"summary":"Citation File Format record","responses":{"200":{"description":"CITATION.cff"}}}},"/api/llm/openapi.json":{"get":{"tags":["Evidence"],"summary":"OpenAPI contract","responses":{"200":{"description":"OpenAPI 3.1 JSON"}}}}},"components":{"schemas":{"ErrorEnvelope":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}},"required":["error"],"additionalProperties":true},"RagRequest":{"type":"object","required":["q"],"properties":{"q":{"type":"string","minLength":1,"maxLength":300},"n":{"type":"integer","minimum":1,"maximum":8},"types":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"string","description":"Comma-separated LIUS node types."}]}},"additionalProperties":true},"RagHit":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"summary":{"type":"string"},"content":{"type":"string"},"score":{"type":"number"},"citation":{"type":"string"},"source_type":{"type":"string"},"source_label":{"type":"string"}},"required":["id","name","type","url"],"additionalProperties":true},"ContextBlock":{"type":"object","properties":{"ref":{"type":"string","example":"[1]"},"title":{"type":"string"},"type":{"type":"string"},"url":{"type":"string","format":"uri"},"text":{"type":"string"}},"required":["ref","title","type","url","text"],"additionalProperties":true},"RagResponse":{"type":"object","properties":{"api_version":{"type":"string","example":"llm-rag-v2"},"mode":{"type":"string","example":"node_search_trigram"},"q":{"type":"string"},"terms":{"type":"array","items":{"type":"string"}},"expanded_terms":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"count":{"type":"integer"},"hits":{"type":"array","items":{"$ref":"#/components/schemas/RagHit"}},"context_blocks":{"type":"array","items":{"$ref":"#/components/schemas/ContextBlock"}},"query_analysis":{"type":"object"},"suggested_queries":{"type":"array","items":{"type":"string"}},"failure_kind":{"type":"string","enum":["none","empty_query","too_short","unsupported_language","not_found","timeout","db_error"]},"not_found":{"type":"boolean"},"message":{"type":"string"},"answerability":{"type":"object"},"retrieval_policy":{"type":"object"}},"required":["api_version","mode","q","count","hits","context_blocks","failure_kind","not_found","answerability","retrieval_policy"],"additionalProperties":true},"AnswerResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"api_version":{"type":"string"},"q":{"type":"string"},"request_id":{"type":"string"},"grounded":{"type":"boolean"},"answer":{"type":"string"},"citations":{"type":"array","items":{"type":"object"}},"evidence":{"type":"array","items":{"type":"object"}},"limitations":{"type":"array","items":{"type":"string"}},"confidence":{"type":"string"},"retrieve":{"type":"object"}},"additionalProperties":true},"GenerateRequest":{"type":"object","required":["task"],"properties":{"task":{"type":"string","enum":["narrative","publishing","grant","tag"]},"topic":{"type":"string","maxLength":200},"transcript":{"type":"string","maxLength":5000}},"additionalProperties":false},"GenerateResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"api_version":{"type":"string","example":"llm-generate-v2"},"task":{"type":"string"},"topic":{"type":"string"},"transcript_chars":{"type":"integer"},"request_id":{"type":"string"},"output":{"type":"string"},"provider":{"type":"string"},"hits":{"type":"array","items":{"type":"object"}},"citations":{"type":"array","items":{"type":"object"}},"context_blocks":{"type":"array","items":{"$ref":"#/components/schemas/ContextBlock"}},"retrieval_policy":{"type":"object"},"retrieve":{"type":"object"},"latency_ms":{"type":"integer"}},"additionalProperties":true},"BenchmarkQuestion":{"type":"object","properties":{"schema_version":{"type":"string"},"benchmark_version":{"type":"string"},"qid":{"type":"string"},"suite":{"type":"string"},"layer":{"type":"string"},"category":{"type":"string"},"question":{"type":"string"},"expected_answer":{"type":"string"},"answer_aliases":{"type":"array","items":{"type":"string"}},"source_refs":{"type":"array","items":{}},"rubric":{},"license":{"type":"string"}},"required":["schema_version","qid","suite","layer","question","expected_answer","license"],"additionalProperties":true},"Leaderboard":{"type":"object","properties":{"schema_version":{"type":"string"},"api_version":{"type":"string"},"status":{"type":"string"},"count_policy":{"type":"object"},"score_formula":{"type":"string"},"gates":{"type":"object"},"runs":{"type":"object"},"target_models":{"type":"array","items":{"type":"object"}}},"required":["schema_version","status","gates","runs"],"additionalProperties":true},"EvaluationGate":{"type":"object","properties":{"schema_version":{"type":"string"},"official_promotion_allowed":{"type":"boolean"},"gates":{"type":"array","items":{"type":"object"}},"unlock_sequence":{"type":"array","items":{"type":"string"}},"artifacts":{"type":"object"}},"required":["schema_version","official_promotion_allowed","gates"],"additionalProperties":true},"CitationGraph":{"type":"object","properties":{"schema_version":{"type":"string"},"version":{"type":"string"},"as_of":{"type":"string"},"counts":{"type":"object"},"citation_status_legend":{"type":"object"},"claim_nodes":{"type":"array","items":{"type":"object"}},"source_nodes":{"type":"array","items":{"type":"object"}},"edges":{"type":"array","items":{"type":"object"}}},"required":["schema_version","counts","claim_nodes","source_nodes","edges"],"additionalProperties":true},"Provenance":{"type":"object","properties":{"schema_version":{"type":"string"},"version":{"type":"string"},"canonical_home":{"type":"string","format":"uri"},"public_lineage":{"type":"array","items":{"type":"object"}},"reproducibility":{"type":"object"},"current_counts":{"type":"object"},"leaderboard_status":{"type":"object"}},"required":["schema_version","version","public_lineage","reproducibility"],"additionalProperties":true},"Changelog":{"type":"object","properties":{"schema_version":{"type":"string"},"version":{"type":"string"},"as_of":{"type":"string"},"policy":{"type":"object"},"entries":{"type":"array","items":{"type":"object"}},"errata":{"type":"array","items":{"type":"object"}}},"required":["schema_version","entries","errata"],"additionalProperties":true},"SelfHostGuide":{"type":"object","properties":{"schema_version":{"type":"string"},"version":{"type":"string"},"goal":{"type":"string"},"public_artifacts":{"type":"object"},"minimal_offline_commands":{"type":"array","items":{"type":"string"}},"local_model_runtime":{"type":"array","items":{"type":"string"}},"no_network_boundary":{"type":"object"}},"required":["schema_version","public_artifacts","minimal_offline_commands","no_network_boundary"],"additionalProperties":true},"OfflineScoreSummary":{"type":"object","properties":{"schema_version":{"type":"string"},"benchmark_run_id":{"type":"string"},"scorer":{"type":"object"},"counts":{"type":"object"},"metrics":{"type":"object"},"verification_status":{"type":"string"}},"required":["schema_version","scorer","counts","metrics","verification_status"],"additionalProperties":true},"LlmCapabilityMap":{"type":"object","properties":{"schema_version":{"type":"string"},"version":{"type":"string"},"service":{"type":"object"},"status":{"type":"object"},"counts":{"type":"object"},"capabilities":{"type":"array","items":{"type":"object"}},"artifacts":{"type":"object"}},"required":["schema_version","version","service","status","capabilities","artifacts"],"additionalProperties":true}}}}