stapel-docs

Google-Drive-style workspace documents: a folder tree, one-entity-per-type documents over an open type registry, content-addressed snapshot storage with an update journal and revision history, optimistic-lock editing (v1), trash with irreversible purge, a swappable object-storage seam, comm ingest (docs.create_document) and registry-driven export (PDF built in).

Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-docs

At a glance

Documentation

OpenAPI · capabilities.json · llms.txt (for agents)

What this is

Google-Drive-style workspace documents: a folder tree, documents that are each ONE entity with a type from an open registry (txt / md / csv / opaque file built in), a journal + revision versioning substrate, trash with irreversible purge, and registry-driven export (PDF built in).

The versioning substrate is decided for both collaboration disciplines: snapshot types save whole states under optimistic lock (If-Match carries the client's head_seq — v1's editing model), crdt types accumulate an append-only update journal between snapshots with chat-pattern replay/resync. Which discipline applies is a property of the type, not the request.

Object storage is content-addressed and goes through a swappable seam (STORAGE); the library is body-blind — the storage substrate never parses a document body, only a type's own text_extractor may.

Quick start

The base install rides Django's default_storage; add extras for the boto3 S3/MinIO backend and the PDF exporter:

pip install "stapel-docs[s3,pdf]"

INSTALLED_APPS = [
    # ...
    "stapel_docs",
]

# urls.py
path("docs/", include("stapel_docs.urls"))   # -> /docs/api/v1/...

Authorization asks the workspaces.check_capability comm Function (fail-closed, deny-by-default) — install stapel-workspaces or provide that Function for any HTTP request to be allowed.

An open type registry, not an enum

STAPEL_DOCS = {
    # Add or replace document types ({slug: dotted-path | None removes}):
    "DOC_TYPES": {"sheet": "myproject.docs.SHEET_SPEC"},
    # Add export formats over the built-in pdf:
    "EXPORTERS": {"docx": "myproject.docs.DocxExporter"},
    # Event-driven ingest without writing a subscriber:
    "INGEST": {"meeting.summarized": "myproject.docs.map_summary"},
    # Swap the object store:
    "STORAGE": "stapel_docs.storage.S3Backend",
}

A type whose spec vanishes from the registry degrades to file behavior — read-only, never unreadable: revisions still list, snapshots still download, trash/purge/export still work.

Ingest

Product glue dumps content in with one comm call — no HTTP, no import:

call("docs.create_document", {
    "workspace_id": ws_id, "type": "md", "title": "Weekly sync",
    "body": summary_text, "folder_path": "/Meetings/2026-08",
})

folder_path materializes folders idempotently; an unknown type refuses loudly so content never silently lands under a mistyped slug.

Sharing (v1: closed by default)

The sharing axis (SHARING: whitelist / link modes) ships its config surface with closed defaults — v1 implements exactly the immutable workspace baseline, and opening any sharing knob before the mechanism exists is a loud system-check error (stapel_docs.E010-E013), never a silent no-op.

Settings

All configuration lives in the STAPEL_DOCS namespace (dict setting, flat setting, or env var — resolved lazily). Full table in CONFIG.MD; seam semantics in MODULE.md. Highlights: STORAGE, DOC_TYPES, EXPORTERS, INGEST, REPLAY_WINDOW, AUTO_REVISION_INTERVAL_SECONDS, TRASH_RETENTION_DAYS, SHARING.

comm surface

Operations

python manage.py docs_purge_expired   # purge trash older than TRASH_RETENTION_DAYS

Development

pip install -e . && pip install pytest pytest-django ruff jsonschema djangorestframework
./setup-hooks.sh
pytest tests/

License

MIT — see LICENSE.

_{This page is assembled by stapel-readme from docs/readme.md plus the contract artifacts in docs/. Edit the prose in docs/readme.md; the badges, facts and links above and below it are generated — do not hand-edit README.md.}