Graph Query And Explanation

Graph query and explanation

Turn a question into the smallest safe read plan, execute it, and return an answer that separates evidence from inference.

Choose the route

1. Use graph_ask for an ordinary natural-language question.
2. Use ask_data for a bounded multi-step data question that needs query planning, execution, and correction.
3. Use graph_search for local discovery and graph_federated_search across registered external graph references; add graph_search_synthesis only when the user wants a synthesized answer over several results.
4. Use graph_query for an explicit read-only Cypher or UQL query. Use nl_query when the request needs query planning but no query was supplied.
5. Use graph_code or graph_code_nav for symbols, callers, definitions, and impact. Use graph_document_tree for document structure.
6. Use graph_analyze, graph_explain, graph_evaluate, or graph_epistemic when the answer needs diagnosis, confidence, disagreement, or provenance.
7. Use graph_table, graph_promql, or graph_gis for tabular, metric, or spatial reads.

If the task spans several routes or needs independent verification, delegate through graph_agents and require a final evidence synthesis. Keep a single bounded lookup direct.

Action reference

Epistemic answers — confidence, provenance, and "why do we believe this"

A plain graph_query/graph_ask gives you rows. Four engine_query actions layer the engine's epistemic currency on top, progressively deeper and progressively more feature-gated (call directly, or through the graph_epistemic wrapper above):

1. explain_provenance_by_ids (CONCEPT:AU-KG.memory.knowledge-currency / Seam 1) — take any id list from a prior read and "upgrade" it to calibrated, cited, time-versioned rows (confidence, valid_time, tx_time, source_refs, policy_labels, evidence_spans). In the default full build already. include_epistemic=true on graph_query/graph_ask (Cypher dialect) skips this two-step dance — each row is already an EpistemicRow.
2. explain_belief — the full JustificationGraph rooted at a node: rule is one of Asserted/DerivedSupport/DerivedContradiction/BayesianUpdate. Also in full. Pass disclosure_level (Full/Skeleton/ExistenceOnly) for policy-aware redaction.
3. epistemic_status (what do we believe, why, under whose authority, what would invalidate it) and what_changed (a whole-graph bitemporal diff between two transaction times) — require the opt-in epistemic-tms engine feature, not in the default full build. A {"error": ...} means "capstone unavailable here," not a crash. epistemic_status's own why_not (why is this claim NOT believed — Unknown / InsufficientConfidence / Contradicted / Undecided) and what_would_invalidate (the minimal evidence set whose retraction would flip belief) fields are ALSO reachable as their own dedicated graph_epistemic actions (action="why_not" / action="what_would_invalidate") — a purpose-named projection of the same call, not a separate engine method.
4. explain_policy — runs a search plan against both the caller's RLS-filtered view and the unfiltered one, returning visible_ids/policy_denied_ids — use when an expected row is missing and you need to know whether policy hid it.

Evidence citation — engine_query(action="explain_evidence") walks the same support/contradiction/attack topology as explain_belief, but returns every transitively-reachable located evidence locus instead (11 EvidenceSpan kinds: DocumentSpan, PageBox, CodeSymbol, AudioSegment, TraceSpan, …) plus the AssetOccurrence/Blob identity chain. Requires the opt-in evidence-graph engine feature; every locus resolves to a real CAS-digest reference, never a fabricated excerpt.

Compiled context bundles

graph_search(mode="compiled") reuses the same engine ANN/hybrid retriever every other search mode calls, but additionally MMR-diversifies the candidate set, scores evidence quality from the KnowledgeBatch-shaped epistemic columns (degrading to a neutral prior when absent, never fabricated), weighs bi-temporal freshness, enforces the token budget (logging every drop — token_budget=0, the default, uses the compiler's own internal budget rather than an unbounded one), and runs the live permissioning gate on every candidate before returning citations + a proof graph + a decisions log. Same candidates + session ⇒ same bundle deterministically (diffable for audit/benchmark); as_of compiles a bundle as-of a past point in time. Returns a formatted text bundle, not structured JSON — parse the citations/proof-graph/decisions sections out of it if you need them programmatically.

Workflow

1. Frame the question

• State the target, scope, time boundary, and requested output.
• Identify whether the user supplied a query or expects natural-language planning.
• Treat ambiguous entity names as search terms before using them as identifiers.

2. Retrieve narrowly

• Start with the most selective operation and a bounded result count.
• Keep reads tenant- and graph-scoped when that context is available.
• Request only fields needed for the answer.
• Do not turn a read request into a write, ingestion, or workflow execution.

Example direct plan:

graph_search(query="sample service dependency", mode="hybrid", top_k=8)
graph_query(cypher="MATCH (s:Service {id: $id})-[:DEPENDS_ON]->(d) RETURN d.id", params='{"id":"sample-service"}')

3. Cross-check important claims

• Confirm a semantic match with a structural query when feasible.
• Use graph_epistemic or graph_evaluate when sources conflict.
• Preserve returned citations, node identifiers, confidence, and time context.
• Label any conclusion not directly returned by a source as an inference.

4. Report

Return:

1. the concise answer;
2. the supporting evidence or citations;
3. uncertainty, conflicts, and material gaps;
4. the query or retrieval route used when reproducibility matters.

Use an economy model for bounded retrieval, filtering, and formatting. Escalate only when evidence conflicts, causal judgment is requested, or synthesis spans multiple domains.

Guardrails

• Keep Cypher and UQL read-only.
• Parameterize identifiers and values; never interpolate untrusted text into a query.
• Do not claim that an empty result proves absence outside the queried scope.
• Do not expose hidden credentials, tokens, or unrelated tenant data.
• Stop and ask for scope when two interpretations would produce materially different answers.