chattice 0.1.0__tar.gz

chattice-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+.venv/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+build/
+dist/
+site/
+*.egg-info/
+.DS_Store
+
+.coverage*
+
+.secrets/
+token.json
+oauth-client.json
+service-account*.json
+
+# macOS synchronization duplicates.
+* [0-9]
+* [0-9].*
+.env

chattice-0.1.0/.python-version

@@ -0,0 +1,2 @@
+3.11
+

chattice-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes are documented here. The project follows Semantic
+Versioning. Before 1.0, incompatible changes may be released in a minor
+version and will include migration notes.
+
+## [0.1.0] — Initial public release
+
+### Added
+
+- Async dispatcher, routers, middleware, dependency injection, filters, and
+  typed Google Chat interaction events.
+- HTTP, Pub/Sub, streaming-pull, and Google Workspace Events integrations.
+- Async Google Chat API client with app and delegated-user authentication.
+- Typed Cards v2 builders, dialogs, forms, App Home responses, card updates,
+  attachments, and optional Card image publishing.
+- Finite-state storage, idempotency storage, Redis integrations, lifecycle
+  resources, and observability hooks.
+- FastAPI integration, testing helpers, runnable examples, API reference, and
+  deployment guidance.
+- Raw Google payload and client escape hatches for forward compatibility.
+- Automated dependency, Google Chat schema, Cards SDK, and release-note
+  monitoring.
+
+### Compatibility
+
+- Python 3.11, 3.12, and 3.13.
+- Google Chat API v1 and Cards v2.
+- The package distribution and Python import are both named `chattice`.

chattice-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,6 @@
+# Code of Conduct
+
+Be respectful, constructive, and honest. No harassment, discrimination,
+or hostile behavior. Maintainers may remove contributions or
+participation that violates this. If you experience or witness a
+problem, contact the maintainers privately.

chattice-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to Chattice
+
+Chattice is an async Python framework for Google Chat apps. Contributions
+that are naturally additive are the most welcome:
+
+- new Google UI support (widgets, cards)
+- Google API wrappers behind the raw escape hatch pattern
+- tests, examples, docs, bug fixes
+
+## Workflow
+
+1. Open an issue describing the problem or idea (no PR-first for
+   architectural changes — see the RFC rule below).
+2. Branch off `main`; implement with tests.
+3. Run the full gate suite:
+
+   ```bash
+   uv sync --all-groups
+   uv run pytest -q
+   uv run mypy src tests
+   uv run ruff check . && uv run ruff format --check .
+   uv run mkdocs build --strict
+   bash scripts/verify_package.sh
+   ```
+
+4. Open a PR. The description must state: the problem, public API
+   impact, compatibility impact, tests/docs added, risk level, and
+   whether core changed.
+
+## Rules
+
+- New examples must expose a `main()` executed from
+  `tests/test_examples.py` (docs can never drift).
+- Fixtures must be official payload shapes with provenance recorded in
+  `tests/fixtures/google_chat/interactions/README.md`.
+- Public API changes require the public-API rule (charter §7): typing,
+  tests, docs, deliberate export, compatibility review.
+- Architectural changes (Dispatcher/Router/FSM contracts, new workflow
+  engines, package splits, breaking API) require a lightweight design
+  proposal first: Problem · Current behavior · Proposed API · Why the
+  current API is insufficient · Alternatives · Compatibility ·
+  Migration · Maintenance cost · Simpler solutions rejected.
+
+## License
+
+MIT. By contributing you agree your contributions are licensed
+under it. No CLA required.
+
+## Upstream Google changes
+
+Google updates the wire layer (`google-apps-chat`, `google-apps-card`)
+and ships Developer Preview features continuously. The documented public
+surface changes deliberately, so every upstream change follows one protocol:
+
+1. An update PR arrives from dependabot (weekly, `google-sdks` group)
+   or from the weekly `upstream-check` workflow's `upstream` issue.
+2. CI runs the full suite, mypy/ruff, and the golden fixtures.
+3. Wire analysis of the SDK diff:
+   - a new event FIELD → keep it lossless (`raw`), add a round-trip
+     test; no public API change;
+   - a new event TYPE → decide: typed support (adapter + capability)
+     or explicit `UnknownEvent`; update the Google API mapping and the
+     capabilities matrix;
+   - a breaking change → P0 issue, a Chattice semver decision (rare).
+4. Update fixtures (reviewed), docs (mapping/capabilities), and the
+   compatibility revision.
+5. Pre-release: run every example (the `examples/docs/from_zero.py`
+   journey plus the bots/scenarios).
+
+Principles: Google updates are additive INSIDE the adapters; the public
+Chattice surface changes only by Chattice's own semver decision. The
+lossless paths (`UnknownEvent`, `RawWidget`, `Bot.raw_client`) absorb
+new Google types — a new type must never crash existing bots.

