Graph Research And Analysis

Graph research and analysis

Build a reproducible evidence set, apply the lightest suitable analysis, and separate measured results from hypotheses.

Choose the route

• Use graph_research to organize a research question and source set.
• Use graph_analyze for structural, comparative, impact, or diagnostic work.
• Use graph_mine or graph_mine_deep for associations, anomalies, and deeper discovery over an existing graph.
• Use graph_learn for supported graph-learning tasks.
• Use graph_ops_causal when an operational question requires causal evidence.
• Use graph_claims to inspect or advance the governed claim lifecycle.
• Use graph_feedback to record corrections or outcome signals.
• Use research_artifact to persist an approved report with provenance.

Keep a bounded analysis direct. Delegate a multi-source study through graph_agents when acquisition, independent analyses, critique, and synthesis can run as separate work items.

Action reference

Provenance-aware causal reasoning (do-calculus)

Two engine_query actions — pure functions over the request, no graph read; both require the opt-in epistemic-causal engine feature (not in the default full build) — distinct from graph_ops_causal above, which reasons over the REAL ingested ops entity graph:

• causal_estimate — genuine Pearl do-calculus P(· | do(X₁=x₁, …)) over a caller-supplied linear-Gaussian structural causal model (variables in topological order, each {"id", "parents": [[parent_id, weight]], "bias", "noise_var"}). do_values fixes named variables via graph surgery — incoming edges to the do-fixed variable are CUT, not conditioned on, the operationally meaningful difference from observe(X=x). Returns one calibrated {"mean", "variance", "interval", "level"} estimate per variable, in the same order as variables. Only the intervention op is wired; the engine's observe/counterfactual methods exist Rust-side but are crate-internal — no wire Method exposes a genuine counterfactual ("what WOULD have happened") from outside the engine today.
• rank_by_provenance — order caller-supplied candidates by a weighted blend of similarity AND evidence quality (source reliability, corroboration, calibration precision, freshness) so a well-sourced/well-corroborated/fresh result isn't outranked by a merely-more-similar unsourced one. weights= {"similarity": w1, "evidence_quality": w2}, default {0.5, 0.5}.

Governed mining → claim flywheel

Two pipelines mine evidence into reviewable KG facts, gated by the SAME promotion-governance + action-policy checks every autonomous action passes through — neither exposes a direct propose/accept call; both only run as a byproduct of advancing a Loop cycle (graph_loops, see graph-orchestration-and-automation):

• Claim flywheel (C4/C6) — a research Loop cycle's trace_mining+ insight_validation stages (default ON) mine Episode/ToolCall/OutcomeEvaluation provenance into Claims with a five-state lifecycle (proposed → validated → accepted → deprecated/retracted; retracted is terminal and sticky — a rejected finding is never silently re-proposed from the same content-addressed finding id on a later pass). Every transition is an append-only ClaimLifecycleEvent, never a silent mutation of the Claim's own fields. Advance a cycle with graph_loops(action="run", max_topics=5) or drive, then inspect via graph_query(cypher="MATCH (e:ClaimLifecycleEvent) WHERE e.claim_id = $id RETURN e ORDER BY e.at", params='{"id": "<claim_id>"}'). Cross-reference a resulting claim id with graph-query-and-explanation's epistemic-answer/evidence-citation tools for its justification tree and source loci. For ad hoc association-rule/clustering/ anomaly mining OUTSIDE this governance (raw discovery, not claim promotion), use graph_mine/graph_mine_deep directly instead (Action reference above).
• Placement advisor (X-5) mirrors the same pattern for infrastructure: mines agent-trace co-occurrence (tenant/tool/entity/modality access skew) into typed PlacementProposals (shard_split/replica/cache_prewarm/materialized_join/ embedding_refresh/index_change), persists each as a Claim (status="proposal", is_verified=False), validates and policy-gates it (apply_placement_change, shipped approval_required by default — nothing auto-applies), then runs a measured canary (apply small, measure the SLO delta against placement_canary_tolerance, promote or roll back). On promote, the change reaches the engine's PlacementCatalog admin path (engine_resharding — an ADMIN domain requiring the kg:admin scope, same admin surface, no second placement authority). Manual trigger for one governed pass: graph_loops(action="placement_control", placement_scan_limit=200, placement_canary_tolerance=0.10). Nothing runs this on a schedule automatically — wire it into graph_schedules (graph-orchestration-and-automation) for a continuous cadence. A stuck proposal awaiting approval is granted via graph_orchestrate(action="grant_approval", ...).

Workflow

1. Define the claim and acceptance test

• State the question, decision it informs, population, time window, and success criteria.
• List assumptions that would invalidate the result.
• Decide which outputs are descriptive, predictive, or causal.

2. Assemble evidence

• Fix the authorized tenant, graph, audience, source set, and population before retrieval or delegation.
• Reuse already-ingested evidence before acquiring more.
• Track source identity, observed time, content hash, and relevance.
• Keep contradictory evidence; do not collapse it into a single claim early.
• Bound the corpus and record why each source was included.
• Request only fields needed for the claim; exclude secrets, direct personal identifiers, private endpoints, and unrelated records, and use pseudonyms when identity is not part of the analysis.

3. Analyze

• Start with descriptive graph structure and baselines.
• Use mining or learning only when the data and task support it.
• Compare against a control, prior result, or held-out sample when possible.
• For causal conclusions, state the intervention, outcome, confounders, and identification assumptions.

4. Challenge the result

• Run an independent query or alternative method for material claims.
• Check leakage, duplicated evidence, stale data, and selection bias.
• Report uncertainty and negative results.
• Treat mined patterns and predicted links as proposals until reviewed.

5. Synthesize and persist

Return the question, method, evidence, findings, uncertainty, and recommended next action. For read-only work, stop after returning the redacted synthesis; do not call research_artifact or graph_feedback. Otherwise, persist with research_artifact only when the report is ready for reuse and authorized for its audience. Persist neutral source references, digests, and redacted findings rather than raw source content, endpoints, identities, or trace values. Record authorized corrections with graph_feedback.

Use an economy model for retrieval, extraction, deduplication, and evidence tables. Use a stronger model for adversarial critique, causal judgment, and the final synthesis.

Guardrails

• Do not fabricate measurements, citations, confidence, or source coverage.
• Do not infer causation from correlation alone.
• Preserve tenant, graph, authorization, and audience boundaries across direct and delegated work.
• Do not expose credentials, tokens, personal data, private endpoints, or unrelated records in prompts, evidence tables, reports, or artifacts.
• Keep compute and result sizes bounded.
• Do not let an analysis job's acceptance stand in for a verified result.