Operations

The five core operations: Query, Lint, Review, Reindex, and Export.

Query

particles.operations.query.query(session, request) async

Execute a semantic search over one store and generate a NL answer.

A purely structural request (modes three and four — filters without a question, aggregates, or the predicate listing) dispatches to :func:.structural.structural_query instead: deterministic, no embedding, no LLM call.

Lint

particles.operations.lint.run_lint(session, fix=False, semantic=True, low_coverage_threshold=3, *, contradiction_probe=None, granularity_probe=True) async

Run all lint checks and return a LintReport.

Parameters:

Name	Type	Description	Default
fix	bool	if True, apply status changes immediately (staleness → PROVENANCE_STALE etc.). Defaults to False — lint is read-only unless the caller opts in.	False
semantic	bool	if True, run LLM-assisted contradiction and granularity checks	True
low_coverage_threshold	int	subjects with fewer than this many ACTIVE CLAIM particles are flagged as PHANTOM_SUBJECT (0) or LOW_COVERAGE_SUBJECT (< threshold).	3
contradiction_probe	ContradictionProbeControl | None	optional cap/scope/progress control for the contradiction probe; also carries back the candidate-pair census. None keeps the probe unbounded.	None
granularity_probe	bool	set False to skip the per-particle LLM granularity check within the semantic pass. collect_cards does — GRANULARITY_VIOLATION has no card kind, so for the curation queue and the audit those LLM calls would be pure discard.	True

Review

particles.operations.review.list_inconsistencies(session) async

Return all INCONSISTENCY particles pending review.

particles.operations.review.resolve(session, inconsistency_particle_id, action, reviewer_id, domain='general', note=None, actor='review') async

Apply a resolution action to an INCONSISTENCY particle.

Returns the REVIEW particle written as an audit record. The demotion-only rule is enforced: PREFER resolutions set the lower-trust particle to PROVENANCE_STALE rather than silently suppressing it.

Reindex

particles.operations.reindex.reindex(session, entry_ids=None, extractor_version=None, extractor_id=None, include_failed=True, provider_model=None, rate_limit_per_minute=DEFAULT_RATE_LIMIT_PER_MINUTE, run_post_lint=True, progress=None, dry_run=False, on_plan=None, on_status=None) async

Reindex corpus entries.

The particle-selecting scopes — extractor_version, extractor_id, provider_model — union with each other and intersect with entry_ids when both are supplied. See _identify_scope for why the combination narrows rather than erroring.

Parameters:

Name	Type	Description	Default
entry_ids	list[str] | None	explicit list of entries to reindex; if None, auto-discover scope.	None
extractor_version	str | None	superseded extractor version to replace (filters by extractor_ref).	None
extractor_id	str | None	extractor name to re-extract regardless of version. Useful when a shared upstream (e.g. a prompt change) affects multiple extractors that delegate to it but didn't bump their own version.	None
include_failed	bool	also reindex entries with FAILED snapshots. Applies to auto-discovery only — named entries resolve to their latest COMPLETE snapshot, so an explicit scope never contains a FAILED one to include or exclude.	True
provider_model	str | None	re-extract particles stamped with this "<provider>:<model>" pairing — the handle for undoing an uncalibrated provider swap. Matched exactly; particles with no stamp (deterministic extractors, direct assertions, or anything minted before the stamp existed) never match.	None
rate_limit_per_minute	int	max extraction jobs per minute.	DEFAULT_RATE_LIMIT_PER_MINUTE
run_post_lint	bool	run a Lint pass after reindex completes.	True
progress	Callable[[str], None] | None	optional callback for human-readable progress lines. The CLI wires this to typer.echo when --verbose is set so the operator can see that a long-running reindex isn't stuck.	None
dry_run	bool	compute and report the work plan, then return without extracting — zero LLM calls, zero writes (mirrors the Notion exporter's dry-run discipline). The returned summary carries the full plan including per-snapshot counts.	False
on_plan	Callable[[str], None] | None	optional callback for the upfront work-plan lines (the scope summary + any missing-blob warnings), emitted before the first extraction. Separate from progress because the plan is meant to print unconditionally while per-entry progress stays opt-in.	None
on_status	Callable[[str], None] | None	optional callback fired after each snapshot completes with a compact position line — snapshot 12/89 (entry 0a8fb1a9…) — 3 failed — so a long run's liveness display can show how far along it is, not just elapsed time. Distinct from progress (opt-in, one full line per item, appended): the status is a single replaceable line the CLI feeds to the heartbeat.	None

Returns a summary dict with counts and any errors.