| queryA | Run a tag-aware semantic query against the particle store. Args:
question: Natural-language question. Optional since: omit it
and set structural claim filters (or an aggregate / the predicate
listing) for the deterministic modes — no embedding, no LLM call.
tags: Subtree-expanded tag filters, repeatable.
subject_id: Restrict to particles about this subject.
min_confidence: Minimum confidence value (0.0–1.0).
top_k: Number of particles to retrieve (1–200).
audience: "GENERAL" | "EXPERT" | "REGULATORY".
summary: When ``True``, each hit in ``particles`` is reduced to
``{id, content, confidence, effective_confidence,
subject_ids}`` — provenance, tags, properties, and
embeddings are dropped. The NL ``answer`` string and
coverage gaps are unchanged. Use this when the agent only
needs to surface the answer and pick particles to
``particle_show`` later. Default ``False`` preserves the
full ``QueryResponse`` shape for backward compatibility.
as_of: ISO-8601 past instant (a bare date means start of that
day, UTC): answer what the store believed at T.
Retired hits carry an ``as_of_notes`` entry (current status,
retirement instant + basis, and the superseding belief);
``as_of_excluded_undatable`` discloses retirements the store
cannot date. A future instant is rejected.
during_start: With ``during_end``, a window of world time (ISO-8601
dates, inclusive; either may be omitted for an open end): answer
about what began in, or was in force during, that period.
The window prefilters the candidate set before ranking;
with no question it returns the claims in date order, each with a
``window_hits`` reading (``BEGAN``, ``IN_FORCE``, ``HELD_AT``,
``WITHIN``). A retired claim is admitted for the period it held,
marked with its retirement and its close. Reads ``valid_from``;
``window_coverage`` discloses the undated and unkinded claims the
window could not judge. Resolve the anchor first ("when did the
user move?"), then ask with dates: the anchor step is the caller's.
during_end: The inclusive end date of the window; see ``during_start``.
on: The point form: what held or happened on this date (ISO-8601).
Alternative to ``during_start`` / ``during_end``.
predicate: Structural filter — claims whose predicate term
equals this string (case-insensitive, exact: a CURIE and its
expanded IRI are different strings; discover terms with
``list_predicates``). With a question it prefilters the semantic
candidate set; without one it selects the deterministic listing.
object_eq: Claims whose object equals this value (typed comparison
when both sides normalize — numbers and ISO dates — else
case-insensitive text).
object_gt: Claims whose object is greater than this number or ISO
date; claims whose object would not normalize are excluded and
disclosed in ``claim_coverage.not_normalizable_excluded``.
object_lt: Claims whose object is less than this number or ISO date
(same normalization and disclosure as ``object_gt``).
object_contains: Claims whose object contains this substring
(case-insensitive; every term kind).
count: Deterministic aggregate — the number of matching claims with
their effective-confidence distribution. Rejects a simultaneous
question.
group_by: Deterministic aggregate — bucket matching claims by
"subject", "predicate", or "object" with per-bucket counts and
confidence distribution. Rejects a simultaneous question.
min_effective_confidence: Explicit confidence floor for the aggregate
modes; excluded rows are disclosed. There is no default floor.
list_predicates: List the distinct predicate terms with kind and
claim count (``predicate_vocabulary`` in the response) — the
discovery surface for the exact-string predicate filter.
all_projects: On a server bound to one project, read the whole
store instead of that project's view. The result says so. No effect
on an unbound server.
grounded: Compose a grounded answer: every sentence ends
with the ids of the retrieved particles it rests on (``[p-1a2b3c4d]``,
the form ``particle_show`` accepts), or with ``[inference]`` (the
model's own inference over cited claims) or ``[background]`` (from
nothing in the store). Cited ids are checked against the retrieved
set; a sentence with no valid citation and no label is
``[unattributed]``. Nothing is dropped and nothing is stored.
``answer_attribution`` carries the per-sentence labels and full
cited ids. Omit to use the server's ``query.grounded_answers``.
Returns:
The full ``QueryResponse`` as JSON — answer string plus the
ranked particles, effective confidences, coverage gaps, and
any truncation warning. A structural call returns rows
or counts, not generated prose: the deterministic listing fills
``particles`` ordered by effective confidence, the aggregates fill
``structural_aggregate``, the vocabulary listing fills
``predicate_vocabulary``, and every structural result carries
``claim_coverage`` (the annotated-fraction footer plus the
non-normalizable exclusion disclosure). Each particle's ``contested`` key is
the id of an open INCONSISTENCY referencing it,
else null; the composed contested badge rides
beside it — the response-level ``contested`` list carries one
badge (fired bases + drill-downs) or null per ranked particle,
and with ``summary=True`` each slim hit carries
``contested_bases`` (the fired basis labels, else null) beside
its ``contested`` id. When ``summary=True``, each particle
entry is a small dict instead of the full Pydantic model.
|
| particle_showA | Show one particle with its provenance, subjects, and tags. Args:
particle_id: Full UUID or unambiguous prefix (≥ 8 chars).
Returns:
Dict with ``particle`` (Pydantic JSON), ``subjects`` (list of
``{id, canonical_name}``), and ``provenance`` (list of
``{type, corpus_entry_id, uri_r, source_type, snapshot_id}``).
When the source now states the claim in other words, ``restated_as``
holds that wording and its snapshot; the claim's
``content`` keeps its first wording. Raises if the prefix matches zero
or multiple particles.
|
| particles_listA | List particles, optionally filtered by status or subject. Lightweight alternative to ``query`` and ``lint`` when an agent
just needs the IDs of particles in a particular state — e.g. the
open INCONSISTENCY queue, RETRACTED particles for cleanup, or
every ACTIVE particle linked to a subject. Embeddings are never
included; responses are designed to stay within MCP tool-result
size caps.
Args:
status: Optional status filter — one of
``ACTIVE``, ``SUPERSEDED``, ``RETRACTED``,
``PROVENANCE_STALE``, ``INCONSISTENCY``. Unset returns
particles in any status.
subject_id: Optional subject: a full ID, an ID prefix,
or a name or alias, resolved as ``subjects_show`` resolves it.
When set, only particles linked to that subject via the
``particle_subjects`` join table are returned, and the result
echoes the resolved ``subject_id``. A reference that matches no
subject, or more than one, raises.
limit: Maximum particles to return (default 50). Must be > 0.
offset: Number of particles to skip before returning results
(default 0). Combine with ``limit`` to page through the
full set.
all_projects: On a server bound to one project, read the whole
store instead of that project's view. The result says so. No effect
on an unbound server.
Returns:
Dict with ``particles`` — a list of summary dicts containing
``id``, ``status``, ``content``, ``confidence``,
``subject_ids``, ``asserted_at``, and ``status_reason``. Each
entry's ``contested`` key is the id of an open INCONSISTENCY
referencing it, else null; ``contested_bases``
rides beside it with the fired basis labels —
composed by the same composer the ``query`` tool uses, so all
three bases (stance / divergence / inconsistency) are evaluated
and the two surfaces on one server always agree. Plus
``limit``/``offset`` echoed back so the agent can drive
pagination. Embeddings are intentionally omitted.
|
| particle_searchA | List particles sharing a context fingerprint. Args:
fingerprint: Full 64-char SHA-256 hex or a prefix (≥ 8 chars).
limit: Maximum particles to return (default 50, capped at 200 to
keep responses within MCP per-tool-result token caps —
fingerprint matches share full ``content`` strings).
all_projects: On a server bound to one project, read the whole
store instead of that project's view. The result says so. No effect
on an unbound server.
Returns:
Dict with ``fingerprint`` (the queried value) and ``particles``
(list of ``{id, status, content}`` summaries).
|
| subjects_listA | List subjects in the knowledge graph (alphabetical by canonical_name). Paginated to keep responses within an MCP-client-friendly size — the
full subject set can easily exceed per-tool-result token caps.
Args:
limit: Maximum subjects to return (default 50).
offset: Number of subjects to skip before returning results
(default 0). Combine with ``limit`` to page through the
full set.
order: ``"name"`` (alphabetical, default) or ``"degree"`` —
most-connected first, by descending count of ACTIVE
particles linked to each subject (name tie-break). Use
``"degree"`` to find a store's hub subjects, e.g. as a
``graph_view`` starting scope.
|
| subjects_searchA | Substring search over subject names and aliases (case-insensitive). Args:
query: Substring to match against ``canonical_name`` or any recorded
alias, so "speaker" finds a subject whose alias is "the speaker".
limit: Maximum subjects to return (default 50). A generic
substring like "the" can match thousands of subjects, so
this caps the page size.
offset: Number of matches to skip before returning results
(default 0). Results are alphabetical by canonical_name
so pagination is stable.
|
| subjects_showA | Show one subject with the particle IDs linked to it. Args:
subject_id: A full UUID, an unambiguous prefix (≥ 8 chars), or a
name or alias, matched case-insensitively and exactly. A
reference that matches more than one subject (a prefix shared
by several IDs, a name two subjects share, or a string that is
both a prefix and a name) raises with the candidates named. A
remote engine resolves IDs and prefixes only.
particle_id_limit: Maximum particle IDs to include in
``particle_ids`` (default 100). For hot subjects the full
list can blow the per-tool-result token cap; use
``particles_list(subject_id=…, limit=…, offset=…)`` for
the full set when ``particle_count > particle_id_limit``.
Returns:
Dict with ``subject`` (Pydantic JSON), ``particle_ids`` (capped
at ``particle_id_limit``, ordered by id for stable pagination),
and ``particle_count`` — the true total of linked particles,
so callers can detect when the list was truncated.
|
| list_taxonomiesA | List every taxonomy + its full tag tree. Args:
limit: Maximum taxonomies to return (default 50). Each
taxonomy embeds its full tag tree, so even a handful of
large taxonomies can push the response past the
per-tool-result token cap.
offset: Number of taxonomies to skip before returning results
(default 0). Results are ordered by name so pagination is
stable.
|
| list_corpus_entriesA | List recent corpus entries (most-recently-deposited first). Args:
limit: Maximum entries to return (default 50).
source_type: Optional filter (e.g. ``"WIKIDATA_API"``).
|
| lintA | Run structural lint checks over the particle store (no fixes, no LLM). The MCP surface is read-only, so ``--fix`` is forced off and the
LLM-assisted semantic checks are disabled — agents read findings
and surface them to the operator, who decides whether to act.
Args:
category: Optional ``finding_type`` filter (e.g. ``STALENESS``,
``PHANTOM_SUBJECT``, ``WIKIDATA_LINK_MISMATCH``). When set,
only findings of that kind are returned; ``summary`` is
always the full counts dict and reflects every category
actually emitted by this run.
summary_only: When ``True``, drop the ``findings`` list and
return only the ``summary`` counts dict (plus ``run_at``).
Useful when the agent only needs to know what *kinds* of
problems exist before drilling in with ``category``.
limit: Maximum findings to include after filtering (default
100). Hard cap to keep the response under per-tool-result
size limits even when many findings of one category exist.
A ``truncated`` flag is added when the cap fires.
Returns:
``{run_at, findings, summary}`` matching the ``LintReport``
schema, optionally with ``truncated: True`` and (when
``summary_only``) without the ``findings`` key.
|
| quality_reportA | Return the extraction-quality dashboard snapshot. Particle counts by status / calibration_source / schema_version,
plus the structural-mix percentages, the store's recorded LLM spend
(``llm_spend``), and the curation queue's precision over the default
window (``curation_precision``: per card kind, the cards acted on,
dismissed, snoozed and untouched, with the denominator). Computed
entirely from live DB queries — no LLM involvement.
|
| links_suggestA | Propose co-evidential candidate pairs within Subjects (read-only). Within each Subject, ACTIVE particles whose embeddings exceed the
similarity threshold and are not already linked CO_EVIDENTIAL are
surfaced as candidate pairs for operator review. No LLM call, no
mutation — this is the ``REPORT`` mode of ``particles links suggest``.
Args:
subject_id: Restrict to one Subject. ``None`` scans every
Subject — prefer passing a ``subject_id`` to keep results focused.
threshold: Cosine-similarity floor (0.0–1.0). Defaults to
``links_suggest.candidate_threshold`` when omitted.
limit: Maximum candidate pairs to include across all clusters
(default 100). A ``truncated`` flag is added when the cap fires.
Returns:
``{run_at, mode, clusters, total_candidates, warnings}`` matching the
``SuggestReport`` schema, optionally with ``truncated: True``.
|
| corpus_links_suggestA | Rank undeposited URLs the corpus frequently cites (read-only). Surfaces primary sources the corpus leans on but has never deposited —
"hearsay vs. primary source" gaps — ranked by trust-weighted distinct-source
diversity × recency. Read-only: the ``dismiss`` half of the
workflow lives on the CLI / HTTP API.
Args:
limit: Maximum suggestions to return. Defaults to
``citation_signal.rank_cap`` when omitted.
min_sources: Minimum distinct citing sources required to surface a URL.
Defaults to ``citation_signal.min_distinct_sources`` when omitted.
Returns:
``{suggestions, total_candidates, capped}`` matching the
``DepositSuggestReport`` schema.
|
| events_listA | List operator events, newest first, optionally filtered. Args:
particle: Only events touching this particle id.
subject: Only events touching this subject id.
corpus_entry: Only events touching this corpus entry id.
(At most one of ``particle`` / ``subject`` / ``corpus_entry``.)
event_type: Only events of this type, e.g. ``SOURCE_RETRACTED``,
``SUBJECTS_SPLIT``, ``TRUST_CHANGED``, ``REVIEW_RESOLVED``.
limit: Maximum events to return (default 50).
|
| event_showB | Show one operator event in full — header, refs, and payload. Args:
event_id: The event's id.
|
| graph_viewA | Render one scoped epistemic subgraph of the particle store. Scope is mandatory — pass exactly one of ``subject_id`` / ``query`` /
``inconsistency_id`` / ``manifest``+``section`` (a whole-store render
does not exist; the anti-hairball invariant). Every
epistemic quantity in the result (effective confidence, contested
badges, as-of visibility, utility evidence) is computed at render time
by the engine and never stored.
Args:
subject_id: Neighbourhood scope — this Subject, its particles, and
subjects reachable within ``hops`` via multi-subject particles.
Accepts a subject id or an exact (case-insensitive) canonical
name / alias; the render's ``scope_ref`` is the resolved id.
query: Retrieval-set scope — the top-K hits of the existing query
ranking rendered as their subjects plus the hit particles
("the picture of the knowledge the agent consulted").
inconsistency_id: Evidence scope — a contradiction's
picture: the INCONSISTENCY particle as the anchor, its two
disputant beliefs shown with their true statuses (the
quarantined side included), their subjects and sources. Accepts
a full particle id or a unique prefix (a contested badge's
``inconsistency_id`` is the usual source).
manifest: With ``section``, projection scope — an
manifest section's deterministic selection rendered as
a graph. The manifest path resolves on the engine host.
section: The manifest section's ``region`` id, or its exact
(case-insensitive) title.
hops: Neighbourhood radius for subject scope (clamped to
``graph.max_hops``).
history: Also include retired supersession-chain ancestors, rendered
as ghosts.
as_of: ISO-8601 past instant (a bare date means start of that day,
UTC): render the graph as believed at T. A future
instant is rejected.
max_nodes: Per-call node cap (clamped to ``graph.max_nodes``).
store: Store handle to render from; ``"default"`` is the
canonical store.
all_projects: On a server bound to one project, render from
the whole store instead of that project's view. The result says so.
No effect on an unbound server.
Returns:
The ``GraphData`` render as JSON — ``nodes`` (subjects with display
aggregates), ``edges`` (multi-subject particles), ``particles``
(per-particle epistemics payloads keyed by id), ``supersessions``,
the ``census``, and human-readable ``disclosures`` for any cap that
bound. When ``engine.base_url`` is configured, a ``url`` field
additionally deep-links the same scope on the unified web UI
(``/app#/browse?…``) so the operator can open the
interactive picture — the default stdio install has no HTTP server,
so the field is additive, never assumed.
|
