# svrnty-vision — orientation for Claude

*Inherits Karpathy 4 rules from `~/.claude/CLAUDE.md` and the workspace
contract from `/home/svrnty/workspaces/hermes/CLAUDE.md`. Read both before
touching anything here.*

## What this repo is

A FastAPI HTTP gateway in front of four vision capabilities (VLM analysis,
FLUX image generation, palette extraction, background removal). It is a
**sibling of `bte/`**, not a child. BTE calls it over HTTP.

## Hard invariants

- **Thin gateway only.** Qwen3-VL runs on Spark 2 (vLLM). FLUX runs on
  Spark 1 (ComfyUI). svrnty-vision proxies — it does NOT load model
  weights or pull torch/transformers/diffusers in-process. Two exceptions
  permitted in Phase 4b: `palette` (Pillow + colorthief) and `rembg`
  (rembg lib) — both CPU-light, no GPU.
- **No cloud VLM providers.** The whole point of this extraction is to
  delete Anthropic/OpenAI/Google/Higgsfield SDK dependencies from BTE.
  Do not reintroduce them here. Sovereign-first.
- **Secrets via env only.** No keys in code, logs, or argv. Use
  `pydantic-settings` + `.env` (gitignored).
- **Stay in Python ≥3.11.** Workspace standard.

## Phase status

| Phase | Scope | State |
|---|---|---|
| 4a | Scaffold: FastAPI shell, `/healthz`, four 501 stubs, tests | **done (this commit)** |
| 4b | Port real implementations from BTE; HTTP clients for Spark 1/2 | not started |
| 4c | Delete the corresponding .NET code from BTE | not started |
| 4d | Wire BTE to call svrnty-vision over HTTP via thin adapter | not started |

See `/home/svrnty/workspaces/hermes/sot/01-ROADMAP/BTE-REFACTOR-EXECUTION-PLAN.md`
and `/home/svrnty/workspaces/hermes/bte/docs/REFACTOR-AUDIT-2026-05-24.md` §3 V.

## Layout

```
src/svrnty_vision/
    server.py        # FastAPI app + /healthz + router includes
    settings.py      # pydantic-settings (env-driven)
    routers/
        vlm.py       # POST /vlm/analyze     (501 stub → Spark 2)
        flux.py      # POST /flux/render     (501 stub → Spark 1)
        palette.py   # POST /palette/extract (501 stub → in-process)
        rembg.py     # POST /rembg/cutout    (501 stub → in-process)
tests/
    test_healthz.py  # TestClient smoke
```

## Run / test

```sh
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pip install -e .                                  # required: src/ layout
uvicorn svrnty_vision.server:app --port 8090     # serve
pytest tests/                                     # test
```

## Git

- Default branch: `jp` (workspace convention).
- Local-only until JP authorises the gitea push:
  `git remote add openharbor git@git.openharbor.io:svrnty/svrnty-vision.git`
  then `git push -u openharbor jp`.

## When extending

- New endpoint? Add a router under `src/svrnty_vision/routers/`, register
  it in `server.py`, add a test in `tests/`.
- New Spark dependency? Add the URL to `settings.py` and `.env.example`,
  never hardcode.
- Surgical changes only. Don't refactor adjacent stubs while implementing
  one — each phase has its own commit.