lightweb-adapter-sdk 0.2.2

Published Python SDK for the Lightweb adapter contract

Lightweb adapter SDK

The published Python SDK for the Lightweb adapter contract.

Status: pre-1.0, under active development. The SDK is not yet released to PyPI. The first 0.1.0 release will follow once initial implementation rounds are complete. See CHANGELOG.md for release history.

What this is

Lightweb is a community-owned, deployable platform template for hosting self-hosted alternatives to common web services — files, chat, code, meetings. The platform separates what a member is entitled to (the entitlements service, source of truth) from how those entitlements are provisioned into specific apps (one adapter per app: NextCloud, Matrix, Gitea, Jitsi, and others).

This SDK publishes the contract those adapters implement. It's six methods, a handful of shared types, an event envelope, and a conformance suite that every adapter is expected to pass.

If you want to build an adapter for a new app, this is the library you depend on. If you want to understand how the platform's adapter layer works without writing one, docs/contract.md is the canonical specification.

The contract, briefly

Every adapter implements six methods:

• capabilities() — declares which feature keys this adapter handles and what enforcement it offers.
• apply(member, entitlements) — idempotent; makes the target app's state match the desired entitlements.
• disable(member) — soft-disable; blocks access while preserving data.
• reconcile(member, entitlements) — read-only; returns a drift report comparing app state to desired state.
• health() — the adapter and its target app are reachable.
• list_accounts(cursor) — optional; pages through every account in the app for whole-system reconciliation.

There is no delete. Deletion is destructive, asymmetric, and out of the contract by design; it's handled separately as a gated, human-approved workflow in the platform's reconciler.

The full specification is in docs/contract.md.

Quick start

Install:

pip install lightweb-adapter-sdk

A minimal adapter:

from lightweb_adapter_sdk.adapter import Adapter
from lightweb_adapter_sdk.types import (
    Member, Entitlement, AppAccount, DriftReport,
    Capabilities, HealthStatus, AccountListPage,
)


class MyAdapter:
    """Adapter for MyApp."""

    def capabilities(self) -> Capabilities:
        ...

    def apply(self, member: Member, entitlements: list[Entitlement]) -> AppAccount:
        ...

    def disable(self, member: Member) -> None:
        ...

    def reconcile(self, member: Member) -> DriftReport:
        ...

    def health(self) -> HealthStatus:
        ...

    def list_accounts(self, cursor: str | None = None) -> AccountListPage:
        ...


# Verify the adapter satisfies the contract structurally:
adapter: Adapter = MyAdapter()

The Adapter is a typing.Protocol; your class doesn't have to inherit from it. If it has the right method signatures, it satisfies the contract.

The conformance suite verifies your adapter meets the contract's behavioral requirements (not just its structural ones). See docs/conformance.md for how to run it against your adapter.

Documentation

• docs/contract.md — the canonical contract specification. The authority on what an adapter must do.
• docs/conformance.md — how to wire the conformance suite into your adapter's CI.
• docs/event-consumer.md — JetStream event consumer conventions.
• docs/testkit.md — the testkit for adapter authors.
• ARCHITECTURE.md — repository orientation; what's where and why.

For the broader architectural context — why the adapter contract exists in this shape — see the Lightweb HLD in the platform monorepo at lightweb/platform's docs/hld.md, especially §4.

Status

The SDK is pre-1.0. The current implementation is structured as a sequence of rounds, with Round 5 targeting the first 0.1.0 release. 1.0 follows once the contract has been validated by at least one production adapter.

Relationship to the Lightweb platform

The platform monorepo (lightweb/platform) is AGPLv3 and contains the bespoke spine services and first-party adapters that ship with Lightweb. The platform's first-party adapters consume this SDK the same way third-party adapters do — as a pinned PyPI dependency, not as a source-level inclusion.

This SDK is Apache 2.0. The license boundary is structural: the SDK is the contract third parties implement against, and a permissive license is appropriate for a contract definition.

The SDK has no code-level dependency on the platform monorepo. It does mirror some platform-side artifacts (event envelope schemas, the entitlements service's API shape), but those are vendored as generated bindings, not pulled dynamically.

License

Apache License 2.0. See LICENSE for the full text.

Code of conduct

Project participants are expected to follow the Contributor Covenant.