src.dackar.RCA.doc_extraction.store

Attributes

logger
_ID_SEP

Exceptions

DocExtractionStoreError	Base error for DocExtractionStore backend failures (Chroma / embedding backend).
EmbeddingModelVersionError	Raised when the query-time embedding model does not match the collection's stored model.

Classes

SemanticMatch	One deduplicated result from a DocExtractionStore.query() call.
DocExtractionStore	Chroma-backed store for DocExtractionRecord objects.

Functions

_make_record_id(doc_id, chain_index)
_cosine_similarity(a, b)
_build_where_clause(filter_meta)
_meta_to_semantic_match(record_id, similarity, meta)

Module Contents

src.dackar.RCA.doc_extraction.store.logger

src.dackar.RCA.doc_extraction.store._ID_SEP = '::chain::'

src.dackar.RCA.doc_extraction.store._make_record_id(doc_id, chain_index)

Parameters:

• doc_id (str)

• chain_index (int)

Return type:

str

src.dackar.RCA.doc_extraction.store._cosine_similarity(a, b)

Parameters:

• a (List[float])

• b (List[float])

Return type:

float

class src.dackar.RCA.doc_extraction.store.SemanticMatch

One deduplicated result from a DocExtractionStore.query() call.

record_id: str

doc_id: str

chain_index: int

identified_effect: str | None

assessed_cause: str | None

inferred_fm_label: str | None

fm_id_candidate: str | None

confidence: src.dackar.RCA.doc_extraction.schema.ConfidenceLevel

cause_is_symptom: bool

similarity_score: float

fm_resolution_status: str | None = None

doc_type: str = ''

finding_status: str | None = None

authority_level: str | None = None

epistemic_class: str | None = None

classification_resolution_level: str | None = None

degraded_classification: bool = False

property confidence_weight: float

Numeric weight for this match’s confidence level (HIGH=1.0, MEDIUM=0.7, LOW=0.3).

Used as a multiplier in semantic_contribution (§4.3) so lower-confidence extractions contribute proportionally less to effective_recurrence_count.

Return type:

float

property cause_is_symptom_factor: float

Down-weight factor when the assessed cause is itself a symptom (0.5) vs. a mechanism (1.0).

A symptom-as-cause is a weaker recurrence signal than a true failure mechanism, so it halves this match’s semantic_contribution.

Return type:

float

property semantic_contribution: float

Fractional recurrence contribution for effective_recurrence_count (§4.3).

Return type:

float

exception src.dackar.RCA.doc_extraction.store.DocExtractionStoreError

Bases: RuntimeError

Base error for DocExtractionStore backend failures (Chroma / embedding backend).

query() and resolve_fm_candidates() deliberately degrade to empty/zero results on backend failure rather than raising, recording each event via _record_degradation() so it surfaces in the run manifest (see store_health_summary()). Callers that prefer fail-loud semantics can inspect store_health_summary()[“degraded”] and escalate.

exception src.dackar.RCA.doc_extraction.store.EmbeddingModelVersionError

Bases: DocExtractionStoreError

Raised when the query-time embedding model does not match the collection’s stored model.

class src.dackar.RCA.doc_extraction.store.DocExtractionStore(persist_directory, embed_model='nomic-embed-text-v1.5', ollama_base_url=None, fm_resolution_threshold=0.88, epistemics_classifier=None)

Chroma-backed store for DocExtractionRecord objects.

One collection ("doc_extractions") stores all extraction records across all document types. Each record’s embed_text (§4.1) is computed and stored at upsert time; similarity queries run against these pre-computed vectors.

Key guarantees: - Embedding model version is written into every record’s metadata.

A mismatch between query-time model and stored model raises EmbeddingModelVersionError.

• fm_id_candidate is always null at ingestion; resolve_fm_candidates() writes it back in batch at the start of an RCA run (§3.3 Step C).

• query() deduplicates by doc_id, returning only the best-scoring chain per document.

Parameters:

• persist_directory (str)

• embed_model (str)

• ollama_base_url (Optional[str])

• fm_resolution_threshold (float)

• epistemics_classifier (Optional[Any])

COLLECTION_NAME = 'doc_extractions'

_HNSW_SPACE = 'cosine'

persist_directory

embed_model = 'nomic-embed-text-v1.5'

ollama_base_url

fm_resolution_threshold = 0.88

epistemics_classifier = None

_collection = None

_embedder = None

_degraded_operations: List[Dict[str, Any]] = []

