Metadata-Version: 2.4
Name: keble-task
Version: 2.24.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-helpers<2.0.0,>=1.54.0
Requires-Dist: pydantic-ai-slim<2.0.0,>=1.41.0
Requires-Dist: tenacity<10.0.0,>=9
Provides-Extra: test
Requires-Dist: httpx[socks]<1.0.0,>=0.27; extra == 'test'
Requires-Dist: pydantic-ai-slim[openai]<2.0.0,>=1.41.0; extra == 'test'
Requires-Dist: pytest-asyncio<1.0.0,>=0; extra == 'test'
Requires-Dist: pytest<9.0.0,>=8; extra == 'test'
Description-Content-Type: text/markdown

# 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

```bash
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.
