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

keble_task-2.22.1/AGENTS.md

@@ -0,0 +1,32 @@
+# Keble Task Agent Instructions
+
+Follow the root `TESTING_GUIDELINE.md` when changing tests in this repo.
+
+## Testing Rules
+
+- Keep default tests offline from external providers. 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 integration DB tests and must be
+  marked with `integration`, `db`, `mongo`, and `redis`.
+- 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.
+- 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 `uv run pytest -m "not live and not slow and not eval and not local_stack and not db_stack and not container"`
+  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.22.1/AiAgentChangesLogs.md

@@ -0,0 +1,44 @@
+# Ai Agent Changes Logs
+
+Historical entries before 2026-06-30 23:13 were moved to `logs/AiAgentChangesLogs.20260630.md`.
+
+## 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.
+- Pending proof before merge: default pytest, unit, integration, live LLM guard, pyright, and package build.
+
+## 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.22.1/CLAUDE.md

@@ -0,0 +1,33 @@
+# Keble Task Claude Instructions
+
+Follow the root `TESTING_GUIDELINE.md` for all task package test work.
+
+Keep default tests free of live providers. Mongo/Redis tests are integration DB
+tests; live LLM tests require `RUN_LLM_LIVE=1` and either explicit `LIVE_LLM_*`
+credentials or backend Azure provider settings loaded from `keble.backend/.env`.
+Use the shared marker vocabulary across Keble repos and prefer
+`keble_db.testing` helpers as shared DB fixtures become available.
+
+Executable tests must live 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. Mongo/Redis tests
+must carry `integration`, `db`, `mongo`, and `redis` markers.
+
+Do not recreate root-level `tests/config.py`, `tests/utils.py`, or an
+importable root `tests` package. Shared settings, factories, and test doubles
+belong in `keble_task.testing`.
+
+Do not add empty pytest lifecycle hooks, placeholder test modules, `pass`, `...`,
+or status-only assertions. If a repo lacks a reusable DB or provider fixture,
+enrich `keble_db.testing` or this package's testing helper surface first.
+
+Required checks after test-infrastructure changes:
+
+```bash
+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 pytest -m unit
+uv run pytest -m integration
+uv run pytest -m "live and llm"
+npx --yes pyright .
+```

keble_task-2.22.1/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: keble-task
+Version: 2.22.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.40.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-06-30 against `pyproject.toml`, package exports,
+`keble_task/`, and tests.
+
+- Package: `keble-task 2.22.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.
+
+## Testing
+
+```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 .
+```
+
+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. 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.
+- Relation or graph-context changes can affect all feature rooms that load
+  child tasks or background sessions.

keble_task-2.22.1/README.md

@@ -0,0 +1,58 @@
+# 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-06-30 against `pyproject.toml`, package exports,
+`keble_task/`, and tests.
+
+- Package: `keble-task 2.22.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.
+
+## Testing
+
+```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 .
+```
+
+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. 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.
+- Relation or graph-context changes can affect all feature rooms that load
+  child tasks or background sessions.

keble_task-2.22.1/keble_task/testing/__init__.py

@@ -0,0 +1,12 @@
+"""Package-owned testing helpers for Keble task tests and downstream suites."""
+
+from .config import Settings, build_db, settings
+from .factories import InMemoryCRUDTask, make_task
+
+__all__ = [
+    "InMemoryCRUDTask",
+    "Settings",
+    "build_db",
+    "make_task",
+    "settings",
+]

keble_task-2.22.1/keble_task/testing/config.py

