Metadata-Version: 2.4
Name: swarmauri
Version: 0.11.0.dev1
Summary: Swarmauri namespace microkernel for registry-backed imports, plugin discovery, and composable intelligence infrastructure components.
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: swarmauri,ai-sdk,namespace-package,plugin-discovery,component-registry,composable-intelligence,microkernel,typed-components,pydantic-components,dynamic-imports,entry-points,agents,llms,tools,vector-stores,signing,key-providers
Author: Jacob Stewart
Author-email: jacob@swarmauri.com
Requires-Python: >=3.10,<3.15
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
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_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>
    <a href="https://discord.gg/N4UpBuQv8T">
        <img src="https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white" alt="Discord"/></a></p>

# Swarmauri

Swarmauri is the namespace package for the Swarmauri SDK. It installs the lightweight import microkernel that lets applications use stable `swarmauri.<component_kind>.<ClassName>` import paths while concrete implementations live in separate first-party, community, plugin, or experimental distributions.

## What Is Swarmauri?

Swarmauri is a composable intelligence infrastructure SDK for building typed, pluggable Python systems. The `swarmauri` distribution is the package users install when they want the public namespace, plugin discovery, registry-backed component resolution, and curated optional dependency groups for common component families.

## Why Swarmauri?

Swarmauri gives applications one stable Python namespace for a large and growing set of independently packaged SDK components. Instead of hard-coding every implementation package into application imports, the namespace importer resolves registered component paths through interface and citizenship registries.

## FAQ

### Q: What does the `swarmauri` package install?

A: It installs the public Swarmauri namespace, the namespace importer, interface registry access, plugin citizenship registry access, and entry-point discovery hooks.

### Q: Does `swarmauri` contain every component implementation?

A: No. It routes to installed implementation packages. Foundational packages such as `swarmauri_core`, `swarmauri_base`, and `swarmauri_standard` provide contracts, base behavior, and standard components.

### Q: When should I import from `swarmauri` instead of a concrete package?

A: Use `swarmauri` imports when you want stable public namespace paths. Import a concrete package directly when you want the narrowest dependency surface for one implementation.

This package is best for:

- AI application developers who want stable imports for agents, tools, models, parsers, vector stores, signing components, key providers, middleware, transports, and related SDK components.
- Platform engineers who need registry-driven plugin discovery without hard-coding every implementation package into application code.
- Component authors who want their packages to participate in the Swarmauri namespace through entry points and citizenship mappings.
- Operators who need a small runtime package that can load installed Swarmauri components on demand.

## How The Namespace Works

When `import swarmauri` runs, the package registers `SwarmauriImporter` on `sys.meta_path` and discovers installed plugins. The importer consults two registries:

- `InterfaceRegistry` maps resource namespaces such as `swarmauri.llms`, `swarmauri.tools`, and `swarmauri.signings` to their validation interfaces.
- `PluginCitizenshipRegistry` maps public namespace paths to implementation modules and classifies components as first-class, second-class, or third-class citizens.

The result is a stable public namespace over independently versioned packages. For example, `swarmauri.signings.Ed25519EnvelopeSigner` can resolve to the implementation package that provides the signer, while application code keeps the Swarmauri namespace import.

## Features

- Stable `swarmauri.*` namespace imports for installed SDK components.
- Registry-backed component discovery through first-class, second-class, and third-class citizenship mappings.
- Entry-point scanning for installed plugins and community packages.
- Interface-aware resource kinds for agents, chains, chunkers, conversations, embeddings, LLMs, parsers, tools, vector stores, signing, crypto, key providers, transports, middleware, and more.
- Optional dependency groups for curated component families, including `default`, `full`, and `llms`.
- Pydantic-based typed component workflows through `swarmauri_base` and concrete packages.
- Python 3.10, 3.11, 3.12, 3.13, and 3.14 support.

## Installation

Install the namespace package with `uv`:

```bash
uv add swarmauri
```

Or install it with `pip`:

```bash
pip install swarmauri
```

