keble-positioning

keble-positioning owns positioning grids, views, viewport actions, positionable item records, and agent tools for market-positioning studies.

Verified State

Checked on 2026-06-30 against pyproject.toml, AGENTS.md, package exports, keble_positioning/, CODE_GUIDELINES.md, and the rebased origin/main test layout.

• Package: keble-positioning 0.38.1
• Package version: 0.38.1
• Python: >=3.13,<3.14
• Critical deps: pydantic, keble-db, keble-helpers, keble-agentic-chat, keble-segmenting, pydantic-ai-slim, griffe, keble-task
• Segmenting dependency line: keble-segmenting >=0.38.0,<1
• Task dependency line: keble-task >=2.21.0,<3.0.0
• Test/dev chat source: bundled compatible deps/keble_agentic_chat-3.44.0-py3-none-any.whl
• Source roots: schemas/, crud/, client/, agent/
• Test roots: tests/unit, tests/integration, tests/live/keepa, tests/live/llm, and tracked JSON/static fixtures under tests/assets
• Test helpers: keble_positioning.testing owns package-local settings, Redis namespace helpers, reusable datasets, and dependency builders shared across test layers.
• Storage and live-provider tests can read keble.backend/.env through keble_db.testing; package-local env variables still win when set.
• Public exports: PositioningClient, positioning task metadata, view/grid schemas, action events/results, and query/mutation chat tool providers.

Runtime Contract

• Positioning is schema/protocol first. Backend owns task identity; this package owns positioning domain shapes, action handling, and grid/view contracts.
• Public bootstrap exports include PositioningTaskMetadata, PositioningBootstrapResult, and PositioningViewDetailed.
• abootstrap_positioning(...) seeds the first positioning rows from typed task metadata, including search_terms=payload.search_terms; positioning rows do not persist search_terms.
• atask_handler(...) executes the task request path, for example await positioning_client.atask_handler(request=request), but this package still does not own background orchestration or runtime status recovery.
• Public frontend-facing create flows are product-market-only unless backend, keble-core, and frontend are migrated together.
• Grouped positioning followers are metadata-only. Missing follower SegmentedResult rows are expected and must not be backfilled by copying main/group rows.
• Agent tools must validate arguments term by term and raise typed retry errors for model-correctable inputs.

Testing

Default fast tests are offline:

uv sync --group test
uv run python -c "import keble_segmenting"
uv run python -c "import keble_positioning"
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 .

Compatibility validation commands:

• uv run pytest tests -q
• uv run pytest -m "not live" tests -q
• uv run pytest -m live tests -q
• uv lock
• uv sync

Opt-in layers from AGENTS.md:

RUN_INTEGRATION=1 uv run pytest -m "integration and local_stack"
RUN_INTEGRATION=1 RUN_KEEPA_LIVE=1 RUN_LLM_LIVE=1 uv run pytest -m keepa_live
RUN_INTEGRATION=1 RUN_LLM_LIVE=1 uv run pytest -m "live and llm"

Keep real-service behavior under explicit integration/live markers and env switches. Do not place DB, Keepa, or LLM calls in the default test path. Live Keepa and LLM tests assert current structured invariants directly. Do not reintroduce tracked Keepa or LLM response cache files as proof for live behavior. If real DB or Keepa fixtures are missing, enrich keble-db or keble-keepa testing helpers first instead of adding package-local fake placeholders. Do not add root tests/config.py, tests/redis_namespace.py, or duplicate tests/pytest.ini; shared helpers belong in keble_positioning.testing. Keep tests/assets non-executable and data-only.

The test/dev keble-agentic-chat source is pinned to the bundled compatible deps/keble_agentic_chat-3.44.0-py3-none-any.whl. Do not point it at the sibling ../keble-agentic-chat checkout unless this repo also moves to that checkout's keble-helpers dependency line; otherwise uv run can fail before pytest collection.

Change Logs

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

Side Effect If Changes

• Backend positioning room APIs, task room sockets, frontend workspace tables, and segmenting integration depend on these schemas and events.
• View/action identity changes must propagate to backend, keble-core, and frontend task-row/rendering code together.
• Testing-layer changes must preserve the marker/env-gate split above so the default suite stays offline.
• Test/dev dependency source changes affect every uv run pytest and pyright proof command in this repo; keep pyproject.toml, uv.lock, and bundled dependency wheels aligned.