Metadata-Version: 2.4
Name: keble-segmenting
Version: 0.44.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.56.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

`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

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