cue-notify 0.1.0__tar.gz

cue_notify-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Docs build
+site/
+
+# Local configuration and data
+.env
+.env.*
+!.env.example
+/cue.toml
+*.db
+*.db-journal
+*.sqlite3
+secrets/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store

cue_notify-0.1.0/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[semantic versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- A throughput benchmark (`benchmarks/throughput.py`) and a performance guide.
+- Agent `reviewers`: Cue reports a `cue.approval_requested` event for each reviewer when
+  a message waits for approval, so your own rules and templates notify them.
+- Python (`cue-client`, httpx only) and TypeScript (`cue-client`, no dependencies) SDKs
+  with webhook signature verification, tested in CI and released by tag.
+
+### Fixed
+- Test coverage now measures `cue_notify` (it pointed at a package name from before
+  the rename).
+- The database pool now defaults to the worker's concurrency plus 4 connections. With
+  the old fixed default of 10, a busy worker opened and closed connections constantly;
+  end-to-end throughput roughly doubled with four workers.
+
+### Security
+- Agent keys can no longer review messages (also not another agent's), hold the
+  `admin` scope, change people's preferences or rotate preference tokens.
+- The hosted preference form is read with a size limit, and the unsubscribe
+  confirmation page only names categories that exist.
+- Agent keys cannot see preference tokens (redacted from recipients and message
+  content), delete recipients, send inline profiles, cancel or report engagement on
+  other senders' messages; events they report follow the agent's categories, budget and
+  approval.
+- A `send_at` in the past counts as now, so backdated sends cannot slip past frequency
+  caps or agent budgets.
+- Event and message `data` is limited to 16 KB.
+- The MCP server refuses ids that are not UUIDs instead of resolving them into other API
+  paths.
+- Line breaks in e-mail subjects are collapsed, and messages that cannot be built as
+  e-mail fail over instead of retrying.
+
+## [0.1.0] — 2026-10-10
+
+First public release of Cue, the attention layer between software, AI agents and people.
+
+### Added
+- Event ingestion with idempotency keys and inline recipient profiles.
+- Rules: JSON Logic conditions, wildcard event names, priorities, `stop_processing`,
+  delays, cooldowns and deterministic percentage rollouts, plus a dry-run endpoint.
+- Digests: a rule can group matching events per recipient and grouping key for a
+  window (or until `send_after` events) and send one message rendered from all of them.
+  Smart digests let the AI layer summarise the group from allow-listed fields, falling
+  back to the template. API: `/v1/digests`.
+- A `thread` content field for device-side grouping (APNs `thread-id`, FCM data, e-mail
+  `References`).
+- Preference centre: a per-recipient preference token, a hosted preference page, a
+  token-authenticated JSON API for your own UI (`/v1/preferences/{token}`), RFC 8058
+  one-click unsubscribe with `List-Unsubscribe` headers from the SMTP connector and
+  `links` in webhook payloads, template `links`, token rotation, and a consent ledger
+  (`/v1/recipients/{id}/preferences/history`). Configure with `api.public_url`.
+- Importance (`low`, `normal`, `high`, `critical`) mapped to iOS interruption levels,
+  Android priority, silent Telegram messages and e-mail headers; `critical` breaks
+  through quiet hours and caps only in categories people cannot leave.
+- Expiry: `expires_at` on sends and `expires_after_seconds` on rules; stale messages are
+  dropped and push TTLs shortened to match.
+- Template actions (buttons) for push, Telegram, e-mail and webhooks.
+- Agents: automated senders with a per-person attention budget (5 a day by default), an
+  importance ceiling, allowed categories and an approval policy. Held messages wait in
+  `pending_approval` until approved or rejected (`/v1/messages/{id}/approve`,
+  `/reject`, MCP `review_message`), with the reviewer recorded. API keys can be bound
+  to an agent (`--agent`).
+- Fatigue: a category can pause low and normal messages to people who ignored its
+  last N messages, probe again after the pause, and resume on any engagement.
+- Agent-first distribution: the MCP server is part of the core package
+  (`uvx cue-notify mcp`), an MCP registry manifest (`server.json`), a Claude Code
+  plugin with an integration skill, `llms.txt` and `AGENTS.md`.
+- `cuectl serve --migrate` applies migrations before starting.
+- Categories carrying delivery policy: rolling frequency caps, quiet hours and
+  unsubscribe rules. `transactional` and `marketing` are created by default.
+- Localised Jinja2 templates (sandboxed, strict) with per-channel overrides, versioning
+  and a preview endpoint.
+- Pluggable delivery: a signed webhook connector for your own sending service,
+  bundled connectors for Firebase Cloud Messaging, Twilio SMS, SMTP e-mail and Telegram,
+  a console connector, and third-party connectors via entry points.
+- Multi-address delivery, channel fallback, retry with backoff and automatic disabling
+  of dead addresses.
+- Broadcasts with resumable batches, pause/resume/cancel and audience filters.
+- Optional AI copy personalisation through Pydantic AI (any provider) with fact
+  guardrails, allow-listed context and a daily token budget.
+- Delivery and engagement tracking, including a token-based endpoint for client apps.
+- Scoped API keys, RFC 9457 problem responses, cursor pagination, Prometheus metrics.
+- Hardening: SSRF-safe per-recipient webhooks, resource-bounded template sandbox and
+  rule evaluator, race-free cancellation, job lease heartbeats, and failure states for
+  events, messages and broadcasts whose jobs exhaust their retries.
+- A transactional, database-backed job queue (no Redis required).
+- `cuectl` CLI: `serve`, `worker`, `db`, `keys`, `jobs`, `prune`, `check`, `mcp`.
+- A Model Context Protocol server so AI agents can send notifications and inspect
+  delivery with scoped API keys.
+
+[Unreleased]: https://github.com/murtazox04/Cue/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/murtazox04/Cue/releases/tag/v0.1.0

cue_notify-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Murtazo Xurramov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cue_notify-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.5
+Name: cue-notify
+Version: 0.1.0
+Summary: The attention layer between software, AI agents and people: decides whether, what, when and where to notify.
+Project-URL: Homepage, https://github.com/murtazox04/Cue
+Project-URL: Documentation, https://murtazox04.github.io/Cue
+Project-URL: Repository, https://github.com/murtazox04/Cue
+Project-URL: Issues, https://github.com/murtazox04/Cue/issues
+Project-URL: Changelog, https://github.com/murtazox04/Cue/blob/main/CHANGELOG.md
+Author: Murtazo Xurramov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,attention,email,event-driven,fastapi,fcm,llm,mcp,messaging,notification-engine,notifications,preference-center,push,rules-engine,sms,twilio
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.21
+Requires-Dist: alembic>=1.16
+Requires-Dist: fastapi>=0.120
+Requires-Dist: httpx>=0.28
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: mcp>=2.0
+Requires-Dist: pydantic-settings>=2.10
+Requires-Dist: pydantic>=2.11
+Requires-Dist: sqlalchemy[asyncio]>=2.0.40
+Requires-Dist: typer>=0.16
+Requires-Dist: uvicorn[standard]>=0.34
+Provides-Extra: ai
+Requires-Dist: pydantic-ai-slim[anthropic,google,groq,mistral,openai]>=2.0; extra == 'ai'
+Provides-Extra: all
+Requires-Dist: asyncpg>=0.30; extra == 'all'
+Requires-Dist: prometheus-client>=0.21; extra == 'all'
+Requires-Dist: pydantic-ai-slim[anthropic,google,groq,mistral,openai]>=2.0; extra == 'all'
+Requires-Dist: pyjwt[crypto]>=2.10; extra == 'all'
+Provides-Extra: fcm
+Requires-Dist: pyjwt[crypto]>=2.10; extra == 'fcm'
+Provides-Extra: mcp
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.21; extra == 'metrics'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.30; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Cue
+
+**The attention layer between software, AI agents and people.**
+
+Your product and your agents report what happened;<br/>
+Cue decides whether it is worth someone's attention, what to say, when, and over which
+route, then hands a ready-to-send message to the delivery you plug in.
+
+[![CI](https://github.com/murtazox04/Cue/actions/workflows/ci.yml/badge.svg)](https://github.com/murtazox04/Cue/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.12%20|%203.13%20|%203.14-blue)](https://github.com/murtazox04/Cue/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/murtazox04/Cue/blob/main/LICENSE)
+
+[Documentation](https://murtazox04.github.io/Cue) ·
+[Getting started](https://github.com/murtazox04/Cue/blob/main/docs/getting-started.md) ·
+[Architecture](https://github.com/murtazox04/Cue/blob/main/docs/architecture.md)
+
+</div>
+
+---
+
+People now hear from more software than ever: your product, background jobs, and a
+growing number of AI agents acting on someone's behalf. Each sender is reasonable alone;
+together they bury the person, and phones increasingly silence them. Cue is the one place
+that decides. Your backend (or an agent) reports what happened — `order.shipped`,
+`payment.failed`, `pr.review_requested` — and Cue decides whether a notification is
+warranted, which template and language to use, when to send it in the recipient's time
+zone, how important it really is, and which route to try first. It renders the message
+and hands it to whatever delivery you connect: your own service, a webhook, or a
+ready-made connector.
+
+**Delivery is pluggable. The decisions are Cue's job** — and every one of them is
+recorded, so "why didn't this user get the message?" becomes a query, not an
+investigation.
+
+```bash
+curl -X POST https://cue.example.com/v1/events \
+  -H "Authorization: Bearer $CUE_KEY" -H "Content-Type: application/json" \
+  -d '{"name": "order.shipped", "recipient": "customer-42",
+       "data": {"order_id": "1001"}, "idempotency_key": "order-1001-shipped"}'
+```
+
+Your delivery endpoint then receives a signed, fully rendered message:
+
+```json
+{
+  "id": "01a1…",
+  "channel": "push",
+  "address": "<device token>",
+  "locale": "en",
+  "importance": "normal",
+  "expires_at": null,
+  "content": {"title": "Your order is on its way", "body": "Order 1001 ships today.",
+              "url": "https://shop.example/orders/1001"},
+  "metadata": {"cue_message_id": "01a1…", "cue_tracking_token": "…"},
+  "links": {"preferences": "https://cue.example.com/preferences/…"}
+}
+```
+
+## What Cue decides
+
+- **Whether** — rules with JSON Logic conditions, priorities, wildcards, deterministic
+  rollouts and a dry-run endpoint; unsubscribes, frequency caps, cooldowns and
+  deduplication applied to every message; fatigue that backs off from people who stopped
+  paying attention.
+- **What** — localised, sandboxed Jinja2 templates with per-route variants (a short SMS,
+  a rich e-mail), versioning and previews; optional AI rewording through any
+  [Pydantic AI](https://ai.pydantic.dev) model, with guardrails that keep numbers and
+  links verbatim.
+- **How often** — digests that turn a burst of events into one message per window
+  ("Ann, Bo and 10 others commented"), optionally summarised by AI, plus thread ids so
+  phones and mail clients stack related messages.
+- **When** — delays, quiet hours in each recipient's time zone, scheduled broadcasts,
+  expiry for messages that go stale, and importance levels phones understand.
+- **Who decides** — the person: a hosted preference page (or a JSON API for your own),
+  RFC 8058 one-click unsubscribe for Gmail and Yahoo, and a consent ledger of every
+  change.
+- **Where** — an ordered list of routes per rule (e.g. push, then SMS), every address a
+  person has on a route, fallback on permanent failure, retries on transient failure,
+  dead addresses disabled automatically.
+
+## Built for AI agents
+
+- **Agents as first-class senders.** Each agent gets its own key with a per-person
+  attention budget, an importance ceiling and, where you want it, human approval before
+  anything goes out. See [agents](https://github.com/murtazox04/Cue/blob/main/docs/concepts/agents.md).
+- **MCP built in.** `uvx cue-notify mcp` gives Claude, Cursor or your own agent tools to
+  notify people and inspect delivery, with the same policy and audit trail.
+- **Claude Code plugin.** `/plugin marketplace add murtazox04/Cue`, then
+  `/plugin install cue@cue`, teaches Claude to integrate Cue into your app.
+- **SDKs.** `pip install cue-client` and `npm install cue-client`, both with webhook
+  signature verification. See [SDKs](https://github.com/murtazox04/Cue/blob/main/docs/guides/sdks.md).
+- **Docs for machines.** [`llms.txt`](https://murtazox04.github.io/Cue/llms.txt) and
+  [`AGENTS.md`](https://github.com/murtazox04/Cue/blob/main/AGENTS.md).
+
+## Bring your own delivery
+
+Each route (`push`, `sms`, `email`, `ops-alerts`…) is backed by a **connector**:
+
+| Connector | Use it when |
+|---|---|
+| `webhook` | You already have a sending service, or want full control. Cue POSTs signed JSON to it. |
+| `fcm`, `twilio`, `smtp`, `telegram` | You want a ready-made connector for these providers. |
+| `console` | Local development. |
+| your own | Write a small class and register it as a plugin — see [custom connectors](https://github.com/murtazox04/Cue/blob/main/docs/guides/custom-channels.md). |
+
+Connectors are configuration, not code changes — swap SMS vendors without touching a
+rule.
+
+## Also
+
+- **Engagement tracking** — delivered, opened, clicked, converted; client apps report
+  with a per-message token, no API key needed.
+- **Broadcasts** — audience filters, resumable batches, pause/resume/cancel without
+  double sends.
+- **AI agents** — an MCP server (`cuectl mcp`) lets Claude, Cursor or your own agents
+  notify people and inspect delivery within the scopes you grant.
+- **Simple to run** — one Python service and PostgreSQL (or SQLite). No Redis, no
+  broker, no cron: the durable job queue lives in your database.
+- **Observable** — per-rule event outcomes, status reasons, Prometheus metrics, JSON logs.
+
+## Quick start
+
+```bash
+git clone https://github.com/murtazox04/Cue && cd Cue
+docker compose up --build -d
+docker compose exec api cuectl keys create admin   # prints an API key
+open http://localhost:8000/docs
+```
+
+Or with Python 3.12+:
+
+```bash
+pip install 'cue-notify[postgres]'
+export CUE_WORKER__EMBEDDED=true CUE_CHANNELS__PUSH__PROVIDER=console
+cuectl db upgrade && cuectl keys create admin && cuectl serve
+```
+
+Then follow the [getting-started guide](https://github.com/murtazox04/Cue/blob/main/docs/getting-started.md).
+
+## How it works
+
+```mermaid
+flowchart LR
+    E[POST /v1/events] --> R{Rules}
+    R --> P[Policy<br/>unsubscribe · caps · cooldown · quiet hours]
+    P --> T[Template<br/>locale · route variants]
+    T --> Q[(Queue)]
+    Q --> A[AI rewording<br/>optional]
+    A --> C{Your delivery<br/>webhook · connectors}
+```
+
+| Concept | In one line |
+|---|---|
+| **Event** | Something that happened to a recipient. Idempotent, stored with per-rule outcomes. |
+| **Rule** | When event X (and condition) → send template Y over routes [A, B]. |
+| **Template** | Localised content with route-specific variants. |
+| **Category** | Policy bundle: frequency caps, quiet hours, whether unsubscribing is allowed. |
+| **Channel** | A named route (`push`, `sms`…) backed by a connector. |
+| **Message** | One notification to one recipient, with a full status trail. |
+| **Broadcast** | One template to an audience, in resumable batches. |
+
+## Configuration
+
+Environment variables (`CUE_SECTION__KEY`) or a `cue.toml`:
+
+```toml
+[database]
+url = "postgresql+asyncpg://cue:secret@db/cue"
+
+[channels.push]
+provider = "webhook"
+url = "https://notifications.internal.example/push"
+# secret from CUE_CHANNELS__PUSH__SECRET
+
+[channels.sms]
+provider = "twilio"
+account_sid = "AC…"
+from_number = "+15550100"   # auth token via CUE_CHANNELS__SMS__AUTH_TOKEN
+```
+
+See the [configuration reference](https://github.com/murtazox04/Cue/blob/main/docs/reference/configuration.md) and
+[`examples/cue.toml`](https://github.com/murtazox04/Cue/blob/main/examples/cue.toml).
+
+## Project status
+
+Cue is in early development (0.x): the model and API are stable in shape but may still
+change before 1.0. See the [roadmap](https://github.com/murtazox04/Cue/blob/main/ROADMAP.md) for what comes next. Feedback and
+contributions are very welcome — see [CONTRIBUTING.md](https://github.com/murtazox04/Cue/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/murtazox04/Cue/blob/main/LICENSE)
+
+<!-- mcp-name: io.github.murtazox04/cue -->

cue_notify-0.1.0/README.md

@@ -0,0 +1,196 @@
+<div align="center">
+
+# Cue
+
+**The attention layer between software, AI agents and people.**
+
+Your product and your agents report what happened;<br/>
+Cue decides whether it is worth someone's attention, what to say, when, and over which
+route, then hands a ready-to-send message to the delivery you plug in.
+
+[![CI](https://github.com/murtazox04/Cue/actions/workflows/ci.yml/badge.svg)](https://github.com/murtazox04/Cue/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.12%20|%203.13%20|%203.14-blue)](https://github.com/murtazox04/Cue/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/murtazox04/Cue/blob/main/LICENSE)
+
+[Documentation](https://murtazox04.github.io/Cue) ·
+[Getting started](https://github.com/murtazox04/Cue/blob/main/docs/getting-started.md) ·
+[Architecture](https://github.com/murtazox04/Cue/blob/main/docs/architecture.md)
+
+</div>
+
+---
+
+People now hear from more software than ever: your product, background jobs, and a
+growing number of AI agents acting on someone's behalf. Each sender is reasonable alone;
+together they bury the person, and phones increasingly silence them. Cue is the one place
+that decides. Your backend (or an agent) reports what happened — `order.shipped`,
+`payment.failed`, `pr.review_requested` — and Cue decides whether a notification is
+warranted, which template and language to use, when to send it in the recipient's time
+zone, how important it really is, and which route to try first. It renders the message
+and hands it to whatever delivery you connect: your own service, a webhook, or a
+ready-made connector.
+
+**Delivery is pluggable. The decisions are Cue's job** — and every one of them is
+recorded, so "why didn't this user get the message?" becomes a query, not an
+investigation.
+
+```bash
+curl -X POST https://cue.example.com/v1/events \
+  -H "Authorization: Bearer $CUE_KEY" -H "Content-Type: application/json" \
+  -d '{"name": "order.shipped", "recipient": "customer-42",
+       "data": {"order_id": "1001"}, "idempotency_key": "order-1001-shipped"}'
+```
+
+Your delivery endpoint then receives a signed, fully rendered message:
+
+```json
+{
+  "id": "01a1…",
+  "channel": "push",
+  "address": "<device token>",
+  "locale": "en",
+  "importance": "normal",
+  "expires_at": null,
+  "content": {"title": "Your order is on its way", "body": "Order 1001 ships today.",
+              "url": "https://shop.example/orders/1001"},
+  "metadata": {"cue_message_id": "01a1…", "cue_tracking_token": "…"},
+  "links": {"preferences": "https://cue.example.com/preferences/…"}
+}
+```
+
+## What Cue decides
+
+- **Whether** — rules with JSON Logic conditions, priorities, wildcards, deterministic
+  rollouts and a dry-run endpoint; unsubscribes, frequency caps, cooldowns and
+  deduplication applied to every message; fatigue that backs off from people who stopped
+  paying attention.
+- **What** — localised, sandboxed Jinja2 templates with per-route variants (a short SMS,
+  a rich e-mail), versioning and previews; optional AI rewording through any
+  [Pydantic AI](https://ai.pydantic.dev) model, with guardrails that keep numbers and
+  links verbatim.
+- **How often** — digests that turn a burst of events into one message per window
+  ("Ann, Bo and 10 others commented"), optionally summarised by AI, plus thread ids so
+  phones and mail clients stack related messages.
+- **When** — delays, quiet hours in each recipient's time zone, scheduled broadcasts,
+  expiry for messages that go stale, and importance levels phones understand.
+- **Who decides** — the person: a hosted preference page (or a JSON API for your own),
+  RFC 8058 one-click unsubscribe for Gmail and Yahoo, and a consent ledger of every
+  change.
+- **Where** — an ordered list of routes per rule (e.g. push, then SMS), every address a
+  person has on a route, fallback on permanent failure, retries on transient failure,
+  dead addresses disabled automatically.
+
+## Built for AI agents
+
+- **Agents as first-class senders.** Each agent gets its own key with a per-person
+  attention budget, an importance ceiling and, where you want it, human approval before
+  anything goes out. See [agents](https://github.com/murtazox04/Cue/blob/main/docs/concepts/agents.md).
+- **MCP built in.** `uvx cue-notify mcp` gives Claude, Cursor or your own agent tools to
+  notify people and inspect delivery, with the same policy and audit trail.
+- **Claude Code plugin.** `/plugin marketplace add murtazox04/Cue`, then
+  `/plugin install cue@cue`, teaches Claude to integrate Cue into your app.
+- **SDKs.** `pip install cue-client` and `npm install cue-client`, both with webhook
+  signature verification. See [SDKs](https://github.com/murtazox04/Cue/blob/main/docs/guides/sdks.md).
+- **Docs for machines.** [`llms.txt`](https://murtazox04.github.io/Cue/llms.txt) and
+  [`AGENTS.md`](https://github.com/murtazox04/Cue/blob/main/AGENTS.md).
+
+## Bring your own delivery
+
+Each route (`push`, `sms`, `email`, `ops-alerts`…) is backed by a **connector**:
+
+| Connector | Use it when |
+|---|---|
+| `webhook` | You already have a sending service, or want full control. Cue POSTs signed JSON to it. |
+| `fcm`, `twilio`, `smtp`, `telegram` | You want a ready-made connector for these providers. |
+| `console` | Local development. |
+| your own | Write a small class and register it as a plugin — see [custom connectors](https://github.com/murtazox04/Cue/blob/main/docs/guides/custom-channels.md). |
+
+Connectors are configuration, not code changes — swap SMS vendors without touching a
+rule.
+
+## Also
+
+- **Engagement tracking** — delivered, opened, clicked, converted; client apps report
+  with a per-message token, no API key needed.
+- **Broadcasts** — audience filters, resumable batches, pause/resume/cancel without
+  double sends.
+- **AI agents** — an MCP server (`cuectl mcp`) lets Claude, Cursor or your own agents
+  notify people and inspect delivery within the scopes you grant.
+- **Simple to run** — one Python service and PostgreSQL (or SQLite). No Redis, no
+  broker, no cron: the durable job queue lives in your database.
+- **Observable** — per-rule event outcomes, status reasons, Prometheus metrics, JSON logs.
+
+## Quick start
+
+```bash
+git clone https://github.com/murtazox04/Cue && cd Cue
+docker compose up --build -d
+docker compose exec api cuectl keys create admin   # prints an API key
+open http://localhost:8000/docs
+```
+
+Or with Python 3.12+:
+
+```bash
+pip install 'cue-notify[postgres]'
+export CUE_WORKER__EMBEDDED=true CUE_CHANNELS__PUSH__PROVIDER=console
+cuectl db upgrade && cuectl keys create admin && cuectl serve
+```
+
+Then follow the [getting-started guide](https://github.com/murtazox04/Cue/blob/main/docs/getting-started.md).
+
+## How it works
+
+```mermaid
+flowchart LR
+    E[POST /v1/events] --> R{Rules}
+    R --> P[Policy<br/>unsubscribe · caps · cooldown · quiet hours]
+    P --> T[Template<br/>locale · route variants]
+    T --> Q[(Queue)]
+    Q --> A[AI rewording<br/>optional]
+    A --> C{Your delivery<br/>webhook · connectors}
+```
+
+| Concept | In one line |
+|---|---|
+| **Event** | Something that happened to a recipient. Idempotent, stored with per-rule outcomes. |
+| **Rule** | When event X (and condition) → send template Y over routes [A, B]. |
+| **Template** | Localised content with route-specific variants. |
+| **Category** | Policy bundle: frequency caps, quiet hours, whether unsubscribing is allowed. |
+| **Channel** | A named route (`push`, `sms`…) backed by a connector. |
+| **Message** | One notification to one recipient, with a full status trail. |
+| **Broadcast** | One template to an audience, in resumable batches. |
+
+## Configuration
+
+Environment variables (`CUE_SECTION__KEY`) or a `cue.toml`:
+
+```toml
+[database]
+url = "postgresql+asyncpg://cue:secret@db/cue"
+
+[channels.push]
+provider = "webhook"
+url = "https://notifications.internal.example/push"
+# secret from CUE_CHANNELS__PUSH__SECRET
+
+[channels.sms]
+provider = "twilio"
+account_sid = "AC…"
+from_number = "+15550100"   # auth token via CUE_CHANNELS__SMS__AUTH_TOKEN
+```
+
+See the [configuration reference](https://github.com/murtazox04/Cue/blob/main/docs/reference/configuration.md) and
+[`examples/cue.toml`](https://github.com/murtazox04/Cue/blob/main/examples/cue.toml).
+
+## Project status
+
+Cue is in early development (0.x): the model and API are stable in shape but may still
+change before 1.0. See the [roadmap](https://github.com/murtazox04/Cue/blob/main/ROADMAP.md) for what comes next. Feedback and
+contributions are very welcome — see [CONTRIBUTING.md](https://github.com/murtazox04/Cue/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/murtazox04/Cue/blob/main/LICENSE)
+
+<!-- mcp-name: io.github.murtazox04/cue -->