keble-segmenting 0.41.1

Segmenting (classification + caching) for Keble positioning grid.

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

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.