API Reference¶

Package root (`indicium`)¶

`indicium` ¶

indicium — shared claim/evidence standard package.

Attributes¶

`MEM_NS = 'http://kgmemory.org/ns#'` `module-attribute` ¶

Functions¶

`validate_graph(data: rdflib.Graph, extra_shapes: rdflib.Graph | None = None) -> tuple[bool, str]` ¶

SHACL-validate data against indicium's base shapes.

Parameters:

Name	Type	Description	Default
`data`	`Graph`	The RDF graph to validate.	required
`extra_shapes`	`Graph \| None`	Optional additional SHACL shapes graph (e.g. from a DomainAdapter) merged with the base shapes before validation. Pass `None` (default) for identical behaviour to v0.1.	`None`

Returns:

Type	Description
`tuple[bool, str]`	`(conforms, report_text)`

`claim_to_insight(claim: dict) -> dict` ¶

Project an indicium Claim dict onto an ASTRA Insight dict (lossy).

.. deprecated:: Use indicium.astra_bridge.claim_to_insight(claim: Claim, ...) instead. This function takes a raw dict and will be removed in a future version.

`claim_to_evidence_snippet(claim: dict, source_path: str = '') -> dict` ¶

Map an Indicium Claim dict to an ASB task card EvidenceSnippet dict.

Parameters:

Name	Type	Description	Default
`claim`	`dict`	An Indicium claim dict with at minimum: id, context, subject, qualifier, relation, object. Optional: source_excerpt, evidence.	required
`source_path`	`str`	Explicit source path override. When omitted, the first evidence artifact path is used; falls back to doi:.	`''`

Returns:

Type	Description
`dict`	A dict with snippet_id, source_path, reason and text, the required
`dict`	fields of an EvidenceSnippet.

`claim_jsonld(claim: dict) -> dict` ¶

Vocabulary bases (`indicium.iri_bindings`)¶

Import these instead of spelling the IRIs; see the URI scheme.

`indicium.iri_bindings` ¶

Verified ontology IRIs for the indicium vocabularies.

Provenance: seeded from ASB semantic.py, then verified against EBI OLS4 / CiTO (plan Task 2). Update here AND in the LinkML schema meaning: together.

Verification method¶

ECO labels were fetched from: https://www.ebi.ac.uk/ols4/api/ontologies/eco/terms?iri=http://purl.obolibrary.org/obo/ECO_ CiTO predicates were confirmed to resolve (HTTP 302 → 200) at: http://purl.org/spar/cito/

Changes vs. ASB semantic.py¶

citation: ECO:0000305 → ECO:0000033 Old label: "curator inference used in manual assertion" (wrong branch — this is under inferential/curator-inference, not literature citation). New label: "author statement supported by traceable reference" — an author assertion whose support can be traced to a cited reference; this is the standard GO/ECO code for evidence derived from a published source.
inference: ECO:0000001 → ECO:0000361 Old label: "inference from background scientific knowledge" — a leaf under ECO:0000205 (curator inference) → ECO:0000361. It is too specific (curator only) and was incorrectly described in the task spec as the root. New label: "inferential evidence" — the direct child of ECO:0000000 (root "evidence") that heads the entire inference/reasoning branch. Using the upper-level branch term is correct for a vocabulary binding that must subsume all forms of computational, logical, and manual inference.
speculation: ECO:0007672 → ECO:0000034 Old label: "computational evidence" — entirely wrong; this is about computer-generated data, not hypothetical assertions. New label: "author statement without traceable support" — an assertion not associated with results presented or a cited reference. This is the closest available ECO upper-level term for a speculative/hypothetical claim. ECO does not have a dedicated "speculation" class; this is the best match.

All other terms (data, knowledge) are retained with confirmed labels.

Attributes¶

`ASB_BASE: str = _prefix_reference('asb')` `module-attribute` ¶

`INDICIUM_BASE: str = _prefix_reference('indicium')` `module-attribute` ¶

Functions¶

`asb_term(name: str) -> str` ¶

Return the full IRI of a term in the asb: vocabulary, e.g. Claim.

Quote verification (`indicium.verify`)¶

`indicium.verify` ¶

Quote verification kernel — match an LLM-extracted quote against source text.

Pure-Python, dependency-light, never raises. Shared across projects that ground claims / parameters / failure-modes in source passages (Perspicacité, ASB).

Additive to the indicium standard: this module adds a verifier verb alongside the existing data model (Evidence.quote_exact / TextQuoteSelector). It does NOT touch generated/model.py, the SHACL shapes, or any enum.