Install optional LLM integrations when you want the curated LLM package set:

```bash
uv add "swarmauri[llms]"
```

For the broader curated component bundle:

```bash
uv add "swarmauri[full]"
```

## Usage

Importing `swarmauri` activates the namespace importer and plugin discovery:

```python
import swarmauri

from swarmauri.interface_registry import InterfaceRegistry
from swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry

namespaces = InterfaceRegistry.list_registered_namespaces()
registered = PluginCitizenshipRegistry.total_registry()

print("known namespaces", len(namespaces))
print("known component mappings", len(registered))
```

Resolve a component through a stable namespace path after the implementation package is installed:

```python
import swarmauri

from swarmauri.signings.Ed25519EnvelopeSigner import Ed25519EnvelopeSigner

signer = Ed25519EnvelopeSigner()
print(signer.type)
```

The implementation still comes from the signer package, but application code can use the Swarmauri public namespace.

## Component Author Workflow

To make a component available through the Swarmauri namespace:

1. Implement the concrete class in its own package.
2. Ensure the class satisfies the relevant interface from `swarmauri_core` and base behavior from `swarmauri_base`.
3. Expose the component through a `swarmauri.<kind>` entry point or a citizenship registry mapping.
4. Import `swarmauri` in the consuming environment so the namespace importer and plugin discovery run.
5. Validate the public namespace path in tests.

## Examples

List known public namespaces:

```python
from swarmauri.interface_registry import InterfaceRegistry

for namespace in InterfaceRegistry.list_registered_namespaces():
    print(namespace)
```

Inspect registered first-party and discovered component paths:

```python
from swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry

for public_path, module_path in PluginCitizenshipRegistry.total_registry().items():
    print(public_path, "->", module_path)
```

Invalidate plugin entry-point cache after changing the Python environment at runtime:

```python
from swarmauri.plugin_manager import invalidate_entry_point_cache

invalidate_entry_point_cache()
```

## Related Packages

Core Swarmauri packages:

- [swarmauri_core](https://pypi.org/project/swarmauri_core/) provides interface contracts used by component packages.
- [swarmauri_base](https://pypi.org/project/swarmauri_base/) provides reusable base classes, serialization helpers, and component registration behavior.
- [swarmauri_standard](https://pypi.org/project/swarmauri_standard/) provides first-party standard components across agents, tools, parsers, prompts, metrics, similarities, deprecated distance compatibility shims, and other common resource kinds.

Related component kinds:

- [swarmauri_signing_ed25519](https://pypi.org/project/swarmauri_signing_ed25519/) for Ed25519 envelope signing.
- [swarmauri_signing_jws](https://pypi.org/project/swarmauri_signing_jws/) for JWS signing and verification.
- [swarmauri_keyprovider_inmemory](https://pypi.org/project/swarmauri_keyprovider_inmemory/) for in-memory key management.
- [swarmauri_storage_memory](https://pypi.org/project/swarmauri_storage_memory/) for memory-backed storage adapters.
- [swarmauri_middleware_jsonrpc](https://pypi.org/project/swarmauri_middleware_jsonrpc/) for JSON-RPC middleware.
- [swarmauri_transport_stdio](https://pypi.org/project/swarmauri_transport_stdio/) for stdio transport integrations.

## Documentation

- [Namespace import call flow](docs/callflow.md)
- [Citizenship registry notes](docs/citizenship.md)
- [Outcome notes](docs/outcomes.md)
- [Swarmauri SDK repository](https://github.com/swarmauri/swarmauri-sdk)

## When To Use This Package

Use `swarmauri` when you want the stable SDK namespace and plugin discovery behavior. Use the implementation package directly when you want to depend on only one specific component and do not need namespace routing.

## License

Apache-2.0

## Contributing

Contributions are welcome. Before adding a new public namespace path, update the interface and citizenship registries, add package-level tests for import resolution, and follow the [Swarmauri SDK contribution guide](https://github.com/swarmauri/swarmauri-sdk/blob/master/CONTRIBUTING.md).



