keble-task 2.22.0__tar.gz → 2.24.0__tar.gz

keble_task-2.24.0/AGENTS.md

@@ -0,0 +1,46 @@
+# Keble Task Agent Instructions
+
+Follow the root `TESTING_GUIDELINE.md` when changing tests in this repo.
+
+## Testing Rules
+
+- The normal Keble local development command is local-full and should run
+  Mongo/Redis-heavy tests by default:
+  `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"`.
+- Keep the portable-offline fallback available for machines without local DBs:
+  `uv run pytest -q -m "not live and not slow and not eval and not local_stack and not db_stack and not container"`.
+- The live LLM test must stay marked `live` and `llm` and must require
+  `RUN_LLM_LIVE=1`.
+- Put executable tests under canonical layer folders only: `tests/unit/`,
+  `tests/contract/`, `tests/integration/`, `tests/live/`, `tests/evals/`, or
+  `tests/db_stack/`.
+- Do not add flat `tests/test_*.py`, `tests/schemas/`, `tests/mock/`, or
+  `tests/irl/` folders.
+- Do not recreate root-level `tests/config.py`, `tests/utils.py`, or an
+  importable root `tests` package. Shared test doubles and settings belong in
+  `keble_task.testing`.
+- Tests that use Mongo/Redis fixtures are local-stack integration DB tests and
+  must be marked with `integration`, `db`, `mongo`, `redis`, and `local_stack`;
+  they must run under the local-full command and must not be selected by the
+  portable-offline command.
+- Selected DB tests must fail with a clear missing-config message when Mongo or
+  Redis cannot be resolved; do not hide selected DB coverage behind lazy skips.
+- Use `keble_task.testing.config` for test credentials. It reads explicit env /
+  `tests/.env` / the umbrella `keble.backend/.env`, maps backend Azure provider
+  lists into the live LLM canary, and keeps test database names isolated.
+- Use shared fixtures from `keble_db.testing` as the DB testing toolkit expands;
+  do not introduce ad-hoc shared local database writes.
+- Put quality/regression suites under `tests/evals/` and mark them `eval`.
+  Selecting `uv run pytest -q -m eval` is the eval opt-in; do not add a generic
+  `RUN_EVALS` skip gate. Provider-backed evals also need `live` plus the
+  provider marker and provider-specific env gate.
+- Do not add empty pytest lifecycle hooks, empty test folders, `pass`, `...`, or
+  status-only tests as placeholders. Add meaningful assertions or remove the
+  placeholder module.
+- Do not add full stack or live-provider behavior to the default test command.
+- Run the local-full command, portable-offline fallback, `uv run pytest -q -m eval`,
+  changed layer selectors, and `npx --yes pyright .` after
+  test-infrastructure changes.
+- Update `README.md`, `AGENTS.md`, `CLAUDE.md`, and `AiAgentChangesLogs.md`
+  whenever testing behavior, markers, fixtures, commands, or dependencies
+  change.

keble_task-2.24.0/AiAgentChangesLogs.md

