Metadata-Version: 2.4
Name: keble-positioning
Version: 0.38.1
Summary: Positioning (axes/tags/records) for Keble v2.1 market exploration.
Author-email: zhenhao-ma <bob0103779@gmail.com>
Requires-Python: <3.14,>=3.13
Requires-Dist: griffe<2,>=1.14
Requires-Dist: keble-agentic-chat<4.0.0,>=3.41.0
Requires-Dist: keble-db<2.0.0,>=1.8.1
Requires-Dist: keble-helpers<2.0.0,>=1.41.0
Requires-Dist: keble-segmenting<1,>=0.38.0
Requires-Dist: keble-task<3.0.0,>=2.21.0
Requires-Dist: pydantic-ai-slim<2.0.0,>=1.102.0
Requires-Dist: pydantic<3.0.0,>=2
Provides-Extra: test
Requires-Dist: logfire<5.0.0,>=4.19.0; extra == 'test'
Requires-Dist: openai<3.0.0,>=2.15.0; extra == 'test'
Requires-Dist: pydantic-settings<3.0.0,>=2.12.0; extra == 'test'
Requires-Dist: pytest-asyncio<2.0.0,>=1.3.0; extra == 'test'
Requires-Dist: pytest<9.0.0,>=8.2.0; extra == 'test'
Requires-Dist: socksio<2.0.0,>=1.0.0; extra == 'test'
Description-Content-Type: text/markdown

# 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:

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

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