---
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](https://huggingface.co/spaces):

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

### Example Dockerfile (already included):
```Dockerfile
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:

```bash
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:

1. **Core Components** (`faceforge_core/`): Core algorithms and utilities
2. **API Layer** (`faceforge_api/`): FastAPI endpoints for model interaction
3. **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:
```bash
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:

1. For the integrated app, set `BASE_URL=""` in the environment
2. For separate UI/API components, set `BASE_URL="http://localhost:7860"` (or your server URL)
3. 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:

1. Install the missing package: `pip install transformers`
2. Use mock mode: Set `MOCK_API="true"` in environment variables
3. 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.