How ai4sociaty/apex works
Project type and purpose
• Project Type: Full-stack AI web application for agentic, iterative portrait generation.
• Purpose: Collect user style preferences, generate an initial portrait using a diffusion model (Flux), evaluate with a vision-language model, refine prompts via an LLM, loop until quality thresholds are met, and deliver a polished portrait.
File structure
• Top-level directories:
• apex/ – Python package (config, core logic, models, utils; skip ui/gradio_interface per instructions)
• backend/ – Two microservice folders: flux_server and vllm_server
• web-app/ – React + TypeScript frontend (Vite build)
• data/ – Persistent JSON profiles (+ uploads folder)
• tests/ – Unit tests for backend core logic
• Key files:
• app.py – Python entry point (“API Gateway”)
• user_form*.py – Legacy CLI forms (deprecated)
• setup.py, requirements.txt – Backend packaging & dependencies
• web-app/src – Components, utils, constants, types
README insights
• The high-level workflow:
[User Form Input] → [LLM Style Planner] → [Flux Generation] → [VLM Judge + Scoring] → [LLM Prompt Refiner] → (loop) → [Post-Processing]
• Technologies: React (web-app), Python (apex package), Transformers, Diffusers, PyTorch, CLIP, aesthetic-score
• Microservices: Separate servers for Flux diffusion (flux_server) and vLLM inference (vllm_server)
Main components
a. Frontend (blue)
• React web-app (web-app/src)
• Components: PortraitForm, UI elements (Button, Input, etc.)
• Builds via Vite; served on :3000
b. API Gateway / Backend Orchestrator (green)
• app.py exposing HTTP endpoints (e.g., /generate)
• ProfileManager & PromptGenerator (apex/core)
• Config (apex/config/settings.py) and Validators (apex/utils/validators.py)
c. Microservices (orange)
• Flux Diffusion Server (backend/flux_server)
• vLLM Server (backend/vllm_server)
• Communicate over HTTP or RPC; each has its own requirements.txt and startup script
d. Data Storage (gray)
• JSON profiles (data/profiles)
• Uploaded reference images (data/uploads)
e. External ML Libraries & Services (purple)
• Transformers & Diffusers (flux prompt generation & image synthesis)
• CLIP (“clip-by-openai”) for scoring
• aesthetic-score for quality assessment
Relationships and interactions
1. User fills form in React → submits via REST call to Python backend
2. Backend (app.py) invokes ProfileManager to validate and save profile JSON
3. PromptGenerator produces initial Flux prompt
4. Backend sends prompt to Flux Server → receives generated image
5. Backend sends image + prompt to vLLM Server for scoring/feedback
6. Based on scores, PromptGenerator refines prompt → repeat steps 4–5
7. Once threshold met, backend applies optional post-processing (e.g., upscaling)
8. Final image returned to frontend for display/download
Architectural patterns & design principles
• Separation of concerns: UI vs. orchestration vs. ML inference
• Modular Python package (apex) for core logic, config, models, utils
• Microservices for scalability and independent scaling of heavy ML tasks
• Agentic loop pattern: iterative prompt→generate→evaluate→refine
• Persistence: JSON profiles on disk, enabling reproducibility & local storage