Commercial-grade realtime GIF generation system. Includes a LangGraph agent for orchestration, a Klein4B+BFS head-swap image editor, a GIF generation interface (TBD), and a high-performance FastAPI server.

src/gifstudio/
├── __init__.py
├── __main__.py
├── cli.py                  # CLI entry point (run / graph / serve)
├── config.py               # pydantic-settings, GIFSTUDIO_ env prefix
├── api.py                  # FastAPI server (uvicorn + orjson + uvloop)
├── agent/
│   ├── state.py            # AgentState(MessagesState)
│   ├── graph.py            # LangGraph: START → router → tools → finalize → END
│   ├── nodes.py            # router_node, tool_node, finalize_node
│   └── tools.py            # @tool edit_image, @tool generate_gif
├── image_edit/
│   ├── base.py             # ImageEditor ABC, ImageEditRequest/Result
│   └── klein_headswap.py   # Klein4B + BFS head-swap backend
└── gif_gen/
    └── base.py             # GifGenerator ABC, GifGenRequest/Result (impl TBD)

# Install dependencies
pip install langgraph langchain-core langchain-google-genai pydantic-settings \
    fastapi "uvicorn[standard]" orjson python-multipart

# Editable install
pip install -e /home/echonlab/workspace/gifstudio

All settings use the GIFSTUDIO_ environment variable prefix. Copy .env.example and fill in your values:

cp .env.example .env

Variable	Default	Description
GIFSTUDIO_LLM_PROVIDER	google	LLM provider (google or openai)
GIFSTUDIO_LLM_MODEL	gemini-2.0-flash	Model name
GIFSTUDIO_LLM_API_KEY	—	API key
GIFSTUDIO_LLM_TEMPERATURE	0.0	Sampling temperature
GIFSTUDIO_DEVICE	cuda	Torch device
GIFSTUDIO_DTYPE	bfloat16	Torch dtype
GIFSTUDIO_KLEIN_MODEL_DIR	~/workspace/models/FLUX.2-klein-4B	Klein4B model directory
GIFSTUDIO_KLEIN_LORA_PATH	~/workspace/models/BFS-Best-Face-Swap/bfs_head_v1_flux-klein_4b.safetensors	BFS LoRA weights
GIFSTUDIO_FLUX2_SRC	~/workspace/flux2/src	BFL source root
GIFSTUDIO_OUTPUT_DIR	./output	Output directory

# Show help
gifstudio --help

# Run agent with a prompt
gifstudio run "swap the head in body.png with face.png" --image body.png

# Print agent graph structure
gifstudio graph

# Start API server
gifstudio serve --host 0.0.0.0 --port 8000

Also supports python -m gifstudio.

# Start
gifstudio serve --port 8000
# or
uvicorn gifstudio.api:app --host 0.0.0.0 --port 8000

Method	Path	Description
GET	/health	Health check, reports GPU load status
POST	/v1/headswap	Head-swap: upload body + face images
GET	/v1/headswap/result/{filename}	Download result image
POST	/v1/gif	Generate GIF (backend TBD)

curl -X POST http://localhost:8000/v1/headswap \
  -F "body_image=@body.png" \
  -F "face_image=@face.png" \
  -F "prompt=" \
  -F "seed=42" \
  -F "width=512" \
  -F "height=512"

Response:

{
  "output_path": "output/headswap_a1b2c3d4.png",
  "elapsed_ms": 1234.5,
  "metadata": {"seed": 42, "width": 512, "height": 512}
}

• FastAPI + Starlette — fastest Python web framework, async-native
• ORJSONResponse — orjson serialization (3-10x faster than stdlib json)
• uvicorn + uvloop — C-level event loop for near-native throughput
• ThreadPoolExecutor — GPU work offloaded so the event loop never blocks
• Startup warmup — model loaded on server start, first request pays no loading cost