This release is a pre-release and may not be stable for production use.
Swarmauri Base
swarmauri_base provides the reusable base classes, mixins, and dynamic component model used by Swarmauri SDK implementations. It builds on swarmauri_core interfaces and adds Pydantic models, typed component registration, JSON/YAML/TOML serialization, logging helpers, service helpers, and base classes for each major component family.
Why Swarmauri Base?
swarmauri_base turns Swarmauri interfaces into reusable component foundations. It gives implementation packages consistent Pydantic modeling, resource metadata, dynamic subtype registration, serialization, and family-specific base behavior.
FAQ
Q: What is ComponentBase?
A: ComponentBase is the common Pydantic-backed base for Swarmauri components. It carries fields such as type, resource, name, and version, and participates in dynamic component registration.
Q: What is SubclassUnion used for?
A: SubclassUnion lets Pydantic models hydrate registered concrete component types from serialized payloads that include a type discriminator.
Q: When should I use swarmauri_base instead of swarmauri_core?
A: Use swarmauri_base when building a real component implementation. Use swarmauri_core when you only need the abstract interface contract.
Features
ComponentBasefor Pydantic-backed Swarmauri components withtype,resource,name, andversionfields.DynamicBaseandSubclassUnionfor discriminated-union deserialization from concretetypevalues.- JSON, YAML, and TOML serialization through Pydantic plus Swarmauri mixins.
- Base classes for agents, chains, chunkers, conversations, documents, embeddings, LLMs, tools, toolkits, vector stores, parsers, prompts, transports, middleware, signing, crypto, key providers, tokens, billing, XMP, and more.
- Default mixins for logging, service metadata, batch behavior, retrieval behavior, storage behavior, and component-family-specific workflows.
- Python 3.10, 3.11, 3.12, 3.13, and 3.14 support.
Installation
Install with uv:
uv add swarmauri_base
Install with pip:
pip install swarmauri_base
Usage
Create a typed component by inheriting from ComponentBase:
from typing import Literal
from swarmauri_base.ComponentBase import ComponentBase
@ComponentBase.register_model()
class StoreConfig(ComponentBase):
type: Literal["StoreConfig"] = "StoreConfig"
name: str
Register and hydrate concrete subtypes with SubclassUnion:
from typing import Literal
from pydantic import BaseModel
from swarmauri_base.ComponentBase import ComponentBase
from swarmauri_base.DynamicBase import SubclassUnion
@ComponentBase.register_model()
class StoreConfig(ComponentBase):
type: Literal["StoreConfig"] = "StoreConfig"
name: str
@ComponentBase.register_type(StoreConfig, "SqliteStoreConfig")
class SqliteStoreConfig(StoreConfig):
type: Literal["SqliteStoreConfig"] = "SqliteStoreConfig"
path: str
class StoreEnvelope(BaseModel):
store: SubclassUnion[StoreConfig]
envelope = StoreEnvelope.model_validate_json(
'{"store":{"type":"SqliteStoreConfig","name":"local","path":"./data.db"}}'
)
assert isinstance(envelope.store, SqliteStoreConfig)
Build a concrete tool from ToolBase:
from typing import Any, Literal
from swarmauri_base.tools.ToolBase import ToolBase
class EchoTool(ToolBase):
type: Literal["EchoTool"] = "EchoTool"
name: str = "echo"
description: str = "Return the input payload."
def __call__(self, payload: Any) -> Any:
return payload
tool = EchoTool()
assert tool("hello") == "hello"
assert tool.batch(["a", "b"]) == ["a", "b"]
Component Families
swarmauri_base includes base classes and mixins for these component kinds:
- AI and agent workflow: agents, chains, conversations, prompts, prompt templates, pipelines, swarms, task management strategies, tool LLMs, tools, toolkits, LLMs, VLMs, OCR, STT, and TTS.
- Data and retrieval: documents, document stores, embeddings, vectors, vector stores, parsers, schema converters, data connectors, state, service registries, and storage adapters.
- Math and evaluation: vector-store comparators, deprecated distance compatibility shims, inner products, matrices, measurements, metrics, norms, pseudometrics, seminorms, similarities, tensors, evaluators, evaluator pools, and evaluator results.
- Runtime and infrastructure: transports, middleware, publishers, rate limits, logging handlers, logging formatters, loggers, tracing-oriented mixins, services, and programs.
- Security and trust: cert services, crypto, MRE crypto, cipher suites, signing, proof-of-possession helpers, key providers, token services, XMP embedding, and git filters.
- Business integrations: billing provider base classes and mixins for customers, hosted checkout, payments, invoices, subscriptions, refunds, payouts, reports, promotions, risk, marketplace, and webhooks.
Component Author Workflow
- Start with the relevant interface in swarmauri_core.
- Inherit the matching base class from
swarmauri_base. - Add a stable
typeliteral andresourcevalue. - Register the model or subtype with
ComponentBase.register_model()orComponentBase.register_type(...). - Add package entry points or namespace mappings through swarmauri when the implementation should be discoverable.
- Document installation, direct instantiation, serialization behavior, and any provider-specific configuration in the implementation package README.
Related Packages
Foundational packages:
- swarmauri_core provides the interface contracts that these base classes implement.
- swarmauri provides namespace imports and plugin discovery.
- swarmauri_standard provides first-party components built from these base classes.
- swarmauri_typing provides typing utilities used by dynamic union machinery.
Packages built on component-kind bases:
- swarmauri_signing_ed25519 builds on signing base behavior.
- swarmauri_crypto_composite builds on crypto base behavior.
- swarmauri_keyprovider_inmemory builds on key provider base behavior.
- swarmauri_storage_memory builds on storage adapter base behavior.
- swarmauri_transport_stdio builds on transport base behavior.
- swarmauri_middleware_jsonrpc builds on middleware base behavior.
When To Use This Package
Use swarmauri_base when implementing a Swarmauri component that needs serialization, registration, and shared base behavior. Use swarmauri_core when you only need interface definitions. Use implementation packages such as swarmauri_standard or individual component packages when you need ready-to-run behavior.
License
Apache-2.0
Contributing
When adding or changing a base class, keep it aligned with the corresponding swarmauri_core interface, preserve direct plugin instantiation patterns, update exports and tests, 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_base-0.11.0.dev2.tar.gz.
File metadata
- Download URL: swarmauri_base-0.11.0.dev2.tar.gz
- Upload date:
- Size: 86.1 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 |
75e04bf5ca3d67352946ce8a5a6866efb30ffc032c596128579976a7192c5709
|
|
| MD5 |
69d995f1142ab850eccf6037c0c65f68
|
|
| BLAKE2b-256 |
5b1adbce1490fd0cfbcb6df45ea3c67b1468410553901175099f5b35148d82da
|
File details
Details for the file swarmauri_base-0.11.0.dev2-py3-none-any.whl.
File metadata
- Download URL: swarmauri_base-0.11.0.dev2-py3-none-any.whl
- Upload date:
- Size: 157.8 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 |
0624b141ae9a17e6145a2c4c019111227b7bc548d2606389886538c9de2ffa95
|
|
| MD5 |
19cf431b92e7bf754597c609be2270bf
|
|
| BLAKE2b-256 |
dfd3c8e69bd3a78a72fb8eb9592d3f4c6e901e69902cde2e38c000371657d51a
|
