chattice 0.14.0b1__tar.gz

chattice-0.14.0b1/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+build/
+dist/
+site/
+*.egg-info/
+.DS_Store
+
+.coverage*
+
+# Local development credentials (dogfood service-account keys)
+.secrets/

chattice-0.14.0b1/.python-version

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

chattice-0.14.0b1/AGENTS.md

@@ -0,0 +1,122 @@
+# Repository instructions
+
+## Source of truth
+
+- The current stable official Google Chat API documentation, v1 schema, and
+  official `google-apps-chat` client are the source of truth for Google
+  behavior. Samples clarify documented behavior but do not override the API.
+- Never invent an event type, field, method, scope, capability, deadline, or
+  authentication mode. Link an official source in research or architecture
+  documentation before implementing it.
+- Keep stable behavior separate from Preview or Developer Preview behavior.
+  Experimental support must live behind an explicitly experimental namespace
+  or capability.
+- aiogram and the archived Google Node toolkit are architecture references,
+  not Google Chat specifications. Do not copy their source into this project.
+
+## Architecture rules
+
+- Maintain the boundary: transport -> parser/adapter -> domain event ->
+  dispatcher/router -> handler -> interaction context or Bot API client.
+- Raw transport envelopes and framework domain events are different types.
+  Preserve raw Google data through `.raw`, but do not require handlers to parse
+  raw dictionaries.
+- Core routing must not depend on FastAPI, Starlette, Google credentials,
+  networking, Cards, or FSM. Web integrations adapt ASGI requests to the core.
+- Transport code must not contain business routing. Routers must not know about
+  FastAPI. FSM must not depend on the Google SDK. Cards must not depend on the
+  dispatcher.
+- Synchronous interaction responses and authenticated Chat API calls are
+  distinct operations. Never hide a second network call behind an already-used
+  interaction response.
+- Use a capabilities value object for transport/auth feature differences; do
+  not scatter string comparisons such as `transport == "pubsub"`.
+- Keep mutable state instance-scoped. Async handlers and concurrent event feeds
+  must not rely on module-global mutable state.
+
+## Module map
+
+- `src/chattice/events/`: framework-owned event models.
+- `src/chattice/dispatcher/`: dispatcher, routers, observers, handler plans,
+  middleware execution, and context DI.
+- `src/chattice/adapters/google_chat/`: stable Google payload parsing and mapping.
+- `src/chattice/transports/`: transport-neutral ingress contracts and concrete
+  HTTP/Pub/Sub adapters.
+- `src/chattice/integrations/`: optional web-framework integrations.
+- `src/chattice/client/`: high-level async Chat API client and raw client
+  escape hatch.
+- `src/chattice/auth/`: incoming verification and outgoing credential
+  provider contracts.
+- `src/chattice/cards/`, `fsm/`, `capabilities/`, and `testing/`: isolated
+  subsystems described in the architecture docs.
+- `docs/research/`: dated, sourced facts and unknowns. `docs/architecture/`:
+  intended boundaries. `docs/adr/`: decisions and their status.
+- `tests/fixtures/google_chat/`: only documented official payload shapes or sanitized
+  real payloads with provenance recorded beside the fixture.
+
+Directories may be introduced only when their phase starts; this map is a
+boundary contract, not a demand for empty modules.
+
+## Naming and public API
+
+- Use Google-native terms: `space`, `thread`, `message`, `interaction`,
+  `action`, and `membership`. Do not use Telegram `chat_id` terminology.
+- Public classes use `PascalCase`; functions, parameters, and modules use
+  `snake_case`; constants use `UPPER_SNAKE_CASE`.
+- Internal modules or symbols begin with `_` when importability could otherwise
+  imply support. Export public surfaces deliberately with `__all__`.
+- Keep the working distribution/import name isolated to packaging and the top
+  package so a later rename does not change domain terminology.
+
+## Compatibility and dependencies
+
+- Python 3.11+; CI covers 3.11, 3.12, and 3.13 unless an official dependency
+  incompatibility is documented.
+- Follow Semantic Versioning. Breaking public API changes are allowed before
+  1.0 but must be documented in `CHANGELOG.md`.
+- Core dependencies stay minimal. FastAPI, Redis, Pub/Sub, docs, and testing
+  integrations remain optional development groups or extras.
+- Do not add aiogram as a runtime dependency.
+
+## Workflow and commands
+
+Read the current ExecPlan before a substantial phase and update its Progress,
+Decisions, and Validation sections while working.
+
+```bash
+uv sync
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest --cov=chattice --cov-report=term-missing
+uv run mypy src tests
+uv run python -m compileall -q src tests examples
+uv build
+uv run mkdocs build --strict
+```
+
+## Tests and documentation
+
+- Every bug fix includes a regression test.
+- Every public API change updates the API documentation and an executable or
+  type-checked example.
+- Parser fixtures must cite their official or sanitized-real provenance. Never
+  fabricate Google wire fields for a test.
+- Unit and integration tests must run without Google credentials. Live tests
+  live under `tests/integration/live/` and use the `google_live` marker.
+- Preserve exception chaining and never log tokens, credentials,
+  `Authorization` headers, or private form values by default.
+
+## Definition of done
+
+A change is done when its documented behavior matches stable official Google
+sources, boundaries remain intact, tests cover happy and relevant negative
+paths, public docs and changelog are current, Ruff/format/pytest/mypy pass, the
+package builds, and the active ExecPlan records validation and remaining risks.
+
+
+## Rule provenance
+
+WHAT is written here. WHY lives in `.agent/rationale/` (one file per
+non-obvious constraint); failure records live in `.agent/incidents/`.
+Prefer machine enforcement (tests/lint) over new permanent rules —
+if a test can catch it, write the test instead.

