Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

Jarvis Core

Validate Release PyPI Python License: MIT

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.18.0, which adds persistent HTTP(S) connections via InferenceClient keepalive support, and hardens ledger reservation cleanup, bounds retry sleeps with a total deadline, and decodes OpenAI JSON-string tool-call arguments. Publish this version only after the release workflow completes.

python -m pip install "jarvis-agent-core==0.18.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

Shared inference client (0.18.0)

Both the Jarvis CLI and AI Stack use the Core inference client rather than implementing gateway configuration and protocol handling independently. Core provides a dependency-free InferenceConfig and InferenceClient for bearer authentication, model discovery, capability negotiation, chat completions, SSE streaming, embeddings, request IDs, and normalized transport errors. Applications retain ownership of their agent loops, tools, approvals, persistence, cancellation policy, and telemetry.

from jarvis_core import InferenceClient

client = InferenceClient.from_env(user_agent="my-agent/1.0")
models = client.list_models()
response = client.complete(
    model="qwen3:1.7b",
    messages=[{"role": "user", "content": "Hello"}],
)

Set INFERENCE_BASE_URL=http://inference-host:8080/v1 and INFERENCE_API_KEY for the gateway. JARVIS_BASE_URL and JARVIS_API_KEY remain supported as compatibility fallbacks. Core retries only explicit pre-admission QUEUE_TIMEOUT / QUEUE_FULL rejections, using Retry-After plus jitter; ambiguous generation/transport timeouts and failures after streaming starts are never replayed. Structured SSE error frames are surfaced as InferenceClientError instead of being returned as successful model events. INFERENCE_QUEUE_RETRIES defaults to 1 (maximum 3), and INFERENCE_QUEUE_RETRY_BACKOFF_SECONDS defaults to 0.5.

0.16.2 highlights

The 0.16.2 release adds the cost-aware local-first routing layer and keeps the previous empirical calibration and token-efficiency primitives intact:

  • Cost-aware tier routing chooses between local, cheap-cloud and frontier tiers using deterministic task signals.
  • Bounded escalation prevents repeated failures from creating unbounded model retries and escalates only after the configured tier budget is exhausted.
  • Cheapest eligible model selection allows consumers to select the least expensive enabled model within a tier using estimated input, cached-input and output costs.
  • Verification-aware decisions mark security-sensitive or elevated-risk work for downstream verification.
  • Provider-neutral design keeps concrete provider SDKs, credentials, pricing configuration and model execution outside Core.
  • Black formatting compliance keeps the new routing implementation and tests aligned with the repository's CI formatter.

Cost-aware routing ownership

Core owns the reusable routing policy; applications map the abstract tiers to concrete providers and models:

Deterministic tools
       │
       ├── no LLM when possible
       │
       ▼
   LOCAL tier
       │
       │ bounded failures / elevated complexity
       ▼
   CHEAP tier
       │
       │ bounded failures / high risk
       ▼
 FRONTIER tier
  • Core: routing signals, tier decisions, failure budgets and cost-aware model selection.
  • AI Stack: provider execution, concrete model configuration, pricing data, telemetry and persistence.
  • Jarvis: CLI behavior, workload definitions, user approvals and task-level evaluation.

The intended default for a constrained personal server is local-first execution. Cloud tiers remain opt-in and should only be configured when a stronger model is needed.

The 0.16.0 release added provider-neutral empirical route calibration:

  • 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.

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;
  • cost-aware local/cheap/frontier routing and empirical route calibration;
  • 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 and does not ship vendor SDKs. The shared InferenceClient owns the common Jarvis inference-gateway HTTP contract; applications may keep provider SDKs and vendor-specific transports, credential lifecycle, cancellation policy, telemetry and task-specific error handling at their own boundary.

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 scripts
ruff check src tests scripts --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/cost-aware-routing.md, docs/empirical-calibration.md, docs/releasing.md, CONTRIBUTING.md, AGENTS.md and SECURITY.md.

License

Jarvis Core is available under the MIT License.

Metadata

Release files for jarvis-agent-core 0.18.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

Source distribution for jarvis-agent-core 0.18.0
File Size Uploaded Provenance Actions
jarvis_agent_core-0.18.0.tar.gz 77.2 kB With provenance Details for jarvis_agent_core-0.18.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jarvis-agent-core 0.18.0
File Interpreter ABI Platform Actions
jarvis_agent_core-0.18.0-py3-none-any.whl Python 3 none any Details for jarvis_agent_core-0.18.0-py3-none-any.whl

Total release size: 148.2 kB

Release files / jarvis_agent_core-0.18.0.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL jarvis_agent_core-0.18.0.tar.gz
Size 77.2 kB
Tags Source
SHA-256 checksum
How to use checksums
6a0f83b3f590f7fbef2a3139bc4812f63da4ec3697a576af6098bf41d327bad6
BLAKE2b-256 checksum
How to use checksums
af63bc52ff3804db981fe5ff3deb9ec139237c6fd4823105c789e5af61d125dd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / jarvis_agent_core-0.18.0-py3-none-any.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL jarvis_agent_core-0.18.0-py3-none-any.whl
Size 71.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eac0990c715686e60bba33392e1068761e84c39c95c8df9a5aef2541dfec5aa7
BLAKE2b-256 checksum
How to use checksums
08137ebed199d38814833fa2e1ebfacd02eb95634efb303c8547bfa8eb6ea935
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for jarvis-agent-core 0.18.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Change of provenance

The repository and configuration that created this release differ from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Select from 2 files

Attestation for jarvis_agent_core-0.18.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page