Metadata-Version: 2.4
Name: swarmauri
Version: 0.9.1.dev2
Summary: Namespace package for components, packages, and plugins within the Swarmauri framework.
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: swarmauri,dynamic-json-schema,discriminated-unions,pydantic,schema-first,serialization,yaml,toml,plugin-factory,typed-components
Author: Jacob Stewart
Author-email: jacob@swarmauri.com
Requires-Python: >=3.10,<3.15
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: default
Provides-Extra: full
Provides-Extra: llms
Requires-Dist: httpx (>=0.27.0)
Requires-Dist: pydantic (>=2.9.2)
Requires-Dist: swarmauri_base
Requires-Dist: swarmauri_core
Requires-Dist: swarmauri_distance_minkowski ; extra == "default"
Requires-Dist: swarmauri_distance_minkowski ; extra == "full"
Requires-Dist: swarmauri_embedding_doc2vec ; extra == "default"
Requires-Dist: swarmauri_embedding_doc2vec ; extra == "full"
Requires-Dist: swarmauri_embedding_nmf ; extra == "default"
Requires-Dist: swarmauri_embedding_nmf ; extra == "full"
Requires-Dist: swarmauri_llm_ai21 ; extra == "llms"
Requires-Dist: swarmauri_llm_anthropic ; extra == "llms"
Requires-Dist: swarmauri_llm_cerebras ; extra == "llms"
Requires-Dist: swarmauri_llm_cohere ; extra == "llms"
Requires-Dist: swarmauri_llm_deepinfra ; extra == "llms"
Requires-Dist: swarmauri_llm_deepseek ; extra == "llms"
Requires-Dist: swarmauri_llm_falai ; extra == "llms"
Requires-Dist: swarmauri_llm_gemini ; extra == "llms"
Requires-Dist: swarmauri_llm_groq ; extra == "llms"
Requires-Dist: swarmauri_llm_hyperbolic ; extra == "llms"
Requires-Dist: swarmauri_llm_leptonai ; extra == "llms"
Requires-Dist: swarmauri_llm_llamacpp ; extra == "llms"
Requires-Dist: swarmauri_llm_mistral ; extra == "llms"
Requires-Dist: swarmauri_llm_openai ; extra == "llms"
Requires-Dist: swarmauri_llm_perplexity ; extra == "llms"
Requires-Dist: swarmauri_llm_playht ; extra == "llms"
Requires-Dist: swarmauri_llm_whisper ; extra == "llms"
Requires-Dist: swarmauri_parser_beautifulsoupelement ; extra == "default"
Requires-Dist: swarmauri_parser_beautifulsoupelement ; extra == "full"
Requires-Dist: swarmauri_parser_keywordextractor ; extra == "default"
Requires-Dist: swarmauri_parser_keywordextractor ; extra == "full"
Requires-Dist: swarmauri_signing_ed25519 ; extra == "default"
Requires-Dist: swarmauri_signing_ed25519 ; extra == "full"
Requires-Dist: swarmauri_standard
Requires-Dist: swarmauri_tool_matplotlib ; extra == "default"
Requires-Dist: swarmauri_tool_matplotlib ; extra == "full"
Requires-Dist: swarmauri_vectorstore_doc2vec ; extra == "default"
Requires-Dist: swarmauri_vectorstore_doc2vec ; extra == "full"
Requires-Dist: toml (>=0.10.2)
Requires-Dist: typing_extensions
Description-Content-Type: text/markdown

