Metadata-Version: 2.5
Name: marginalia-ai-sdk
Version: 0.6.1
Summary: Standalone contracts for Research Engine plugins
Project-URL: Homepage, https://github.com/John-Cusack/MarginaliaAI
Project-URL: Source, https://github.com/John-Cusack/MarginaliaAI
Project-URL: Issues, https://github.com/John-Cusack/MarginaliaAI/issues
Project-URL: Changelog, https://github.com/John-Cusack/MarginaliaAI/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/John-Cusack/MarginaliaAI/tree/main/docs
Author: MarginaliaAI
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: corpus,mcp,plugins,research,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.11
Requires-Dist: packaging>=23
Requires-Dist: pydantic<3,>=2.5
Requires-Dist: pyyaml<7,>=6
Description-Content-Type: text/markdown

# Research Engine SDK

`marginalia-ai-sdk` is the standalone, typed contract for building plugins for
[Research Engine](https://github.com/John-Cusack/MarginaliaAI). It contains static manifest
models, boundary DTOs, scoped client protocols, decorators, chunking helpers, and portable
contract tests. It does not install or import the Research Engine core.

## Install

```bash
python -m pip install "marginalia-ai-sdk>=0.6,<0.7"
```

A plugin declares a static `plugin.yaml` inside its top-level import package and advertises
that package through the `research_engine.plugins` entry-point group. Plugin acquisition and
removal belong to pip, uv, or pipx; the running engine never installs plugin dependencies.

```toml
[project.entry-points."research_engine.plugins"]
example = "example"
```

```yaml
schema_version: 2
plugin_id: example
requires:
  core_api: ">=0.6,<0.7"
  python: ">=3.11"
permissions:
  network: none
  filesystem: plugin_data
provides:
  mcp_tools:
    - id: example.search
      entry: example.tools:search
      description: Search the example source.
      input_schema:
        type: object
        properties:
          query: {type: string}
        required: [query]
```

Plugin code executes in the core process after explicit operator approval. Scoped clients are
the supported API boundary, not a security sandbox; install and enable only trusted plugins.

API compatibility follows the core minor release through `0.x`. A plugin supporting core
`0.6.x` should depend on `marginalia-ai-sdk>=0.6,<0.7`.

Core supplies each handler a `PluginContext` with its plugin data directory and
the configured database URL. The URL is a Pydantic `SecretStr`: database-backed
plugins call `context.database_url.get_secret_value()` at the connection
boundary and must not log or serialize that value.

See the [architecture](https://github.com/John-Cusack/MarginaliaAI/blob/main/docs/design/pypi-plugin-distribution-architecture.md),
[changelog](https://github.com/John-Cusack/MarginaliaAI/blob/main/CHANGELOG.md), and
[issue tracker](https://github.com/John-Cusack/MarginaliaAI/issues). Licensed under
[Apache-2.0](https://github.com/John-Cusack/MarginaliaAI/blob/main/LICENSE).
