swarmauri 0.9.1.dev2__tar.gz → 0.11.0.dev1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- swarmauri-0.11.0.dev1/PKG-INFO +269 -0
- swarmauri-0.11.0.dev1/README.md +199 -0
- {swarmauri-0.9.1.dev2 → swarmauri-0.11.0.dev1}/pyproject.toml +25 -14
- {swarmauri-0.9.1.dev2 → swarmauri-0.11.0.dev1}/swarmauri/__init__.py +3 -1
- {swarmauri-0.9.1.dev2 → swarmauri-0.11.0.dev1}/swarmauri/cli.py +21 -7
- {swarmauri-0.9.1.dev2 → swarmauri-0.11.0.dev1}/swarmauri/importer.py +25 -13
- {swarmauri-0.9.1.dev2 → swarmauri-0.11.0.dev1}/swarmauri/interface_registry.py +69 -27
- swarmauri-0.11.0.dev1/swarmauri/plugin_citizenship_registry.py +1153 -0
- {swarmauri-0.9.1.dev2 → swarmauri-0.11.0.dev1}/swarmauri/plugin_manager.py +194 -107
- swarmauri-0.9.1.dev2/PKG-INFO +0 -264
- swarmauri-0.9.1.dev2/README.md +0 -199
- swarmauri-0.9.1.dev2/swarmauri/plugin_citizenship_registry.py +0 -651
- {swarmauri-0.9.1.dev2 → swarmauri-0.11.0.dev1}/LICENSE +0 -0
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: swarmauri
|
|
3
|
+
Version: 0.11.0.dev1
|
|
4
|
+
Summary: Swarmauri namespace microkernel for registry-backed imports, plugin discovery, and composable intelligence infrastructure components.
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
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
|
|
8
|
+
Author: Jacob Stewart
|
|
9
|
+
Author-email: jacob@swarmauri.com
|
|
10
|
+
Requires-Python: >=3.10,<3.15
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
24
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
25
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
26
|
+
Classifier: Topic :: System :: Distributed Computing
|
|
27
|
+
Provides-Extra: default
|
|
28
|
+
Provides-Extra: full
|
|
29
|
+
Provides-Extra: llms
|
|
30
|
+
Requires-Dist: httpx (>=0.27.0)
|
|
31
|
+
Requires-Dist: pydantic (>=2.9.2)
|
|
32
|
+
Requires-Dist: swarmauri_base
|
|
33
|
+
Requires-Dist: swarmauri_core
|
|
34
|
+
Requires-Dist: swarmauri_embedding_doc2vec ; extra == "default"
|
|
35
|
+
Requires-Dist: swarmauri_embedding_doc2vec ; extra == "full"
|
|
36
|
+
Requires-Dist: swarmauri_embedding_nmf ; extra == "default"
|
|
37
|
+
Requires-Dist: swarmauri_embedding_nmf ; extra == "full"
|
|
38
|
+
Requires-Dist: swarmauri_llm_ai21 ; extra == "llms"
|
|
39
|
+
Requires-Dist: swarmauri_llm_anthropic ; extra == "llms"
|
|
40
|
+
Requires-Dist: swarmauri_llm_cerebras ; extra == "llms"
|
|
41
|
+
Requires-Dist: swarmauri_llm_cohere ; extra == "llms"
|
|
42
|
+
Requires-Dist: swarmauri_llm_deepinfra ; extra == "llms"
|
|
43
|
+
Requires-Dist: swarmauri_llm_deepseek ; extra == "llms"
|
|
44
|
+
Requires-Dist: swarmauri_llm_falai ; extra == "llms"
|
|
45
|
+
Requires-Dist: swarmauri_llm_gemini ; extra == "llms"
|
|
46
|
+
Requires-Dist: swarmauri_llm_groq ; extra == "llms"
|
|
47
|
+
Requires-Dist: swarmauri_llm_hyperbolic ; extra == "llms"
|
|
48
|
+
Requires-Dist: swarmauri_llm_leptonai ; extra == "llms"
|
|
49
|
+
Requires-Dist: swarmauri_llm_llamacpp ; extra == "llms"
|
|
50
|
+
Requires-Dist: swarmauri_llm_mistral ; extra == "llms"
|
|
51
|
+
Requires-Dist: swarmauri_llm_openai ; extra == "llms"
|
|
52
|
+
Requires-Dist: swarmauri_llm_perplexity ; extra == "llms"
|
|
53
|
+
Requires-Dist: swarmauri_llm_playht ; extra == "llms"
|
|
54
|
+
Requires-Dist: swarmauri_llm_whisper ; extra == "llms"
|
|
55
|
+
Requires-Dist: swarmauri_parser_beautifulsoupelement ; extra == "default"
|
|
56
|
+
Requires-Dist: swarmauri_parser_beautifulsoupelement ; extra == "full"
|
|
57
|
+
Requires-Dist: swarmauri_parser_keywordextractor ; extra == "default"
|
|
58
|
+
Requires-Dist: swarmauri_parser_keywordextractor ; extra == "full"
|
|
59
|
+
Requires-Dist: swarmauri_signing_ed25519 ; extra == "default"
|
|
60
|
+
Requires-Dist: swarmauri_signing_ed25519 ; extra == "full"
|
|
61
|
+
Requires-Dist: swarmauri_standard
|
|
62
|
+
Requires-Dist: swarmauri_tool_matplotlib ; extra == "default"
|
|
63
|
+
Requires-Dist: swarmauri_tool_matplotlib ; extra == "full"
|
|
64
|
+
Requires-Dist: swarmauri_vectorstore_doc2vec ; extra == "default"
|
|
65
|
+
Requires-Dist: swarmauri_vectorstore_doc2vec ; extra == "full"
|
|
66
|
+
Requires-Dist: toml (>=0.10.2)
|
|
67
|
+
Requires-Dist: typing_extensions
|
|
68
|
+
Description-Content-Type: text/markdown
|
|
69
|
+
|
|
70
|
+

