This release is a pre-release and may not be stable for production use.
Swarmauri
Swarmauri is the namespace package for the Swarmauri SDK. It installs the lightweight import microkernel that lets applications use stable swarmauri.<component_kind>.<ClassName> import paths while concrete implementations live in separate first-party, community, plugin, or experimental distributions.
What Is Swarmauri?
Swarmauri is a composable intelligence infrastructure SDK for building typed, pluggable Python systems. The swarmauri distribution is the package users install when they want the public namespace, plugin discovery, registry-backed component resolution, and curated optional dependency groups for common component families.
Why Swarmauri?
Swarmauri gives applications one stable Python namespace for a large and growing set of independently packaged SDK components. Instead of hard-coding every implementation package into application imports, the namespace importer resolves registered component paths through interface and citizenship registries.
FAQ
Q: What does the swarmauri package install?
A: It installs the public Swarmauri namespace, the namespace importer, interface registry access, plugin citizenship registry access, and entry-point discovery hooks.
Q: Does swarmauri contain every component implementation?
A: No. It routes to installed implementation packages. Foundational packages such as swarmauri_core, swarmauri_base, and swarmauri_standard provide contracts, base behavior, and standard components.
Q: When should I import from swarmauri instead of a concrete package?
A: Use swarmauri imports when you want stable public namespace paths. Import a concrete package directly when you want the narrowest dependency surface for one implementation.
This package is best for:
- AI application developers who want stable imports for agents, tools, models, parsers, vector stores, signing components, key providers, middleware, transports, and related SDK components.
- Platform engineers who need registry-driven plugin discovery without hard-coding every implementation package into application code.
- Component authors who want their packages to participate in the Swarmauri namespace through entry points and citizenship mappings.
- Operators who need a small runtime package that can load installed Swarmauri components on demand.
How The Namespace Works
When import swarmauri runs, the package registers SwarmauriImporter on sys.meta_path and discovers installed plugins. The importer consults two registries:
InterfaceRegistrymaps resource namespaces such asswarmauri.llms,swarmauri.tools, andswarmauri.signingsto their validation interfaces.PluginCitizenshipRegistrymaps public namespace paths to implementation modules and classifies components as first-class, second-class, or third-class citizens.
The result is a stable public namespace over independently versioned packages. For example, swarmauri.signings.Ed25519EnvelopeSigner can resolve to the implementation package that provides the signer, while application code keeps the Swarmauri namespace import.
Features
- Stable
swarmauri.*namespace imports for installed SDK components. - Registry-backed component discovery through first-class, second-class, and third-class citizenship mappings.
- Entry-point scanning for installed plugins and community packages.
- Interface-aware resource kinds for agents, chains, chunkers, conversations, embeddings, LLMs, parsers, tools, vector stores, signing, crypto, key providers, transports, middleware, and more.
- Optional dependency groups for curated component families, including
default,full, andllms. - Pydantic-based typed component workflows through
swarmauri_baseand concrete packages. - Python 3.10, 3.11, 3.12, 3.13, and 3.14 support.
Installation
Install the namespace package with uv:
uv add swarmauri
Or install it with pip:
pip install swarmauri
Install optional LLM integrations when you want the curated LLM package set:
uv add "swarmauri[llms]"
For the broader curated component bundle:
uv add "swarmauri[full]"
Usage
Importing swarmauri activates the namespace importer and plugin discovery:
import swarmauri
from swarmauri.interface_registry import InterfaceRegistry
from swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry
namespaces = InterfaceRegistry.list_registered_namespaces()
registered = PluginCitizenshipRegistry.total_registry()
print("known namespaces", len(namespaces))
print("known component mappings", len(registered))
Resolve a component through a stable namespace path after the implementation package is installed:
import swarmauri
from swarmauri.signings.Ed25519EnvelopeSigner import Ed25519EnvelopeSigner
signer = Ed25519EnvelopeSigner()
print(signer.type)
The implementation still comes from the signer package, but application code can use the Swarmauri public namespace.
Component Author Workflow
To make a component available through the Swarmauri namespace:
- Implement the concrete class in its own package.
- Ensure the class satisfies the relevant interface from
swarmauri_coreand base behavior fromswarmauri_base. - Expose the component through a
swarmauri.<kind>entry point or a citizenship registry mapping. - Import
swarmauriin the consuming environment so the namespace importer and plugin discovery run. - Validate the public namespace path in tests.
Examples
List known public namespaces:
from swarmauri.interface_registry import InterfaceRegistry
for namespace in InterfaceRegistry.list_registered_namespaces():
print(namespace)
Inspect registered first-party and discovered component paths:
from swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry
for public_path, module_path in PluginCitizenshipRegistry.total_registry().items():
print(public_path, "->", module_path)
Invalidate plugin entry-point cache after changing the Python environment at runtime:
from swarmauri.plugin_manager import invalidate_entry_point_cache
invalidate_entry_point_cache()
Related Packages
Core Swarmauri packages:
- swarmauri_core provides interface contracts used by component packages.
- swarmauri_base provides reusable base classes, serialization helpers, and component registration behavior.
- swarmauri_standard provides first-party standard components across agents, tools, parsers, prompts, metrics, similarities, deprecated distance compatibility shims, and other common resource kinds.
Related component kinds:
- swarmauri_signing_ed25519 for Ed25519 envelope signing.
- swarmauri_signing_jws for JWS signing and verification.
- swarmauri_keyprovider_inmemory for in-memory key management.
- swarmauri_storage_memory for memory-backed storage adapters.
- swarmauri_middleware_jsonrpc for JSON-RPC middleware.
- swarmauri_transport_stdio for stdio transport integrations.
Documentation
When To Use This Package
Use swarmauri when you want the stable SDK namespace and plugin discovery behavior. Use the implementation package directly when you want to depend on only one specific component and do not need namespace routing.
License
Apache-2.0
Contributing
Contributions are welcome. Before adding a new public namespace path, update the interface and citizenship registries, add package-level tests for import resolution, and follow the Swarmauri SDK contribution guide.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file swarmauri-0.11.0.dev1.tar.gz.
File metadata
- Download URL: swarmauri-0.11.0.dev1.tar.gz
- Upload date:
- Size: 29.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c410a89ef2de6814cfb9bb1927362a9f69a399651cc193d9b611533da3fc6a9c
|
|
| MD5 |
926bf89347853fe6e88b9f2c6dbb67c9
|
|
| BLAKE2b-256 |
81cb7bb0a1f4401bec2684406bd1acdb9e89aa077eee5795297857cb7ef1770c
|
File details
Details for the file swarmauri-0.11.0.dev1-py3-none-any.whl.
File metadata
- Download URL: swarmauri-0.11.0.dev1-py3-none-any.whl
- Upload date:
- Size: 28.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6c004b63d6458ca09c157fcd574d62ae213417643da6c898b7ba3bc4b1b4e30c
|
|
| MD5 |
6fd2261cb52d12aa5d5d294a4c6c8c25
|
|
| BLAKE2b-256 |
93602c0940e4ccae1ed5307104008582c6255de5f9e62c0417061a0611913d2f
|
