Corpus

Deposit and fetch operations. The corpus is the blob store plus metadata layer that sits beneath the particle store.

Deposit

particles.corpus.deposit.deposit_url(session, url, deposited_by='operator', mutability=None, fetch_policy=None, source_type=None, tags=None, follow_post_links=None, follow_comment_links=None, out_follow_targets=None) async

Fetch a URL and deposit it into the corpus.

Domain-specific importers (Wikidata, Numista, …) are tried first via the plugin registry. Falls back to a generic HTTP fetch for any URL not claimed by a registered importer.

URL fragments (#anchor) are stripped before any importer lookup, fetch, or storage. HTTP servers never receive the fragment (it's client-side anchor navigation), so it carries no signal for extraction; keeping it in uri_r would just create spurious one-corpus-entry-per-anchor noise for operators who paste a section link.

follow_post_links and follow_comment_links: when the matched importer participates in deposit-time follow, the primary URL is fetched as a secondary corpus entry and a row is written to corpus_follow_edges recording the relationship. None (the default) consults the importer's DEFAULT_FOLLOW_POST_LINKS / DEFAULT_FOLLOW_COMMENT_LINKS constants. Explicit True / False overrides the importer default. The recursive follow call hardcodes both flags to False — the depth-1 cap.

out_follow_targets (optional): when supplied, each successful follow appends (entry_id, snapshot_id, uri_r) for the secondary corpus entry. Operator-facing surface (the CLI uses this to print the follow result so operators see both entries), not API-load-bearing.

Returns (entry_id, snapshot_id) for the primary deposit. Follow targets surface via out_follow_targets.

particles.corpus.deposit.deposit_file(session, path, deposited_by='operator', mutability=None, fetch_policy=None, source_type=None, tags=None, content_date=None) async

Deposit a local file into the corpus.

Source type is auto-detected from file extension. Deduplication is by SHA-256 content hash — re-depositing the same file returns the existing entry.

content_published_at is captured at deposit time so an archival document is not stamped with the import date. Precedence (highest wins): an explicit content_date (the CLI --date) › a leading date line in the content › the file mtime (see deposit_date config). deposit_vault routes through here, so vault files get the leading-date / mtime capture too (without the per-file --date override).

Parameters:

Name	Type	Description	Default
path	Path	Absolute or relative path to the file.	required
deposited_by	str	Agent ID recorded on the corpus entry.	'operator'
source_type	str | None	Override auto-detected source type.	None
content_date	datetime | None	Explicit authorship date; overrides auto-detection.	None

Returns:

Type	Description
tuple[str, str]	Tuple of (entry_id, snapshot_id).

particles.corpus.deposit.load_blob(content_hash)

Retrieve raw content from the blob store by SHA-256 hash.

Raises:

Type	Description
FileNotFoundError	If no blob exists for the given hash.

Fetch

particles.corpus.fetch.maybe_refetch(session, entry_id, force=False) async

Check whether entry needs re-fetching; create a new snapshot if content changed.

Returns the latest snapshot (new RESPONSE/REVISIT or existing) or None if the entry has no URI-R, has fetch_policy=NEVER, or names a local file that no longer exists.

Dispatches on the URI-R scheme: a file:// entry takes the local tier — stat then hash, no network — and everything else takes the HTTP ladder.

particles.corpus.fetch.path_from_file_uri(uri_r)

The local path a file:// URI-R names.

deposit_file records path.resolve().as_uri(), so the round trip is exact for anything this SDK deposited. Percent-escapes (spaces, non-ASCII) are decoded; a file://host/... authority other than localhost is rejected rather than silently reinterpreted as a local path.