Svrnty 2a90c3f884 feat: initial scaffold — FastAPI shell + stub vision routers

Phase 4a of the BTE refactor (audit 2026-05-24 §3 V). svrnty-vision is a
sovereign HTTP gateway in front of four vision capabilities — VLM (Spark 2
Qwen3-VL), FLUX image gen (Spark 1 ComfyUI), palette extraction, and
background removal. This commit lays only the scaffold: FastAPI app,
/healthz, four 501-stub routers, pydantic-settings config, pytest smoke.

Real implementations land in Phase 4b. BTE code is untouched in 4a.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-24 13:25:57 -04:00

3.0 KiB

Raw Blame History

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

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.

3.0 KiB Raw Blame History