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.

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.