![Swarmauri Logo](https://raw.githubusercontent.com/swarmauri/swarmauri-sdk/master/assets/swarmauri_sdk_brand.png)

<p align="center">
    <a href="https://pepy.tech/project/swarmauri/">
        <img src="https://static.pepy.tech/badge/swarmauri/month" alt="PyPI - Downloads"/></a>
    <a href="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/swarmauri/">
        <img alt="Hits" src="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/swarmauri.svg"/></a>
    <a href="https://pypi.org/project/swarmauri/">
        <img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue" alt="PyPI - Python Version"/></a>
    <a href="https://pypi.org/project/swarmauri/">
        <img src="https://img.shields.io/pypi/l/swarmauri" alt="PyPI - License"/></a>
    <a href="https://pypi.org/project/swarmauri/">
        <img src="https://img.shields.io/pypi/v/swarmauri?label=swarmauri&color=green" alt="PyPI - swarmauri"/></a>
</p>
---

# Swarmauri SDK

The Swarmauri SDK offers a comprehensive suite of tools designed for building distributed, extensible systems using the Swarmauri framework.

## Swarmauri Namespace Microkernel

The `swarmauri` package is implemented as a namespace microkernel. When the
package is imported it registers a custom importer that consults the interface
and plugin citizenship registries to locate actual implementations. This design
keeps the namespace lightweight while still allowing first-party and community
plugins to be discovered and loaded on demand. New resource kinds are declared
in `interface_registry.py`, then mapped to plugin modules via
`plugin_citizenship_registry.py`. For a deeper look at the import flow, see
[`docs/callflow.md`](docs/callflow.md).

## Public Operator Surfaces

Swarmauri exposes three stable operator-facing surfaces:

1. **Namespace imports (`swarmauri.<kind>`)**  
   The primary runtime surface is the namespace import path. Importing concrete
   operators through the `swarmauri` namespace triggers the microkernel
   importer and resolves to the installed implementation.

2. **Registry contracts (`interface_registry.py`)**  
   The interface registry defines the accepted interface path for each resource
   kind. This is the canonical public contract that implementations must satisfy.

3. **Citizenship mappings (`plugin_citizenship_registry.py`)**  
   Citizenship maps each public interface path to a concrete plugin module that
   can be loaded. This is the public compatibility surface used to connect
   interface contracts to implementations.

Together these surfaces allow operators to use stable import paths while
implementations evolve independently.

## Native Dynamic Schemas and Serialization

Swarmauri treats dynamic, typed component serialization as a core runtime
strength. Registered component families use `type` discriminators and dynamic
unions so factories, HTTP APIs, queues, and persisted JSON payloads can restore
the concrete subclass that was serialized.

Every `ComponentBase`-derived component inherits JSON support from Pydantic and
YAML/TOML helpers from the Swarmauri base mixins. That means the same component
initialization can move through JSON, YAML, or TOML configuration files and dump
back to those formats while preserving concrete kin.

```python
from typing import Literal
from pydantic import BaseModel
from swarmauri_base.ComponentBase import ComponentBase
from swarmauri_base.DynamicBase import SubclassUnion


@ComponentBase.register_model()
class RuntimeConnector(ComponentBase):
    type: Literal["RuntimeConnector"] = "RuntimeConnector"
    label: str


@ComponentBase.register_type(RuntimeConnector, "HttpRuntimeConnector")
class HttpRuntimeConnector(RuntimeConnector):
    type: Literal["HttpRuntimeConnector"] = "HttpRuntimeConnector"
    endpoint: str


class RuntimePayload(BaseModel):
    connector: SubclassUnion[RuntimeConnector]


payload = RuntimePayload.model_validate(
    {
        "connector": {
            "type": "HttpRuntimeConnector",
            "label": "orders",
            "endpoint": "https://api.example.test/orders",
        }
    }
)

assert isinstance(payload.connector, HttpRuntimeConnector)
```

Without this, applications usually fall back to untyped dictionaries or manual
factory switches. With it, Swarmauri can publish JSON Schema for the available
kin classes and hydrate concrete components from the same payloads used by
APIs, databases, and configuration files.

## Core 
- **Core Interfaces**: Define the fundamental communication and data-sharing protocols between components in a Swarmauri-based system.

## Standard
- **Base Classes**: Provide a foundation for constructing Swarmauri components, with standardized methods and properties.
- **Mixins**: Reusable code fragments designed to be integrated into various classes, offering shared functionality across different components.
- **Concrete Classes**: Ready-to-use, pre-implemented classes that fulfill standard system needs while adhering to Swarmauri principles. **These classes are the first in line for ongoing support and maintenance, ensuring they remain stable, performant, and up to date with future SDK developments.**

## Community
- **Third-Party Plug-in Integration**: Concrete classes designed to extend the frameworkâ€™s capabilities by utilizing third-party libraries and plugins.
- **Open Source Contributions**: A collaborative space for developers to contribute new components, plug-ins, and features.

## Experimental
- **In-Development Components**: Early-stage features and components that push the boundaries of the Swarmauri framework, offering innovative solutions that are still in testing phases.

# Features

- **Polymorphism**: Allows for dynamic behavior switching between components, enabling flexible, context-aware system behavior.
- **Dynamic JSON Schemas**: Updates discriminated-union schemas as registered component kin become available.
- **Discriminated Unions**: Provides a robust method for handling multiple possible object types in a type-safe manner.
- **Serialization**: Efficiently encode and decode component initializations across JSON, YAML, and TOML while preserving concrete `type`.
- **Intensional and Extensional Programming**: The microkernel continues to leverage both rule-based (intensional) patterns and set-based (extensional) plugin discovery, allowing you to build and manipulate complex data structures with ease.

## Use Cases

- **Modular Systems**: Develop scalable, pluggable systems that can evolve over time by adding or modifying components without disrupting the entire ecosystem.
- **Distributed Architectures**: Build systems with distributed nodes that seamlessly communicate using the SDKâ€™s standardized interfaces.
- **Third-Party Integrations**: Extend the system's capabilities by easily incorporating third-party tools, libraries, and services.
- **Prototype and Experimentation**: Test cutting-edge ideas using the experimental components in the SDK, while retaining the reliability of core and standard features for production systems.

## Extension Surface

Swarmauri is designed to be extended by adding new resource kinds or new
implementations for existing kinds.

For extension work:

- Add or update the interface contract in
  [`swarmauri/interface_registry.py`](swarmauri/interface_registry.py).
- Register the concrete implementation in
  [`swarmauri/plugin_citizenship_registry.py`](swarmauri/plugin_citizenship_registry.py).
- Ensure the implementation module can be imported and instantiated directly
  through its public class API.
- Validate import resolution against the call flow documented in
  [`docs/callflow.md`](docs/callflow.md).

This extension surface keeps the microkernel small while allowing packages,
plugins, and standards modules to participate in the same runtime model.

## Authoring Guide

When authoring new Swarmauri components:

1. **Define the interface first**  
   Start from the interface contract and ensure your class adheres to the
   expected methods and typing.

2. **Implement concrete behavior in your package**  
   Keep domain logic in the implementation package and keep the namespace
   microkernel declarations focused on discovery and routing.

3. **Register the implementation**  
   Add citizenship entries so the namespace importer can resolve your class.

4. **Instantiate plugins directly in usage examples**  
   Prefer direct class imports/instantiation in examples and integrations unless
   a manager abstraction is explicitly required.

5. **Document expected workflow**  
   Include installation, minimal usage, and extension notes so users can adopt
   and extend the component safely.

# Future Development

The Swarmauri SDK is an evolving platform, and the community is encouraged to contribute to its growth. Upcoming releases will focus on enhancing the framework's modularity, providing more advanced serialization methods, and expanding the community-driven component library.

## Modules Overview

### Importer
- [importer.py](swarmauri/importer.py): Handles the dynamic importing of modules and components within the Swarmauri framework.

### Interface Registry
- [interface_registry.py](swarmauri/interface_registry.py): Manages the registration and lookup of interfaces used for communication between different components.

### Plugin Citizenship Registry
- [plugin_citizenship_registry.py](swarmauri/plugin_citizenship_registry.py): Maintains a registry of plugins and their citizenship status within the Swarmauri ecosystem.

When introducing a new resource kind or class, remember to update both the
`plugin_citizenship_registry.py` and `interface_registry.py` so the framework can
discover and validate your additions.

## Contributing

Contributions are welcome! If you'd like to add a new feature, fix a bug, or improve documentation, kindly go through the [contributions guidelines](https://github.com/swarmauri/swarmauri-sdk/blob/master/contributing.md) first.

