Skip to content

API Reference

Engine

The main entry point for all Aevum operations.

Engine wires together the episodic ledger, consent ledger, graph store, policy bridge, complication registry, and the five governed functions.

aevum.core.engine.Engine

The Aevum context kernel.

Wires together the episodic ledger, consent ledger, graph store, policy bridge, complication registry, and the five governed functions.

Functions

ingest(*, data, provenance, purpose, subject_id, actor, idempotency_key=None, episode_id=None, correlation_id=None, model_context=None)

query(*, purpose, subject_ids, actor, constraints=None, classification_max=0, episode_id=None, correlation_id=None, model_context=None, capture_witness=True)

review(*, audit_id, actor, action=None, episode_id=None, correlation_id=None)

commit(*, event_type, payload, actor, witness=None, idempotency_key=None, episode_id=None, correlation_id=None)

replay(*, audit_id, actor, scope=None, episode_id=None, correlation_id=None, model_context=None)

verify_sigchain()

install_complication(instance, *, auto_approve=False)

Install a complication: validate manifest, check conflicts, register.

Parameters:

Name Type Description Default
instance Any

A Complication instance (from aevum.sdk).

 required
auto_approve bool

If True, immediately approve (for testing / trusted installs).

 False

Raises:

Type Description
ComplicationError

if manifest is invalid or capability conflicts exist.

approve_complication(name)

Admin approval: PENDING → APPROVED → ACTIVE.

suspend_complication(name)

Admin suspension: ACTIVE → SUSPENDED.

resume_complication(name)

Admin resume: SUSPENDED → ACTIVE.

list_complications()

complication_state(name)

register_webhook(webhook_id, url, secret, events=None)

deregister_webhook(webhook_id)

create_review(*, proposed_action, reason, actor, autonomy_level=1, risk_assessment='', deadline_iso=None)

get_ledger_entries()

ledger_count()

OutputEnvelope

Every function returns exactly one OutputEnvelope. No exceptions.

Always check result.status before accessing result.data. The audit_id is always present, even on error.

aevum.core.envelope.models.OutputEnvelope

Bases: BaseModel

The mandatory return type of all five functions. Spec Section 05.

aevum.core.envelope.models.ProvenanceRecord

Bases: BaseModel

aevum.core.envelope.models.ReviewContext

Bases: BaseModel

aevum.core.envelope.models.UncertaintyAnnotation

Bases: BaseModel

aevum.core.envelope.models.SourceHealthSummary

Bases: BaseModel

aevum.core.envelope.models.ReasoningTrace

Bases: BaseModel

aevum.core.envelope.models.ReasoningStep

Bases: BaseModel

ConsentGrant

The unit of permission. Every ingest, query, and replay operation requires an active, non-expired ConsentGrant for the subject and operation.

Valid operations: "ingest", "query", "replay", "export"

aevum.core.consent.models.ConsentGrant

Bases: BaseModel

AuditEvent

The 18-field immutable episodic ledger entry. Every operation appends exactly one AuditEvent to urn:aevum:provenance. This is the information stored in each chain entry — the raw material for deterministic replay.

aevum.core.audit.event.AuditEvent dataclass

Immutable episodic ledger entry. All 18 fields required.

Functions

hash_event_for_chain(event) staticmethod

SHA3-256 over all fields (excluding signature) for prior_hash chaining.

See also