Provenance & Write-back

Graphomics records why every claim in the graph exists. Analyses write back as Assertions — confidence-scored, organization-scoped statements — each linked to the Analysis, Experiment, and Decision that produced it. You can then trace any entity's lineage back through that chain.

The provenance model

text

Experiment ──HAS_ANALYSIS──▶ Analysis ──ASSERTED──▶ Assertion ──SUBJECT/OBJECT──▶ entities
                                    └──RECORDED──▶ Decision
Assertion ──SUPERSEDED_BY──▶ Assertion   (newer claims supersede older ones)

Experiment — the study or run context.
Analysis — a specific method applied within an experiment.
Assertion — a subject → predicate → object claim with a confidence, direction, evidence_refs, validity window (valid_from / valid_to), and organization_id. Its id is a deterministic hash of (analysis, subject, predicate, object), so re-recording the same finding is idempotent.
Decision — the action that produced the finding (a pipeline run, a review, a verdict), carrying the actor, rationale, and evidence.

This is what it means for the loop to close end-to-end: a pipeline result can be written back as an Assertion carrying the workflow id and the statistics behind it, then queried later as first-class provenance. See the Schema reference for the exact field lists.

Record a finding

Over MCP, provenance_record_finding writes an Experiment → Analysis → Assertion chain in one call and projects the corresponding graph edges. Its payload:

text

experiment  { id, title?, nexus_ref?, started_at?, actor_user?, actor_org? }
analysis    { id, method?, occurred_at, summary?, model?, confidence? }
assertions  [ { subject:{label,key_field,value}, predicate, object:{label,key_field,value},
                confidence, direction?, asserted_at?, valid_from?, valid_to?,
                evidence_refs?, supersedes? } ]
organization_id
decision_ids?     # optional: link this analysis to the Decision(s) that produced it

Decisions can also be ingested over REST at POST /api/v1/provenance/decisions using the DecisionEvent contract. The caller's organization_id is derived from the API key — it is never a request field.

Query lineage

Trace the experiments, analyses, assertions, and decisions behind any entity.

REST:

bash

curl -s $GRAPHOMICS_API_URL/provenance/lineage \
  -H "X-API-Key: $GRAPHOMICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity": "<entity-id-or-name>", "limit": 50}'

Response shape:

json

{
  "entity": "...",
  "as_of": null,
  "paths": [
    {
      "experiment": { "...": "..." },
      "analysis":   { "...": "..." },
      "assertion":  { "...": "..." },
      "subject":    { "...": "..." },
      "object":     { "...": "..." },
      "decisions":  [ ]
    }
  ],
  "count": 1
}

Pass an as_of timestamp for a point-in-time view (respecting assertion validity windows). Over MCP, the equivalent tool is provenance_lineage(entity, as_of=None, limit=50).

Additional decision-provenance queries are available over REST: POST /api/v1/provenance/query, /provenance/current, /provenance/as-of, /provenance/ledger, and /provenance/search.