Swarmauri SDK

Swarmauri is a composable intelligence infrastructure SDK for building typed, pluggable Python systems. The repository contains the public swarmauri namespace package, interface contracts, reusable base classes, standard components, community integrations, plugin packages, and package-level documentation for independently installable Swarmauri distributions.

Why Swarmauri?

Swarmauri separates component contracts from implementations so applications can compose agents, tools, models, parsers, vector stores, signing components, key providers, transports, middleware, billing providers, and storage adapters without locking every workflow to one provider package. The namespace package gives users stable imports while individual packages keep dependencies focused.

FAQ

Q: What is the main package to install?

A: Install swarmauri when you want the public namespace, plugin discovery, and curated optional dependency groups.

Q: Which package should component authors start with?

A: Start with swarmauri_core for interfaces, then use swarmauri_base when the implementation needs serialization, component registration, and reusable base behavior.

Q: Where are ready-to-use components?

A: Use swarmauri_standard for first-party standard components, or install a focused community, plugin, or standards package for a specific provider or component kind.

Q: Does this repository support modern Python versions?

A: Swarmauri package metadata and badges target Python 3.10, 3.11, 3.12, 3.13, and 3.14.

Features

• Stable swarmauri.* namespace imports through the namespace package.
• Interface-first package architecture through swarmauri_core.
• Pydantic-backed base classes, serialization helpers, and dynamic component registration through swarmauri_base.
• First-party standard components through swarmauri_standard.
• Independently installable community, plugin, experimental, and standards packages.
• Component families for agents, chains, conversations, documents, embeddings, LLMs, parsers, prompts, schema converters, tools, toolkits, vector stores, signing, crypto, key providers, transports, middleware, storage, XMP, billing, and more.
• Python 3.10, 3.11, 3.12, 3.13, and 3.14 support.

Installation

Install the namespace package with uv:

uv add swarmauri

Install it with pip:

pip install swarmauri

Install the broader curated component bundle:

uv add "swarmauri[full]"
pip install "swarmauri[full]"

Install only foundational packages when building components:

uv add swarmauri_core swarmauri_base
pip install swarmauri_core swarmauri_base

Install focused packages when you only need one component family:

uv add swarmauri_vectorstore_pinecone
uv add swarmauri_tool_jupyterexportlatex
uv add swarmauri_signing_ed25519

Usage

Importing swarmauri activates namespace discovery for installed components:

import swarmauri

from swarmauri.interface_registry import InterfaceRegistry
from swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry

print(len(InterfaceRegistry.list_registered_namespaces()))
print(len(PluginCitizenshipRegistry.total_registry()))

Use the namespace package for stable public imports after the implementation package is installed:

import swarmauri

from swarmauri.signings.Ed25519EnvelopeSigner import Ed25519EnvelopeSigner

signer = Ed25519EnvelopeSigner()
print(signer.type)

Use direct package imports when you want the narrowest dependency surface:

from swarmauri_standard.documents import Document
from swarmauri_standard.tools import AdditionTool

doc = Document(content="Direct package import")
tool = AdditionTool()

print(doc.type)
print(tool("2+2"))

Examples

Discover registered component mappings:

from swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry

for public_path, module_path in list(PluginCitizenshipRegistry.total_registry().items())[:10]:
    print(public_path, "->", module_path)

Use dynamic component serialization from swarmauri_base:

from typing import Literal

from pydantic import BaseModel
from swarmauri_base.ComponentBase import ComponentBase
from swarmauri_base.DynamicBase import SubclassUnion


@ComponentBase.register_model()
class ConnectorBase(ComponentBase):
    type: Literal["ConnectorBase"] = "ConnectorBase"
    label: str


@ComponentBase.register_type(ConnectorBase, "ApiConnector")
class ApiConnector(ConnectorBase):
    type: Literal["ApiConnector"] = "ApiConnector"
    endpoint: str


class ConnectorSpec(BaseModel):
    connector: SubclassUnion[ConnectorBase]


spec = ConnectorSpec.model_validate_json(
    '{"connector":{"type":"ApiConnector","label":"primary","endpoint":"https://api.example.test"}}'
)

assert isinstance(spec.connector, ApiConnector)

Package Structure

Foundational packages:

• swarmauri provides the namespace importer and plugin discovery layer.
• swarmauri_core provides interface contracts and shared types.
• swarmauri_base provides reusable base classes, serialization helpers, and component registration behavior.
• swarmauri_standard provides first-party standard components.
• swarmauri_typing provides dynamic typing utilities used by Swarmauri base classes.

Repository package areas:

• pkgs/core, pkgs/base, pkgs/typing, and pkgs/swarmauri contain foundational packages.
• pkgs/swarmauri_standard contains first-party standard components.
• pkgs/community contains community-maintained packages and provider integrations.
• pkgs/plugins contains plugin packages.
• pkgs/standards contains standard-interface and standards-oriented packages.
• pkgs/experimental contains early-stage packages.

Common package families:

• swarmauri_vectorstore_* packages provide vector database integrations.
• swarmauri_embedding_* packages provide embedding model integrations.
• swarmauri_tool_* packages provide task-specific tools.
• swarmauri_parser_* packages provide parsing utilities.
• swarmauri_signing_* packages provide signing implementations.
• swarmauri_keyprovider_* packages provide key-management implementations.
• swarmauri_billing_* packages provide billing provider implementations and stubs.

Related Packages

Security and signing packages:

• swarmauri_signing_ed25519
• swarmauri_signing_jws
• swarmauri_crypto_composite
• swarmauri_keyprovider_inmemory

Runtime and infrastructure packages:

• swarmauri_transport_stdio
• swarmauri_middleware_jsonrpc
• swarmauri_storage_memory

Billing provider packages:

• swarmauri_billing_adyen
• swarmauri_billing_authorize_net
• swarmauri_billing_braintree
• swarmauri_billing_paypal
• swarmauri_billing_stripe

Documentation

• Dynamic schemas guide
• Swarmauri namespace call flow
• Swarmauri citizenship notes
• Contribution guide
• Style guide
• Package index

For Contributors

Create component packages with direct instantiation in mind. Plugins should expose clear package-level imports, use the relevant swarmauri_core interface and swarmauri_base base class, document installation and usage, and register entry points where namespace discovery is expected.

[project.entry-points.'swarmauri.vectorstores']
YourVectorStore = "swarmauri_vectorstore_yourplugin:YourVectorStore"

from typing import Literal

from swarmauri_base.ComponentBase import ComponentBase
from swarmauri_base.vector_stores.VectorStoreBase import VectorStoreBase


@ComponentBase.register_type(VectorStoreBase, "YourVectorStore")
class YourVectorStore(VectorStoreBase):
    type: Literal["YourVectorStore"] = "YourVectorStore"

License

The Swarmauri SDK is licensed under the Apache License 2.0. See the LICENSE file for details.