Store¶
SQLAlchemy repository functions for particles and subjects.
Particle store¶
particles.store.particle_store.insert_particle(session, particle, embedding=None, domain_hint=None)
async
¶
Persist a particle and its provenance edges. Flushes but does not commit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
AsyncSession
|
Active async SQLAlchemy session. |
required |
particle
|
Particle
|
The particle to insert. |
required |
embedding
|
list[float] | None
|
Optional pre-computed embedding vector for cosine search. |
None
|
domain_hint
|
str | None
|
Domain label for INCONSISTENCY particles (Extension B). |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the particle is born |
particles.store.particle_store.get_particle(session, particle_id)
async
¶
Fetch a particle by UUID. Returns None if not found.
particles.store.particle_store.get_active_particles_for_entry(session, corpus_entry_id)
async
¶
particles.store.particle_store.get_active_particles_with_embeddings(session, min_confidence=0.0, subject_id=None)
async
¶
Return all ACTIVE particles that have embeddings, for cosine similarity search.
particles.store.particle_store.update_particle_status(session, particle_id, new_status, reason=None, uncertainty_nature=None)
async
¶
Transition a particle's status, enforcing the normative transition table.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
particle_id
|
str
|
UUID of the particle to update. |
required |
new_status
|
Status
|
Target status. Invalid transitions raise ValueError. |
required |
reason
|
StatusReason | None
|
Optional StatusReason recorded alongside the transition. |
None
|
uncertainty_nature
|
UncertaintyNature | None
|
If provided, also updates uncertainty_nature (used by Review to mark BOTH_VALID resolutions as ALEATORY). |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the transition is not permitted or particle not found. |
particles.store.particle_store.count_particles_by_status(session)
async
¶
Subject store¶
particles.store.subject_store.insert_subject(session, subject)
async
¶
Persist a new subject. Flushes but does not commit.
particles.store.subject_store.get_subject(session, subject_id)
async
¶
Look up a subject by full UUID or unambiguous prefix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
subject_id
|
str
|
Full UUID or unique prefix (e.g. first 8 chars). |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the prefix matches more than one subject. |
particles.store.subject_store.find_by_name(session, name)
async
¶
Case-insensitive lookup against canonical_name and aliases.
Used by the subject resolver during extraction to avoid creating duplicate subjects for the same real-world entity.
particles.store.subject_store.find_by_external_ref(session, namespace, external_id)
async
¶
Look up a subject by external ontology reference.
particles.store.subject_store.list_all_subjects(session, *, limit=None, offset=0, order='name')
async
¶
List subjects, alphabetical by default.
order="degree" sorts by descending count of ACTIVE particles linked
via particle_subjects (canonical-name tie-break) — "most-connected
first", the seed the web UI's Browse route opens on. Degree counts only
ACTIVE links: a subject whose beliefs are all retired is not a good
picture of the store's current shape.
particles.store.subject_store.add_aliases(session, subject_id, new_aliases, *, actor='subjects-alias')
async
¶
Append aliases to a subject; return (updated subject, actually-added names).
Idempotent: names already present (case-insensitive) are silently skipped.
Invalidates the subject resolver cache so subsequent extractions pick up
the new aliases immediately. Records a SUBJECT_ALIASED operator event
when names are actually added.
particles.store.subject_store.merge_subjects(session, source_id, target_id, *, actor='subjects-merge')
async
¶
Merge source subject into target. Source is deleted; its particles are re-linked.
The source's canonical_name and aliases are added to the target as aliases. All particle_subjects join rows pointing to source are re-pointed to target. Irreversible — caller should confirm before committing.
Returns:
| Type | Description |
|---|---|
tuple[Subject, list[str], int]
|
Tuple of (updated_target_subject, aliases_added, particles_relinked). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If either subject is not found, or source == target. |
particles.store.subject_store.set_subject_class(session, subject_id, subject_class)
async
¶
Set (or update) the subject_class for a subject. Idempotent.
The extraction pipeline's classification path (no operator event — an
automated pipeline step fails inclusion criterion). For the
operator-initiated override verb, use :func:reclassify_subject.
Trust store¶
particles.store.trust_store.resolve_trust_score(session, uri_r)
async
¶
Return the effective trust score [0.0, 1.0] for a corpus entry URI.
particles.store.trust_store.upsert_trust_rule(session, scope, pattern, score, modifier, rationale=None, asserted_by='operator', actor='trust-set')
async
¶
Insert or replace a trust rule for the given scope+pattern.
Records a TRUST_CHANGED operator event. A domain/pattern
rule has no particle/subject/entry ref, so the event carries its target
in payload only.