VerificationResult also carries a char_span — (start, end) offsets into the matched candidate's original (un-normalized) text — so callers can highlight or re-slice the exact source region instead of re-searching for it.

verify_quote(..., punctuation_flexible=True) adds an opt-in pass that matches a quote's alphanumeric tokens in order across arbitrary punctuation/whitespace (e.g. "P=0.001" ~ "P = 0.001,"), so a verbatim-modulo-punctuation quote verifies instead of degrading to a sub-threshold LCS. This mirrors ASB claim_ledger's token-sequence matcher, letting both projects share one kernel.

Classes¶

`VerificationResult` `dataclass` ¶

Functions¶

`verify_quote(quote: str, candidates: Sequence[str], *, near_threshold: float = 0.9, punctuation_flexible: bool = False) -> VerificationResult` ¶

Verify quote against candidates (source passage texts).

Outcomes

verified: quote is contained in some candidate (whitespace-flexible, case-sensitive). quote_exact = the candidate's verbatim span; score = 1.0; char_span = (start, end) offsets into that candidate's original text.
repaired: no containment, but the longest common substring vs the best candidate clears near_threshold (ratio over len(normalized quote)). quote_exact = that LCS region from the candidate; score = ratio; char_span best-effort (the normalized span is re-located in the original candidate; may be None).
unverified: nothing clears the threshold (likely paraphrase/hallucination). matched_index = quote_exact = char_span = None; score = best below-threshold ratio (0.0 when quote/candidates are empty or share no run).

With punctuation_flexible=True, an opt-in pass between containment and LCS matches the quote's alphanumeric tokens in order across arbitrary punctuation (e.g. "P=0.001" ~ "P = 0.001,"); a hit is verified, score 1.0. Off by default so existing thresholds are unchanged.

Never raises: empty/whitespace quote or empty candidates -> unverified. Ties resolved by highest score, then lowest index.

ASTRA bridge (`indicium.astra_bridge`)¶

Typed conversion between Claim objects and ASTRA insights. Needs the astra extra.

`indicium.astra_bridge` ¶

ASTRA ↔ Indicium bridge — convert between ASTRA Insight dicts and Indicium Claims.

Optional-extra-gated: pyyaml must be installed (pip install "indicium-standard[astra]" or pip install pyyaml). The pyyaml extra is already in the codegen extra and dev dependency-group, so it is always available during development.

Gap 6 implementation from the Indicium v1.3 design spec.

Functions¶

`claim_to_insight(claim: 'Claim', *, evidence_doi: str | None = None) -> dict` ¶

Convert an Indicium Claim to an ASTRA Insight YAML dict.

Mapping rules: - claim text: "{subject} {qualifier} {relation} {object}" (stripped). - evidence: DOI item if evidence_doi provided, else artifact item using claim id. - indicium_claim_ref: set to claim.id when present. - created_at: current UTC ISO timestamp.

Parameters:

Name	Type	Description	Default
`claim`	`'Claim'`	Indicium Claim object.	required
`evidence_doi`	`str \| None`	DOI to include in the evidence list. Optional.	`None`

Returns:

Type	Description
`dict`	ASTRA Insight dict (id, claim, created_at, evidence, indicium_claim_ref).

`insight_to_claim(insight: dict, *, analysis_id: str, source_doi: str | None = None) -> 'Claim'` ¶

Convert an ASTRA Insight dict to a best-effort Indicium Claim.

Mapping rules: - subject/object: split claim text at verb heuristic, or use full text as object. - qualifier: defaults to has_property; overridden when a known verb is found. - relation: same as qualifier_str (the matched verb phrase) or "has_property". - context: ASTRA scope field joined with tags; empty string if absent. - asserted_by: set to analysis_id. - astra_insight_ref: set to "{analysis_id}/{insight['id']}".

Parameters:

Name	Type	Description	Default
`insight`	`dict`	ASTRA Insight dict (id, claim, scope, tags, …).	required
`analysis_id`	`str`	ASTRA analysis ID used as asserted_by and ref prefix.	required
`source_doi`	`str \| None`	If provided, appended to context.	`None`

Returns:

Type	Description
`'Claim'`	A best-effort Indicium Claim (some slots may be empty strings).

`load_astra_findings(astra_yaml_path: Path) -> list['Claim']` ¶

Load an astra.yaml file and return all findings as Indicium Claims.

Findings are ASTRA's analysis conclusions — the primary output of a sensitivity/multiverse analysis run.

Parameters:

