keble-segmenting

SegmentingProgress.event_callbacks is runtime-only orchestration state. It is accepted by Pydantic for worker execution, but excluded from serialization and JSON Schema so API frameworks can safely expose progress snapshots in OpenAPI.

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.
• Local-full tests run DB-heavy integration by default. Provider-backed quality coverage belongs in marked eval layers with explicit provider gates.
• Reusable test settings, datasets, provider helpers, and shared assertion helpers live in keble_segmenting.testing; executable tests stay under canonical tests/unit, tests/integration, and tests/evals roots.

Testing

uv sync --group test
RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 RUN_DB_STACK=1 uv run pytest -q -m "not live and not container"
uv run pytest -q -m "not live and not slow and not eval and not local_stack and not db_stack and not container"
uv run pytest -q -m eval
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 provider-backed eval 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. Mongo/Redis integration tests are integration, db, mongo, redis, and local_stack; they run in local-full and are excluded from portable-offline. Selecting them without configured local storage fails with a clear environment requirement. Eval tests belong under tests/evals/ and selecting -m eval is the eval opt-in; do not add a generic RUN_EVALS gate. Provider-backed evals also carry live and llm, so a real run uses RUN_LLM_LIVE=1 uv run pytest -q -m "eval and llm".

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.