Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Swarmauri Logo

PyPI - Downloads Hits PyPI - Python Version PyPI - License PyPI - swarmauri_core Discord

Swarmauri Core

Composable execution contracts

The executions, tasks, workflows, permissions, delegation and invocations namespaces define driver-neutral lifecycle, admitted task authority and invocation contracts. Existing service registries, task assignment, transports and token interfaces remain in use. See the composition guide.

swarmauri_core provides the interface contracts for the Swarmauri SDK. It is the package component authors use when they need stable abstract interfaces for agents, tools, LLMs, parsers, vector stores, cryptography, signing, key providers, transports, middleware, billing, storage, XMP, and other composable intelligence infrastructure components.

Why Swarmauri Core?

swarmauri_core keeps component contracts separate from implementations. Package authors can depend on stable interfaces without pulling in every base class, provider adapter, model package, or runtime integration.

FAQ

Q: What belongs in swarmauri_core?

A: Interface contracts, protocol shapes, enums, and shared types for Swarmauri component families.

Q: Should application developers instantiate classes from this package?

A: Usually no. Most application code uses concrete implementations from swarmauri_standard, community packages, or provider-specific packages. Component authors use swarmauri_core to implement the correct contract.

Q: How does this package relate to swarmauri_base?

A: swarmauri_core defines interfaces. swarmauri_base implements reusable base classes and serialization behavior on top of those interfaces.

What Is Included?

The package is intentionally implementation-light. It defines contracts, protocol shapes, enums, and shared types so implementation packages can interoperate without depending on each other directly.

Major interface families include:

  • Agents and agent APIs: IAgent, conversation, parser, retrieval, toolkit, and vector-store agent mixins.
  • LLM and multimodal prediction: text LLMs, tool LLMs, OCR, STT, TTS, and VLM interfaces.
  • Documents and parsing: document contracts, parser contracts, chunkers, conversations, prompts, and prompt templates.
  • Retrieval and vectors: vector, matrix, tensor, metric, similarity, vector-store comparator, deprecated distance compatibility contracts, vector store, and document store contracts.
  • Security and trust: crypto, MRE crypto, cipher suites, signing, proof-of-possession, token services, key providers, certificates, and XMP embedding.
  • Runtime infrastructure: middleware, transports, storage adapters, publishers, rate limits, tracing, state, service registries, and pipelines.
  • Business systems: billing provider interfaces for customers, payments, invoices, subscriptions, refunds, payouts, risk, reporting, webhooks, and marketplace flows.

Features

  • Stable abstract interfaces for Swarmauri component packages.
  • Shared types for crypto, signing, key management, transports, billing, and proof-of-possession workflows.
  • Zero runtime dependencies.
  • Interface-first design for packages that later inherit reusable behavior from swarmauri_base.
  • Python 3.10, 3.11, 3.12, 3.13, and 3.14 support.

Installation

Install with uv:

uv add swarmauri_core

Install with pip:

pip install swarmauri_core

Usage

Use swarmauri_core when defining a new implementation package or validating that a class satisfies a public Swarmauri contract.

import asyncio
from typing import Any, Optional

from swarmauri_core.agents.IAgent import IAgent
from swarmauri_core.messages.IMessage import IMessage


class MinimalAgent(IAgent):
    def exec(
        self,
        input_data: Optional[Any] = None,
        llm_kwargs: Optional[dict] = None,
    ) -> Any:
        return {"input": input_data, "kwargs": llm_kwargs or {}}

    async def aexec(
        self,
        input_str: Optional[str | IMessage] = "",
        llm_kwargs: Optional[dict] = None,
    ) -> Any:
        return self.exec(input_str, llm_kwargs)

    def batch(
        self,
        inputs: list[str | IMessage],
        llm_kwargs: Optional[dict] = None,
    ) -> list[Any]:
        return [self.exec(item, llm_kwargs) for item in inputs]

    async def abatch(
        self,
        inputs: list[str | IMessage],
        llm_kwargs: Optional[dict] = None,
    ) -> list[Any]:
        return await asyncio.gather(
            *(self.aexec(item, llm_kwargs) for item in inputs)
        )

Implement a parser contract:

from pathlib import Path

from swarmauri_core.documents.IDocument import IDocument
from swarmauri_core.parsers.IParser import IParser


class PlainTextParser(IParser):
    def parse(self, data: str | bytes | Path) -> list[IDocument]:
        raise NotImplementedError("Return concrete Document instances here.")

Implement a storage or retrieval contract in a concrete package, then expose the class through swarmauri_base and the public swarmauri namespace when appropriate.

Component Author Workflow

  1. Choose the closest interface from swarmauri_core.
  2. Implement domain behavior in a package-specific class.
  3. Add reusable serialization and registration behavior with swarmauri_base when the implementation should become a Swarmauri component.
  4. Publish or register the implementation package through the appropriate swarmauri.<kind> entry point or namespace mapping.
  5. Document installation and usage in the implementation package README.

Foundational packages:

  • swarmauri provides the namespace importer and plugin discovery layer.
  • swarmauri_base provides reusable base classes built on these interfaces.
  • swarmauri_standard provides first-party implementations for common component kinds.

Packages built around specific core component kinds:

When To Use This Package

Use swarmauri_core when you are designing or implementing a Swarmauri-compatible component and need the interface contract. Use swarmauri_base when you also need reusable base-class behavior, serialization helpers, and component registration. Use swarmauri_standard when you want ready-to-use implementations.

License

Apache-2.0

Contributing

When adding or changing a core interface, keep the contract narrow, update downstream base classes where needed, add focused tests, and follow the Swarmauri SDK contribution guide.

Run checkpoints and tool steps

swarmauri_core.run_stores defines IRunStore, RunCheckpoint, and RunConflictError. Checkpoints have an opaque text payload and a revision guarded by an atomic save. swarmauri_core.tool_llms.IToolStepModel is the opt-in contract for proposing tool calls and formatting their results.

Metadata

Release files for swarmauri_core 0.11.0.dev9

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

Source distribution (sdist)

Source distribution for swarmauri_core 0.11.0.dev9
File Size Uploaded Provenance Actions
swarmauri_core-0.11.0.dev9.tar.gz 76.3 kB Without provenance Details for swarmauri_core-0.11.0.dev9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for swarmauri_core 0.11.0.dev9
File Interpreter ABI Platform Actions
swarmauri_core-0.11.0.dev9-py3-none-any.whl Python 3 none any Details for swarmauri_core-0.11.0.dev9-py3-none-any.whl

Total release size: 234.3 kB

Release files / swarmauri_core-0.11.0.dev9.tar.gz

Download URL swarmauri_core-0.11.0.dev9.tar.gz
Size 76.3 kB
Tags Source
SHA-256 checksum
How to use checksums
74d3d1289e560483162f1c477a95d7073f8120924193304828c1807e086f8447
BLAKE2b-256 checksum
How to use checksums
8746f215c6e8899e4233e592ae780778dc85047902b7df284dd711895109c450
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / swarmauri_core-0.11.0.dev9-py3-none-any.whl

Download URL swarmauri_core-0.11.0.dev9-py3-none-any.whl
Size 158.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ae8c9ce838cd37498c2091e980d6b8d07cffc477e09b8a813cf92a1c81b3bc9f
BLAKE2b-256 checksum
How to use checksums
868008939b85ce92e6a1cfbec83e0a08cffbca4863518dee9821d6fdcdf65484
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for swarmauri_core 0.11.0.dev9

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

Release history Release notifications | RSS feed

This release
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