Metadata-Version: 2.4
Name: keble-agentic-chat
Version: 3.45.1
Author-email: zhenhao-ma <bob0103779@gmail.com>
Requires-Python: <3.14,>=3.13
Requires-Dist: keble-db<2.0.0,>=1.8.1
Requires-Dist: keble-exceptions<2.0.0,>=0.0.15
Requires-Dist: keble-helpers<2.0.0,>=1.44.0
Requires-Dist: langgraph-checkpoint-mongodb>=0.1.0
Requires-Dist: langgraph-checkpoint>=4.1.1
Requires-Dist: langgraph>=1.2.4
Requires-Dist: pydantic-ai-slim<2.0.0,>=1.102.0
Requires-Dist: tenacity<10.0.0,>=9
Provides-Extra: test
Requires-Dist: httpx[socks]<1.0.0,>=0.27; extra == 'test'
Requires-Dist: keble-agentic-override<1,>=0.0.1; extra == 'test'
Requires-Dist: keble-rag<2,>=1.0.1; (python_version >= '3.13') and extra == 'test'
Requires-Dist: pydantic-ai-slim[openai]<2.0.0,>=1.102.0; extra == 'test'
Requires-Dist: pydantic-settings<3.0.0,>=2.2.1; extra == 'test'
Requires-Dist: pyright<2.0.0,>=1.1.403; extra == 'test'
Requires-Dist: pytest-asyncio<0.24.0,>=0.23.6; extra == 'test'
Requires-Dist: pytest<9.0.0,>=8.2.0; extra == 'test'
Description-Content-Type: text/markdown

# keble-agentic-chat

`keble-agentic-chat` is the host-neutral chat runtime package for Keble
Pydantic-AI and LangGraph based chat flows. It owns durable chat history,
timeline schemas, client/server action rows, background subagent sessions,
live socket frames, tool-provider composition, and LangGraph turn execution.

## Verified State

Checked on 2026-06-30 against `pyproject.toml`, `keble_agentic_chat/`,
package exports, and the current test layout.

- Package: `keble-agentic-chat 3.45.1`
- Python: `>=3.13,<3.14`
- Critical deps: `keble-helpers`, `keble-db`, `keble-exceptions`,
  `pydantic-ai-slim`, `langgraph`, `langgraph-checkpoint`,
  `langgraph-checkpoint-mongodb`, `tenacity`
- Source roots: `runtime/`, `schemas/`, `store/`, `crud/`, `subagents/`,
  `adapters/`
- Public exports: `AgenticChat`, `LangGraph` runtime helpers, action and
  live-frame schemas, subagent/session contracts, and generic browser
  client-tool primitives.

## Runtime Contract

- `LangGraphChatRuntime` is the turn engine. Pydantic-AI executes provider
  calls; LangGraph owns control flow, interrupts, resume, and checkpointing.
- `AgenticChat` is a thin per-scope holder for durable storage and run
  control. It is not a feature-specific orchestration layer.
- Timeline entries are the public read contract. Raw provider messages are
  private resume state.
- The LangGraph checkpoint `pending` channel is the deferred-batch source of
  truth. `ChatPendingResume` only carries origin metadata for host dependency
  rehydration.
- Hosts compose package-owned `GeneralChatToolProvider`,
  `ClientActionChatToolProvider`, and subagent delegation providers instead
  of reimplementing tool registration.

## Testing

Default tests are offline and must exclude live, slow, eval, local-stack,
DB-stack, and container layers.

```bash
uv sync --group test
uv run pytest -m "not live and not slow and not eval and not local_stack and not db_stack and not container"
uv run npx --yes pyright .
```

Integration and live tests must use the marker and env guards declared in
`pyproject.toml`.
Package-owned test helpers live under `keble_agentic_chat.testing`; do not
recreate root-level `tests/config.py`, root test packages, or cross-test imports
through `tests.*`.

Mongo/Redis/Qdrant integration settings load explicit process env first, then
the umbrella `keble.backend/.env` through `keble_db.testing.resolve_test_env`.
Live Azure model lists map from backend `AZURE_PROVIDER_ENDPOINTS`,
`AZURE_PROVIDER_API_TOKENS`, and
`AZURE_OPENAI_CHAT_MODELS_DEPLOYMENTS` when package-local list env vars are
absent. Set `KEBLE_BACKEND_ENV_FILE=/path/to/.env` from unusual worktree or CI
layouts, and keep package-owned test database/collection names isolated.

## Change Logs

Historical release notes and long AI change history live under `logs/`.
Keep this README focused on the active contract only.

## Side Effect If Changes

- Backend chat rooms, guided bootstrap, positioning rooms, and any chat
  client-tool flow depend on `pending_resume` staying an origin-metadata
  bridge rather than a second authorization gate.
- Frontend action rendering depends on the typed client-tool payload/result
  schemas staying aligned with `keble-core`.
- Storage or timeline schema changes require backend, frontend, and tests to
  move together.
