{"id":22962960,"url":"https://github.com/swarmauri/swarmauri-sdk","last_synced_at":"2026-05-20T09:04:40.628Z","repository":{"id":260077991,"uuid":"783516011","full_name":"swarmauri/swarmauri-sdk","owner":"swarmauri","description":"a monorepo featuring modular microkernel frameworks and single purpose extensions","archived":false,"fork":false,"pushed_at":"2026-03-26T10:11:08.000Z","size":68940,"stargazers_count":104,"open_issues_count":298,"forks_count":47,"subscribers_count":5,"default_branch":"master","last_synced_at":"2026-03-27T03:32:41.246Z","etag":null,"topics":["agents","ai","chunking","factories","llm-framework","measures","metrics","modular","monorepo","nlp","orchestration","orchestration-framework","parsing","tooling","tools","vectors"],"latest_commit_sha":null,"homepage":"https://swarmauri.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swarmauri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["swarmauri"]}},"created_at":"2024-04-08T03:39:16.000Z","updated_at":"2026-03-26T09:29:51.000Z","dependencies_parsed_at":"2024-11-17T09:24:37.648Z","dependency_job_id":"3f1a402f-a51d-4eba-b4ca-fa3ea3815a53","html_url":"https://github.com/swarmauri/swarmauri-sdk","commit_stats":null,"previous_names":["swarmauri/swarmauri-sdk"],"tags_count":5168,"template":false,"template_full_name":null,"purl":"pkg:github/swarmauri/swarmauri-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmauri%2Fswarmauri-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmauri%2Fswarmauri-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmauri%2Fswarmauri-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmauri%2Fswarmauri-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swarmauri","download_url":"https://codeload.github.com/swarmauri/swarmauri-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmauri%2Fswarmauri-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291132,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","chunking","factories","llm-framework","measures","metrics","modular","monorepo","nlp","orchestration","orchestration-framework","parsing","tooling","tools","vectors"],"created_at":"2024-12-14T19:18:56.923Z","updated_at":"2026-05-20T09:04:40.622Z","avatar_url":"https://github.com/swarmauri.png","language":"Python","funding_links":["https://github.com/sponsors/swarmauri"],"categories":[],"sub_categories":[],"readme":"![Swarmauri Logo](https://raw.githubusercontent.com/swarmauri/swarmauri-sdk/master/assets/swarmauri_sdk_brand.png)\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://pepy.tech/project/swarmauri/\"\u003e\n        \u003cimg src=\"https://static.pepy.tech/badge/swarmauri/month\" alt=\"PyPI - Downloads\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/swarmauri/\"\u003e\n        \u003cimg alt=\"Hits\" src=\"https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/swarmauri.svg\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/swarmauri/\"\u003e\n        \u003cimg 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\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/swarmauri/\"\u003e\n        \u003cimg src=\"https://img.shields.io/pypi/l/swarmauri\" alt=\"PyPI - License\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/swarmauri/\"\u003e\n        \u003cimg src=\"https://img.shields.io/pypi/v/swarmauri?label=swarmauri\u0026color=green\" alt=\"PyPI - swarmauri\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# Swarmauri SDK\n\nThe 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.\n\n## Installation Options\n\nSwarmauri offers multiple installation options to suit different needs:\n\n### Option 1: Complete SDK Installation\n\nFor a full-featured experience with all standard components:\n\n```bash\n# Install the main namespace package with standard components\npip install swarmauri\n\n# Install the main namespace package with extra standard components\npip install \"swarmauri[full]\"\n\n# Or with uv for faster installation\nuv pip install swarmauri\nuv pip install \"swarmauri[full]\"\n```\n\n### Option 2: Core Only\nFor a minimal installation with just the core interfaces:\n\n```bash\n# Install only the core components\npip install swarmauri_core\n\n# Or with uv for faster installation\nuv pip install swarmauri_core\n```\n\n### Option 3: Standalone Packages\n\nInstall specific packages for targeted functionality:\n\n```bash\n# Install only the vector store implementations you need\npip install swarmauri_vectorstore_pinecone\npip install swarmauri_vectorstore_annoy\n\n# Install specific tools\npip install swarmauri_tool_jupyterexportlatex\n\n# Or with uv for faster installation\nuv pip install swarmauri_vectorstore_pinecone\nuv pip install swarmauri_vectorstore_annoy\nuv pip install swarmauri_tool_jupyterexportlatex\n```\n\n### Development Installation\n\nFor contributors or those wanting the latest features:\n```bash\n# Clone the repository\ngit clone https://github.com/swarmauri/swarmauri-sdk.git\ncd swarmauri-sdk\n\n# Install in development mode\npip install -e .\n\n# Or with UV for faster installation\npip install uv\nuv pip install -e .\n```\n\n## Using Swarmauri Components\n\n## Native Dynamic Schemas and Serialization\n\nSwarmauri components are built to preserve concrete kin across runtime\nboundaries. A component can be initialized from JSON, YAML, or TOML, dumped back\nto the same formats, and restored later with its `type` discriminator intact.\nThat matters when factories, APIs, queues, or databases only see serialized\npayloads: Swarmauri can hydrate the concrete subclass instead of forcing every\napplication to maintain a handwritten `if type == ...` factory.\n\nThe dynamic schema registry updates the available discriminated-union members as\ncomponent classes are registered. A field typed as `SubclassUnion[ToolBase]`,\n`SubclassUnion[ToolkitBase]`, or another registered base can accept newly\navailable component kin and expose an accurate JSON Schema for the current\nruntime surface.\n\n```python\nfrom typing import Literal\nfrom pydantic import BaseModel\nfrom swarmauri_base.ComponentBase import ComponentBase\nfrom swarmauri_base.DynamicBase import SubclassUnion\n\n\n@ComponentBase.register_model()\nclass ConnectorBase(ComponentBase):\n    type: Literal[\"ConnectorBase\"] = \"ConnectorBase\"\n    label: str\n\n\n@ComponentBase.register_type(ConnectorBase, \"ApiConnector\")\nclass ApiConnector(ConnectorBase):\n    type: Literal[\"ApiConnector\"] = \"ApiConnector\"\n    endpoint: str\n\n\nclass ConnectorSpec(BaseModel):\n    connector: SubclassUnion[ConnectorBase]\n\n\nspec = ConnectorSpec.model_validate_json(\n    '{\"connector\":{\"type\":\"ApiConnector\",\"label\":\"primary\",\"endpoint\":\"https://api.example.test\"}}'\n)\n\nassert isinstance(spec.connector, ApiConnector)\nassert \"ApiConnector\" in str(ConnectorSpec.model_json_schema())\n```\n\nSee the [dynamic schemas guide](infra/docs/swarmauri-sdk/docs/guide/dynamic_schemas.md)\nfor factory, API, database, JSON, YAML, and TOML examples.\n\n### Method 1: Use the namespace package (recommended)\n\nThe `swarmauri` package acts as a namespace microkernel. Importing `swarmauri`\nregisters a custom importer that resolves classes from installed first-party and\ncommunity plugins.\n\n```python\nimport swarmauri\n\n# import concrete implementations through the unified namespace\nfrom swarmauri.documents import Document\nfrom swarmauri.tools import AdditionTool\nfrom swarmauri.messages import HumanMessage\n\ndoc = Document(content=\"Hello from the namespace package\")\ntool = AdditionTool()\nmsg = HumanMessage(content=\"Run a quick tool check\")\n\nprint(doc.type)\nprint(tool(\"2+2\"))\nprint(msg.content)\n```\n\n### Method 2: Use the index to discover what is available\n\nUse the plugin citizenship registry as an index of resource paths to concrete\nmodule locations.\n\n```python\nfrom swarmauri.plugin_citizenship_registry import PluginCitizenshipRegistry\n\n# Full index across first-, second-, and third-class plugins\nindex = PluginCitizenshipRegistry.total_registry()\nprint(f\"Indexed resources: {len(index)}\")\n\n# Example: inspect a few tool entries\ntool_rows = sorted(\n    (resource, module)\n    for resource, module in index.items()\n    if resource.startswith(\"swarmauri.tools.\")\n)\nfor resource, module in tool_rows[:5]:\n    print(f\"{resource} -\u003e {module}\")\n\n# Optional: inspect by citizenship class\nfirst_class_only = PluginCitizenshipRegistry.list_registry(\"first\")\nprint(f\"First-class resources: {len(first_class_only)}\")\n```\n\n### Method 3: Direct package imports\n\nFor explicit dependency control, import classes directly from their package.\n\n```python\nfrom swarmauri_standard.documents import Document\nfrom swarmauri_standard.tools import AdditionTool\n\ndoc = Document(content=\"Direct package import\")\ntool = AdditionTool()\n```\n\n## Package Structure\nThe Swarmauri SDK is organized into several key packages:\n\n- `swarmauri_core`: Core interfaces and constants\n- `swarmauri_base`: Abstract base classes for extensibility\n- `swarmauri_standard`: Standard implementations of common components\n- `swarmauri`: Main namespace package that unifies all components\n- `pkgs/community`: Community-maintained packages and integrations\n- `pkgs/deprecated`: Retired packages that remain for historical reference\n\nIndividual components follow these naming conventions:\n\n- `swarmauri_vectorstore_`*: Vector database integrations\n- `swarmauri_embedding_`*: Embedding model implementations\n- `swarmauri_tool_`*: Task-specific tools\n- `swarmauri_parser_`*: Text parsing utilities\n- `swarmauri_distance_`*: Distance calculation methods\n\n\n## For Contributors\nIf you want to contribute to the Swarmauri SDK, please read our [guidelines for contributing](https://github.com/swarmauri/swarmauri-sdk/blob/master/CONTRIBUTING.md) and [style guide](https://github.com/swarmauri/swarmauri-sdk/blob/master/STYLE_GUIDE.md) to get started.\n\n### Creating a New Plugin\nSwarmauri uses Python's entry point system for plugin discovery. Here's how to register your component:\n\n```python\n# In your pyproject.toml\n[project.entry-points.'swarmauri.vectorstores']\nYourVectorStore = \"swarmauri_vectorstore_yourplugin:YourVectorStore\"\n\n# In your implementation file\n@ComponentBase.register_type(VectorStoreBase, \"YourVectorStore\")\nclass YourVectorStore(VectorStoreBase):\n    # Your implementation\n```\n\n## License\nThe Swarmauri SDK is licensed under the Apache License 2.0. See the [LICENSE](https://github.com/swarmauri/swarmauri-sdk/blob/master/LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswarmauri%2Fswarmauri-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswarmauri%2Fswarmauri-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswarmauri%2Fswarmauri-sdk/lists"}