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.

Metadata

Release files for swarmauri_base 0.11.0.dev7

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

Built distribution (wheel)

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

Total release size: 316.3 kB

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

Download URL swarmauri_base-0.11.0.dev7.tar.gz
Size 108.1 kB
Tags Source
SHA-256 checksum
How to use checksums
295fbfef25da8fc06c0c227adea189b5bd490abf5a78aedec94045738fa8d93a
BLAKE2b-256 checksum
How to use checksums
9d5b2ae52bf111b3eee9f233f2c4f5734154c4276bb76b80d8fde8026113b047
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","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.dev7-py3-none-any.whl

Download URL swarmauri_base-0.11.0.dev7-py3-none-any.whl
Size 208.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f8f7980a7685fbc1145ee396e82912ebdcbd98f2acfe637984ebcd05af513298
BLAKE2b-256 checksum
How to use checksums
8af1d68892a60f69e6cf6f3a0944f45b7d5ea96d7f401f6a1e508f20199bb4d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","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.dev7

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