property embedding_model_version: str

Return type:

str

_get_embedder()

_get_collection()

_embed_texts(texts)

Parameters:

texts (List[str])

Return type:

List[List[float]]

_embed_query(text)

Parameters:

text (str)

Return type:

List[float]

_chroma_collection()

upsert(record)

Embed and store one extraction record. Returns the Chroma record_id.

Records with no embed_text are stored with a single-space document to avoid Chroma rejecting empty strings; they are retrievable by metadata but will not surface in similarity queries.

Parameters:

record (src.dackar.RCA.doc_extraction.schema.DocExtractionRecord)

Return type:

str

upsert_batch(records)

Embed and store multiple extraction records in one batch call.

Parameters:

records (List[src.dackar.RCA.doc_extraction.schema.DocExtractionRecord])

Return type:

int

query(query_text, *, top_k=5, similarity_threshold=0.75, near_match_window=0.1, filter_meta=None, exact_doc_ids=None)

Query for semantically similar extraction records.

The embedding model used at query time must match the collection’s stored embedding_model_version. A mismatch raises EmbeddingModelVersionError.

Deduplication: only the highest-scoring chain per doc_id is returned.

Parameters:

• query_text (str) – The query string (e.g. fm.name | fm.expected_symptoms | event.symptom_description).

• top_k (int) – Maximum number of doc_id-deduplicated results to return.

• similarity_threshold (float) – Minimum cosine similarity for inclusion in the main result set.

• near_match_window (float) – Width of the soft zone below threshold that populates near_matches.

• filter_meta (Optional[Dict[str, Any]]) – Optional Chroma metadata pre-filter (e.g. {"doc_type": "CR"}).

• exact_doc_ids (Optional[set]) – Set of doc_ids already counted via exact-match recurrence (kg_context.past_events). Matching records are excluded from both matches and near_matches to prevent double-counting. None or empty set disables the guard.

Returns:

• matches: similarity >= similarity_threshold, deduplicated, top_k max, exact_doc_ids excluded

• near_matches: similarity in [similarity_threshold - near_match_window, similarity_threshold)

Return type:

(matches, near_matches) where

_assert_model_version()

Raise EmbeddingModelVersionError if stored records use a different model.

Return type:

None

resolve_fm_candidates(fm_list, *, resolution_threshold=None)

Resolve fm_id_candidate for unresolved extraction records.

Called once per RCA run before Step 3 / Step 2d. For each record with fm_id_candidate == “” (unresolved), embeds the stored inferred_fm_label and compares against the KG FM list for the current asset neighborhood. Writes fm_id_candidate (and fm_id_candidate_alt) back to the collection if cosine similarity >= resolution_threshold.

Parameters:

• fm_list (List[Tuple[str, str]]) – List of (fm_id, fm_label) tuples from the KG.

• resolution_threshold (Optional[float]) – Override default; defaults to self.fm_resolution_threshold.

Returns:

Number of records updated.

Return type:

int

count()

Return total number of extraction records in the collection.

Return type:

int

delete_by_doc_id(doc_id)

Delete all extraction records for a given source document (re-ingestion path).

Parameters:

doc_id (str)

Return type:

None

_record_degradation(operation, exc)

Record a degraded (error-swallowed) operation for run-manifest surfacing.

query() and resolve_fm_candidates() degrade to empty/zero results on backend failure rather than crashing a batch run; each such event is captured here so store_health_summary() can report it and the failure is not misread downstream as a legitimate “no semantic recurrence”.

Parameters:

• operation (str)

• exc (Exception)

Return type:

None

property degraded: bool

True when any query/resolve operation swallowed a backend error this run.

Return type:

bool

store_health_summary()

Degradation summary for run_manifest (store_health section).

Returns {"degraded": bool, "degraded_operation_count": int, "events": [...]}. The orchestrator stamps this onto the run manifest so a swallowed Chroma/embedding error surfaces as an explicit degraded-run signal instead of a silent under-count.

Return type:

Dict[str, Any]

src.dackar.RCA.doc_extraction.store._build_where_clause(filter_meta)

Parameters:

filter_meta (Dict[str, Any])

Return type:

Optional[Dict[str, Any]]

src.dackar.RCA.doc_extraction.store._meta_to_semantic_match(record_id, similarity, meta)

Parameters:

• record_id (str)

• similarity (float)

• meta (Dict[str, Any])

Return type:

Optional[SemanticMatch]