|
|
71
|
+
|
|
72
|
+
<p align="center">
|
|
73
|
+
<a href="https://pepy.tech/project/swarmauri/">
|
|
74
|
+
<img src="https://static.pepy.tech/badge/swarmauri/month" alt="PyPI - Downloads"/></a>
|
|
75
|
+
<a href="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/swarmauri/">
|
|
76
|
+
<img alt="Hits" src="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/swarmauri.svg"/></a>
|
|
77
|
+
<a href="https://pypi.org/project/swarmauri/">
|
|
78
|
+
<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>
|
|
79
|
+
<a href="https://pypi.org/project/swarmauri/">
|
|
80
|
+
<img src="https://img.shields.io/pypi/l/swarmauri" alt="PyPI - License"/></a>
|
|
81
|
+
<a href="https://pypi.org/project/swarmauri/">
|
|
82
|
+
<img src="https://img.shields.io/pypi/v/swarmauri?label=swarmauri&color=green" alt="PyPI - swarmauri"/></a>
|
|
83
|
+
<a href="https://discord.gg/N4UpBuQv8T">
|
|
84
|
+
<img src="https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white" alt="Discord"/></a></p>
|
|
85
|
+
|
|
86
|
+
# Swarmauri
|
|
87
|
+
|
|
88
|
+
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.
|
|
89
|
+
|
|
90
|
+
## What Is Swarmauri?
|
|
91
|
+
|
|
92
|
+
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.
|
|
93
|
+
|
|
94
|
+
## Why Swarmauri?
|
|
95
|
+
|
|
96
|
+
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.
|
|
97
|
+
|
|
98
|
+
## FAQ
|
|
99
|
+
|
|
100
|
+
### Q: What does the `swarmauri` package install?
|
|
101
|
+
|
|
102
|
+
A: It installs the public Swarmauri namespace, the namespace importer, interface registry access, plugin citizenship registry access, and entry-point discovery hooks.
|
|
103
|
+
|
|
104
|
+
### Q: Does `swarmauri` contain every component implementation?
|
|
105
|
+
|
|
106
|
+
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.
|
|
107
|
+
|
|
108
|
+
### Q: When should I import from `swarmauri` instead of a concrete package?
|
|
109
|
+
|
|
110
|
+
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.
|
|
111
|
+
|
|
112
|
+
This package is best for:
|
|
113
|
+
|
|
114
|
+
- AI application developers who want stable imports for agents, tools, models, parsers, vector stores, signing components, key providers, middleware, transports, and related SDK components.
|
|
115
|
+
- Platform engineers who need registry-driven plugin discovery without hard-coding every implementation package into application code.
|
|
116
|
+
- Component authors who want their packages to participate in the Swarmauri namespace through entry points and citizenship mappings.
|
|
117
|
+
- Operators who need a small runtime package that can load installed Swarmauri components on demand.
|
|
118
|
+
|
|
119
|
+
## How The Namespace Works
|
|
120
|
+
|
|
121
|
+
When `import swarmauri` runs, the package registers `SwarmauriImporter` on `sys.meta_path` and discovers installed plugins. The importer consults two registries:
|
|
122
|
+
|
|
123
|
+
- `InterfaceRegistry` maps resource namespaces such as `swarmauri.llms`, `swarmauri.tools`, and `swarmauri.signings` to their validation interfaces.
|
|
124
|
+
- `PluginCitizenshipRegistry` maps public namespace paths to implementation modules and classifies components as first-class, second-class, or third-class citizens.
|
|
125
|
+
|
|
126
|
+
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.
|
|
127
|
+
|
|
128
|
+
## Features
|
|
129
|
+
|
|
130
|
+
- Stable `swarmauri.*` namespace imports for installed SDK components.
|
|
131
|
+
- Registry-backed component discovery through first-class, second-class, and third-class citizenship mappings.
|
|
132
|
+
- Entry-point scanning for installed plugins and community packages.
|
|
133
|
+
- Interface-aware resource kinds for agents, chains, chunkers, conversations, embeddings, LLMs, parsers, tools, vector stores, signing, crypto, key providers, transports, middleware, and more.
|
|
134
|
+
- Optional dependency groups for curated component families, including `default`, `full`, and `llms`.
|
|
135
|
+
- Pydantic-based typed component workflows through `swarmauri_base` and concrete packages.
|
|
136
|
+
- Python 3.10, 3.11, 3.12, 3.13, and 3.14 support.
|
|
137
|
+
|
|
138
|
+
## Installation
|
|
139
|
+
|
|
140
|
+
Install the namespace package with `uv`:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
uv add swarmauri
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Or install it with `pip`:
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
pip install swarmauri
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Install optional LLM integrations when you want the curated LLM package set:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
uv add "swarmauri[llms]"
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
For the broader curated component bundle:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
uv add "swarmauri[full]"
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Usage
|
|
165
|
+
|
|
166
|
+
Importing `swarmauri` activates the namespace importer and plugin discovery:
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
import swarmauri
|
|
170
|
+
|
|
171
|
+
from swarmauri.interface_registry import InterfaceRegistry
|
|
172
|
+
from swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry
|
|
173
|
+
|
|
174
|
+
namespaces = InterfaceRegistry.list_registered_namespaces()
|
|
175
|
+
registered = PluginCitizenshipRegistry.total_registry()
|
|
176
|
+
|
|
177
|
+
print("known namespaces", len(namespaces))
|
|
178
|
+
print("known component mappings", len(registered))
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Resolve a component through a stable namespace path after the implementation package is installed:
|
|
182
|
+
|
|
183
|
+
```python
|
|
184
|
+
import swarmauri
|
|
185
|
+
|
|
186
|
+
from swarmauri.signings.Ed25519EnvelopeSigner import Ed25519EnvelopeSigner
|
|
187
|
+
|
|
188
|
+
signer = Ed25519EnvelopeSigner()
|
|
189
|
+
print(signer.type)
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
The implementation still comes from the signer package, but application code can use the Swarmauri public namespace.
|
|
193
|
+
|
|
194
|
+
## Component Author Workflow
|
|
195
|
+
|
|
196
|
+
To make a component available through the Swarmauri namespace:
|
|
197
|
+
|
|
198
|
+
1. Implement the concrete class in its own package.
|
|
199
|
+
2. Ensure the class satisfies the relevant interface from `swarmauri_core` and base behavior from `swarmauri_base`.
|
|
200
|
+
3. Expose the component through a `swarmauri.<kind>` entry point or a citizenship registry mapping.
|
|
201
|
+
4. Import `swarmauri` in the consuming environment so the namespace importer and plugin discovery run.
|
|
202
|
+
5. Validate the public namespace path in tests.
|
|
203
|
+
|
|
204
|
+
## Examples
|
|
205
|
+
|
|
206
|
+
List known public namespaces:
|
|
207
|
+
|
|
208
|
+
```python
|
|
209
|
+
from swarmauri.interface_registry import InterfaceRegistry
|
|
210
|
+
|
|
211
|
+
for namespace in InterfaceRegistry.list_registered_namespaces():
|
|
212
|
+
print(namespace)
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Inspect registered first-party and discovered component paths:
|
|
216
|
+
|
|
217
|
+
```python
|
|
218
|
+
from swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry
|
|
219
|
+
|
|
220
|
+
for public_path, module_path in PluginCitizenshipRegistry.total_registry().items():
|
|
221
|
+
print(public_path, "->", module_path)
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Invalidate plugin entry-point cache after changing the Python environment at runtime:
|
|
225
|
+
|
|
226
|
+
```python
|
|
227
|
+
from swarmauri.plugin_manager import invalidate_entry_point_cache
|
|
228
|
+
|
|
229
|
+
invalidate_entry_point_cache()
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Related Packages
|
|
233
|
+
|
|
234
|
+
Core Swarmauri packages:
|
|
235
|
+
|
|
236
|
+
- [swarmauri_core](https://pypi.org/project/swarmauri_core/) provides interface contracts used by component packages.
|
|
237
|
+
- [swarmauri_base](https://pypi.org/project/swarmauri_base/) provides reusable base classes, serialization helpers, and component registration behavior.
|
|
238
|
+
- [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.
|
|
239
|
+
|
|
240
|
+
Related component kinds:
|
|
241
|
+
|
|
242
|
+
- [swarmauri_signing_ed25519](https://pypi.org/project/swarmauri_signing_ed25519/) for Ed25519 envelope signing.
|
|
243
|
+
- [swarmauri_signing_jws](https://pypi.org/project/swarmauri_signing_jws/) for JWS signing and verification.
|
|
244
|
+
- [swarmauri_keyprovider_inmemory](https://pypi.org/project/swarmauri_keyprovider_inmemory/) for in-memory key management.
|
|
245
|
+
- [swarmauri_storage_memory](https://pypi.org/project/swarmauri_storage_memory/) for memory-backed storage adapters.
|
|
246
|
+
- [swarmauri_middleware_jsonrpc](https://pypi.org/project/swarmauri_middleware_jsonrpc/) for JSON-RPC middleware.
|
|
247
|
+
- [swarmauri_transport_stdio](https://pypi.org/project/swarmauri_transport_stdio/) for stdio transport integrations.
|
|
248
|
+
|
|
249
|
+
## Documentation
|
|
250
|
+
|
|
251
|
+
- [Namespace import call flow](docs/callflow.md)
|
|
252
|
+
- [Citizenship registry notes](docs/citizenship.md)
|
|
253
|
+
- [Outcome notes](docs/outcomes.md)
|
|
254
|
+
- [Swarmauri SDK repository](https://github.com/swarmauri/swarmauri-sdk)
|
|
255
|
+
|
|
256
|
+
## When To Use This Package
|
|
257
|
+
|
|
258
|
+
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.
|
|
259
|
+
|
|
260
|
+
## License
|
|
261
|
+
|
|
262
|
+
Apache-2.0
|
|
263
|
+
|
|
264
|
+
## Contributing
|
|
265
|
+
|
|
266
|
+
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).
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+

|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<a href="https://pepy.tech/project/swarmauri/">
|
|
5
|
+
<img src="https://static.pepy.tech/badge/swarmauri/month" alt="PyPI - Downloads"/></a>
|
|
6
|
+
<a href="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/swarmauri/">
|
|
7
|
+
<img alt="Hits" src="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/swarmauri.svg"/></a>
|
|
8
|
+
<a href="https://pypi.org/project/swarmauri/">
|
|
9
|
+
<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>
|
|
10
|
+
<a href="https://pypi.org/project/swarmauri/">
|
|
11
|
+
<img src="https://img.shields.io/pypi/l/swarmauri" alt="PyPI - License"/></a>
|
|
12
|
+
<a href="https://pypi.org/project/swarmauri/">
|
|
13
|
+
<img src="https://img.shields.io/pypi/v/swarmauri?label=swarmauri&color=green" alt="PyPI - swarmauri"/></a>
|
|
14
|
+
<a href="https://discord.gg/N4UpBuQv8T">
|
|
15
|
+
<img src="https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white" alt="Discord"/></a></p>
|
|
16
|
+
|
|
17
|
+
# Swarmauri
|
|
18
|
+
|
|
19
|
+
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.
|
|
20
|
+
|
|
21
|
+
## What Is Swarmauri?
|
|
22
|
+
|
|
23
|
+
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.
|
|
24
|
+
|
|
25
|
+
## Why Swarmauri?
|
|
26
|
+
|
|
27
|
+
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.
|
|
28
|
+
|
|
29
|
+
## FAQ
|
|
30
|
+
|
|
31
|
+
### Q: What does the `swarmauri` package install?
|
|
32
|
+
|
|
33
|
+
A: It installs the public Swarmauri namespace, the namespace importer, interface registry access, plugin citizenship registry access, and entry-point discovery hooks.
|
|
34
|
+
|
|
35
|
+
### Q: Does `swarmauri` contain every component implementation?
|
|
36
|
+
|
|
37
|
+
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.
|
|
38
|
+
|
|
39
|
+
### Q: When should I import from `swarmauri` instead of a concrete package?
|
|
40
|
+
|
|
41
|
+
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.
|
|
42
|
+
|
|
43
|
+
This package is best for:
|
|
44
|
+
|
|
45
|
+
- AI application developers who want stable imports for agents, tools, models, parsers, vector stores, signing components, key providers, middleware, transports, and related SDK components.
|
|
46
|
+
- Platform engineers who need registry-driven plugin discovery without hard-coding every implementation package into application code.
|
|
47
|
+
- Component authors who want their packages to participate in the Swarmauri namespace through entry points and citizenship mappings.
|
|
48
|
+
- Operators who need a small runtime package that can load installed Swarmauri components on demand.
|
|
49
|
+
|
|
50
|
+
## How The Namespace Works
|
|
51
|
+
|
|
52
|
+
When `import swarmauri` runs, the package registers `SwarmauriImporter` on `sys.meta_path` and discovers installed plugins. The importer consults two registries:
|
|
53
|
+
|
|
54
|
+
- `InterfaceRegistry` maps resource namespaces such as `swarmauri.llms`, `swarmauri.tools`, and `swarmauri.signings` to their validation interfaces.
|
|
55
|
+
- `PluginCitizenshipRegistry` maps public namespace paths to implementation modules and classifies components as first-class, second-class, or third-class citizens.
|
|
56
|
+
|
|
57
|
+
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.
|
|
58
|
+
|
|
59
|
+
## Features
|
|
60
|
+
|
|
61
|
+
- Stable `swarmauri.*` namespace imports for installed SDK components.
|
|
62
|
+
- Registry-backed component discovery through first-class, second-class, and third-class citizenship mappings.
|
|
63
|
+
- Entry-point scanning for installed plugins and community packages.
|
|
64
|
+
- Interface-aware resource kinds for agents, chains, chunkers, conversations, embeddings, LLMs, parsers, tools, vector stores, signing, crypto, key providers, transports, middleware, and more.
|
|
65
|
+
- Optional dependency groups for curated component families, including `default`, `full`, and `llms`.
|
|
66
|
+
- Pydantic-based typed component workflows through `swarmauri_base` and concrete packages.
|
|
67
|
+
- Python 3.10, 3.11, 3.12, 3.13, and 3.14 support.
|
|
68
|
+
|
|
69
|
+
## Installation
|
|
70
|
+
|
|
71
|
+
Install the namespace package with `uv`:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
uv add swarmauri
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Or install it with `pip`:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
pip install swarmauri
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Install optional LLM integrations when you want the curated LLM package set:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
uv add "swarmauri[llms]"
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
For the broader curated component bundle:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
uv add "swarmauri[full]"
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Usage
|
|
96
|
+
|
|
97
|
+
Importing `swarmauri` activates the namespace importer and plugin discovery:
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
import swarmauri
|
|
101
|
+
|
|
102
|
+
from swarmauri.interface_registry import InterfaceRegistry
|
|
103
|
+
from swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry
|
|
104
|
+
|
|
105
|
+
namespaces = InterfaceRegistry.list_registered_namespaces()
|
|
106
|
+
registered = PluginCitizenshipRegistry.total_registry()
|
|
107
|
+
|
|
108
|
+
print("known namespaces", len(namespaces))
|
|
109
|
+
print("known component mappings", len(registered))
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Resolve a component through a stable namespace path after the implementation package is installed:
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
import swarmauri
|
|
116
|
+
|
|
117
|
+
from swarmauri.signings.Ed25519EnvelopeSigner import Ed25519EnvelopeSigner
|
|
118
|
+
|
|
119
|
+
signer = Ed25519EnvelopeSigner()
|
|
120
|
+
print(signer.type)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The implementation still comes from the signer package, but application code can use the Swarmauri public namespace.
|
|
124
|
+
|
|
125
|
+
## Component Author Workflow
|
|
126
|
+
|
|
127
|
+
To make a component available through the Swarmauri namespace:
|
|
128
|
+
|
|
129
|
+
1. Implement the concrete class in its own package.
|
|
130
|
+
2. Ensure the class satisfies the relevant interface from `swarmauri_core` and base behavior from `swarmauri_base`.
|
|
131
|
+
3. Expose the component through a `swarmauri.<kind>` entry point or a citizenship registry mapping.
|
|
132
|
+
4. Import `swarmauri` in the consuming environment so the namespace importer and plugin discovery run.
|
|
133
|
+
5. Validate the public namespace path in tests.
|
|
134
|
+
|
|
135
|
+
## Examples
|
|
136
|
+
|
|
137
|
+
List known public namespaces:
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
from swarmauri.interface_registry import InterfaceRegistry
|
|
141
|
+
|
|
142
|
+
for namespace in InterfaceRegistry.list_registered_namespaces():
|
|
143
|
+
print(namespace)
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Inspect registered first-party and discovered component paths:
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
from swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry
|
|
150
|
+
|
|
151
|
+
for public_path, module_path in PluginCitizenshipRegistry.total_registry().items():
|
|
152
|
+
print(public_path, "->", module_path)
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Invalidate plugin entry-point cache after changing the Python environment at runtime:
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
from swarmauri.plugin_manager import invalidate_entry_point_cache
|
|
159
|
+
|
|
160
|
+
invalidate_entry_point_cache()
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Related Packages
|
|
164
|
+
|
|
165
|
+
Core Swarmauri packages:
|
|
166
|
+
|
|
167
|
+
- [swarmauri_core](https://pypi.org/project/swarmauri_core/) provides interface contracts used by component packages.
|
|
168
|
+
- [swarmauri_base](https://pypi.org/project/swarmauri_base/) provides reusable base classes, serialization helpers, and component registration behavior.
|
|
169
|
+
- [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.
|
|
170
|
+
|
|
171
|
+
Related component kinds:
|
|
172
|
+
|
|
173
|
+
- [swarmauri_signing_ed25519](https://pypi.org/project/swarmauri_signing_ed25519/) for Ed25519 envelope signing.
|
|
174
|
+
- [swarmauri_signing_jws](https://pypi.org/project/swarmauri_signing_jws/) for JWS signing and verification.
|
|
175
|
+
- [swarmauri_keyprovider_inmemory](https://pypi.org/project/swarmauri_keyprovider_inmemory/) for in-memory key management.
|
|
176
|
+
- [swarmauri_storage_memory](https://pypi.org/project/swarmauri_storage_memory/) for memory-backed storage adapters.
|
|
177
|
+
- [swarmauri_middleware_jsonrpc](https://pypi.org/project/swarmauri_middleware_jsonrpc/) for JSON-RPC middleware.
|
|
178
|
+
- [swarmauri_transport_stdio](https://pypi.org/project/swarmauri_transport_stdio/) for stdio transport integrations.
|
|
179
|
+
|
|
180
|
+
## Documentation
|
|
181
|
+
|
|
182
|
+
- [Namespace import call flow](docs/callflow.md)
|
|
183
|
+
- [Citizenship registry notes](docs/citizenship.md)
|
|
184
|
+
- [Outcome notes](docs/outcomes.md)
|
|
185
|
+
- [Swarmauri SDK repository](https://github.com/swarmauri/swarmauri-sdk)
|
|
186
|
+
|
|
187
|
+
## When To Use This Package
|
|
188
|
+
|
|
189
|
+
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.
|
|
190
|
+
|
|
191
|
+
## License
|
|
192
|
+
|
|
193
|
+
Apache-2.0
|
|
194
|
+
|
|
195
|
+
## Contributing
|
|
196
|
+
|
|
197
|
+
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).
|
|
198
|
+
|
|
199
|
+
|
|
@@ -1,25 +1,35 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "swarmauri"
|
|
3
|
-
version = "0.
|
|
4
|
-
description = "
|
|
3
|
+
version = "0.11.0.dev1"
|
|
4
|
+
description = "Swarmauri namespace microkernel for registry-backed imports, plugin discovery, and composable intelligence infrastructure components."
|
|
5
5
|
keywords = [
|
|
6
6
|
"swarmauri",
|
|
7
|
-
"
|
|
8
|
-
"
|
|
9
|
-
"
|
|
10
|
-
"
|
|
11
|
-
"
|
|
12
|
-
"
|
|
13
|
-
"toml",
|
|
14
|
-
"plugin-factory",
|
|
7
|
+
"ai-sdk",
|
|
8
|
+
"namespace-package",
|
|
9
|
+
"plugin-discovery",
|
|
10
|
+
"component-registry",
|
|
11
|
+
"composable-intelligence",
|
|
12
|
+
"microkernel",
|
|
15
13
|
"typed-components",
|
|
14
|
+
"pydantic-components",
|
|
15
|
+
"dynamic-imports",
|
|
16
|
+
"entry-points",
|
|
17
|
+
"agents",
|
|
18
|
+
"llms",
|
|
19
|
+
"tools",
|
|
20
|
+
"vector-stores",
|
|
21
|
+
"signing",
|
|
22
|
+
"key-providers",
|
|
16
23
|
]
|
|
17
24
|
license = "Apache-2.0"
|
|
18
25
|
readme = "README.md"
|
|
19
26
|
repository = "http://github.com/swarmauri/swarmauri-sdk"
|
|
20
27
|
requires-python = ">=3.10,<3.15"
|
|
21
28
|
classifiers = [
|
|
29
|
+
"Development Status :: 4 - Beta",
|
|
30
|
+
"Intended Audience :: Developers",
|
|
22
31
|
"License :: OSI Approved :: Apache Software License",
|
|
32
|
+
"Operating System :: OS Independent",
|
|
23
33
|
"Programming Language :: Python",
|
|
24
34
|
"Programming Language :: Python :: 3",
|
|
25
35
|
"Programming Language :: Python :: 3 :: Only",
|
|
@@ -28,6 +38,10 @@ classifiers = [
|
|
|
28
38
|
"Programming Language :: Python :: 3.12",
|
|
29
39
|
"Programming Language :: Python :: 3.13",
|
|
30
40
|
"Programming Language :: Python :: 3.14",
|
|
41
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
42
|
+
"Topic :: Software Development :: Libraries",
|
|
43
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
44
|
+
"Topic :: System :: Distributed Computing",
|
|
31
45
|
]
|
|
32
46
|
authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
|
|
33
47
|
dependencies = [
|
|
@@ -50,7 +64,6 @@ default = [
|
|
|
50
64
|
"swarmauri_parser_keywordextractor",
|
|
51
65
|
"swarmauri_parser_beautifulsoupelement",
|
|
52
66
|
#"swarmauri_vectorstore_tfidf",
|
|
53
|
-
"swarmauri_distance_minkowski",
|
|
54
67
|
"swarmauri_signing_ed25519",
|
|
55
68
|
]
|
|
56
69
|
|
|
@@ -62,7 +75,6 @@ full = [
|
|
|
62
75
|
"swarmauri_embedding_doc2vec",
|
|
63
76
|
#"swarmauri_embedding_tfidf",
|
|
64
77
|
"swarmauri_embedding_nmf",
|
|
65
|
-
"swarmauri_distance_minkowski",
|
|
66
78
|
"swarmauri_tool_matplotlib",
|
|
67
79
|
"swarmauri_signing_ed25519",
|
|
68
80
|
]
|
|
@@ -116,7 +128,6 @@ swarmauri_tool_matplotlib = { workspace = true }
|
|
|
116
128
|
swarmauri_parser_keywordextractor = { workspace = true }
|
|
117
129
|
swarmauri_parser_beautifulsoupelement = { workspace = true }
|
|
118
130
|
#swarmauri_vectorstore_tfidf = { workspace = true }
|
|
119
|
-
swarmauri_distance_minkowski = { workspace = true }
|
|
120
131
|
swarmauri_signing_ed25519 = { workspace = true }
|
|
121
132
|
|
|
122
133
|
[tool.pytest.ini_options]
|
|
@@ -157,7 +168,7 @@ dev = [
|
|
|
157
168
|
"python-dotenv>=1.0.0",
|
|
158
169
|
"jsonschema>=4.18.5",
|
|
159
170
|
"ipython>=8.28.0",
|
|
160
|
-
"
|
|
171
|
+
"httpx>=0.27",
|
|
161
172
|
"flake8>=7.0",
|
|
162
173
|
"ruff>=0.9.9",
|
|
163
174
|
"pytest-benchmark>=4.0.0",
|
|
@@ -6,7 +6,9 @@ from .plugin_manager import discover_and_register_plugins
|
|
|
6
6
|
logger = logging.getLogger(__name__)
|
|
7
7
|
|
|
8
8
|
try:
|
|
9
|
-
if not any(
|
|
9
|
+
if not any(
|
|
10
|
+
isinstance(importer, SwarmauriImporter) for importer in _sys.meta_path
|
|
11
|
+
):
|
|
10
12
|
logger.info("Registering SwarmauriImporter in _sys.meta_path.")
|
|
11
13
|
_sys.meta_path.insert(0, SwarmauriImporter())
|
|
12
14
|
else:
|
|
@@ -13,7 +13,9 @@ def run_command(command):
|
|
|
13
13
|
Run a shell command and handle errors.
|
|
14
14
|
"""
|
|
15
15
|
try:
|
|
16
|
-
result = subprocess.run(
|
|
16
|
+
result = subprocess.run(
|
|
17
|
+
command, check=True, text=True, capture_output=True
|
|
18
|
+
)
|
|
17
19
|
logger.info(result.stdout)
|
|
18
20
|
except subprocess.CalledProcessError as e:
|
|
19
21
|
logger.error(f"Command failed: {e.stderr}")
|
|
@@ -31,7 +33,9 @@ def install_plugin(plugin_name, use_pip=False, use_poetry=False):
|
|
|
31
33
|
logger.info(f"Adding plugin '{plugin_name}' using poetry...")
|
|
32
34
|
run_command(["poetry", "add", plugin_name])
|
|
33
35
|
else:
|
|
34
|
-
logger.warning(
|
|
36
|
+
logger.warning(
|
|
37
|
+
"Specify --use-pip or --use-poetry to install the plugin."
|
|
38
|
+
)
|
|
35
39
|
|
|
36
40
|
|
|
37
41
|
def remove_plugin(plugin_name, use_pip=False, use_poetry=False):
|
|
@@ -45,7 +49,9 @@ def remove_plugin(plugin_name, use_pip=False, use_poetry=False):
|
|
|
45
49
|
logger.info(f"Removing plugin '{plugin_name}' using poetry...")
|
|
46
50
|
run_command(["poetry", "remove", plugin_name])
|
|
47
51
|
else:
|
|
48
|
-
logger.warning(
|
|
52
|
+
logger.warning(
|
|
53
|
+
"Specify --use-pip or --use-poetry to remove the plugin."
|
|
54
|
+
)
|
|
49
55
|
|
|
50
56
|
|
|
51
57
|
def validate_plugin(plugin_name):
|
|
@@ -89,7 +95,9 @@ def register_plugin(plugin_name):
|
|
|
89
95
|
if "." in entry_point.group
|
|
90
96
|
else None
|
|
91
97
|
)
|
|
92
|
-
plugin_manager.register(
|
|
98
|
+
plugin_manager.register(
|
|
99
|
+
entry_point.name, plugin_class, resource_kind
|
|
100
|
+
)
|
|
93
101
|
logger.info(f"Plugin '{plugin_name}' registered successfully.")
|
|
94
102
|
return
|
|
95
103
|
logger.warning(f"Plugin '{plugin_name}' not found among entry points.")
|
|
@@ -120,10 +128,14 @@ def main():
|
|
|
120
128
|
description="Swarmauri CLI: Manage plugins and namespace components."
|
|
121
129
|
)
|
|
122
130
|
|
|
123
|
-
subparsers = parser.add_subparsers(
|
|
131
|
+
subparsers = parser.add_subparsers(
|
|
132
|
+
dest="command", help="Subcommands for the CLI"
|
|
133
|
+
)
|
|
124
134
|
|
|
125
135
|
# Subcommand: Install Plugin
|
|
126
|
-
install_parser = subparsers.add_parser(
|
|
136
|
+
install_parser = subparsers.add_parser(
|
|
137
|
+
"install", help="Install a new plugin."
|
|
138
|
+
)
|
|
127
139
|
install_parser.add_argument(
|
|
128
140
|
"plugin_name", type=str, help="Name of the plugin to install."
|
|
129
141
|
)
|
|
@@ -155,7 +167,9 @@ def main():
|
|
|
155
167
|
)
|
|
156
168
|
|
|
157
169
|
# Subcommand: Register Plugin
|
|
158
|
-
register_parser = subparsers.add_parser(
|
|
170
|
+
register_parser = subparsers.add_parser(
|
|
171
|
+
"register", help="Register a plugin."
|
|
172
|
+
)
|
|
159
173
|
register_parser.add_argument(
|
|
160
174
|
"plugin_name", type=str, help="Name of the plugin to register."
|
|
161
175
|
)
|