Metadata-Version: 2.4
Name: piilot-sdk
Version: 0.4.0
Summary: Piilot plugin SDK — public primitives (connectors, tools, modules, agents, HTTP, DB, scheduler, cache, storage, access, knowledge) for building Piilot plugins.
Author-email: Kinetics Consulting V2 <contact@piilot.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Kinetics-Consulting-V2/AICockpit
Project-URL: Documentation, https://github.com/Kinetics-Consulting-V2/AICockpit/blob/main/docs/sdk/PLUGIN_DEVELOPMENT.md
Project-URL: Changelog, https://github.com/Kinetics-Consulting-V2/AICockpit/blob/main/docs/sdk/SDK_CHANGELOG.md
Project-URL: Issues, https://github.com/Kinetics-Consulting-V2/AICockpit/issues
Project-URL: Repository, https://github.com/Kinetics-Consulting-V2/AICockpit
Keywords: piilot,plugin,sdk,agents,llm,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: jsonschema<5.0,>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: black>=25.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

# piilot-sdk

Public SDK for building **Piilot** plugins — the AI cockpit with data
sovereignty.

[![PyPI version](https://img.shields.io/pypi/v/piilot-sdk.svg)](https://pypi.org/project/piilot-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/piilot-sdk.svg)](https://pypi.org/project/piilot-sdk/)
[![License](https://img.shields.io/pypi/l/piilot-sdk.svg)](https://github.com/Kinetics-Consulting-V2/AICockpit/blob/main/piilot/LICENSE)

## What is it

`piilot-sdk` is the stable, narrow public contract Piilot plugins import
from. A plugin **MUST only import from `piilot.sdk.*`** — any import from
`backend.*` is refused at boot by the loader's AST check.

The SDK exposes primitives for:

- **Connectors** — credentials storage with manifest-driven auto-encrypt
- **Tools** — agent tool registration with namespace isolation
- **Modules** — dashboards and workflow surfaces (`register_module`)
- **Agents** — session scope + templates (`register_template`) + system prompt builders
- **HTTP** — `register_router` / `register_webhook_router` with auth deps
- **DB** — RLS-aware `cursor`, `run_in_thread`, `execute_values`, `Json`
- **Scheduler** — `register_sync_handler` for per-provider sync dispatch
- **Cache** — async Redis primitives with namespace auto-prefix
- **Storage** — async S3 primitives with namespace auto-prefix
- **Access** — `check_grant` passthrough
- **Crypto** — `mask_api_key` helper

## Install

```bash
pip install piilot-sdk
```

## Quick start

Create a plugin entry point:

```python
# piilot_pack_hello/__init__.py
from piilot.sdk import Plugin, Context
from piilot.sdk import tools, http

class Plugin(Plugin):
    def register(self, ctx: Context) -> None:
        tools.register_tool({
            "id": "hello.greet",
            "label_key": "hello.tools.greet.label",
            "description_key": "hello.tools.greet.description",
            "callable": lambda name: f"Hello, {name}!",
        })

        http.register_router(
            routes=[...],
            prefix="/api/hello",
        )
```

Declare it as a Piilot plugin in your `pyproject.toml`:

```toml
[project.entry-points."piilot.plugins"]
hello = "piilot_pack_hello:Plugin"

[tool.piilot.plugin]
manifest_version = 1
namespace = "hello"
sdk_compat = ">=0.2.0,<1.0.0"
# ...
```

## Documentation

Full guide: [PLUGIN_DEVELOPMENT.md](https://github.com/Kinetics-Consulting-V2/AICockpit/blob/main/docs/sdk/PLUGIN_DEVELOPMENT.md).

Changelog: [SDK_CHANGELOG.md](https://github.com/Kinetics-Consulting-V2/AICockpit/blob/main/docs/sdk/SDK_CHANGELOG.md).

Template repo: [piilot-plugin-template](https://github.com/Kinetics-Consulting-V2/piilot-plugin-template).

## Versioning

Semver. Breaking changes bump the major. Plugins pin a compatible range
via `sdk_compat` in their manifest.

## License

Apache-2.0. See [LICENSE](LICENSE).
