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_base Discord

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

  • ComponentBase for Pydantic-backed Swarmauri components with type, resource, name, and version fields.
  • DynamicBase and SubclassUnion for discriminated-union deserialization from concrete type values.
  • 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

  1. Start with the relevant interface in swarmauri_core.
  2. Inherit the matching base class from swarmauri_base.
  3. Add a stable type literal and resource value.
  4. Register the model or subtype with ComponentBase.register_model() or ComponentBase.register_type(...).
  5. Add package entry points or namespace mappings through swarmauri when the implementation should be discoverable.
  6. Document installation, direct instantiation, serialization behavior, and any provider-specific configuration in the implementation package README.

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:

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.

Run storage

swarmauri_base.run_stores.RunStoreBase implements shared checkpoint revision rules. A backend supplies an insert, a read, and an atomic compare-and-swap.

HTTP TTS transport

tts.HttpTTSMixin shares file, streaming and bounded async batch transport for standalone TTS providers. Provider packages own request schemas, fixed URLs and stream decoding. _speech_endpoint(streaming) selects provider-owned unary and streaming routes; _audio_content(response) decodes unary JSON audio when needed. _speech_request(payload, streaming) prepares headers and body once for providers that require XML or an exact body signature. Existing JSON/binary providers retain their default behavior. Transport does not replay potentially billable requests.

tts.JsonAudioTTSMixin decodes complete base64/data-URI audio from JSON for file and batch workflows. It rejects URL audio and malformed/empty data, and checks WAV headers when WAV is requested. Providers validate their own status and format fields. Its stream/astream methods raise locally; a complete JSON response is never labeled an incremental stream.

Metadata

Release files for swarmauri_base 0.11.0.dev12

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_base 0.11.0.dev12
File Size Uploaded Provenance Actions
swarmauri_base-0.11.0.dev12.tar.gz 110.9 kB Without provenance Details for swarmauri_base-0.11.0.dev12.tar.gz

Built distribution (wheel)

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

Total release size: 322.5 kB

Release files / swarmauri_base-0.11.0.dev12.tar.gz

Download URL swarmauri_base-0.11.0.dev12.tar.gz
Size 110.9 kB
Tags Source
SHA-256 checksum
How to use checksums
e9966d2d4244abb094e6de8746390c0a92cc74e34fc094070b3e9e8b9b8dd254
BLAKE2b-256 checksum
How to use checksums
2bb4deb73cfc7bb91a2e31e7400d28c375b62000e61a5f4e77806660b590bca0
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_base-0.11.0.dev12-py3-none-any.whl

Download URL swarmauri_base-0.11.0.dev12-py3-none-any.whl
Size 211.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f57353e83426e33b2f9f0c5b0af591954f64366337d677ca9b9283cbc626da76
BLAKE2b-256 checksum
How to use checksums
6416e092de9c0452b050a5306c101df3e8e98ade31e10f22c53e02fb53303eab
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_base 0.11.0.dev12

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