The Swarmauri SDK provides a powerful, extensible framework for building AI-powered applications. This repository includes core interfaces, standard abstract base classes, and concrete reference implementations.

Swarmauri offers multiple installation options to suit different needs:

For a full-featured experience with all standard components:

# Install the main namespace package with standard components
pip install swarmauri

# Install the main namespace package with extra standard components
pip install "swarmauri[full]"

# Or with uv for faster installation
uv pip install swarmauri
uv pip install "swarmauri[full]"

For a minimal installation with just the core interfaces:

# Install only the core components
pip install swarmauri_core

# Or with uv for faster installation
uv pip install swarmauri_core

Install specific packages for targeted functionality:

# Install only the vector store implementations you need
pip install swarmauri_vectorstore_pinecone
pip install swarmauri_vectorstore_annoy

# Install specific tools
pip install swarmauri_tool_jupyterexportlatex

# Or with uv for faster installation
uv pip install swarmauri_vectorstore_pinecone
uv pip install swarmauri_vectorstore_annoy
uv pip install swarmauri_tool_jupyterexportlatex

For contributors or those wanting the latest features:

# Clone the repository
git clone https://github.com/swarmauri/swarmauri-sdk.git
cd swarmauri-sdk

# Install in development mode
pip install -e .

# Or with UV for faster installation
pip install uv
uv pip install -e .

The swarmauri package acts as a namespace microkernel. Importing swarmauri registers a custom importer that resolves classes from installed first-party and community plugins.

import swarmauri

# import concrete implementations through the unified namespace
from swarmauri.documents import Document
from swarmauri.tools import AdditionTool
from swarmauri.messages import HumanMessage

doc = Document(content="Hello from the namespace package")
tool = AdditionTool()
msg = HumanMessage(content="Run a quick tool check")

print(doc.type)
print(tool("2+2"))
print(msg.content)

Use the plugin citizenship registry as an index of resource paths to concrete module locations.

from swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry

# Full index across first-, second-, and third-class plugins
index = PluginCitizenshipRegistry.total_registry()
print(f"Indexed resources: {len(index)}")

# Example: inspect a few tool entries
tool_rows = sorted(
    (resource, module)
    for resource, module in index.items()
    if resource.startswith("swarmauri.tools.")
)
for resource, module in tool_rows[:5]:
    print(f"{resource} -> {module}")

# Optional: inspect by citizenship class
first_class_only = PluginCitizenshipRegistry.list_registry("first")
print(f"First-class resources: {len(first_class_only)}")

For explicit dependency control, import classes directly from their package.

from swarmauri_standard.documents import Document
from swarmauri_standard.tools import AdditionTool

doc = Document(content="Direct package import")
tool = AdditionTool()

The Swarmauri SDK is organized into several key packages:

• swarmauri_core: Core interfaces and constants
• swarmauri_base: Abstract base classes for extensibility
• swarmauri_standard: Standard implementations of common components
• swarmauri: Main namespace package that unifies all components
• pkgs/community: Community-maintained packages and integrations
• pkgs/deprecated: Retired packages that remain for historical reference

Individual components follow these naming conventions:

• swarmauri_vectorstore_*: Vector database integrations
• swarmauri_embedding_*: Embedding model implementations
• swarmauri_tool_*: Task-specific tools
• swarmauri_parser_*: Text parsing utilities
• swarmauri_distance_*: Distance calculation methods

If you want to contribute to the Swarmauri SDK, please read our guidelines for contributing and style guide to get started.

Swarmauri uses Python's entry point system for plugin discovery. Here's how to register your component:

# In your pyproject.toml
[project.entry-points.'swarmauri.vectorstores']
YourVectorStore = "swarmauri_vectorstore_yourplugin:YourVectorStore"

# In your implementation file
@ComponentBase.register_type(VectorStoreBase, "YourVectorStore")
class YourVectorStore(VectorStoreBase):
    # Your implementation

The Swarmauri SDK is licensed under the Apache License 2.0. See the LICENSE file for details.