Metadata-Version: 2.4
Name: keble-segmenting
Version: 0.41.1
Summary: Segmenting (classification + caching) for Keble positioning grid.
Author-email: zhenhao-ma <bob0103779@gmail.com>
Requires-Python: <3.14,>=3.13
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.43.0
Requires-Dist: pydantic-ai-slim<2.0.0,>=1.41.0
Requires-Dist: pydantic<3.0.0,>=2
Requires-Dist: typing-extensions<5.0.0,>=4.8.0
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-segmenting

`keble-segmenting` owns segmented grids, dimension and mask discovery,
item classification, coverage/read models, queue work contracts, and agent
tools used by positioning and backend workflows.

## Verified State

Checked on 2026-07-01 against `pyproject.toml`, package exports,
`keble_segmenting/`, `CODE_GUIDELINES.md`, and tests.

- Package: `keble-segmenting 0.41.1`
- Python: `>=3.13,<3.14`
- Critical deps: `pydantic`, `keble-db`, `keble-helpers`,
  `keble-agentic-chat`, `pydantic-ai-slim`, `typing-extensions`
- Source roots: `schemas/`, `crud/`, `client/`, `agent/`, `utils/`
- Public exports: `SegmentingClient`, CRUD classes, action/event schemas,
  queue contracts, `ForAgent` schemas, and mutation/query chat tool
  providers.

## Runtime Contract

- Segmenting owns the grid and classification domain. Backend and
  positioning code should use package schemas/actions instead of recreating
  grid state.
- Progress belongs to actions and queue work, not side-effect taxonomies.
  Keep action status, progress payloads, and callback events aligned.
- Stable keys are execution identity. Display names are UX only and may
  collide.
- Default tests must stay offline. DB/provider coverage belongs in marked
  integration/live layers with cleanup.
- Reusable test settings, datasets, live helpers, and shared assertion helpers
  live in `keble_segmenting.testing`; executable tests stay under canonical
  `tests/unit`, `tests/integration`, and `tests/live` roots.

## 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"
npx --yes pyright .
```

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.

Mongo/Redis integration settings load explicit process env first, then the
umbrella `keble.backend/.env` through `keble_db.testing.resolve_test_env`.
Segmenting live LLM settings map backend `AZURE_PROVIDER_ENDPOINTS`,
`AZURE_PROVIDER_API_TOKENS`, and `AZURE_OPENAI_CHAT_MODELS_DEPLOYMENTS` into
the package text/vision model lists when package-local list env vars are absent.
Set `KEBLE_BACKEND_ENV_FILE=/path/to/.env` from unusual worktree or CI layouts.

## Change Logs

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

## Side Effect If Changes

- `keble-positioning`, backend segmentation workers, task room progress, and
  frontend positioning tables depend on segmenting action/event contracts.
- Queue or coverage schema changes require backend worker and frontend
  display updates in the same migration.
- Test/dev dependency source changes affect every `uv run pytest` and pyright
  proof command in this repo; keep `pyproject.toml`, `uv.lock`, and the bundled
  dependency wheel aligned.