chattice-0.14.0b1/CHANGELOG.md

@@ -0,0 +1,210 @@
+# Changelog
+
+All notable changes will be documented here. The project follows Semantic
+Versioning after the first public release; pre-1.0 APIs may change.
+
+## [0.14.0b1] — 2026-08-16 — first public beta release
+
+(0.14.0 was the internal release candidate; the public beta ships as
+0.14.0b1 per ADR-011.)
+
+## [0.14.0] — 2026-08-15 — first public beta candidate
+
+### Added
+
+- Core-boundary remediation: independent Workspace Events runtime, typed
+  command kinds and action sources, explicit preview enrollment, transport-
+  uniform response-capability DI, and lossless unknown Cards JSON fallback.
+- The optional AI integration moved from `chattice.ai` to
+  `chattice.experimental.ai`; it remains in the distribution but is explicitly
+  outside the stable core API.
+- Additive DX enrichment: zero-fetch contextual sends, direct ActionData
+  button binding, and immutable read-side message metadata accessors. The
+  imperative `Bot.send_message()` API remains fully supported and unchanged.
+- Scope-aware outbound local preflight: known user/app credential scopes now
+  filter message capabilities through documented any-of rules without hidden
+  network calls; unknown scopes preserve backward-compatible behavior.
+- Project rename to **Chattice** (ADR-010) and the versioning policy
+  (ADR-011): this is the FIRST PUBLIC BETA CANDIDATE.
+- Owner-safe push idempotency state machine (claim/complete/release,
+  429 on active, atomic expired-lease takeover, bounded completed
+  retention).
+- Race-safe FSM lazy expiry (compare-and-delete) and the full FSM
+  record/CAS storage model.
+- Class-only framework error logging — handler exception messages
+  (potentially secret-bearing) never reach logs; runtime redaction
+  regression test.
+- Human documentation product (troubleshooting, enterprise and
+  deployment guides, mkdocstrings API reference, aiogram side-by-side,
+  mental models), coding-agent documentation (docs/agents, PUBLIC_API),
+  OSS repository hardening (CONTRIBUTING/SECURITY/CoC/templates/
+  policies), license & provenance audit, curated sdist policy.
+
+### Status
+
+**Pre-1.0 beta / release candidate.** The documented stable beta surface is
+frozen against incompatible change; additions remain possible. Experimental
+and raw/advanced surfaces carry their separate contracts. Not published to
+PyPI.
+
+## [0.13.0] — 2026-08-15 — development release
+
+### Added
+
+- Phase 14 gap closure: Workspace Events official Pub/Sub binding,
+  slash commands / link previews / sender-aware card responses,
+  dedupe claim/complete/release, secure-by-default push verification,
+  capability-model split, off-loop verification and Bot.close(),
+  ActionData, AccessoryWidget, FSM records, FormModel, lifespan,
+  RawWidget, response validation.
+- Phase 15 dogfooding scenarios + CRM workflow; post-review
+  reconciliation (8 blockers); selective gap audit (argument_text,
+  notification options, private viewer, card updates, poll recipe).
+
+## [0.12.0] — 2026-08-15
+
+### Added
+
+- Value-first README and Getting Started; honest aiogram comparison;
+  public API audit.
+- Named example bots (echo/command/buttons/form/dialog/fsm/fastapi/pubsub/
+  workspace_events), each executable and test-covered.
+- Reproducible fresh-venv package verification script.
+
+### Status
+
+**Pre-1.0 beta / release candidate.** The public API may still change
+before 1.0.0 (semver applies to post-1.0 releases only). Not published
+to PyPI.
+
+## [0.11.0] — 2026-08-15
+
+### Added
+
+- `chattice.testing`: MockBot (call recorder with message assertions),
+  EventFactory (typed event builders — no raw Google JSON in unit tests),
+  FakeChatTransport (migrated; compat re-export), card assertions,
+  FSM seeding helper.
+- Live integration suite skeleton (`tests/integration/live`) with an
+  honest skip and full setup instructions.
+
+## [0.10.0] — 2026-08-15
+
+### Added
+
+- `chattice.idempotency`: IdempotencyStorage protocol, Memory +
+  Redis implementations (SET NX EX — single-command atomicity);
+  Pub/Sub push-router dedupe by messageId.
+- `chattice.observability`: ObservabilityHooks + Dispatcher
+  observability_hooks (additive, failure-isolated).
+- Bot: per-call `timeout` on all operations.
+- Architecture docs: reliability (retry classification, verified quotas,
+  backoff guidance), observability (OTel bridge example), security audit
+  with a source-scan redaction test.
+
+## [0.9.0] — 2026-08-15
+
+### Added
+
+- Pub/Sub push ingress: PubSubPushAdapter (documented envelope ->
+  interaction event), create_pubsub_router (204 ack, no sync responses);
+  capability rows for transport="pubsub".
+- Workspace Events ingress family: WorkspaceEvent model, CloudEvent
+  parser, workspace_event observer, create_workspace_events_router.
+- SubscriptionManager protocol skeleton (implementation deferred).
+
+## [0.8.0] — 2026-08-15
+
+### Added
+
+- `chattice.auth`: CredentialsProvider (canonical home), lazy
+  ServiceAccountCredentialsProvider (file/info), UserCredentialsProvider
+  with lazy refresh; AuthMode; CHAT_BOT_SCOPE. Client re-exports the
+  protocol for Phase 4 compatibility.
+- `chattice.capabilities`: Capability matrix (single source of truth,
+  verified Google facts), Capabilities.require() guards that fail BEFORE
+  network calls; capabilities injected into handler context.
+- `chattice.experimental`: preview-feature namespace marker.
+
+## [0.7.0] — 2026-08-14
+
+### Added
+
+- `chattice.fsm`: State/StatesGroup, FSMContext (name-based DI via
+  `data["state"]`), StorageKey + FSMStrategy on Google refs (default
+  USER_IN_SPACE), MemoryStorage, StateFilter, FSMError.
+- Dispatcher(fsm_storage=..., fsm_strategy=...) pre-injects the FSM
+  context before filter evaluation (additive; unconfigured behavior
+  unchanged).
+- `chattice[redis]` extra: RedisStorage (per-command atomicity only —
+  update_data is not cross-process, documented honestly).
+
+## [0.6.0] — 2026-08-14
+
+### Added
+
+- Dialogs: Button/Action `interaction=OPEN_DIALOG`, `Dialog` facade,
+  `ActionStatus.ok/.invalid`; DIALOG/actionStatus sync responses;
+  `router.dialog_submit` / `router.dialog_cancel` observers.
+- Forms: full TextInput/SelectionInput/DateTimePicker fields, `Validation`
+  facade (character limit + input type); Section.from_proto rebuilds form
+  widgets (Phase 5 debt closed).
+- App Home: RenderActions pushCard (APP_HOME) and updateCard (SUBMIT_FORM)
+  sync responses.
+
+## [0.5.0] — 2026-08-14
+
+### Added
+
+- `chattice.cards`: typed facade builders over the official
+  google-apps-card SDK — Card, CardHeader, Section, TextParagraph,
+  Divider, ButtonList, Button (action/parameters or open link), Action,
+  OpenLink, TextInput, SelectionInput, DateTimePicker; serialization to
+  documented Cards v2 JSON; raw proto escape hatch.
+- FastAPI integration: handlers may return a Card — MESSAGE replies with
+  `cardsV2`; CARD_CLICKED replies with `actionResponse UPDATE_MESSAGE`
+  (documented bot-message card replacement).
+
+## [0.4.0] — 2026-08-14
+
+### Added
+
+- `chattice.client`: `Bot` — async outgoing Chat API operations
+  (`send_message`, `get_message`, `update_message`, `delete_message`,
+  `get_space`) over the official `google-apps-chat` SDK with a lazy
+  grpc_asyncio client; `raw_client` escape hatch; `MessageReplyOption`
+  thread semantics; `request_id` idempotency passthrough.
+- `ChatAPIError` hierarchy wrapping SDK errors with preserved code/details
+  and chaining; `CredentialsProvider` protocol.
+
+## [0.3.0] — 2026-08-14
+
+### Added
+
+- `chattice.transports.http`: web-framework-neutral HTTP interaction core —
+  `IncomingRequest`, `InteractionResponse` with double-response guard,
+  `InteractionContext` with the documented 30-second sync deadline,
+  `HTTPInteractionAdapter`, `GoogleTokenVerifier` (google-auth based,
+  both documented audience strategies), `MockVerifier`.
+- `chattice.integrations.fastapi`: `create_chat_router()` for FastAPI
+  (optional extra `chattice[fastapi]`), also usable under plain Starlette.
+- Verification failures map to HTTP 401 per the official docs; malformed
+  payloads to 400; handler failures to 500.
+
+## Unreleased
+
+- Added the pure Google Chat interaction adapter for all eight stable event
+  types, direct/App Home envelopes, typed common/form data, and explicit parser
+  exceptions.
+- Added immutable actor/space/thread/message references, lifecycle, command,
+  widget, App Home, form-submit, and dialog metadata domain values.
+- Added dedicated routing observers and provenance-recorded Google fixtures.
+- Added immutable synthetic domain events.
+- Added the Phase 1 dispatcher, nested routers, observers, filters, middleware,
+  dependency injection, routing control, and error routing.
+- Added comprehensive core-engine tests, executable examples, and architecture
+  documentation.
+
+## 0.0.0 - 2026-08-13
+
+- Added Phase 0 research, architecture, ADRs, and repository scaffold.