@@ -0,0 +1,99 @@
+## 2026-07-08 — 2.23.0 (TaskBase.thinking_mode, Program AP)
+State: branch feature/task-thinking-mode off main a071a29.
+
+zma: user-selectable thinking mode (speed-first vs quality-first) must be explicitly recorded at the keble-task level and inherited task->subtasks.
+
+Ai: TaskBase gains first-class `thinking_mode: Optional[str]` (open str per the framework-fields-stay-str convention; camelCase wire `thinkingMode`; None = legacy = QUALITY_FIRST downstream) beside `language`; `TaskClient.acreate` gains the `thinking_mode` kwarg threaded into TaskBase. Tests: camelCase round-trip + legacy-dump-None. 49 offline pass; pyright 0.
+
+# Ai Agent Changes Logs
+
+Historical entries before 2026-06-30 23:13 were moved to `logs/AiAgentChangesLogs.20260630.md`.
+
+## 2026-07-18 04:25 CST
+State: `fix/review2-exact-task-cost-rates`; REVIEW2 WP2 task-cost dependency
+correction implemented and verified before backend consumer migration.
+
+zma:
+- Continue the finalized Data Infra REVIEW2 plan, double-check every edge case,
+  and leave all repositories wired, released, and merged only after full proof.
+
+Ai:
+- Corrected a WP0 census miss: per-million token prices cannot use ISO `Money`
+  because valid prices such as USD 0.075 require fractional cents.
+- Reused shared `LlmTokenPriceBand` integer micros inside `TaskCostTokenRates`,
+  added a bounded 2.24.x reader for legacy Money-shaped rows, and locked removal
+  to 2.25.0 after the repair sweep.
+- Added exact Decimal FX, exponent-0/2/3 additional-cost decoding, cached-input
+  de-duplication, typed missing-price failures, and rejection of sub-micro or
+  mixed-currency rates. Removed the public-package local source override and
+  resolved the released `keble-helpers 1.54.0` artifact.
+- Proof: 9 focused unit tests, 58 portable tests, 14 cost integrations, and 172
+  isolated local-full tests passed; Pyright and Ruff checks passed on source,
+  and isolated Mongo/Redis collections were empty before container removal.
+
+## 2026-07-02 21:12 CST
+State: branch `refactor/local-db-evals-keble-task`; local-full pytest default and eval selector cleanup.
+
+zma:
+- Change the testing standard so local DB-heavy tests run by default in the Keble local-full lane.
+- Keep portable-offline tests available, move quality/eval tests to the eval layer, and run eval selections separately.
+
+Ai:
+- Removed the legacy `RUN_INTEGRATION` collection skip from Mongo/Redis integration tests; local-stack integration tests now run when selected by the local-full command or `-m integration`.
+- Changed missing Mongo/Redis config in selected DB fixtures from lazy skip to clear pytest failure, while keeping live LLM gated by `RUN_LLM_LIVE=1`.
+- Updated README, AGENTS, and CLAUDE testing instructions with the local-full command, portable-offline fallback, direct `-m eval` selection, and no generic `RUN_EVALS` gate.
+- Proof: local-full `161 passed, 1 deselected` in pytest `2.74s` / wall `21.35s`; portable-offline `47 passed, 115 deselected` in pytest `0.35s` / wall `1.92s`; unit `35 passed, 127 deselected`; contract `12 passed, 150 deselected`; integration `114 passed, 48 deselected`; eval and db_stack selected no tests; `npx --yes pyright .` `0 errors`; `uv build` produced `keble_task-2.22.1`.
+
+## 2026-07-02 15:29 CST
+State: branch `refactor/harden-pytests-keble-task`; marker tightening for the cross-repo pytest hardening follow-up.
+
+zma:
+- Continue the repo-by-repo pytest hardening.
+- Ensure default tests stay offline while DB/LLM tests remain useful and explicitly marked.
+
+Ai:
+- Marked Mongo/Redis integration and live LLM tests as `local_stack` in the collection hook.
+- Added `RUN_INTEGRATION=1` gating for Mongo/Redis integration tests so default pytest no longer runs real local-stack services opportunistically.
+- Updated README, AGENTS, and CLAUDE testing instructions with the stricter command split.
+- Proof: default `47 passed, 115 deselected in 0.28s`; unit `35 passed, 127 deselected in 0.27s`; contract `12 passed, 150 deselected in 0.24s`; integration with `RUN_INTEGRATION=1` `114 passed, 48 deselected in 1.87s`; `db` `114 passed, 1 skipped, 47 deselected in 1.90s`; `mongo` `114 passed, 1 skipped, 47 deselected in 1.90s`; `redis` `114 passed, 1 skipped, 47 deselected in 1.87s`; `local_stack` `114 passed, 1 skipped, 47 deselected in 1.84s`; live guard `1 skipped, 161 deselected in 0.19s`; live LLM with `RUN_LLM_LIVE=1` `1 passed, 161 deselected in 7.18s`; asyncio with `RUN_INTEGRATION=1` `103 passed, 1 skipped, 58 deselected in 1.94s`; `npx --yes pyright .` `0 errors`; `uv build` succeeded.
+
+## 2026-07-02 00:58 CST
+State: branch `refactor/harden-pytests-keble-task`; pytest hardening follow-up for `prompts/202060701/1.5-harden-pytests-and-remove-redundant.md`.
+
+zma:
+- Execute the cross-repo pytest hardening plan repo by repo.
+- Reconsider over-trimmed IRL tests, remove weak placeholders, and use `keble.backend/.env` credentials instead of skipping DB/LLM tests for missing repo-local env.
+
+Ai:
+- Bumped `keble-task` to `2.22.1` and raised the `keble-db` dependency to `>=1.8.1`.
+- Updated `keble_task.testing.config` to read explicit env / `tests/.env` / backend `.env` for Mongo and Redis, and to map the first backend Azure endpoint/token/deployment into the live LLM canary.
+- Added unit coverage for backend env fallback, Azure provider-list mapping, and explicit-env precedence.
+- Removed empty pytest lifecycle hooks from `tests/conftest.py` and updated docs to forbid placeholder test modules/hooks.
+- Proof: config focus `3 passed`; default pytest `161 passed, 1 deselected`; unit `35 passed, 127 deselected`; contract `12 passed, 150 deselected`; integration `114 passed, 48 deselected`; live LLM guard `1 skipped, 161 deselected`; opt-in live LLM `1 passed, 161 deselected`; pyright `0 errors`; `uv build` succeeded.
+
+## 2026-07-01 03:32
+State: Strict testing-folder follow-up for `keble-task`; no runtime task API behavior, schemas, or dependencies changed.
+
+zma:
+- Continue the cross-repo testing refactor after tightening `TESTING_GUIDELINE.md` marker and folder allowances.
+- Enforce canonical test layer folders and package-owned shared test helpers.
+
+Ai:
+- Moved test settings into `keble_task.testing.config`.
+- Moved shared in-memory task test doubles and factories into `keble_task.testing.factories`.
+- Removed root `tests/config.py`, `tests/utils.py`, `tests/pytest.ini`, and `tests/__init__.py` so tests no longer import through `tests.*`.
+- Updated docs to keep future shared task test helpers under `keble_task.testing`.
+
+## 2026-06-30 23:13
+        State: Documentation-only README compaction and AI log archival; no runtime code, schemas, dependencies, or tests were changed.
+
+        zma:
+        - Auto compact and summarize README.md files across repos unless already small.
+- Cross-check retained README information for validity and keep only critical, necessary information.
+- Move lengthy AiAgentChangesLogs.md files into repo-local logs/AiAgentChangesLogs.2026****.md.
+- Merge the documentation changes to main repo by repo.
+
+        Ai:
+        - Archived the previous long agent change log into `logs/AiAgentChangesLogs.20260630.md`.
+- Compacted `README.md` to current purpose, validated wiring, install/test gates, and high-risk side effects.
+- Kept only critical current README facts cross-checked against manifests, config, source roots, compose scripts, or existing guideline files.

