Metadata-Version: 2.4
Name: stapel-chat
Version: 0.2.0
Summary: Conversations, messaging and support chat for the Stapel framework
License: MIT
Project-URL: Homepage, https://github.com/usestapel/stapel-chat
Project-URL: Repository, https://github.com/usestapel/stapel-chat
Project-URL: Documentation, https://github.com/usestapel/stapel-chat#readme
Project-URL: Changelog, https://github.com/usestapel/stapel-chat/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/usestapel/stapel-chat/issues
Keywords: django,stapel,chat,messaging,support
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: stapel-core<1.0,>=0.27.0
Provides-Extra: channels
Requires-Dist: stapel-core[channels]<1.0,>=0.27.0; extra == "channels"
Provides-Extra: all
Requires-Dist: stapel-core[channels]<1.0,>=0.27.0; extra == "all"
Dynamic: license-file

<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->

# stapel-chat

[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-chat/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-chat/actions/workflows/ci.yml?query=branch%3Amain)
[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-chat?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-chat)
[![pypi](https://img.shields.io/pypi/v/stapel-chat?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-chat/)
[![downloads](https://static.pepy.tech/badge/stapel-chat/month)](https://pepy.tech/project/stapel-chat)
[![python](https://img.shields.io/pypi/pyversions/stapel-chat?logo=python&logoColor=white)](https://pypi.org/project/stapel-chat/)
[![license](https://img.shields.io/github/license/usestapel/stapel-chat)](https://github.com/usestapel/stapel-chat/blob/main/LICENSE)
[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-chat/blob/main/docs/llms.txt)

> Conversations and messaging: direct (1:1, idempotent by participant pair), group and support threads on one model; text/system messages with a monotonic per-conversation seq, replies and opaque CDN attachment keys; per-participant read markers and unread counts; anchor-paginated history (canonical anchor=seq) and conversation lists; a support layer (unassigned queue, first-come assignment, open/pending/resolved with reopen); and an optional Channels consumer for realtime delivery with seq-replay resume.

Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.

## Install

```bash
pip install stapel-chat
```

## At a glance

| Fact | Value |
|---|---|
| Version | `0.2.0` |
| Python | `>=3.11` (3.11, 3.12, 3.13, 3.14) |
| HTTP operations | 10 |
| Config axes | 3 |
| Usage surface | 11 |
| Extension points | 4 |
| Error codes | 54 |
| Fleet dependencies | [`stapel-auth`](https://github.com/usestapel/stapel-auth) (optional) · [`stapel-cdn`](https://github.com/usestapel/stapel-cdn) (optional) · [`stapel-core`](https://github.com/usestapel/stapel-core) |

## Documentation

[OpenAPI](https://github.com/usestapel/stapel-chat/blob/main/docs/schema.json) · [capabilities.json](https://github.com/usestapel/stapel-chat/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-chat/blob/main/docs/llms.txt)

One model backs three kinds of thread: **direct** (1:1, idempotent by
participant pair), **group**, and **support** (a customer↔operator thread with a
queue and assignment lifecycle). Messages carry a monotonic per-conversation
**seq** that is the canonical anchor for history pagination and the resume
cursor for realtime — so nothing depends on a socket staying up.

## Quick start

```python
INSTALLED_APPS = [
    # ...
    "stapel_core.django.apps.CommonDjangoConfig",
    "stapel_core.django.users",
    "rest_framework",
    "stapel_chat",
]

# urls.py
urlpatterns = [
    path("chat/", include("stapel_chat.urls")),
]
```

## What you get

- **Conversations** — `POST /chat/api/conversations` (`direct` / `group` /
  `support`); direct is get-or-create by participant pair. `GET` lists your
  conversations (anchor-paginated) with `unread_count`.
- **Messages** — `GET/POST /chat/api/conversations/{id}/messages`. History is
  anchored on `seq` (newest-first, both directions). Sending allocates the next
  `seq` and emits `chat.message` in one transaction.
- **Read markers** — `POST /chat/api/conversations/{id}/read` (`upto_seq`).
- **Support** — `GET /chat/api/support/queue`,
  `POST .../support/conversations/{id}/{assign,resolve,reopen}`.
- **Realtime (optional)** — `stapel_chat.consumers.ChatConsumer` over Channels:
  `hello{last_seq}` → replay by seq → live delivery. Install the extra:

  ```
  pip install 'stapel-chat[channels]'
  ```

  and wire it behind `stapel_core.django.jwt.channels.JWTAuthMiddlewareStack` in
  your `asgi.py`.

## Configuration (`STAPEL_CHAT`)

| Key | Default | Meaning |
|---|---|---|
| `CHAT_KINDS` | `["direct","group","support"]` | Enabled thread kinds (drop `support` to disable the operator queue) |
| `ATTACHMENTS` | `True` | Allow opaque attachment keys on messages |
| `MAX_BODY_LENGTH` | `4000` | Hard cap on a text body |
| `SCOPE_PROVIDER` | `stapel_chat.scope.DefaultScopeProvider` | Resolve/enforce the opaque `scope_key` (e.g. per workspace) |

See [MODULE.md](https://github.com/usestapel/stapel-chat/blob/main/MODULE.md)
for the extension seams, comm surface and anti-patterns.

## License

MIT — see [LICENSE](https://github.com/usestapel/stapel-chat/blob/main/LICENSE).

---

<sub>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`.</sub>