chattice-0.14.0b1/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.14.0b1/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# 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.

chattice-0.14.0b1/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.14.0b1/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: chattice
+Version: 0.14.0b1
+Summary: Async typed event framework for Google Chat apps
+Author: chattice contributors
+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: gemini
+Requires-Dist: google-genai<3,>=1; extra == 'gemini'
+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
+
+# 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-public%20beta-orange)](#status)
+
+```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 (doctrine §16).
+
+## 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](docs/aiogram-comparison.md)).
+- **Not a Google product.** Independent open-source project, not
+  endorsed by Google.
+
+## 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, observers, magic filters, middleware, DI |
+| Cards | Typed facades (buttons, forms, validation), sync updates (UPDATE_MESSAGE / UPDATE_USER_MESSAGE_CARDS, sender-derived) |
+| 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 |
+| 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
+uv add chattice            # core
+uv add "chattice[fastapi]" # FastAPI integration
+uv add "chattice[redis]"   # Redis FSM/idempotency storage
+uv add "chattice[pubsub]"  # Pub/Sub push + streaming pull
+```
+
+## 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](docs/getting-started/installation.md), the
+[5-minute Quickstart](docs/getting-started/quickstart.md), and the
+[Space → Thread → Message mental model](docs/concepts/mental-model.md). The
+[public API reference](docs/public-api.md), [Google mapping](docs/reference/google-api-mapping.md),
+and [aiogram comparison](docs/aiogram-comparison.md) are linked from the docs site.
+Runnable examples live in [`examples/`](examples/README.md); LLM agents get
+[`llms.txt`](llms.txt).
+
+## Status
+
+Pre-1.0 **public beta** (current version 0.14.0b1) — see
+[CHANGELOG](CHANGELOG.md). The documented stable beta
+surface is frozen: 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](LICENSE).

chattice-0.14.0b1/PUBLIC_API.md

@@ -0,0 +1,26 @@
+# PUBLIC_API — machine-readable index
+
+This file is the thin generated-style index for coding agents. 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.auth: AuthMode · CredentialsProvider · ServiceAccountCredentialsProvider · UserCredentialsProvider · CHAT_BOT_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 · TextInput · SelectionInput · DateTimePicker · Action · OpenLink · Dialog · ActionStatus · ActionStatusCode · Validation · TextInputType · AccessoryWidget · RawWidget
+- chattice.client: Bot · 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.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