2a90c3f884
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>
79 lines
3.0 KiB
Markdown
79 lines
3.0 KiB
Markdown
# 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.
|