Supported composition

Build governed knowledge

Flow

From an installed repository checkout:

python -m examples.quickstarts.governed_knowledge

This composition addresses a CRM revision structurally, resolves a JSON Pointer, checks the observed value, records the derivation, and commits a reviewable artifact. The same evidence API accepts text spans, record fields, table cells, page regions, and media time ranges.

Typed evidence to a revisioned artifact

"""Validate structured evidence, then commit a reviewable artifact revision."""

import datetime as dt

from mari_kit import JsonPointer, ObjectRef, RevisionRef, ScopeRef
from mari_kit.knowledge import (
    Activity,
    KnowledgeArtifact,
    LocatedEvidence,
    validate_located_evidence,
)
from mari_kit.platform import InMemoryArtifactStore


def run() -> dict[str, object]:
    scope = ScopeRef(tenant="acme", space="sales")
    source = RevisionRef(
        object=ObjectRef(namespace="crm", object_id="account:42", scope=scope),
        revision="crm-v7",
    )
    material = {"plan": {"name": "enterprise", "monthly_price": 599}}
    evidence = LocatedEvidence(
        ref=source,
        locator=JsonPointer(pointer="/plan/monthly_price"),
        quote="599",
    )
    report = validate_located_evidence(
        (evidence,), resolve_material=lambda ref: material if ref == source else None
    )
    if not report.accepted:
        raise ValueError(report.issues)

    artifact = KnowledgeArtifact(
        artifact_id="fact:account-42-price",
        revision="fact-v1",
        value={"subject": "account:42", "monthly_price": 599},
        scope=scope,
        recorded_at=dt.datetime(2026, 9, 3, tzinfo=dt.UTC),
        generated_by=Activity(
            identifier="price-extractor-v1", implementation="host:model"
        ),
        evidence=(evidence,),
        derived_from=(source,),
    )
    store = InMemoryArtifactStore()
    store.commit(artifact, expected_revision=None)
    return {
        "artifact": store.get(artifact.artifact_id, scope=scope),
        "evidence": report.valid,
    }


if __name__ == "__main__":
    print(run())

Page-region and media-range evidence require a caller-supplied locator that can read the application’s chosen PDF, image, audio, or video representation. Mari validates the reference, visibility set, resolution result, and quoted material. The application assigns the acceptance policy and transaction.

Boundary	Returned value
Evidence resolution	LocatedEvidenceReport with valid rows and individual issues
Derived identity	RevisionRef containing scope, namespace, object, revision, and optional unit
Write	KnowledgeArtifact committed with compare-and-swap semantics
Adapter verification	assert_artifact_store_conforms

Maintain derived knowledge

Declare computational inputs with KnowledgeArtifact.derivation_spec and the dependency planner. Include the selection rule, implementation version, and configuration as well as source material. Citation validation checks source resolution. Semantic support and approval remain separate governance decisions.