chattice-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chattice contributors
+
+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.

chattice-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.5
+Name: chattice
+Version: 0.1.0
+Summary: Async typed event framework for Google Chat apps
+Project-URL: Documentation, https://whiteysage.github.io/chattice/
+Project-URL: Source, https://github.com/WhiteySage/chattice
+Project-URL: Issues, https://github.com/WhiteySage/chattice/issues
+Project-URL: Changelog, https://github.com/WhiteySage/chattice/blob/main/CHANGELOG.md
+Author: WhiteySage
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: google-apps-chat<1.0.0,>=0.10.4
+Requires-Dist: google-auth<3,>=2.30
+Requires-Dist: pydantic<3.0,>=2.10
+Provides-Extra: fastapi
+Requires-Dist: fastapi<1,>=0.115; extra == 'fastapi'
+Provides-Extra: gcs
+Requires-Dist: google-cloud-storage<4,>=3; extra == 'gcs'
+Provides-Extra: gemini
+Requires-Dist: google-genai<3,>=1; extra == 'gemini'
+Provides-Extra: media
+Requires-Dist: google-api-python-client<3,>=2.198; extra == 'media'
+Provides-Extra: pubsub
+Requires-Dist: google-cloud-pubsub<3,>=2.21; extra == 'pubsub'
+Provides-Extra: redis
+Requires-Dist: redis<7,>=5; extra == 'redis'
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/WhiteySage/chattice/main/docs/assets/brand/chattice-logo.png"
+     alt="Chattice" width="320" />
+
+# Chattice
+
+Async, typed event framework for Google Chat apps — aiogram-quality DX, Google-native semantics.
+
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://pypi.org/project/chattice/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-pre--1.0-orange)](#status)
+[![Discussions](https://img.shields.io/badge/discussions-questions%20%26%20help-blue)](https://github.com/WhiteySage/chattice/discussions)
+
+```python
+from chattice import Dispatcher, F, Router
+from chattice.events import MessageEvent
+
+router = Router()
+
+
+@router.message(F.text == "ping")
+async def ping(message: MessageEvent) -> str:
+    return "pong"  # synchronous interaction response (no auth, 30 s deadline)
+
+
+dispatcher = Dispatcher()
+dispatcher.include_router(router)
+```
+
+## What this is
+
+- **Google Chat-native.** Space, Thread, Message, Command, Action, Card,
+  Dialog, App Home, Workspace Events are first-class typed objects. No
+  Telegram concepts leak into the domain model.
+- **aiogram ergonomics.** Routers, magic filters (`F`), middleware,
+  dependency injection, FSM — the DX you know, without Telegram
+  semantics.
+- **Explicit response model.** A handler RETURN is the synchronous
+  interaction response (30 s deadline); outbound `Bot` calls are
+  separate authenticated operations. Contextual `message.reply()` /
+  `thread.send()` / `space.send()` methods are zero-fetch adapters over
+  that same Bot, never a hidden second channel.
+- **Secure by default.** Incoming verification is fail-closed, push
+  endpoints require a verifier, outbound privacy gates (private
+  messages, notifications, preview features) fail closed before any
+  network call.
+- **Core is small.** Core abstracts Google Chat platform primitives and
+  technical boilerplate ONLY. Business scenarios (polls, approvals,
+  tickets) are assembled from the primitives in your
+  application code — never added to core.
+
+## What this is not
+
+- **Not a Telegram framework.** No `chat_id`, no `CallbackQuery`, no
+  `Update` hierarchy, no Telegram-style long polling (see the
+  [aiogram comparison](https://whiteysage.github.io/chattice/aiogram-comparison/)).
+- **Not a Google product.** Independent open-source project, not
+  endorsed by Google.
+
+## Two ways to run
+
+Chattice has two honest startup models (see the
+[aiogram side-by-side](docs/aiogram-comparison.md)):
+
+```python
+# HTTP — Google calls your HTTPS endpoint; the handler RETURN is the
+# synchronous response (Dialogs and App Home work here).
+app.include_router(create_chat_router(dispatcher, GoogleTokenVerifier(audience=...)))
+# python -m uvicorn app:app
+
+# Pub/Sub streaming pull — a persistent subscriber process, visually
+# like aiogram's start_polling, but it is NOT Telegram polling.
+# No domain/TLS needed; no Dialogs, no App Home — answers go outbound
+# through the authenticated Bot.
+await dispatcher.run_pubsub(subscription, bot=bot)
+# python app.py
+```
+
+## Capabilities
+
+| Area | Support |
+| --- | --- |
+| Events | MESSAGE, CARD_CLICKED, APP_COMMAND (slash/quick/message actions), ADDED/REMOVED_FROM_SPACE, APP_HOME, SUBMIT_FORM, WIDGET_UPDATED |
+| Routing | Routers, observer-wide filters, magic filters, middleware, DI |
+| Cards | Typed facades, public/non-sensitive PNG/JPEG publication through an optional AssetPublisher, sync updates |
+| Memberships | APP-auth add/get/list/remove for internal human users; caller-member Space listing |
+| Dialogs | OPEN_DIALOG, submit/cancel observers, action status; capability-gated per transport |
+| FSM | State/StatesGroup, Memory + Redis record storage (compare-and-set) |
+| Ingress | HTTP (verified), Pub/Sub push (verified), Pub/Sub streaming pull, Workspace Events CloudEvents |
+| Media | Local-file attachments sent with USER auth end to end (`media.upload` → `messages.create`, sender = HUMAN); download USER/APP; metadata APP; 200 MB local preflight |
+| Auth | App (service account), user (OAuth refresh), incoming verification |
+| Testing | MockBot, EventFactory, assertions, fake transport |
+
+## Install
+
+Python 3.11+ (3.11–3.13 tested). MIT-licensed.
+
+```bash
+pip install "chattice[fastapi,pubsub,redis]"  # core + all integrations
+
+# or pick only what you need:
+#   pip install chattice            core
+#   pip install "chattice[fastapi]" FastAPI integration
+#   pip install "chattice[redis]"   Redis FSM/idempotency storage
+#   pip install "chattice[pubsub]"  Pub/Sub push + streaming pull
+#   pip install "chattice[gcs]"     Local Card image publication through GCS
+
+# using uv
+uv add "chattice[fastapi,pubsub,redis]"
+```
+
+## Quickstart
+
+1. Parse a documented interaction payload:
+
+```python
+from chattice.adapters.google_chat import parse_interaction
+
+event = parse_interaction(payload)
+result = await dispatcher.feed_update(event)
+```
+
+2. Serve HTTP interactions (FastAPI):
+
+```python
+from fastapi import FastAPI
+from chattice.integrations.fastapi import create_chat_router
+from chattice.transports.http import GoogleTokenVerifier
+
+app = FastAPI()
+app.include_router(create_chat_router(dispatcher, GoogleTokenVerifier(audience="...")))
+```
+
+3. Send messages:
+
+```python
+from chattice.client import Bot
+
+bot = Bot(credentials=...)
+await bot.send_message("spaces/AAA", text="hello")
+```
+
+Inside an interaction handler, configure the same Bot once and use the known
+Google context without extra fetches:
+
+```python
+dispatcher = Dispatcher(bot=bot)
+
+
+@router.message()
+async def reply(message: MessageEvent) -> None:
+    await message.reply("hello in this thread")
+```
+
+## Docs
+
+Start with [Installation](https://whiteysage.github.io/chattice/getting-started/installation/), the
+[5-minute Quickstart](https://whiteysage.github.io/chattice/getting-started/quickstart/), and the
+[Space → Thread → Message mental model](https://whiteysage.github.io/chattice/concepts/mental-model/). The
+[public API reference](https://whiteysage.github.io/chattice/public-api/), [Google mapping](https://whiteysage.github.io/chattice/reference/google-api-mapping/),
+and [aiogram comparison](https://whiteysage.github.io/chattice/aiogram-comparison/) are linked from the docs site.
+Runnable examples live in [`examples/`](https://github.com/WhiteySage/chattice/tree/main/examples); machine-readable documentation is available in
+[`llms.txt`](https://whiteysage.github.io/chattice/llms.txt).
+
+## Status
+
+Pre-1.0 **public release** (current version 0.1.0) — see
+[CHANGELOG](CHANGELOG.md). The documented public
+surface is the compatibility baseline: pre-1.0 work may add APIs but does not incompatibly
+rename, remove, or change existing contracts. `chattice.experimental`
+has no compatibility promise. `Bot.raw_client` and raw event payloads
+follow Google's SDK and wire schema rather than the stable facade
+promise. **Not an official Google product** — independent open-source
+software, not endorsed by Google. MIT License, see [LICENSE](https://github.com/WhiteySage/chattice/blob/main/LICENSE).

chattice-0.1.0/PUBLIC_API.md

@@ -0,0 +1,28 @@
+# PUBLIC_API — machine-readable index
+
+This file is the compact machine-readable index. The full
+human reference: `docs/public-api.md`; rendered signatures:
+`docs/api.md`. Architecture test `tests/test_architecture.py::test_every_public_export_is_importable` pins every package's `__all__`; the canonical entry-point rule lives in `docs/public-api.md`.
+
+- chattice: Dispatcher · Router · F · __version__
+- chattice.actions: ActionData (`function=` discriminator binding) · ActionDataDecodeError · ActionDataFilter
+- chattice.assets: AssetPublisher
+- chattice.auth: AuthMode · CredentialsProvider · ServiceAccountCredentialsProvider · UserCredentialsProvider · CHAT_BOT_SCOPE · CHAT_APP_MEMBERSHIPS_SCOPE
+- chattice.capabilities: ResponseCapabilities · ResponseCapability · OutboundCapabilities · OutboundCapability · PreviewCapabilities · PreviewFeature · PREVIEW_APP_COMMAND_TYPES · CapabilityNotSupported
+- chattice.cards: Card · CardHeader · Section · Button (string or ActionData binding) · ButtonList · TextParagraph · Divider · Image (`from_url`/`from_path`/`from_bytes`) · TextInput · SelectionInput · DateTimePicker · Action · OpenLink · Dialog · ActionStatus · ActionStatusCode · Validation · TextInputType · AccessoryWidget · RawWidget
+- chattice.client: Bot (message/media/Card asset/membership/Space operations) · MessageReplyOption · ChatAPIError + wrapped error classes · wrap_api_error · CredentialsProvider (compat re-export)
+- chattice.dispatcher: Dispatcher (`bot=` contextual binding) · Router · EventObserver · Lifespan · LifespanResource
+- chattice.events: Event · MessageEvent (`reply`, lossless read metadata) · CommandEvent · CommandKind · ActionEvent · ActionSource · AddedToSpaceEvent · RemovedFromSpaceEvent · UnknownEvent · ErrorEvent · AppHomeEvent · FormSubmitEvent · WidgetUpdatedEvent · SpaceRef.send · ThreadRef.send · refs · form input values · DialogEventType · TimeZone
+- chattice.filters: F · MagicExpression · MagicField · Filter · BaseFilter · FilterLike · FilterValue
+- chattice.forms: FormModel · FormDecodeError · FormFilter
+- chattice.fsm: State · StatesGroup · FSMContext · FSMStrategy · StorageKey · BaseStorage · MemoryStorage · RedisStorage (lazy) · StateFilter · FSMError · FSMRecord · FSMRecordConflict · FSMRecordStorage · MemoryFSMRecordStorage · RedisFSMRecordStorage (lazy) · BaseStorageFromRecord
+- chattice.idempotency: IdempotencyStorage · MemoryIdempotencyStorage · RedisIdempotencyStorage · ClaimResult · new_owner
+- chattice.integrations.fastapi: create_chat_router · create_pubsub_router · create_workspace_events_router
+- chattice.integrations.gcs: GCSAssetPublisher
+- chattice.middleware: Middleware · BaseMiddleware · MiddlewareLike · NextHandler
+- chattice.observability: ObservabilityHooks
+- chattice.testing: MockBot · EventFactory · FakeChatTransport · assert_card_has_button · assert_card_header · set_state_for
+- chattice.transports.http: SYNC_RESPONSE_DEADLINE · HTTPInteractionAdapter · InteractionContext · IncomingRequest · IncomingRequestVerifier · GoogleTokenVerifier · MockVerifier · InteractionResponse · ResponseState · WidgetAutocomplete · RawInteractionResponse · VerificationError · DoubleResponseError
+- chattice.transports.pubsub: PubSubPushAdapter · PubSubEnvelopeError · decode_message_data · PubSubPushVerifier · GooglePubSubVerifier · MockPubSubVerifier
+- chattice.workspace_events: EventsDispatcher · EventsRouter · WorkspaceEvent · WorkspaceEventType · WorkspaceEventError · parse_workspace_event · parse_workspace_envelope
+- chattice.experimental: marker has no direct exports; chattice.experimental.ai is distributed but explicitly unstable and outside the stable API

chattice-0.1.0/README.md

@@ -0,0 +1,173 @@
+<img src="https://raw.githubusercontent.com/WhiteySage/chattice/main/docs/assets/brand/chattice-logo.png"
+     alt="Chattice" width="320" />
+
+# Chattice
+
+Async, typed event framework for Google Chat apps — aiogram-quality DX, Google-native semantics.
+
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://pypi.org/project/chattice/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-pre--1.0-orange)](#status)
+[![Discussions](https://img.shields.io/badge/discussions-questions%20%26%20help-blue)](https://github.com/WhiteySage/chattice/discussions)
+
+```python
+from chattice import Dispatcher, F, Router
+from chattice.events import MessageEvent
+
+router = Router()
+
+
+@router.message(F.text == "ping")
+async def ping(message: MessageEvent) -> str:
+    return "pong"  # synchronous interaction response (no auth, 30 s deadline)
+
+
+dispatcher = Dispatcher()
+dispatcher.include_router(router)
+```
+
+## What this is
+
+- **Google Chat-native.** Space, Thread, Message, Command, Action, Card,
+  Dialog, App Home, Workspace Events are first-class typed objects. No
+  Telegram concepts leak into the domain model.
+- **aiogram ergonomics.** Routers, magic filters (`F`), middleware,
+  dependency injection, FSM — the DX you know, without Telegram
+  semantics.
+- **Explicit response model.** A handler RETURN is the synchronous
+  interaction response (30 s deadline); outbound `Bot` calls are
+  separate authenticated operations. Contextual `message.reply()` /
+  `thread.send()` / `space.send()` methods are zero-fetch adapters over
+  that same Bot, never a hidden second channel.
+- **Secure by default.** Incoming verification is fail-closed, push
+  endpoints require a verifier, outbound privacy gates (private
+  messages, notifications, preview features) fail closed before any
+  network call.
+- **Core is small.** Core abstracts Google Chat platform primitives and
+  technical boilerplate ONLY. Business scenarios (polls, approvals,
+  tickets) are assembled from the primitives in your
+  application code — never added to core.
+
+## What this is not
+
+- **Not a Telegram framework.** No `chat_id`, no `CallbackQuery`, no
+  `Update` hierarchy, no Telegram-style long polling (see the
+  [aiogram comparison](https://whiteysage.github.io/chattice/aiogram-comparison/)).
+- **Not a Google product.** Independent open-source project, not
+  endorsed by Google.
+
+## Two ways to run
+
+Chattice has two honest startup models (see the
+[aiogram side-by-side](docs/aiogram-comparison.md)):
+
+```python
+# HTTP — Google calls your HTTPS endpoint; the handler RETURN is the
+# synchronous response (Dialogs and App Home work here).
+app.include_router(create_chat_router(dispatcher, GoogleTokenVerifier(audience=...)))
+# python -m uvicorn app:app
+
+# Pub/Sub streaming pull — a persistent subscriber process, visually
+# like aiogram's start_polling, but it is NOT Telegram polling.
+# No domain/TLS needed; no Dialogs, no App Home — answers go outbound
+# through the authenticated Bot.
+await dispatcher.run_pubsub(subscription, bot=bot)
+# python app.py
+```
+
+## Capabilities
+
+| Area | Support |
+| --- | --- |
+| Events | MESSAGE, CARD_CLICKED, APP_COMMAND (slash/quick/message actions), ADDED/REMOVED_FROM_SPACE, APP_HOME, SUBMIT_FORM, WIDGET_UPDATED |
+| Routing | Routers, observer-wide filters, magic filters, middleware, DI |
+| Cards | Typed facades, public/non-sensitive PNG/JPEG publication through an optional AssetPublisher, sync updates |
+| Memberships | APP-auth add/get/list/remove for internal human users; caller-member Space listing |
+| Dialogs | OPEN_DIALOG, submit/cancel observers, action status; capability-gated per transport |
+| FSM | State/StatesGroup, Memory + Redis record storage (compare-and-set) |
+| Ingress | HTTP (verified), Pub/Sub push (verified), Pub/Sub streaming pull, Workspace Events CloudEvents |
+| Media | Local-file attachments sent with USER auth end to end (`media.upload` → `messages.create`, sender = HUMAN); download USER/APP; metadata APP; 200 MB local preflight |
+| Auth | App (service account), user (OAuth refresh), incoming verification |
+| Testing | MockBot, EventFactory, assertions, fake transport |
+
+## Install
+
+Python 3.11+ (3.11–3.13 tested). MIT-licensed.
+
+```bash
+pip install "chattice[fastapi,pubsub,redis]"  # core + all integrations
+
+# or pick only what you need:
+#   pip install chattice            core
+#   pip install "chattice[fastapi]" FastAPI integration
+#   pip install "chattice[redis]"   Redis FSM/idempotency storage
+#   pip install "chattice[pubsub]"  Pub/Sub push + streaming pull
+#   pip install "chattice[gcs]"     Local Card image publication through GCS
+
+# using uv
+uv add "chattice[fastapi,pubsub,redis]"
+```
+
+## Quickstart
+
+1. Parse a documented interaction payload:
+
+```python
+from chattice.adapters.google_chat import parse_interaction
+
+event = parse_interaction(payload)
+result = await dispatcher.feed_update(event)
+```
+
+2. Serve HTTP interactions (FastAPI):
+
+```python
+from fastapi import FastAPI
+from chattice.integrations.fastapi import create_chat_router
+from chattice.transports.http import GoogleTokenVerifier
+
+app = FastAPI()
+app.include_router(create_chat_router(dispatcher, GoogleTokenVerifier(audience="...")))
+```
+
+3. Send messages:
+
+```python
+from chattice.client import Bot
+
+bot = Bot(credentials=...)
+await bot.send_message("spaces/AAA", text="hello")
+```
+
+Inside an interaction handler, configure the same Bot once and use the known
+Google context without extra fetches:
+
+```python
+dispatcher = Dispatcher(bot=bot)
+
+
+@router.message()
+async def reply(message: MessageEvent) -> None:
+    await message.reply("hello in this thread")
+```
+
+## Docs
+
+Start with [Installation](https://whiteysage.github.io/chattice/getting-started/installation/), the
+[5-minute Quickstart](https://whiteysage.github.io/chattice/getting-started/quickstart/), and the
+[Space → Thread → Message mental model](https://whiteysage.github.io/chattice/concepts/mental-model/). The
+[public API reference](https://whiteysage.github.io/chattice/public-api/), [Google mapping](https://whiteysage.github.io/chattice/reference/google-api-mapping/),
+and [aiogram comparison](https://whiteysage.github.io/chattice/aiogram-comparison/) are linked from the docs site.
+Runnable examples live in [`examples/`](https://github.com/WhiteySage/chattice/tree/main/examples); machine-readable documentation is available in
+[`llms.txt`](https://whiteysage.github.io/chattice/llms.txt).
+
+## Status
+
+Pre-1.0 **public release** (current version 0.1.0) — see
+[CHANGELOG](CHANGELOG.md). The documented public
+surface is the compatibility baseline: pre-1.0 work may add APIs but does not incompatibly
+rename, remove, or change existing contracts. `chattice.experimental`
+has no compatibility promise. `Bot.raw_client` and raw event payloads
+follow Google's SDK and wire schema rather than the stable facade
+promise. **Not an official Google product** — independent open-source
+software, not endorsed by Google. MIT License, see [LICENSE](https://github.com/WhiteySage/chattice/blob/main/LICENSE).

chattice-0.1.0/SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+## Reporting
+
+Report suspected security vulnerabilities through **GitHub private
+vulnerability reporting** (Security Advisories) on the public
+repository — enable the feature before the first public release.
+Until the repository is public, contact the project owner directly.
+Do not open a public issue for vulnerabilities.
+
+## Supported versions
+
+For pre-1.0 releases, only the latest release receives security fixes.
+The policy will be expanded before 1.0.
+
+## Security model
+
+Chattice ships transport verification and capability guards:
+
+- Incoming HTTP interactions: `GoogleTokenVerifier` (Google-issued
+  bearer tokens, audience + issuer checks) → 401 on failure.
+- Pub/Sub push: `GooglePubSubVerifier` (signature, audience, REQUIRED
+  service-account email, email_verified) — secure by default; an
+  explicit `allow_unverified=True` opt-in exists for local use only.
+- Push dedupe is an owner-safe state machine; handlers must stay
+  idempotent (push has no exactly-once guarantee).
+- Secrets are never logged: the redaction source-scan test pins this.
+
+If you find a bypass, please report it per the section above.

chattice-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,64 @@
+# Third-party notices
+
+Chattice is licensed under the MIT License. This file lists the direct
+third-party dependencies of the project and their licenses, based on the
+locked dependency inventory. It is an engineering compliance record, not legal
+advice. Versions are the locked versions in `uv.lock`.
+
+All declared direct dependencies carry permissive licenses compatible
+with the MIT License (Apache-2.0, MIT, BSD-2/3-Clause, ISC). No
+GPL/AGPL/SSPL dependency is declared.
+
+## Runtime dependencies
+
+| Package | Version | License |
+| --- | --- | --- |
+| [google-apps-chat](https://github.com/googleapis/google-cloud-python/tree/main/packages/google-apps-chat) | 0.10.4 | Apache-2.0 |
+| [google-auth](https://github.com/googleapis/google-auth-library-python) | 2.56.3 | Apache-2.0 |
+| [pydantic](https://github.com/pydantic/pydantic) | 2.13.4 | MIT |
+
+## Optional extras
+
+| Package | Version | License | Extra |
+| --- | --- | --- | --- |
+| [fastapi](https://github.com/fastapi/fastapi) | 0.141.1 | MIT | `fastapi` |
+| [redis](https://github.com/redis/redis-py) | 6.4.0 | MIT | `redis` |
+| [google-genai](https://github.com/googleapis/python-genai) | 2.18.1 | Apache-2.0 | `gemini` |
+| [google-cloud-pubsub](https://github.com/googleapis/python-pubsub) | 2.39.1 | Apache-2.0 | `pubsub` |
+
+## Development, documentation and build dependencies
+
+| Package | Version | License |
+| --- | --- | --- |
+| [cryptography](https://github.com/pyca/cryptography) | 45.0.7 | Apache-2.0 OR BSD-3-Clause |
+| [fakeredis](https://github.com/cunla/fakeredis-py) | 2.37.0 | BSD-3-Clause |
+| [httpx](https://github.com/encode/httpx) | 0.28.1 | BSD-3-Clause |
+| [mkdocs](https://github.com/mkdocs/mkdocs) | 1.6.1 | BSD-2-Clause |
+| [mkdocs-material](https://github.com/squidfunk/mkdocs-material) | 9.7.7 | MIT |
+| [mkdocstrings[python]](https://github.com/mkdocstrings/mkdocstrings) | 1.0.6 | ISC |
+| [mypy](https://github.com/python/mypy) | 1.20.2 | MIT (with identified PSF-licensed portions) |
+| [pyjwt](https://github.com/jpadilla/pyjwt) | 2.13.0 | MIT |
+| [pytest](https://github.com/pytest-dev/pytest) | 8.4.2 | MIT |
+| [pytest-asyncio](https://github.com/pytest-dev/pytest-asyncio) | 1.4.0 | Apache-2.0 |
+| [pytest-cov](https://github.com/pytest-dev/pytest-cov) | 7.1.0 | MIT |
+| [ruff](https://github.com/astral-sh/ruff) | 0.16.3 | MIT |
+| [uvicorn](https://github.com/encode/uvicorn) | 0.52.3 | BSD-3-Clause |
+| [hatchling](https://github.com/pypa/hatch) | >=1.27 (build backend) | MIT |
+
+## What is and is not distributed
+
+The wheel packages `src/chattice` and project licensing/typing
+metadata; it does NOT embed dependency source trees. Declaring
+dependencies in wheel metadata causes installers to fetch their
+independently licensed distributions; it does not relicense or copy
+them into Chattice.
+
+An exact-artifact SBOM for the locked dependency set is generated from
+`uv.lock` with `scripts/gen_sbom.py` (SPDX 2.3 JSON, written to
+`docs/release/`). Run it after every lock change and commit the result.
+
+## Chattice license
+
+MIT License — see [LICENSE](LICENSE). This project is independent
+open-source software: not official Google software and not endorsed by
+Google.