@@ -0,0 +1,169 @@
+"""Environment-backed settings for Keble task integration and live tests."""
+
+from __future__ import annotations
+
+import logging
+import json
+
+from keble_db import Db, DbSettingsABC
+from keble_db.testing import backend_env_values, resolve_test_env
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_first_backend_json_list_value(
+    *,
+    explicit_env_name: str,
+    backend_env_name: str,
+) -> str | None:
+    """Resolve a live-test value from explicit env or backend JSON-list config.
+
+    The package live LLM canary needs one OpenAI-compatible endpoint, token, and
+    deployment. Backend stores provider values as JSON-style lists, so task tests
+    use the first configured value only when the package-specific `LIVE_LLM_*`
+    variable is absent.
+    """
+
+    explicit_value = resolve_test_env(explicit_env_name)
+    if explicit_value is not None:
+        return explicit_value
+
+    backend_value = backend_env_values().get(backend_env_name)
+    if backend_value is None:
+        return None
+
+    parsed_value = json.loads(backend_value)
+    if not isinstance(parsed_value, list) or not parsed_value:
+        return None
+
+    first_value = parsed_value[0]
+    if not isinstance(first_value, str) or first_value.strip() == "":
+        return None
+
+    return first_value.strip()
+
+
+class Settings(DbSettingsABC, BaseSettings):
+    """Settings protocol implementation used only by opt-in pytest layers."""
+
+    model_config = SettingsConfigDict(
+        env_file="./tests/.env", env_file_encoding="utf-8", case_sensitive=True
+    )
+
+    MONGO_DB_URI: str | None = Field(
+        default_factory=lambda: resolve_test_env("MONGO_DB_URI")
+    )
+    MONGO_DB_DATABASE: str = "__keble_task__pytest__"
+    TASK_COLLECTION: str = "__keble_task__pytest__task__"
+    TASK_RELATION_COLLECTION: str = "__keble_task__pytest__task_relation__"
+    TASK_COST_COLLECTION: str = "__keble_task__pytest__task_cost__"
+
+    REDIS_URI: str | None = Field(default_factory=lambda: resolve_test_env("REDIS_URI"))
+
+    LIVE_LLM_ENDPOINT: str | None = Field(
+        default_factory=lambda: _resolve_first_backend_json_list_value(
+            explicit_env_name="LIVE_LLM_ENDPOINT",
+            backend_env_name="AZURE_PROVIDER_ENDPOINTS",
+        )
+    )
+    LIVE_LLM_API_TOKEN: str | None = Field(
+        default_factory=lambda: _resolve_first_backend_json_list_value(
+            explicit_env_name="LIVE_LLM_API_TOKEN",
+            backend_env_name="AZURE_PROVIDER_API_TOKENS",
+        )
+    )
+    LIVE_LLM_CHAT_DEPLOYMENT: str | None = Field(
+        default_factory=lambda: _resolve_first_backend_json_list_value(
+            explicit_env_name="LIVE_LLM_CHAT_DEPLOYMENT",
+            backend_env_name="AZURE_OPENAI_CHAT_MODELS_DEPLOYMENTS",
+        )
+    )
+
+    @property
+    def qdrant_host(self) -> str | None:
+        """Return no Qdrant host because task tests do not use Qdrant."""
+
+        return None
+
+    @property
+    def qdrant_port(self) -> int | None:
+        """Return no Qdrant port because task tests do not use Qdrant."""
+
+        return None
+
+    @property
+    def qdrant_collection(self) -> str | None:
+        """Return no Qdrant collection because task tests do not use Qdrant."""
+
+        return None
+
+    @property
+    def mongo_db_uri(self) -> str | None:
+        """Expose the configured Mongo URI through the keble-db protocol."""
+
+        return self.MONGO_DB_URI
+
+    @property
+    def mongo_db_database(self) -> str:
+        """Expose the configured Mongo database through the keble-db protocol."""
+
+        return self.MONGO_DB_DATABASE
+
+    @property
+    def redis_uri(self) -> str | None:
+        """Expose the configured Redis URI through the keble-db protocol."""
+
+        return self.REDIS_URI
+
+    @property
+    def sql_write_uri(self) -> str | None:
+        """Return no SQL write URI because task tests do not use SQL."""
+
+        return None
+
+    @property
+    def sql_read_uri(self) -> str | None:
+        """Return no SQL read URI because task tests do not use SQL."""
+
+        return None
+
+    @property
+    def sql_uri(self) -> str | None:
+        """Return no SQL URI because task tests do not use SQL."""
+
+        return None
+
+    @property
+    def neo4j_uri(self) -> str | None:
+        """Return no Neo4j URI because task tests do not use Neo4j."""
+
+        return None
+
+    @property
+    def neo4j_user(self) -> str | None:
+        """Return no Neo4j user because task tests do not use Neo4j."""
+
+        return None
+
+    @property
+    def neo4j_password(self) -> str | None:
+        """Return no Neo4j password because task tests do not use Neo4j."""
+
+        return None
+
+    @property
+    def neo4j_database(self) -> str | None:
+        """Return no Neo4j database because task tests do not use Neo4j."""
+
+        return None
+
+
+settings = Settings()
+
+
+def build_db() -> Db:
+    """Build a keble-db adapter only after a test opts into real services."""
+
+    return Db(settings)

keble_task-2.22.1/keble_task/testing/factories.py

