Spaces:
No application file
No application file
File size: 3,832 Bytes
b7cdd54 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | ---
title: Project Agent
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
---
# Project Agent
Project Agent is a FastAPI web app that turns a rough project idea into a **100% runnable starter project** preview, then creates a ZIP only after the user confirms it. The deployed app is designed to stay usable for free on Hugging Face Spaces even when no Ollama service is available.
## Features
- Suggest -> Preview -> Regenerate -> Confirm ZIP workflow
- Fast/Deep generation modes with Fast Mode as the default
- Template-first project generation with required docs, scripts, and dependency files
- Safe fallback previews when AI is unavailable, slow, or invalid
- ZIP output that contains generated source, config, scripts, and docs only
- Safe path validation and generated output constrained to `generated/`
- Docker-ready deployment for Hugging Face Spaces
## Requirements
The app depends on:
- `fastapi`
- `uvicorn[standard]`
- `jinja2`
- `python-dotenv`
- `httpx`
## Run Locally
Install dependencies:
```bash
pip install -r requirements.txt
```
Start the app with the default Hugging Face-friendly port:
```bash
python -m app.main
```
Or run Uvicorn directly:
```bash
uvicorn app.main:app --host 0.0.0.0 --port 7860
```
To use a different port:
```bash
PORT=8000 python -m app.main
```
Then open `http://127.0.0.1:7860` or the port you set.
## Environment Variables
Optional app/runtime variables:
```env
PORT=7860
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5-coder
```
Notes:
- `PORT` defaults to `7860`, which matches Hugging Face Spaces.
- If `OLLAMA_BASE_URL` is missing or unreachable, Fast Mode still works by returning a complete template-based preview.
- Deep Mode remains optional. If AI is unavailable, the app still returns a valid preview and notes that Deep AI enrichment was skipped.
## Hugging Face Spaces Deployment
Deploy this project as a **Docker Space**.
### 1. Create the Space
- Create a new Space on Hugging Face
- Choose **Docker** as the Space SDK
- Push this repository to the Space
### 2. Container Runtime
The included `Dockerfile` starts the app with:
```bash
uvicorn app.main:app --host 0.0.0.0 --port 7860
```
The container also supports `PORT` overrides through the environment and defaults to `7860`.
### 3. Free Deployment Behavior
For the free public version, you do **not** need cloud Ollama.
- Fast Mode works without Ollama by using template fallback
- Deep Mode attempts AI enrichment only if Ollama is reachable
- If Ollama is unavailable, the app still returns a complete preview instead of failing
### 4. Optional AI Configuration
If you later want AI-backed planning on a deployment that can reach Ollama, set:
```env
OLLAMA_BASE_URL=https://your-ollama-endpoint
OLLAMA_MODEL=qwen2.5-coder
```
If those values are not set, the app remains usable in fallback mode.
## ZIP Output Behavior
Generated ZIPs:
- do not include installed libraries
- do not include `.venv`
- do not include `node_modules`
- do include dependency manifests, setup scripts, run scripts, starter code, and generated docs
This keeps ZIP creation compatible with Hugging Face temporary storage.
## API Endpoints
- `GET /` renders the frontend
- `POST /api/suggest` returns a normalized project preview
- `POST /api/zip` writes the confirmed project into `generated/` and returns a download URL
- `GET /downloads/{filename}` downloads the generated ZIP
## Deployment Notes
- Generated project artifacts are written only inside `generated/`
- The app assumes ephemeral writable storage is acceptable for preview ZIP downloads
- No dependency installation happens during preview or ZIP creation
|