Name	Type	Description	Default
`astra_yaml_path`	`Path`	Path to an astra.yaml file.	required

Returns:

Type	Description
`list['Claim']`	List of Indicium Claims, one per finding. Returns [] if no findings.

`load_astra_prior_insights(astra_yaml_path: Path) -> list['Claim']` ¶

Load an astra.yaml file and return all prior_insights as Indicium Claims.

Prior insights are literature-backed facts that inform ASTRA decisions; they are distinct from findings (which are analysis conclusions).

Parameters:

Name	Type	Description	Default
`astra_yaml_path`	`Path`	Path to an astra.yaml file.	required

Returns:

Type	Description
`list['Claim']`	List of Indicium Claims, one per prior_insight. Returns [] if none.

Adapters¶

ASTRA, dict-based (`indicium.adapters.astra`, deprecated)¶

`indicium.adapters.astra` ¶

Project an indicium Claim onto an ASTRA Insight (lossy — claim becomes a string).

ASTRA Insight = {id, claim (str), evidence: [{doi|artifact, quote:{exact}}]}. The 5-slot SuperPattern is flattened into the claim string; full typing is preserved in the RDF/RO-Crate forms, not here.

Functions¶

`claim_to_insight(claim: dict) -> dict` ¶

Project an indicium Claim dict onto an ASTRA Insight dict (lossy).

.. deprecated:: Use indicium.astra_bridge.claim_to_insight(claim: Claim, ...) instead. This function takes a raw dict and will be removed in a future version.

ASB task card adapter (`indicium.adapters.scitask`)¶

`indicium.adapters.scitask` ¶

Project an indicium Claim onto the EvidenceSnippet dict of an ASB task card.

The target structure is the EvidenceSnippet class of the ASB task card schema, asb_schema/asb_card.yaml in the asb-schema package (asb-schema>=0.4.0). Its fields are snippet_id, source_path, reason and text. The module keeps its earlier name, indicium.adapters.scitask, so that existing imports keep working.

Functions¶

`claim_to_evidence_snippet(claim: dict, source_path: str = '') -> dict` ¶

Map an Indicium Claim dict to an ASB task card EvidenceSnippet dict.

Parameters:

Name	Type	Description	Default
`claim`	`dict`	An Indicium claim dict with at minimum: id, context, subject, qualifier, relation, object. Optional: source_excerpt, evidence.	required
`source_path`	`str`	Explicit source path override. When omitted, the first evidence artifact path is used; falls back to doi:.	`''`

Returns:

Type	Description
`dict`	A dict with snippet_id, source_path, reason and text, the required
`dict`	fields of an EvidenceSnippet.

KGmemory (`indicium.adapters.kgmemory`)¶

`indicium.adapters.kgmemory` ¶

KGmemory-ready projection (latent). Points outward at mem:SemanticMemory.

We do NOT import, vendor, or modify KGmemory's vocabulary — we only reference its canonical IRI so an emitted claim is ingestible if/when KGmemory adopts it. The ECO->validationState crosswalk is intentionally NOT here (it is KGmemory's seam to author).

Attributes¶

`MEM_NS = 'http://kgmemory.org/ns#'` `module-attribute` ¶

Functions¶

`claim_jsonld(claim: dict) -> dict` ¶

Validation (`indicium.validate`)¶

`indicium.validate` ¶

SHACL validation over the generated shapes plus any supplemental shapes.

Functions¶

`validate_graph(data: rdflib.Graph, extra_shapes: rdflib.Graph | None = None) -> tuple[bool, str]` ¶

SHACL-validate data against indicium's base shapes.

Parameters:

Name	Type	Description	Default
`data`	`Graph`	The RDF graph to validate.	required
`extra_shapes`	`Graph \| None`	Optional additional SHACL shapes graph (e.g. from a DomainAdapter) merged with the base shapes before validation. Pass `None` (default) for identical behaviour to v0.1.	`None`

Returns:

Type	Description
`tuple[bool, str]`	`(conforms, report_text)`

API Reference¶

Package root (indicium)¶

indicium ¶

Attributes¶

MEM_NS = 'http://kgmemory.org/ns#' module-attribute ¶

Functions¶

validate_graph(data: rdflib.Graph, extra_shapes: rdflib.Graph | None = None) -> tuple[bool, str] ¶

claim_to_insight(claim: dict) -> dict ¶

claim_to_evidence_snippet(claim: dict, source_path: str = '') -> dict ¶

claim_jsonld(claim: dict) -> dict ¶

