agentivium-core

Agentivium Core

agentivium-core defines the small, domain-neutral contracts shared by Agentivium agent-native systems. It provides typed schemas and abstract interfaces for intent parsing, policy validation, planning, tool adaptation, provider-neutral LLM calls, execution tracing, evaluation, and stateful assistant runtimes. Version 0.6.0 hardens the formal verification kernel with strict critical-check aggregation, typed counterfactuals, deterministic output, and explicit component composition on top of the 0.5 memory and retrieval layer.

It is not an agent runtime, a provider-specific LLM wrapper, or a domain implementation. Schedulers, provider clients, policies, and orchestration belong in extension packages.

Install

pip install agentivium-core

For local development:

pip install -e ".[dev]"

Extend the core

Domain packages subclass schemas and implement interfaces:

from agentivium_core.intent import IntentIR, IntentParser


class MyIntentIR(IntentIR):
    domain: str = "my_domain"
    task: str


class MyIntentParser(IntentParser):
    def parse(
        self,
        request: str,
        context: dict[str, object] | None = None,
    ) -> MyIntentIR:
        return MyIntentIR(raw_request=request, task=request)

The dependency direction stays one-way: domain packages import agentivium_core; the core never imports a domain package.

Verifiable intent kernel

The 0.4.0 kernel keeps domain semantics in extensions while core provides the mechanism:

Intent + snapshots + candidate decision + evidence
  → verification checks
  → intent-decision relation
  → admissibility
  → approval / escalation
  → guarded domain execution
  → audit trace

The default policy fails closed: unsupported hard constraints, unknown policy compliance, missing required evidence, contradictions, expired snapshots, and provider exceptions cannot produce an accepted decision. Admissibility remains separate from authorization and approval.

Stable cross-package imports are documented in the 0.4 compatibility note. See the verifiable-intent guide for a complete non-domain extension example and strictness behavior. The additive formal verification contract documents strict aggregation, typed counterfactuals, deterministic output, and provider APIs.

The additive public changes and migration notes are documented in the 0.6 compatibility note.

Memory and retrieval

The 0.5.0 memory layer makes lifecycle and authority boundaries explicit. Records declare scope, namespace, provenance, confidence, expiry, and supersession. Retrieval excludes expired or superseded records by default. Compaction is an application-replaceable contract; the offline reference implementation preserves recent turns verbatim and produces a traceable summary without storing hidden reasoning.

from agentivium_core.memory import InMemoryMemoryStore, MemoryQuery, MemoryRecord
from agentivium_core.retrieval import MemoryRetriever

store = InMemoryMemoryStore()
store.add(
    MemoryRecord(
        memory_id="preference-1",
        memory_type="preference",
        text="Prefer concise answers",
        content={"response_style": "concise"},
        thread_id="thread-1",
    )
)

matches = store.query(MemoryQuery(text="concise", thread_id="thread-1"))
results = MemoryRetriever(store, thread_id="thread-1").retrieve("concise")

Vector retrieval remains optional: applications inject an EmbeddingClient and a VectorStore; Core includes only an in-memory cosine adapter for tests and small local deployments. See the 0.5 compatibility note.

Public API

from agentivium_core.intent import IntentIR, IntentParser
from agentivium_core.planner import ActionPlan, Planner
from agentivium_core.policy import (
    PolicyValidator,
    ValidationIssue,
    ValidationResult,
)
from agentivium_core.tools import ToolAdapter
from agentivium_core.trace import ExecutionTrace
from agentivium_core.eval import EvaluationRecord

Stateful assistant runtime

Agentivium Core 0.3.0 added reusable abstractions for multi-turn assistant systems: conversation state, context packs, memory, retrieval, ambiguity modeling, clarification requests, intent updates, tool permissions, trace events, and multi-turn evaluation records.

from agentivium_core.clarification import (
    BlockingFirstClarificationPlanner,
    IntentAmbiguity,
)

ambiguities = [
    IntentAmbiguity(
        field="policy.account",
        ambiguity_type="missing_required",
        severity="blocking",
        reason="Account is required.",
        question="Which account should I use?",
    )
]

planner = BlockingFirstClarificationPlanner()
request = planner.plan_clarification(ambiguities)

print(request.questions[0].question)

Domain packages specialize these contracts. For example, hpc-claw can build HPC-specific context providers, policy checks, and tool adapters on top of the core assistant-runtime interfaces without adding scheduler logic to core.

Provider-neutral LLM abstraction

agentivium-core defines LLMClient, LLMRequest, LLMResponse, PromptTemplate, StructuredOutputSpec, and LLMCallTrace so downstream packages can use LLMs without coupling core to OpenAI, Anthropic, Gemini, Ollama, vLLM, llama.cpp, or any other provider.

from agentivium_core.llm import (
    LLMClient,
    LLMRequest,
    LLMResponse,
    PromptTemplate,
)


class MyLocalLLMClient(LLMClient):
    def generate(self, request: LLMRequest) -> LLMResponse:
        return LLMResponse(content='{"intent": "example"}', model="local")


template = PromptTemplate(
    name="intent_parser",
    system="You extract structured intent.",
    user_template="Request: {request}",
)

messages = template.render({"request": "Run a small MPI job."})
client = MyLocalLLMClient()
response = client.generate(LLMRequest(messages=messages))
print(response.content)

Production provider clients live in domain or provider packages. Core only defines the contracts and a MockLLMClient for tests and demos.

See the concepts, API reference, extension guide, and examples. The complete v0.1 rationale and boundaries are preserved in the original design guideline.