Core Schema¶
Pydantic v2 models for all particle and corpus types. These are the data structures that flow through the entire SDK.
Particle¶
particles.core.schema.Particle
¶
Bases: BaseModel
The minimal unit of knowledge in the Particles standard (§6.1–6.2).
A particle is a single claim with full provenance. content is the
human-readable assertion. confidence and uncertainty_nature quantify
epistemic state. subject_ids links the claim to canonical entities.
properties carries structured ontology-keyed data for structured
extractors (e.g. Numista); it is never used for conflict detection.
Attributes:
| Name | Type | Description |
|---|---|---|
content |
str
|
The claim text (min length 1) — one falsifiable assertion (§6.1). |
confidence |
Confidence
|
Stored, immutable confidence record (§6.3); never modified after creation. |
uncertainty_nature |
UncertaintyNature
|
EPISTEMIC (reducible) or ALEATORY (irreducible). |
provenance |
list[ProvenanceRef]
|
Corpus entry / snapshot references. |
asserted_by |
str
|
Agent or extractor ID that created this particle. |
status |
Status
|
Lifecycle status (ACTIVE, SUPERSEDED, RETRACTED, …). Only the
transitions in the normative §6.6 table are legal; go through
:func: |
subject_ids |
list[str]
|
UUIDs of subjects this particle is a statement about. |
properties |
dict[str, object] | None
|
Nomisma ontology-keyed structured data. |
Subject¶
particles.core.schema.Subject
¶
Bases: BaseModel
A canonical real-world entity, identified independently of any source.
Subjects are the nodes of the knowledge graph. Particles are statements (properties or edges) about subjects. Resolution is by canonical_name (case-insensitive) or aliases; external_ids enable cross-ontology lookup.
Attributes:
| Name | Type | Description |
|---|---|---|
canonical_name |
str
|
The authoritative display name (e.g. "1 Pfennig (1948-1950) GDR"). |
aliases |
list[str]
|
Alternative names used during subject resolution. |
external_ids |
list[ExternalRef]
|
Cross-references to Wikidata, Numista, Nomisma, etc. |
subject_class |
str | None
|
Nomisma ontology class for exporter template selection
(e.g. |
Confidence¶
particles.core.schema.Confidence
¶
Bases: BaseModel
The stored, immutable confidence record (§6.3).
confidence.value is never modified after particle creation. It is the extractor's confidence as calibrated at creation time; calibration_source/calibration_method/calibration_ref record how. effective_confidence is computed at query time only and never stored. §6.3 makes the separation of the two quantities normative, and the Conformance Profile §4 pins the formula and its test vectors.
ProvenanceRef¶
particles.core.schema.ProvenanceRef
¶
Bases: BaseModel
Points into the corpus with snapshot-level precision (§7.3).
Field-reuse convention (blessing the INCONSISTENCY
precedent): when type is :data:ProvenanceRefType.PARTICLE, the
referenced particle id travels in corpus_entry_id (and
snapshot_id, when set, carries the same particle id). Consumers:
build_inconsistency_particle (writer), the retraction-propagation
lint and the premise machinery (readers).
Supporting types¶
particles.core.schema.ExternalRef
¶
Bases: BaseModel
A reference to an entity in an external ontology or catalogue.
particles.core.schema.CorpusEntry
¶
Bases: BaseModel
Stable record of a source and its relationship to its origin (§7.2).
The entry is the append-only unit of the corpus (§7.1); mutability
(§7.4) and fetch_policy (§7.5) declare how its snapshot list may grow.
particles.core.schema.Snapshot
¶
Bases: BaseModel
A timestamped, content-addressed capture of a corpus source (§7.2).
Snapshots are only ever appended: the corpus is an append-only archive and the system of record, with the particle store a derived view over it (§7.1), so a re-fetch adds a snapshot rather than rewriting one. Sharing them between stores is §7.3.
particles.core.schema.SourceTrustStatement
¶
Bases: BaseModel
Operator-defined trust policy record (§6.4).
Stored as first-class records; consulted by conflict resolution and query. Demotion-only rule: may only demote confidence, never silently suppress conflicts.
Enumerations¶
particles.core.schema.UncertaintyNature
¶
Bases: StrEnum
particles.core.schema.SourceType
¶
Bases: StrEnum
Core source type identifiers. Domain-specific extractors define their own strings.
particles.core.schema.ExtractionStatus
¶
Bases: StrEnum
particles.core.status.Status
¶
Bases: StrEnum
particles.core.status.StatusReason
¶
Bases: StrEnum