arvis.host_api: the named runtime surface
Pinned at HOST_API_VERSION (see
VERSIONING.md); each module below is a
stable import path.
arvis.host_api.access
Identity and organization-scoped authorization.
The principal and generic access context a host builds for governed calls,
the host-attested stamp PRODUCTION effect syscalls require
(AuthenticatedPrincipal, passed to run_as), the typed access verdict,
and the organization-scoped authorization policy (scoped grants). Resource
meaning and scope construction remain host responsibilities.
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
AccessDecision
Bases: StrEnum
Binary authorization decision emitted by an access policy.
AccessVerdict
dataclass
Outcome of an authorization evaluation.
reason_code is populated on DENY with a canonical access-layer reason
code (see ARVIS_ACCESS_SPEC_V1 and the ReasonCodeRegistry). It is
None on ALLOW.
AccessContext
dataclass
The (principal, effect, resource) triple evaluated by a policy.
resource_scope names a narrower area than the whole organization: a
matter, a project, a folder, whatever the layer above calls it. The token
is OPAQUE to ARVIS, which never parses it, never derives a hierarchy from
it, and never treats one scope as containing another. It only hands it to
the scope rule the policy was given.
Leaving it None means the resource is not sub-scoped, which is how every resource behaved before scoped grants existed.
AuthenticatedPrincipal
dataclass
Bases: Principal
Host-attested identity accepted for production effects.
ARVIS does not authenticate credentials itself. The host authenticates the subject and constructs this explicit stamp on the trusted context channel. The additional fields are governance material, not secrets or credentials.
Principal
dataclass
Identity on whose behalf a syscall is executed.
A bare principal (user_id only, no organization, no grants) denotes the
resource owner. This reproduces the pre-authorization behaviour, where
access was scoped solely by user_id.
ResolvedAccess
dataclass
An access decision context plus the resource the resolver already read.
A resolver that must READ a resource to authorize (owner, organization and
scope live on the resource) can return this instead of a bare
AccessContext, carrying the resource it read so the syscall body reuses
it INSTEAD OF reading a second time. For a pure-READ syscall this collapses
the two lookups into one and closes the time-of-check/time-of-use gap at its
root: what was authorized is exactly what is returned, with no live store
between the two (counter-audit B3-VFS-01, b4).
resource is opaque to the kernel authorization path, which only reads
context; it is handed to the body verbatim. Resolvers that do not read a
resource keep returning a bare AccessContext; the handler treats that as
resource=None, so this is additive and backward-compatible.
The three lookup outcomes a reading resolver can report:
- it READ the resource:
resourceholds it,lookup_erroris None. A pure-READ body returns it directly (single-read). - the lookup raised an EXPECTED condition (not-found, ...):
resourceis None andlookup_errorholds that exception. Every receiving body maps it to its precise code WITHOUT a second lookup or effect, so a live store cannot answer the retry with a different resource (the TOCTOU that an absorbed expected failure would reopen). This gives finesse AND safety at once. - it read NOTHING (absent reference, root creation): both are None and the body proceeds as before.
OrganizationScopedAuthorization
Bases: AuthorizationPolicy
Reference organization-aware policy. Generic, not domain-specific.
It subsumes the personal case: a resource with no organization
(resource_organization_id is None) is owner-scoped, identical to
OwnerScopedAuthorization. A resource that belongs to an organization is
accessible when the principal belongs to that same organization and holds
the required capability.
Grants are opaque tokens. ARVIS only tests membership of the required
capability in principal.grants. Assigning meaning to those tokens, and
deciding which capability a given access requires, belongs to the
realization layer, which MAY inject capability_for.
A resource MAY also carry a resource_scope, naming a narrower area
inside the organization. Belonging to the organization and holding the
capability is then not enough: the principal's grants must also cover that
scope. The rule deciding coverage is injectable through scope_covers,
and defaults to verbatim equality, which is behaviour-neutral for resources
that carry no scope.
arvis.host_api.cognition
Cognitive inputs a host injects into a run.
The retrieval snapshot carrying grounded, host-side retrieval results into the governed pipeline.
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
CognitiveRetrievalSnapshot
dataclass
ZKCS-safe retrieval snapshot.
Contains: - no raw user data - no document text - no summaries - no reconstruction capability
arvis.host_api.control
PROVISIONAL: the host-side cognitive control runtime.
The control engine and its strategies (exploration, hysteresis, regime policy) a host may run as a component of its own product surface. This module is PROVISIONAL: it tracks the most active research area of the kernel, so its surface may change in a minor release. Changes are documented in the changelog; no deprecation window is guaranteed. Every other host_api module is stable.
What this engine is NOT (campaign SURFACE, DM-S3): it is not on the
kernel verdict path. The gate decision stack of the pipeline is the
only producer of the governed verdict; CognitiveControlEngine is
a host-side component whose recommendations never override, feed or
shadow that stack, and a structural contract test keeps the kernel
from ever importing it
(tests/contracts/test_control_engine_isolation.py).
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
CognitiveControlDeps
dataclass
Full dependency bundle for the control engine.
Inject concrete kernel implementations here.
CognitiveControlEngine
Host-side cognitive control runtime (NOT the kernel gate).
This engine is a component a host (for example a product embedding
arvis) runs on its own surface, exported through the PROVISIONAL
host_api.control module. It is not on the kernel verdict path:
the pipeline's gate decision stack is the only producer of the
governed verdict, this engine is never instantiated by the
pipeline, and a structural contract test keeps the kernel from
importing it (campaign SURFACE, DM-S3,
tests/contracts/test_control_engine_isolation.py). The
Lyapunov verdict it produces below is a host-side recommendation
computed with the same math primitives, not the governed decision.
It constructs its own IRGEpsilonController instance: tuning
the pipeline's controller does not tune this one, and vice versa
(constant unification is tracked by audit P1-9, campaign HARDEN).
Responsibilities: - fuse risk modulation - derive gate mode - compute epsilon - smooth risk - update drift/regime/dynamics - run adaptive/counterfactual recommendations - produce a host-side Lyapunov verdict recommendation
ExplorationController
Kernel-safe exploration/exploitation policy.
ModeHysteresis
Kernel-safe hysteresis controller.
Maintains cognitive mode stability across risk transitions.
CognitiveRegimePolicy
Kernel-safe regime → control mapping.
arvis.host_api.conversation
The propose-confirm conversational spine.
Pending turns and continuation resolution: how a host carries a governed proposal across turns until it is confirmed or dropped.
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
ContinuationResolver
Bases: Protocol
Boundary contract for deciding, purely, whether a follow-up turn answers a pending continuation.
A resolver handles exactly one kind. try_resolve inspects the
pending turn and the raw follow-up text and returns an opaque reference when
the turn answers the pending (an identifier the product maps back to an
action, or a token such as a confirm or cancel marker), or None when the
turn does not answer it. A resolver never executes and never performs IO:
turning a reference into an effect is the product's responsibility.
PendingTurn
dataclass
A deferred conversational continuation: the engine asked something and
awaits a follow-up of a given kind.
Kernel invariants: - immutable - declarative - no execution
kind and payload are opaque to arvis. A downstream product names the
kind (for instance a selection among candidates, or a confirmation) and is
the only party that interprets the payload. The payload carries references
only (identifiers, short markers), never heavy content such as message
bodies, so a pending turn stays bounded and auditable.
PendingTurnStatus
Bases: StrEnum
Lifecycle of a pending continuation.
A pending turn is created PENDING. It is CONSUMED when the next turn
answers it, or ABANDONED when the next turn is unrelated or a newer
pending replaces it. There is at most one active pending per conversation.
resolve_continuation
resolve_continuation(
pending: PendingTurn,
turn_text: str,
resolvers: Sequence[ContinuationResolver],
) -> str | None
Dispatch a follow-up turn to the resolver whose kind matches the pending.
Returns the opaque reference chosen by that resolver when the turn answers
the pending, or None when no resolver handles the pending's kind or the
turn does not answer it. A None result means the pending should be
abandoned and normal routing should resume. Pure: no IO, no execution.
arvis.host_api.engine
Building and configuring an engine.
The engine facade, its configuration, the low-level cognitive OS a host reaches for deterministic replay and IR control, and the contraction monitor configuration a host passes when constructing an engine.
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
ArvisEngine
Friendly public runtime wrapper for ARVIS.
ArvisEngine is the recommended high-level entrypoint for most users. Its surface is part of the beta contract: every method carries an explicit signature, and run-shaped methods return a single public type, CognitiveResultView.
The open-shaped input channels (cognitive_input,
conversation_context, timeline, confirmation_result, extra)
belong to host integration. host_context_available is deliberately
different: a typed, content-free host attestation and never raw context.
Example
from arvis import ArvisEngine
engine = ArvisEngine() result = engine.ask("Analyze this situation")
os
property
os: CognitiveOS
Low-level CognitiveOS instance.
config
property
config: CognitiveOSConfig
Runtime configuration.
version
property
version: str
ARVIS package version.
run
run(
user_id: str,
cognitive_input: Any,
*,
host_context_available: bool = False,
conversation_context: Any = None,
timeline: Any = None,
confirmation_result: Any = None,
extra: dict[str, Any] | None = None,
) -> CognitiveResultView
Execute a cognitive request.
run_as
run_as(
principal: AuthenticatedPrincipal,
cognitive_input: Any,
*,
host_context_available: bool = False,
conversation_context: Any = None,
timeline: Any = None,
confirmation_result: Any = None,
extra: dict[str, Any] | None = None,
) -> CognitiveResultView
Execute a cognitive request with a host-authenticated identity.
Delegates to :meth:CognitiveOS.run_as unchanged: the stamp must
be an exact AuthenticatedPrincipal (no subclasses), ARVIS
derives the turn owner from it, and the host stays responsible
for authenticating the session or service. This is the channel
PRODUCTION effect syscalls require (campaign SURFACE, DM-S2).
ask
ask(
prompt: str,
*,
user_id: str = "default",
host_context_available: bool = False,
conversation_context: Any = None,
timeline: Any = None,
confirmation_result: Any = None,
extra: dict[str, Any] | None = None,
) -> CognitiveResultView
Convenience method for prompt-style requests.
run_ir
run_ir(
user_id: str,
cognitive_input: Any,
*,
host_context_available: bool = False,
conversation_context: Any = None,
timeline: Any = None,
confirmation_result: Any = None,
extra: dict[str, Any] | None = None,
) -> dict[str, Any]
Execute and export canonical IR.
replay_verified
replay_verified(
ir: dict[str, Any], *, expected_global_commitment: str
) -> CognitiveResultView
Replay and authenticate an IR against an external commitment.
replay_recomposed
replay_recomposed(
ir: dict[str, Any],
) -> CognitiveResultView
Recompose an IR without authenticating it.
inspect
inspect(result: CognitiveResultView) -> dict[str, Any]
Inspect a CognitiveResultView.
register_tool
register_tool(tool: BaseTool) -> None
Register a tool.
freeze_tools
freeze_tools() -> str
Freeze the tool registry after bootstrap (F-004).
list_tools
list_tools() -> list[str]
List registered tools.
get_tool_spec
get_tool_spec(name: str) -> ToolSpec | None
Get tool specification.
list_tool_specs
list_tool_specs() -> dict[str, ToolSpec]
List all tool specifications.
CognitiveOS
The governed runtime: one instance runs ONE cognitive turn.
The host constructs an instance (optionally with a
CognitiveOSConfig), registers and freezes its tool surface, and
calls :meth:run once; parallelism and cross-turn continuity
belong to the host by instantiation (one engine per governed
turn). Every verdict composes a hashed commitment binding the
tool registry, the effective configuration, the active policy
tables and the redacted effect journals (F-007), so what ran is
what can be proven. :class:ArvisEngine is the recommended
facade; this class is the runtime it delegates to.
config
property
config: CognitiveOSConfig
Effective runtime configuration (F-004-a5).
Frozen at construction and not reassignable: the configuration the runtime was built with is the configuration it governs under, for the whole lifetime of the instance.
register_tool
register_tool(tool: Any) -> None
Register a tool (a BaseTool with a ToolSpec manifest).
Bootstrap-time only: after :meth:freeze_tools (or the first
run in the PRODUCTION profile, F-019) registration is
refused by the frozen registry.
freeze_tools
freeze_tools() -> str
Freeze the tool registry after bootstrap (F-004).
Returns the registry fingerprint for host-side pinning.
list_tools
list_tools() -> list[str]
Names of the registered tools, in registry order.
get_tool_spec
get_tool_spec(name: str) -> ToolSpec | None
Defensive copy of one tool's declared manifest, or None.
list_tool_specs
list_tool_specs() -> dict[str, ToolSpec]
Defensive copies of every declared manifest, by name.
run
run(
user_id: str,
cognitive_input: Any,
*,
host_context_available: bool = False,
conversation_context: Any = None,
timeline: Any = None,
confirmation_result: Any = None,
extra: dict[str, Any] | None = None,
) -> CognitiveResultView
Govern one turn and return its full result view.
cognitive_input follows the documented input contracts: a
dict carrying an explicit risk float rides the graded
three-band policy, and a bare string is governed with a
minimal projection (conservative by construction; see
docs/PATH_TO_ALLOW.md). Thread the previous turn's
view.next_scientific_state back in through
extra={"scientific_state": ...} to make the trajectory
measurable (DM-S4). The view carries the verdict
(status), the stability assessment, the exported IR and
the composed global_commitment.
run_as
run_as(
principal: AuthenticatedPrincipal,
cognitive_input: Any,
*,
host_context_available: bool = False,
conversation_context: Any = None,
timeline: Any = None,
confirmation_result: Any = None,
extra: dict[str, Any] | None = None,
) -> CognitiveResultView
Run with a host-authenticated identity on the trusted channel.
ARVIS validates the explicit stamp and derives the turn owner from it; the host remains responsible for authenticating the session or service.
run_ir
run_ir(
user_id: str,
cognitive_input: Any,
*,
host_context_available: bool = False,
conversation_context: Any = None,
timeline: Any = None,
confirmation_result: Any = None,
extra: dict[str, Any] | None = None,
) -> dict[str, Any]
Govern one turn and return only the exported canonical IR.
Same contract as :meth:run; the return value is the
portable, replayable record (docs/IR.md) rather than the
full result view.
replay_verified
replay_verified(
ir: dict[str, Any], *, expected_global_commitment: str
) -> CognitiveResultView
Replay an IR and AUTHENTICATE it against an external commitment.
Campaign 5 (D-6): expected_global_commitment is MANDATORY.
The IR is recomposed and its global commitment is checked
against the value the caller supplies from a source OUTSIDE the
IR (a signed record, an append-only journal, a host attestation).
A missing or mismatched commitment raises. Replaying an IR and
trusting the commitment it carries about itself proves nothing;
authentication requires an external anchor. The host owns that
anchor's durability (documented host requirement).
This intentionally has no default: a caller with nothing to
check against wants :meth:replay_recomposed, which says so.
replay_recomposed
replay_recomposed(
ir: dict[str, Any],
) -> CognitiveResultView
Recompose an IR into a view WITHOUT authenticating it.
Campaign 5 (D-6): the recomposed view carries a freshly computed
commitment, but nothing here proves it matches the commitment of
the original run: no external anchor is checked. The name says
so. Use this to inspect or rebuild an IR; use
:meth:replay_verified when you have an external commitment to
authenticate against and want a trust decision.
inspect
inspect(result: CognitiveResultView) -> dict[str, Any]
One dict with a result's summary, trace, stability and IR.
A convenience for operators and debuggers; every field is also reachable directly on the view.
CognitiveOSConfig
dataclass
production
classmethod
production(**overrides: Any) -> CognitiveOSConfig
Closed production profile.
Doctrine: deny-by-default is an attribute of the PRODUCTION profile, not of the library. The factory fixes runtime_mode=PRODUCTION and defaults the audit commitment policy to REQUIRED. Other fields can be overridden, but the production invariants enforced by post_init cannot be weakened: an override that relaxes them is refused at construction (F-003-a5).
CognitiveResultView
dataclass
Public result of a governed run (beta contract).
The public decision contract is :attr:status (typed) and the
structured decision block of :meth:to_dict; decision
itself carries the rich kernel object. stability and trace
are deliberately Any: heterogeneous internal enrichment
channels, surfaced through their typed *_view companions.
status
property
status: DecisionStatus
Typed public verdict of the run (beta contract, a15).
quickstart_payload
quickstart_payload() -> dict[str, Any]
Compact structured payload intended for examples, onboarding, demos, and README snippets.
to_json
to_json(*, indent: int = 2) -> str
Stable JSON serialization of public structured output.
Strict JSON (b1, audit a17, 13.1): a non-finite float would serialize as NaN/Infinity, which are not valid JSON numbers; this fails loudly instead of emitting an out-of-contract document.
quickstart_json
quickstart_json(*, indent: int = 2) -> str
Compact JSON payload for quickstarts.
explain
explain() -> str
Human-friendly executive summary intended for examples, demos, CLI usage, and onboarding.
pretty
pretty() -> str
Pretty printed structured payload for terminal use.
DecisionStatus
Bases: StrEnum
Public, typed verdict of a governed run (beta contract, a15).
The three risk bands of the governed gate, plus NONE for views that
carry no decision (the minimal no-trace view). This enum, together
with the structured decision block of
CognitiveResultView.to_dict(), is the public contract of a
decision: consumers must never derive a verdict from the repr of an
internal object (audit a14, A14-BETA-02).
from_decision
classmethod
from_decision(decision: Any) -> DecisionStatus
Derive the public status from a decision object.
Reads the declarative surface of the kernel decision
(allowed, requires_user_validation); a confirmation
requirement is neither a clean pass nor a hard block, so it
surfaces as its own band. An absent decision maps to NONE.
ContractionMonitorCore
v0 contraction monitor.
Pure transition; no slow/symbolic state, no composite-W.
governance_manifest
governance_manifest() -> dict[str, Any]
Declarative identity for commitment fingerprinting.
Binds the monitor's actual calibration into the run commitment (component_fingerprint_material), so two runs governed by differently calibrated monitors never share a commitment while pretending to be the same component.
MonitorConfig
dataclass
Calibratable v0 constants. Defaults match the v0 contract.
arvis.host_api.knowledge
The knowledge flow.
Events, signals, snapshots and state a host exchanges with the knowledge subsystem.
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
KnowledgeEvent
dataclass
Declarative knowledge event.
Kernel invariants: - immutable - no side effects - no internal generation
KnowledgeSignal
Bases: StrEnum
Declarative signals explaining why a given KnowledgeState was reached.
A KnowledgeSignal is: - observable - non-sensitive - non-semantic - non-decisional
It does NOT: - assert truth - store content - trigger behavior - enforce policy
KnowledgeSnapshot
dataclass
Immutable, declarative snapshot of system epistemic state at a given moment in time.
KnowledgeState
Bases: StrEnum
Declarative representation of system knowledge awareness.
This is NOT: - confidence - correctness - response quality
It is a structural signal used to model what the system knows or does not know.
arvis.host_api.llm
The LLM adapter contract.
The response type a host-provided language model adapter produces for the governed runtime.
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
LLMResponse
Bases: BaseModel
A provider-neutral completion: content plus usage and provenance.
What the LLM runtime hands back to the pipeline whatever the provider; hosts see it when they bind a runtime of their own.
arvis.host_api.memory
Governed long-term memory.
The repository protocol a host implements for persistence, the entry and record types, the policy gate, the context projector that turns stored entries into turn context, the default type registry, and the governance vocabulary (visibility, sharing, retention, encryption, principal).
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
Governance
dataclass
Governance regime attached to a long-term memory fact.
The four levers -- visibility, sharing, retention, encryption -- are the substrate. The personal-facing N0-N3 presets live in the surface layer. Composition (personal vs organization) takes the strictest value lever-by-lever and is handled by the PolicyGate.
Defaults are backward-compatible and conservative: the value grounds answers without being echoed, personal scope only, kept until revoked, server-side encryption at rest, authored by the user.
GovernanceEncryption
Bases: StrEnum
Encryption mode, least to most restrictive.
GovernancePrincipal
Bases: StrEnum
Authority that authored the governance regime.
GovernanceRetention
Bases: StrEnum
Retention intent, least to most restrictive.
GovernanceSharing
Bases: StrEnum
Sharing scope, least to most restrictive.
GovernanceVisibility
Bases: StrEnum
How a declared value may surface, least to most restrictive.
MemoryLongEntry
dataclass
Kernel representation of long-term memory.
ZKCS guarantees: - content-agnostic - immutable - temporal traceability
MemoryLongType
Bases: StrEnum
Declarative types of long-term memory.
Kernel guarantees: - no user content - classification only
MemoryLongPolicyGate
PolicyGate for long-term memory append operations.
Guarantees: - declarative only - no arbitrary keys - controlled TTL - notes are system-only
validate_append
validate_append(entry: MemoryLongEntry) -> None
Validate whether an entry is allowed.
Raises ValueError if refused.
compose
compose(
*, personal: Governance, organization: Governance
) -> Governance
Compose a personal regime with an organization policy, taking the strictest value lever-by-lever. The organization is a non-negotiable floor when a personal fact enters its scope.
MemoryLongContextProjector
Projects long-term declarative memory into cognition-safe signals.
ZKCS invariant: - no ciphertext access - no payload reconstruction - only key-level declarative projection
MemoryLongRepository
Bases: ABC
Abstract repository for long-term memory entries.
Read-only from the cognition perspective. No inference, no validation, no write policy.
list_entries
abstractmethod
list_entries(*, user_id: str) -> list[MemoryLongRecord]
Return all entries (raw).
Includes: - active - revoked - expired
No filtering here (low-level access).
- no ordering guarantees
- no filtering logic here
list_active_entries
abstractmethod
list_active_entries(
*, user_id: str
) -> list[MemoryLongEntry]
Return ACTIVE entries only.
Filtering rules (implementation side): - revoked_at is None - expires_at is None or in the future
This is the DEFAULT method used by cognition layer.
list_active_entries_batch
abstractmethod
list_active_entries_batch(
*, user_ids: Iterable[str]
) -> dict[str, list[MemoryLongEntry]]
Batch read for scalability (multi-user inference / async pipelines).
Returns:
| Type | Description |
|---|---|
dict[str, list[MemoryLongEntry]]
|
{ user_id: [MemoryLongEntry, ...], ... |
dict[str, list[MemoryLongEntry]]
|
} |
MemoryLongSnapshot
dataclass
Read-only snapshot of active long-term memory.
- no content
- no reasoning
- no personalization logic
arvis.host_api.services
Mounting host services into the kernel.
The syscall protocol and the service registry through which a host mounts its own governed services (storage, mail, domain tools).
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
SyscallHandler
The mediated boundary every kernel-visible operation crosses.
Dispatches cognitive syscalls under a sealed identity context: effect payloads are frozen and redacted at authorization, capabilities are single-use, and each effect journals a pre-effect intent bound to its result (F-008-a5). Hosts receive it through arvis.host_api.services for advanced integrations; the engine wires it automatically.
begin_run
begin_run(run_id: str) -> None
Mark the entry of a run (campaign 6, Lot 5).
Called by the runtime with a fresh unguessable run id before any syscall of the run. Also clears the pending intent commitment map: a run boundary never leaks pairing state into the next run.
handle
handle(syscall: Syscall) -> SyscallResult
Coordinate admission, outbox activation, dispatch and journaling.
KernelServiceRegistry
dataclass
Registry of kernel-level services available to syscalls.
This keeps SyscallHandler scalable by avoiding constructor growth as new subsystems are added.
SyscallEffect
Bases: StrEnum
Governance-relevant, structural effect class of a syscall.
READ: no state mutation and no external side-effect (idempotent). EFFECT: mutates governed state and/or triggers an external effect.
This is a STRUCTURAL property declared at registration time. It is NOT the runtime governance verdict (ALLOW / REQUIRE_CONFIRMATION / ABSTAIN), which is decided per-turn by the cognitive gate.
arvis.host_api.telemetry
Observing a run.
The in-memory sink a host hands to the engine and the event kinds it reads back.
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
InMemoryTelemetrySink
Append-only, thread-safe, deterministic in-memory sink.
Intended for tests, replay verification, and local introspection. Reads return defensive copies to prevent external mutation.
TelemetryKind
Bases: StrEnum
Categories of observe-only telemetry events.
Telemetry never enters any fingerprint or commitment (a pinned exclusion, DM-H5): emitting more or less of it cannot change what a run commits to.
arvis.host_api.tools
Declaring and running governed tools.
The base class and spec a host implements for its domain tools, the registry, manager and executor of the governed tool runtime, and the policy-evaluation objects a host uses to authorize an invocation: the invocation, its authorized effect context, and the evaluator.
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
ToolInvocation
dataclass
One tool invocation with frozen payload and sealed effect context.
payload
property
payload: dict[str, Any]
Fresh execution-safe copy of the authorized payload.
frozen_payload
property
frozen_payload: FrozenEffectPayload
Immutable canonical payload owned by this invocation.
payload_sha256
property
payload_sha256: str
Canonical payload hash captured before authorization.
canonical_payload_bytes
property
canonical_payload_bytes: bytes
Canonical payload bytes captured before authorization.
materialize_payload
materialize_payload() -> dict[str, Any]
Explicit payload materialization for validation or execution.
ToolPolicyEvaluator
Evaluates one tool invocation against the registered manifests.
Enforces registration and the manifest's declared risk budget
(max_risk) in every profile. The consent and egress gates
are the HOST's: in the PRODUCTION profile a tool declaring
required_consent or data_egress is denied when the
matching host gate is missing (F-017, F-018); other profiles
leave that decision to the host.
BaseTool
Bases: ABC
input_data contains: - tool_payload - idempotency_key - invocation - effect_context
validate
validate(input_data: dict[str, Any]) -> None
Optional validation hook. Raise Exception if invalid.
execute_invocation
execute_invocation(invocation: ToolInvocation) -> Any
New structured execution path. Default fallback to legacy.
AuthorizedEffectContext
dataclass
Sealed identity and provenance visible to one authorized effect.
The authentication fields describe the provenance asserted by the host;
they are not credentials and ARVIS does not authenticate them. A local
profile may use explicit values such as "unattested" and "none".
Production admission separately requires those values to match the exact
:class:~arvis.kernel_core.access.models.AuthenticatedPrincipal on the
trusted current context.
commitment_sha256
property
commitment_sha256: str
Canonical SHA-256 of every authorized effect-context field.
to_material
to_material() -> dict[str, Any]
Return the complete canonical commitment material.
ToolExecutor
Executes an AUTHORIZED tool invocation, never a raw one.
The private minting authority binds execution to the authorization that approved it; calling a tool around this class bypasses the guarantees (docs/architecture/EFFECT_PATH.md).
claim_minting_authority
claim_minting_authority() -> InvocationAuthority
Public mint claims are forbidden; composition owns the authority.
execute_invocation
execute_invocation(
authorized: AuthorizedInvocation, result: Any, ctx: Any
) -> ToolResult | None
Public capability execution is forbidden outside SyscallHandler.
execute
execute(
arg1: Any, arg2: Any | None = None
) -> ToolResult | None
Direct execution is forbidden (D-7).
There is no unauthorized path to an effect. A tool runs only
through :meth:execute_invocation handed a capability the tool
manager minted after its policy authorized the invocation. Every
direct form raises, so neither a tool name nor a rebuilt
result/ctx can drive an effect that policy never evaluated.
ToolManager
Unified tool lifecycle orchestrator.
Responsibilities:
- authorize an invocation fully BEFORE the effect syscall
(:meth:authorize)
- provide private activation/execution operations only to the single
SyscallHandler that claims the effect boundary
Retry orchestration is owned by CognitiveRuntime and must pass through SyscallHandler for audit/replay consistency; every attempt is re-authorized, so every intent binds its own fresh verdict.
authorize
authorize(
result: Any, ctx: Any
) -> ToolAuthorizationOutcome | None
Authorize one immutable invocation before the effect syscall.
Static preparation is delegated to :class:ToolAuthorizationService.
The manager retains only the security-sensitive responsibilities:
confirmation transaction ownership and capability minting.
owns_outcome
owns_outcome(outcome: ToolAuthorizationOutcome) -> bool
Whether an exact outcome is admissible for this manager.
Allowed outcomes must carry the exact intact capability registered by this manager's private authority. Refusal outcomes have no executable capability; their constructor-level invariant is sufficient because they can only produce a pre-effect refusal.
activate_authorized
activate_authorized(*args: Any, **kwargs: Any) -> bool
Public activation is forbidden; SyscallHandler owns this transition.
abort_authorized
abort_authorized(*args: Any, **kwargs: Any) -> bool
Public revocation is forbidden outside the syscall transaction.
execute_authorized
execute_authorized(
*args: Any, **kwargs: Any
) -> ToolResult | None
Public capability execution is forbidden outside SyscallHandler.
capability_state
capability_state(authorized: Any) -> CapabilityState | None
Return the lifecycle state of an exact manager-owned capability.
capability_activation
capability_activation(
authorized: Any,
) -> CapabilityActivationBinding | None
Return the immutable receipt binding of an exact capability.
run
run(result: Any, ctx: Any) -> ToolResult | None
Direct effect composition is not part of the public runtime surface.
ToolRegistry
The declared tool surface: capture, freeze, fingerprint.
Registration captures each tool's manifest as canonical bytes;
:meth:freeze pins the surface (F-004) and returns the
fingerprint the commitment composes over. References handed out
are caller-owned copies, never the private capture
(A14-BETA-01).
register
register(tool: BaseTool, *, replace: bool = False) -> None
Register a tool under its declared name.
F-004: a governed registry is never mutated silently. A frozen registry refuses any registration, and re-registering an existing name requires an explicit replace=True.
The tool's declared spec is captured here, once: schemas are canonicalized and the private copy is rebuilt from those bytes. Registration is atomic; if the capture is refused, nothing is registered (and an explicit replacement leaves the previous registration in place).
freeze
freeze() -> str
Freeze the registry after bootstrap.
The manifest is snapshotted here, as canonical bytes, and the fingerprint is computed from that snapshot exactly once; neither is ever recomputed from live objects afterwards. Freezing an already frozen registry is idempotent and returns the pinned fingerprint. Returns the registry fingerprint so the host can pin and audit the frozen tool surface.
manifest
manifest() -> dict[str, Any]
Canonical, governance-complete description of the surface.
One entry per registered tool: identity (registry name,
implementation qualname, declared spec name) and every
governance-relevant spec field. Declared schemas appear as
canonical sha256 hashes, never in clear (F-018 coherence): the
manifest commits to the schemas without carrying content. Tools
without a spec expose "spec": None.
Once frozen, the manifest is decoded from the frozen snapshot bytes: every call returns a fresh document, and mutating a returned document cannot reach the pinned surface.
fingerprint
fingerprint() -> str
Deterministic hash of the governance manifest of the surface.
sha256 of the canonical JSON serialization of :meth:manifest.
Any governance-relevant change (a tool added or replaced, a spec
flag, a schema, the manifest structure version) changes the
fingerprint the host has pinned. Once frozen, the pinned
fingerprint is returned as-is and never recomputed.
get_spec
get_spec(name: str) -> ToolSpec | None
Defensive copy of the captured spec, for inspection.
Mutating the returned spec's schemas cannot reach the registry: every call rebuilds them from the canonical bytes captured at registration.
list_specs
list_specs() -> dict[str, ToolSpec]
Defensive copies of every captured spec, for inspection.
verified_spec
verified_spec(name: str) -> ToolSpec | None
Spec for the governed effect path, integrity-checked when frozen.
Authorization and dispatch read the tool surface through this method, never through the live tool object. Once the registry is frozen, the private capture is re-canonicalized and compared to the bytes pinned at registration; any divergence (an internal mutation of the captured surface) refuses the read fail-closed instead of validating against a surface the host never pinned.
Every call returns a fresh ToolSpec rebuilt from the pinned canonical bytes, never the private capture itself (audit a14, A14-BETA-01): the returned object is caller-owned, so no reference obtained here can modify the surface a later authorization or dispatch validates against, even between check and use. The bytes are immutable, so the copy is atomic with respect to any concurrent mutation of schema dictionaries.
ToolSpec
dataclass
crosses_trust_boundary
property
crosses_trust_boundary: bool
Whether executing this tool involves a third party (a provider), so it is not a purely local, in-boundary execution. A host reads this to separate sovereign tools (no provider) from connected ones.
arvis.host_api.vfs
The governed virtual file system surface.
The item model a host adapter translates its store into, and the typed exceptions its routes are expected to handle.
Re-export layer only: every symbol is defined where it lives; this module pins the import path (see VERSIONING.md, host integration surface).
VFSCycleError
VFSError
Bases: ArvisDomainError
Base class for all VFS domain errors.