Vocabulary bases (indicium.iri_bindings)¶

indicium.iri_bindings ¶

Verification method¶

Changes vs. ASB semantic.py¶

Attributes¶

ASB_BASE: str = _prefix_reference('asb') module-attribute ¶

INDICIUM_BASE: str = _prefix_reference('indicium') module-attribute ¶

Functions¶

asb_term(name: str) -> str ¶

Quote verification (indicium.verify)¶

indicium.verify ¶

Classes¶

VerificationResult dataclass ¶

Functions¶

verify_quote(quote: str, candidates: Sequence[str], *, near_threshold: float = 0.9, punctuation_flexible: bool = False) -> VerificationResult ¶

ASTRA bridge (indicium.astra_bridge)¶

indicium.astra_bridge ¶

Functions¶

claim_to_insight(claim: 'Claim', *, evidence_doi: str | None = None) -> dict ¶

insight_to_claim(insight: dict, *, analysis_id: str, source_doi: str | None = None) -> 'Claim' ¶

load_astra_findings(astra_yaml_path: Path) -> list['Claim'] ¶

load_astra_prior_insights(astra_yaml_path: Path) -> list['Claim'] ¶

Adapters¶

ASTRA, dict-based (indicium.adapters.astra, deprecated)¶

indicium.adapters.astra ¶

Functions¶

claim_to_insight(claim: dict) -> dict ¶

ASB task card adapter (indicium.adapters.scitask)¶

indicium.adapters.scitask ¶

Functions¶

claim_to_evidence_snippet(claim: dict, source_path: str = '') -> dict ¶

KGmemory (indicium.adapters.kgmemory)¶

indicium.adapters.kgmemory ¶

Attributes¶

MEM_NS = 'http://kgmemory.org/ns#' module-attribute ¶

Functions¶

claim_jsonld(claim: dict) -> dict ¶

Validation (indicium.validate)¶

indicium.validate ¶

Functions¶

validate_graph(data: rdflib.Graph, extra_shapes: rdflib.Graph | None = None) -> tuple[bool, str] ¶

Package root (`indicium`)¶

`indicium` ¶

`MEM_NS = 'http://kgmemory.org/ns#'` `module-attribute` ¶

`validate_graph(data: rdflib.Graph, extra_shapes: rdflib.Graph | None = None) -> tuple[bool, str]` ¶

`claim_to_insight(claim: dict) -> dict` ¶

`claim_to_evidence_snippet(claim: dict, source_path: str = '') -> dict` ¶

`claim_jsonld(claim: dict) -> dict` ¶

Vocabulary bases (`indicium.iri_bindings`)¶

`indicium.iri_bindings` ¶

`ASB_BASE: str = _prefix_reference('asb')` `module-attribute` ¶

`INDICIUM_BASE: str = _prefix_reference('indicium')` `module-attribute` ¶

`asb_term(name: str) -> str` ¶

Quote verification (`indicium.verify`)¶

`indicium.verify` ¶

`VerificationResult` `dataclass` ¶

`verify_quote(quote: str, candidates: Sequence[str], *, near_threshold: float = 0.9, punctuation_flexible: bool = False) -> VerificationResult` ¶

ASTRA bridge (`indicium.astra_bridge`)¶

`indicium.astra_bridge` ¶

`claim_to_insight(claim: 'Claim', *, evidence_doi: str | None = None) -> dict` ¶

`insight_to_claim(insight: dict, *, analysis_id: str, source_doi: str | None = None) -> 'Claim'` ¶

`load_astra_findings(astra_yaml_path: Path) -> list['Claim']` ¶

`load_astra_prior_insights(astra_yaml_path: Path) -> list['Claim']` ¶

ASTRA, dict-based (`indicium.adapters.astra`, deprecated)¶

`indicium.adapters.astra` ¶

`claim_to_insight(claim: dict) -> dict` ¶

ASB task card adapter (`indicium.adapters.scitask`)¶

`indicium.adapters.scitask` ¶

`claim_to_evidence_snippet(claim: dict, source_path: str = '') -> dict` ¶

KGmemory (`indicium.adapters.kgmemory`)¶

`indicium.adapters.kgmemory` ¶

`MEM_NS = 'http://kgmemory.org/ns#'` `module-attribute` ¶

`claim_jsonld(claim: dict) -> dict` ¶

Validation (`indicium.validate`)¶

`indicium.validate` ¶

`validate_graph(data: rdflib.Graph, extra_shapes: rdflib.Graph | None = None) -> tuple[bool, str]` ¶