Metadata-Version: 2.4
Name: lucille-sdk
Version: 0.1.0
Summary: Lucille platform SDK: the integration declaration surface products build against (and, in later phases, the platform client).
Project-URL: Repository, https://github.com/gald33/Lucille
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# lucille-sdk

The stable contract a product builds against to run on the Lucille platform,
without importing the Lucille backend.

It is **interface only** — around 800 lines, no dependencies, stdlib-only by
design. A product imports the declaration surface and the capability seams; a
*host* registers concrete providers behind those seams before the product is
imported. In-process that host is the Lucille backend; out-of-process it is the
product's own runtime.

```python
from lucille_sdk import Integration, IntegrationDescriptor
from lucille_sdk.services import get_message_compose
from lucille_sdk.telegram import settled_text
```

## What is in it

| Module | What it declares |
|---|---|
| `integration` | `Integration` base class, settings-provider seam |
| `specs` | `IntegrationDescriptor`, action/service/intent/recipe specs |
| `services` | identity, jobs, LLM, messaging seams |
| `storage` | object-storage seam |
| `telegram` | Telegram client seam, and the shared settle text rule |
| `scheduling` | user-job scheduling seam |
| `feedback` | feedback-ticket seam |

Each seam is a `register_*_provider()` / `get_*()` pair, so the product calls a
capability without knowing what implements it. The exception is `settled_text`,
a pure rule with no host-specific behaviour, imported directly.

## Why it is published

A product repository has to be able to install this in isolation — in CI, and
on a contributor's machine — without credentials for the platform's own
repository. That is the whole reason it is a separate distribution rather than
a package inside the backend.

## Versioning

The contract is what other repositories pin, so a breaking change to a seam
signature is a major bump. Adding a seam, or a field with a default, is a minor
one.
