Jarvis Core

jarvis-agent-core is a small, typed, dependency-free Python library for building portable AI-agent runtimes. It provides reusable contracts and deterministic runtime primitives without requiring a particular model vendor, application, database, deployment platform, user interface or operating-system sandbox.

The package is designed to be useful standalone. Any Python application can install it, implement the provider protocol, and reuse the shared runtime contracts.

Install

Python 3.10+ is required. The current release is 0.16.0.

python -m pip install "jarvis-agent-core==0.16.0"

For development:

git clone https://github.com/abdullahalrifat/jarvis-core.git
cd jarvis-core
python -m pip install -e . -r requirements-dev.txt
python -m pytest

0.16.0 highlights

The 0.16.0 release adds provider-neutral empirical route calibration on top of the existing token-efficient runtime primitives:

• Empirical route observations capture quality, correctness, latency, token usage, cost, tool failures, cache usage, source and timestamp.
• Recency-weighted scoring gives recent production evidence more influence than stale observations.
• Conservative routing safeguards require a minimum sample count and configurable quality floor before measured evidence can change route selection.
• Reusable utility scoring balances quality and reliability with latency, cost and tool failures.
• Backward-compatible observations allow existing consumers to continue loading older route evidence.

Calibration ownership

Core is the canonical home for the reusable calibration algorithm. The intended production architecture is:

Jarvis CLI -> AI Stack -> provider/model
     │             │
     └──────┬──────┘
            ▼
       jarvis-core
   contracts + calibration

• Core: observation contracts, calibration algorithm, recency weighting, quality safeguards and route utility.
• AI Stack: provider execution, runtime telemetry, persistence and conversion of telemetry into Core observations.
• Jarvis: CLI behavior, real workload definitions and task-level evaluation.

Neither downstream application should implement a second calibration algorithm, and Core must never depend on either downstream application.

The 0.15.0 release added provider-neutral primitives for making agent execution more token-efficient and predictable:

• Context budgets for bounded prompt/context construction.
• Deterministic context compilation so relevant context can be selected and ordered consistently.
• Agent state ledgers for compact, structured execution state instead of repeatedly replaying large histories.
• Token estimation and usage/cost accounting for requests and accumulated model usage.
• Route budgets and adaptive routing so applications can choose an appropriate model based on remaining budget and task signals.
• Failure and command/file state recording for compact runtime bookkeeping.

These primitives are intentionally provider-neutral. Anthropic, Ollama, Hugging Face, LiteLLM and other provider integrations remain responsibilities of the consuming application. Provider-specific caching metadata, SDK behavior, credentials and transport logic do not belong in Core.

A typical application can use the primitives to keep the agent loop efficient: retrieve only relevant repository context, keep stable state structured and compact, use lightweight/local models for simple work, escalate to stronger models when task signals justify it, and rely on deterministic tools and verification rather than spending model tokens on work the runtime can perform directly.

See CHANGELOG.md for the complete release history.

What Core provides

Core contains provider-neutral building blocks for:

• model requests, responses, usage and tool calls;
• provider capability and routing primitives;
• empirical route calibration and benchmark evidence;
• agent capabilities and approval decisions;
• portable sandbox requirements and consumer-owned sandbox executor contracts;
• token accounting, budgets and context compaction;
• artifacts and content-addressed references;
• evidence, verification and completion requirements;
• failure classification, recovery and retry policy;
• multi-agent tasks, teams and orchestration;
• instructions, memory and MCP permission vocabulary;
• schedules, remote-run and execution-state contracts;
• leases, permissions and execution-proof records;
• repository/developer-intelligence primitives;
• evaluation cases, benchmarks and tracing;
• review/change transactions and verification policy;
• reusable sandbox policy and host-boundary validation.

Common agent brain boundary

Core owns the meaning of agent execution: model contracts, tool vocabulary, capabilities, approval semantics, evidence, verification, execution state and portable isolation requirements. Applications own the actual execution adapters.

The Core boundary is deliberately implementation-neutral. A CLI can implement a sandbox with native OS primitives, while a server can implement the same requirements with containers or another isolated worker. Both consume the same policy semantics.

Provider-neutral model boundary

Core defines the model boundary but never ships a model-provider SDK. Concrete HTTP transports, SDK clients, credentials, endpoint-specific request formatting, retries and provider-specific error handling remain application responsibilities.

What Core deliberately does not do

Core does not:

• call model APIs;
• store API keys or credentials;
• execute shell commands or arbitrary repository changes;
• provide a database or persistence backend;
• provide a web server, CLI or user interface;
• start MCP processes;
• enforce operating-system isolation itself;
• provide a cloud-worker implementation;
• impose tenancy, deployment or organization policy.

This boundary keeps the package portable and safe to embed in different applications.

Compatibility and release policy

• semantic versioning is used while the pre-1.0 API stabilizes;
• patch releases should remain compatible within a minor line;
• breaking public contracts require a new minor version while the API remains pre-1.0;
• releases are immutable once published;
• PyPI publication uses GitHub Actions Trusted Publishing;
• the package README is the PyPI project description, so documentation changes intended for PyPI require a new package version;
• every release-worthy change must update pyproject.toml, CHANGELOG.md, README.md when applicable, and relevant docs/ files in the same PR;
• CI enforces that the package version, changelog entry and README current-release/install version stay synchronized.

Release flow

code/docs change
    -> version + CHANGELOG + README/docs
    -> CI metadata consistency check
    -> full CI
    -> merge to main
    -> validate exact merged SHA
    -> build wheel + sdist
    -> clean-environment install check
    -> checksums + provenance
    -> GitHub Release
    -> PyPI Trusted Publishing

Consumers should depend on a published PyPI version rather than a mutable Git branch. During local development, an editable checkout may be used explicitly.

Development checks

python scripts/check_release_consistency.py
black --check src tests
ruff check src tests --select E9,F63,F7,F82
pytest -q --cov=jarvis_core --cov-report=term-missing --cov-fail-under=85
python -m build
python -m twine check dist/*

See docs/contract-boundaries.md, docs/empirical-calibration.md, docs/releasing.md, CONTRIBUTING.md, AGENTS.md and SECURITY.md.

License

Jarvis Core is available under the MIT License.