fefcc38e11
Workspace, org, channel, memory, delegation client for Molecule AI. Package renamed to molecule-ai-sdk for PyPI.
136 lines
4.5 KiB
Markdown
136 lines
4.5 KiB
Markdown
# molecule_plugin — Python SDK for building Molecule AI plugins
|
|
|
|
A Molecule AI plugin is a directory that bundles rules, skills, and per-runtime
|
|
install adaptors. Any plugin that conforms to this contract is installable
|
|
on any Molecule AI workspace whose runtime the plugin supports.
|
|
|
|
## Quick start
|
|
|
|
Copy `template/` to a new directory and edit:
|
|
|
|
```
|
|
my-plugin/
|
|
├── plugin.yaml # name, version, runtimes, description
|
|
├── rules/my-rule.md # optional — appended to CLAUDE.md at install
|
|
├── skills/my-skill/
|
|
│ ├── SKILL.md # instructions injected into the system prompt
|
|
│ └── tools/do_thing.py # optional LangChain @tool functions
|
|
└── adapters/
|
|
├── claude_code.py # one-liner: `from molecule_plugin import AgentskillsAdaptor as Adaptor`
|
|
└── deepagents.py # same
|
|
```
|
|
|
|
Validate:
|
|
|
|
```python
|
|
from molecule_plugin import validate_manifest
|
|
errors = validate_manifest("my-plugin/plugin.yaml")
|
|
assert not errors, errors
|
|
```
|
|
|
|
## CLI
|
|
|
|
The SDK ships a CLI for validating Molecule AI artifacts before publishing:
|
|
|
|
```bash
|
|
python -m molecule_plugin validate plugin my-plugin/
|
|
python -m molecule_plugin validate workspace workspace-configs-templates/claude-code-default/
|
|
python -m molecule_plugin validate org org-templates/molecule-dev/
|
|
python -m molecule_plugin validate channel channels.yaml
|
|
python -m molecule_plugin validate my-plugin/ # kind defaults to 'plugin'
|
|
```
|
|
|
|
Exit code is 0 when valid, 1 when any errors are found — suitable for CI.
|
|
Add `-q` / `--quiet` to suppress success lines and emit only errors.
|
|
|
|
Programmatic equivalents:
|
|
|
|
```python
|
|
from molecule_plugin import (
|
|
validate_plugin,
|
|
validate_workspace_template,
|
|
validate_org_template,
|
|
validate_channel_file,
|
|
validate_channel_config,
|
|
)
|
|
```
|
|
|
|
## Per-runtime adaptors — when to write a custom one
|
|
|
|
The default `AgentskillsAdaptor` handles the common shape: rules go into
|
|
the runtime's memory file (CLAUDE.md), skill dirs go into `/configs/skills/`.
|
|
That covers most plugins.
|
|
|
|
Write a custom adaptor when you need to:
|
|
|
|
- **Register runtime tools dynamically** — call `ctx.register_tool(name, fn)`.
|
|
- **Register DeepAgents sub-agents** — call `ctx.register_subagent(name, spec)`.
|
|
- **Write to a non-standard memory file** — call `ctx.append_to_memory(filename, content)`.
|
|
|
|
Minimum custom adaptor:
|
|
|
|
```python
|
|
# adapters/deepagents.py
|
|
from molecule_plugin import InstallContext, InstallResult
|
|
|
|
class Adaptor:
|
|
def __init__(self, plugin_name: str, runtime: str):
|
|
self.plugin_name, self.runtime = plugin_name, runtime
|
|
|
|
async def install(self, ctx: InstallContext) -> InstallResult:
|
|
ctx.register_subagent("my-agent", {"prompt": "...", "tools": [...]})
|
|
return InstallResult(plugin_name=self.plugin_name, runtime=self.runtime, source="plugin")
|
|
|
|
async def uninstall(self, ctx: InstallContext) -> None:
|
|
pass
|
|
```
|
|
|
|
## Resolution order (understood by the platform)
|
|
|
|
For `(plugin_name, runtime)`:
|
|
|
|
1. **Platform registry** — `workspace-template/plugins_registry/<plugin>/<runtime>.py`
|
|
(curated; set by the Molecule AI team for quality-assured plugins).
|
|
2. **Plugin-shipped** — `<plugin_root>/adapters/<runtime>.py` (what this SDK helps you build).
|
|
3. **Raw-drop fallback** — copies plugin files into `/configs/plugins/<name>/`
|
|
and surfaces a warning; no tools are wired.
|
|
|
|
You generally ship for path #2. If your plugin becomes popular enough to be
|
|
promoted to "default," the Molecule AI team PRs a copy of your adaptor into
|
|
the platform registry (path #1) so it survives upstream breakage.
|
|
|
|
## Testing locally
|
|
|
|
The SDK ships `AgentskillsAdaptor` as a standalone, unit-testable class:
|
|
|
|
```python
|
|
import asyncio
|
|
from pathlib import Path
|
|
from molecule_plugin import AgentskillsAdaptor, InstallContext
|
|
|
|
ctx = InstallContext(
|
|
configs_dir=Path("/tmp/configs"),
|
|
workspace_id="local",
|
|
runtime="claude_code",
|
|
plugin_root=Path("./my-plugin"),
|
|
)
|
|
asyncio.run(AgentskillsAdaptor("my-plugin", "claude_code").install(ctx))
|
|
# check /tmp/configs/CLAUDE.md, /tmp/configs/skills/
|
|
```
|
|
|
|
## Publishing
|
|
|
|
A plugin is just a directory. Push it to any Git host. Installation via
|
|
`POST /plugins/install {git_url}` is on the roadmap — see the platform's
|
|
`PLAN.md` under "Install-from-GitHub-URL flow." Until then, plugins are
|
|
bundled into the platform by dropping them into `plugins/` at deploy time.
|
|
|
|
## Supported runtimes
|
|
|
|
As of 2026-Q2: `claude_code`, `deepagents`, `langgraph`, `crewai`, `autogen`,
|
|
`openclaw`. See the live list with:
|
|
|
|
```bash
|
|
curl $PLATFORM_URL/plugins
|
|
```
|