keble-task

keble-task owns generic Keble task schemas, task relations, task-room graph context, lifecycle/action events, task cost records, and agent query/mutation tool contracts.

Verified State

Checked on 2026-07-18 against pyproject.toml, package exports, keble_task/, and tests.

• Package: keble-task 2.24.1
• Python: >=3.13,<3.14
• Critical deps: keble-helpers, keble-db, pydantic-ai-slim, tenacity
• Source roots: schemas/, actions/, crud/, main/, agent/, utils/
• Public exports: TaskClient, CRUD classes, task/task-relation schemas, task-cost schemas, lifecycle/action events, and agent tool providers.

Runtime Contract

• Task identity, stage, relations, and cost accounting belong here. Feature packages should attach domain metadata instead of redefining task rows.
• First-class long-running features should be real TaskType flows in the consuming service, not generic subagent workflows plus parallel adapters.
• Lifecycle and action events must stay typed and stable for backend websocket fanout and frontend task-list rendering.
• Mongo CRUD changes must expose indexed query shapes directly and keep index creation in startup wiring, not request handlers.
• Token rates are stored as native-currency micros per million tokens through the shared LlmTokenPriceBand. Metered non-token provider spend that can be smaller than one ISO minor unit uses TaskCostMicrosAmount; settled values remain Money. This preserves rates such as USD 0.075 and one-item charges such as USD 0.002 without rounding either to cents.
• Version 2.24.x reads the legacy Money-per-counter rate shape only for migration and writes the canonical currency + priceBand shape. Migrate stored rows and old admin clients before removing that reader in 2.25.0.
• Version 2.24.1 also reads legacy additionalCost rows while new metered provider rows write exactAdditionalCost: {currency, micros} and keep the legacy field at zero in the same currency. The two nonzero representations are rejected to prevent double counting.

Testing

uv sync --group test
RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 RUN_DB_STACK=1 uv run pytest -q -m "not live and not container"
uv run pytest -q -m "not live and not slow and not eval and not local_stack and not db_stack and not container"
uv run pytest -q -m eval
uv run pytest -q -m integration
RUN_LLM_LIVE=1 uv run pytest -m "live and llm"
uv run npx --yes pyright .

Package-owned test helpers live under keble_task.testing; do not recreate root-level tests/config.py, tests/utils.py, root test packages, or legacy source folders such as tests/schemas/.

Mongo/Redis integration settings load explicit process env first, then tests/.env, then the umbrella keble.backend/.env through keble_db.testing.resolve_test_env. Live LLM settings load explicit LIVE_LLM_* values first and otherwise map the first backend Azure endpoint/token/deployment entry. Set KEBLE_BACKEND_ENV_FILE=/path/to/.env from unusual worktree or CI layouts. Mongo/Redis tests are integration, db, mongo, redis, and local_stack; they run in the local-full Keble command and stay out of the portable-offline fallback command. Selecting integration tests without configured Mongo/Redis now fails with a clear environment requirement instead of silently skipping. Eval tests use tests/evals/ plus eval; selecting -m eval is the eval opt-in, with no generic RUN_EVALS gate. Keep the package-owned test database and collection names isolated.

Change Logs

Historical release notes and long AI change history live under logs/.

Side Effect If Changes

• Backend task APIs, owner task lists, task room sockets, cost accounting, and frontend task rows depend on these schemas/events.
• Backend pricing configuration and task-cost admin clients must use the exact micro-rate wire introduced in 2.24.0 and the exact additional-spend wire from 2.24.1; optional missing prices are unknown, not free usage.
• Relation or graph-context changes can affect all feature rooms that load child tasks or background sessions.