@@ -0,0 +1,67 @@
+"""Reusable task test doubles and factories."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from bson import ObjectId
+from keble_helpers import SharingScope, Status
+
+from keble_task.schemas import TaskMongoObject, TaskStage
+
+
+class InMemoryCRUDTask:
+    """Minimal in-memory CRUDTask stand-in for TaskClient unit tests."""
+
+    def __init__(self, task: TaskMongoObject) -> None:
+        """Store one task row by Mongo ObjectId for deterministic unit tests."""
+
+        self._tasks = {task.id: task}
+
+    async def aincrement_attempts(self, amongo, *, _id: ObjectId) -> TaskMongoObject:
+        """Increment attempts on the stored task and return the updated row."""
+
+        task = self._tasks[_id]
+        updated = task.model_copy(update={"attempts": int(task.attempts) + 1})
+        self._tasks[_id] = updated
+        return updated
+
+    async def aupdate(self, amongo, *, _id: ObjectId, obj_in: dict) -> None:
+        """Apply a partial update to the stored task row."""
+
+        task = self._tasks[_id]
+        self._tasks[_id] = task.model_copy(update=obj_in)
+
+    async def afirst_by_id(self, amongo, *, _id: ObjectId) -> TaskMongoObject | None:
+        """Return the stored task for an ObjectId, if it exists."""
+
+        return self._tasks.get(_id)
+
+
+def make_task(
+    *,
+    expected_token: int = 1,
+    consumed_token: int = 0,
+    metadata: dict | None = None,
+) -> TaskMongoObject:
+    """Build a valid task row for TaskClient unit and contract tests."""
+
+    return TaskMongoObject(
+        id=ObjectId(),
+        stage=TaskStage.PENDING,
+        task_type=str(uuid.uuid4()),
+        progress_key=str(uuid.uuid4()),
+        title=None,
+        subtitle=None,
+        image="https://example.com/x.png",
+        metadata=metadata,
+        sharing_scope=SharingScope.PRIVATE,
+        status=Status.ACTIVE,
+        owner=str(uuid.uuid4()),
+        expected_token=expected_token,
+        consumed_token=consumed_token,
+        attempts=0,
+        timeout_mins=120,
+        created=datetime.now(timezone.utc),
+    )

keble_task-2.22.0/AiAgentChangesLogs.md → keble_task-2.22.1/logs/AiAgentChangesLogs.20260630.md

@@ -1,3 +1,16 @@
+## 2026-06-30 22:07 CST
+State: `keble-task` strict test folder normalization on branch `refactor/testing-normalization-keble-task`.
+
+zma:
+- Continue the strict cross-repo testing cleanup from `prompts/20260630/1.3 cross-repos-tests-boost.md`.
+- Enforce canonical test folders and marker allowances from the updated root `TESTING_GUIDELINE.md`.
+
+Ai:
+- Moved executable tests from flat `tests/test_*.py` and legacy `tests/schemas/` into canonical `tests/unit`, `tests/contract`, `tests/integration`, and `tests/live` roots.
+- Updated pytest collection marking to classify tests by canonical layer folder and mark Mongo/Redis task-client tests with `integration`, `db`, `mongo`, and `redis`.
+- Added missing `redis` and `container` marker registrations to keep the repo aligned with the shared marker vocabulary.
+- Updated README/AGENTS/CLAUDE to forbid new flat or legacy test folders and to use the stricter default test command.
+
 ## 2026-06-30 13:42 CST
 State: branch `refactor/testing-layers-keble-task`; package line moving from `2.21.0` to `2.22.0`.
 

{keble_task-2.22.0 → keble_task-2.22.1}/pyproject.poetry.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "keble-task"
-version = "2.5.1"
+version = "2.22.1"
 description = ""
 authors = ["zhenhao-ma <bob0103779@gmail.com>"]
 readme = "README.md"
@@ -10,7 +10,7 @@ classifiers = [
 [tool.poetry.dependencies]
 python = ">=3.13,<3.14"
 keble-helpers = ">=1.12.6,<2.0.0"
-keble-db = ">=1.6.2,<2.0.0"
+keble-db = ">=1.8.1,<2.0.0"
 pydantic-ai-slim = ">=1.41.0,<2.0.0"
 tenacity = ">=9,<10.0.0"
 

{keble_task-2.22.0 → keble_task-2.22.1}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "keble-task"
-version = "2.22.0"
+version = "2.22.1"
 description = ""
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
-dependencies = ["keble-helpers>=1.40.0,<2.0.0", "keble-db>=1.7.1,<2.0.0", "pydantic-ai-slim>=1.41.0,<2.0.0", "tenacity>=9,<10.0.0"]
+dependencies = ["keble-helpers>=1.40.0,<2.0.0", "keble-db>=1.8.1,<2.0.0", "pydantic-ai-slim>=1.41.0,<2.0.0", "tenacity>=9,<10.0.0"]
 
 [[project.authors]]
 name = "zhenhao-ma"
@@ -24,7 +24,6 @@ test = ["pytest>=8,<9.0.0", "pytest-asyncio>=0,<1.0.0", "pydantic-ai-slim[openai
 default-groups = ["test"]
 
 [tool.uv.sources]
-keble-db = {path = "../keble-py/keble-db"}
 keble-helpers = {path = "../keble-py/keble-helpers"}
 
 [tool.hatch.build]
@@ -42,8 +41,10 @@ markers = [
   "db: any real database test",
   "postgres: PostgreSQL tests",
   "mongo: MongoDB tests",
+  "redis: Redis tests",
   "qdrant: Qdrant tests",
   "neo4j: Neo4j tests",
+  "container: tests that start Testcontainers resources",
   "db_stack: multi-database integration tests",
   "keepa: Keepa-related tests",
   "keepa_contract: recorded Keepa contract tests",