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.
Security and signing packages:
Runtime and infrastructure packages:
Billing provider packages:
Documentation
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.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
评论