metadata

title: FaceForge
emoji: 🧑‍🎨
colorFrom: indigo
colorTo: pink
sdk: gradio
sdk_version: 4.44.1
app_file: app.py
pinned: false

faceforge

Interactive latent space editor for face generation using pretrained GANs and diffusion models.

🚀 Deploy on Hugging Face Spaces (Recommended)

FaceForge is ready to run as a Gradio app on Hugging Face Spaces:

Push your code to a public GitHub repository.
Create a new Space at https://huggingface.co/spaces (choose the Gradio SDK or Docker SDK).
Add your requirements.txt and the provided Dockerfile to your repo.
Set the entrypoint to app.py (which integrates both the API and UI components).
Deploy! Your app will be live at https://<your-username>.hf.space.

Example Dockerfile (already included):

FROM huggingface/transformers:latest
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install --no-cache-dir transformers
COPY . .
EXPOSE 7860
ENV PYTHONPATH="/app"
ENV PYTHONUNBUFFERED=1
ENV API_URL="/api"
ENV MOCK_API="true"
ENV BASE_URL=""
CMD ["python", "app.py"]

Local Development (Optional)

You can still run FaceForge locally:

pip install -r requirements.txt
python main.py

This will start the integrated application with both the API and UI components available:

UI accessible at http://localhost:7860/
API accessible at http://localhost:7860/api/

Architecture

FaceForge uses a modular architecture:

Core Components (faceforge_core/): Core algorithms and utilities
API Layer (faceforge_api/): FastAPI endpoints for model interaction
UI Layer (faceforge_ui/): Gradio interface for user interaction

The main application integrates these components into a single FastAPI application where:

The API is mounted at /api/
The Gradio UI is mounted at the root path /

Features

Latent space exploration and manipulation
Attribute direction discovery (PCA/classifier)
Custom attribute-preserving loss
Modular, testable core
Gradio UI for interactive exploration

Controls (Gradio UI)

Enter prompts (comma-separated)
Choose sampling mode (distance/circle)
Adjust player position sliders
Click "Generate" to see results

Testing

Run all tests with:

pytest tests/

Debugging

If you encounter Gradio schema-related errors like:

TypeError: argument of type 'bool' is not iterable

The application includes a patch that should fix the issue automatically. This patch addresses a known issue with schema processing in older Gradio versions.

Common Issues:

API Connection Errors

If you see errors like:

Invalid URL '/api/generate': No scheme supplied. Perhaps you meant https:///api/generate?

This indicates an issue with URL formatting. The application should handle this automatically with the following settings:

For the integrated app, set BASE_URL="" in the environment
For separate UI/API components, set BASE_URL="http://localhost:7860" (or your server URL)
Using relative URLs within the same server requires the correct base URL configuration

The updated app uses proper URL formatting that works in both integrated and separated modes.

Missing Dependencies

If you see errors about missing Python packages like transformers, you have options:

Install the missing package: pip install transformers
Use mock mode: Set MOCK_API="true" in environment variables
Use the Docker image which includes all dependencies: docker build -t faceforge .

Environment Variables

MOCK_API: Set to "true" to use mock API responses (for testing without ML dependencies)
API_URL: Override the API endpoint URL
BASE_URL: Base URL for relative API paths (leave empty for integrated deployment)
PORT: Set the port for the server (default: 7860)

Notes

The backend and frontend are fully integrated for Spaces deployment.
The application will use the actual ML framework when dependencies are available, and fall back to mock implementations when they're missing.
For custom model integration, edit the core and backend modules as needed.