# svrnty-vision

Sovereign vision HTTP gateway. FastAPI shell that exposes four endpoints:

| Endpoint | Purpose | Implementation |
|---|---|---|
| `POST /vlm/analyze` | Vision-language model evaluation | Proxies to Spark 2 (Qwen3-VL via vLLM) |
| `POST /flux/render` | Image generation | Proxies to Spark 1 (FLUX on ComfyUI) |
| `POST /palette/extract` | Dominant-color palette | In-process (Pillow + colorthief) |
| `POST /rembg/cutout` | Background removal | In-process (rembg) |

Plus `GET /healthz` for liveness.

## Why it exists

Brand Truth Engine (BTE) is a .NET 10 + Svrnty.CQRS service. Vision tooling
(VLM, image gen, palette, rembg) was originally embedded in BTE with cloud
provider SDKs (Anthropic, OpenAI, Google, Higgsfield). Per the
2026-05-24 refactor audit, that surface is extracted into this sibling repo
so BTE stays narrow and sovereign-first.

## Architecture invariant

**svrnty-vision is a thin HTTP gateway — it does NOT run heavy ML models
in-process.** Qwen3-VL runs on Spark 2 (vLLM). FLUX runs on Spark 1
(ComfyUI). svrnty-vision orchestrates HTTP calls to those services and
normalises the responses for BTE.

The two in-process exceptions (palette, rembg) are CPU-light Python
libraries — Pillow/colorthief and rembg respectively. They land in 4b.

## Status

Current implementation: all four listed endpoints exist. `/vlm/analyze` proxies
to Qwen3-VL through the configured VLM endpoint, `/flux/render` proxies to
ComfyUI FLUX, `/palette/extract` runs in process, `/rembg/cutout` runs in
process, and `/healthz` returns 200.

## Cortex OS Package Candidate

`svrnty-vision` is also documented as a child-local Visual Perception Package
Candidate under canonical sense `VISION`. Existing BTE-shaped HTTP routes remain
current route adapters; exact Cortex OS candidate tool ids, grant rules, host
adapter candidates, and Visual Evidence contract live in `docs/` and
`candidate-manifests/`.

This does not grant Core promotion, Seed installation, Runtime startup, Profile
Exposure, provider admission, or wildcard tool access.

Legacy intention coverage is tracked in `docs/LEGACY-INGEST.md`.

## Cortex OS Boundary

This repo owns child-local sovereign vision gateway source, BTE-shaped HTTP route
adapters, package-candidate docs, visual-evidence contracts, host-adapter
candidates, tool-grant manifests, Docker package context, validators, fixtures,
and proof packets only. Cleanup agents must not start Runtime, start Docker,
build or run containers, install packages, start FastAPI/Uvicorn, call VLM,
FLUX, palette, or rembg endpoints, call Spark/ComfyUI/vLLM services, call cloud
vision/image providers, read credentials or env values, mutate
BTE/Core/Seed/sibling/OpenDesign repos, grant wildcard tools, grant Profile
Exposure, write durable Hindsight memory, or claim readiness without explicit
governed approval. Run, test, Docker, endpoint, provider, and configuration
examples below are operator/developer docs, not cleanup-route authorization.

## Run

```sh
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .                       # required: src/ layout

# either:
python -m svrnty_vision.server
# or:
uvicorn svrnty_vision.server:app --port 8090

curl http://localhost:8090/healthz
# {"status":"ok","version":"0.1.0"}
```

## Test

```sh
pytest tests/
```

## Configuration

Copy `.env.example` to `.env` and edit. All settings have safe defaults
for local development (Spark 1/2 hostnames are placeholders).