keble_task-2.24.0/CLAUDE.md

@@ -0,0 +1,5 @@
+@AGENTS.md
+
+This CLAUDE.md is an import ALIAS only: the canonical package rules live in
+`AGENTS.md` (imported above). Do NOT load both files — if your tool already
+read AGENTS.md, skip this file (and vice versa). Never add rules here.

keble_task-2.24.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: keble-task
+Version: 2.24.0
+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.0`
+- 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`; ISO `Money` remains the contract for concrete
+  additional spend. This separation preserves prices such as USD 0.075 without
+  rounding them to cents and prevents cached input from being billed twice.
+- 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.
+
+## 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; 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.

keble_task-2.24.0/README.md

@@ -0,0 +1,78 @@
+# 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.0`
+- 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`; ISO `Money` remains the contract for concrete
+  additional spend. This separation preserves prices such as USD 0.075 without
+  rounding them to cents and prevents cached input from being billed twice.
+- 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.
+
+## 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; 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.

{keble_task-2.22.0 → keble_task-2.24.0}/keble_task/main.py

@@ -25,20 +25,18 @@ from keble_db import AgentDbDeps, ExtendedAsyncRedis, QueryBase
 from keble_helpers import (
     AgenticActionEventStatus,
     AgenticEventEmitter,
-    Currency,
     ExchangeRateInUsd,
     Language,
     Money,
     ObjectId,
     PydanticModelConfig,
     SharingScope,
-    UsageAccountingRecorderProtocol,
     UsageAccountingSource,
     utc_now,
 )
 from motor.motor_asyncio import AsyncIOMotorClient
 from neo4j import AsyncDriver as Neo4jAsyncDriver
-from pydantic import BaseModel, ConfigDict, SkipValidation
+from pydantic import BaseModel, ConfigDict
 from pydantic_ai.usage import RunUsage
 from pymongo import ASCENDING, DESCENDING
 from pymongo.errors import DuplicateKeyError
@@ -632,6 +630,9 @@ class TaskClient:
         subtitle: Optional[str] = None,
         metadata: Optional[TaskMetadata] = None,
         language: Optional[Language] = None,
+        # Program AP (2.23.0): the run's thinking mode (keble_helpers
+        # AgentThinkingMode wire values); the framework stores it verbatim.
+        thinking_mode: Optional[str] = None,
         task_type: str,
         timeout_mins: int = 120,
         sharing_scope: SharingScope = SharingScope.PRIVATE,
@@ -689,6 +690,7 @@ class TaskClient:
                     subtitle=subtitle,
                     metadata=metadata,
                     language=language,
+                    thinking_mode=thinking_mode,
                     owner=str(owner),
                     consumed_token=consumed_token,
                     expected_token=expected_token,
@@ -2338,8 +2340,7 @@ class TaskClient:
                     aneo4j=aneo4j,
                     qdrant_client=qdrant_client,
                     task_handler_metadata=task_handler_metadata,
-                    event_emitter=task_lifecycle_event_emitter
-                    or AgenticEventEmitter(),
+                    event_emitter=task_lifecycle_event_emitter or AgenticEventEmitter(),
                 )
             except Exception as exc:
                 logger.critical(
@@ -2390,9 +2391,7 @@ class TaskClient:
     ):
         """Retry all undone tasks asynchronously."""
         # fetch all undone
-        after = utc_now() - timedelta(
-            minutes=include_tasks_created_within_minutes
-        )
+        after = utc_now() - timedelta(minutes=include_tasks_created_within_minutes)
         db_objs = await self.crud_task.aget_multi(
             amongo,
             query=QueryBase(