---
sdk: docker
emoji: 🚀
colorFrom: green
colorTo: yellow
pinned: true
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/66367933cc7af105efbcd2dc/vyiXnaRZq9vZMNYDBtIfw.png
---
# PromptForge v4.0

> **Structured prompt generator for Google AI Studio.**
> Transform any instruction into a production-ready prompt — with role, constraints, style, safety guardrails, and few-shot examples — via a polished dark-first web UI.

---

## What's New in v4.0

| Feature | Detail |
|---|---|
| **2 new personas** | `devops_eng` and `ml_engineer` |
| **Stats dashboard** | Real-time bar charts, status breakdown, refinement count |
| **Batch generate** | Up to 10 prompts in a single API call |
| **Full-text search** | `GET /api/search?q=…` across all stored prompts |
| **Duplicate setting** | One-click copy of any saved instruction setting |
| **Favourite / archive** | Star prompts and settings; archive completed work |
| **API key validation** | Live ✓ key-check endpoint for HF and Google |
| **Model override** | Use any HF or Gemini model, not just the defaults |
| **Dark/light theme** | Persistent theme, toggled with `Alt+T` |
| **Keyboard shortcuts** | Full keyboard navigation (press `?` to see all) |
| **Retry + backoff** | AI calls now retry up to 3× with exponential backoff |
| **Word count** | Every generated prompt shows its word count |
| **Auto-tagging** | Tags are inferred from instruction text automatically |
| **6 seeded settings** | React, FastAPI, Blog, SQL, Docker/CI, LLM Fine-tuning |

---

## Project Structure

```
promptforge_v4/
├── backend/
│   ├── main.py               # FastAPI app — all routes
│   ├── schemas.py            # Pydantic v2 models
│   ├── prompt_logic.py       # Core generation engine
│   ├── ai_client.py          # HuggingFace + Google Gemini client
│   ├── store.py              # Prompt manifest persistence
│   └── instruction_store.py  # Instruction settings persistence
├── frontend/
│   ├── index.html            # Single-page app (4 pages)
│   ├── style.css             # Dark-first design system
│   └── client.js             # Vanilla JS — all UI logic
├── tests/
│   └── test_promptforge.py   # 60+ pytest tests
├── logs/                     # Auto-created; holds .json stores
├── requirements.txt
├── .env.example
└── README.md
```

### File rename table (original → v4.0)

| Uploaded filename | Correct path |
|---|---|
| `deepseek_python_20260217_9f4e5a.py` | `backend/main.py` |
| `deepseek_python_20260217_2030de.py` | `backend/schemas.py` |
| `deepseek_python_20260217_5bfa10.py` | `backend/prompt_logic.py` |
| `deepseek_python_20260217_6a4c4c.py` | `backend/ai_client.py` |
| `deepseek_python_20260217_eb3ef8.py` | `backend/store.py` |
| `deepseek_python_20260217_c1c990.py` | `backend/instruction_store.py` |
| `deepseek_html_20260217_cdc933.html` | `frontend/index.html` |
| `deepseek_css_20260217_6dc1e7.css`   | `frontend/style.css` |
| `deepseek_javascript_20260217_99ef58.js` | `frontend/client.js` |
| `deepseek_txt_20260217_77ef1d.txt`   | `requirements.txt` |

---

## Quick Start

### 1. Create virtual environment

```bash
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

### 2. Set environment variables (optional)

```bash
cp .env.example .env
# Edit .env — all variables are optional for local use
```

### 3. Run the server

```bash
cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 7860
```

Open **http://localhost:7860** in your browser.

### 4. Run tests

```bash
cd backend
pytest ../tests/test_promptforge.py -v --asyncio-mode=auto
```

---

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `7860` | Server port |
| `LOG_DIR` | `logs` | Directory for JSON persistence files |
| `HF_API_KEY` | _(empty)_ | Hugging Face API key for AI enhancement |
| `GOOGLE_API_KEY` | _(empty)_ | Google AI Studio API key |

---

## 5-Step Workflow

```
1. INPUT     → Enter your instruction (+ persona, style, constraints)
2. REVIEW    → Edit any generated field in the manifest
3. FINALISE  → Approve → ready to copy into Google AI Studio
4. EXPORT    → Download as JSON or plain text
5. REFINE    → Describe changes → new version is created
```

---

## API Reference

### System

| Method | Endpoint | Description |
|---|---|---|
| GET | `/health` | Liveness check |
| GET | `/api/config` | Env key status + model defaults |
| GET | `/api/stats` | Dashboard metrics |
| POST | `/api/check-key` | Validate HF or Google API key |

### Instruction Settings

| Method | Endpoint | Description |
|---|---|---|
| POST | `/api/instructions` | Create setting |
| GET | `/api/instructions` | List (supports `?tag=`, `?q=`, `?favorites_only=true`) |
| GET | `/api/instructions/tags` | All tag values |
| GET | `/api/instructions/export` | Export all as JSON |
| GET | `/api/instructions/{id}` | Get single setting |
| PATCH | `/api/instructions/{id}` | Update setting |
| DELETE | `/api/instructions/{id}` | Delete setting |
| POST | `/api/instructions/{id}/duplicate` | Clone setting |
| POST | `/api/instructions/{id}/favorite` | Toggle favourite |
| POST | `/api/instructions/bulk-delete` | Bulk delete |

### Prompts

| Method | Endpoint | Description |
|---|---|---|
| POST | `/api/generate` | Generate prompt from instruction |
| POST | `/api/generate/from-settings` | Generate from saved setting |
| POST | `/api/generate/batch` | Generate up to 10 at once |
| GET | `/api/explain/{id}` | Explain prompt structure decisions |
| POST | `/api/approve` | Approve (+ optional field edits) |
| POST | `/api/export` | Export approved prompt |
| POST | `/api/refine` | Refine with feedback → new version |
| POST | `/api/prompts/{id}/favorite` | Toggle prompt favourite |
| POST | `/api/prompts/{id}/archive` | Archive prompt |
| GET | `/api/search?q=…` | Full-text search across prompts |

### History

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/history` | List all prompts (supports filters) |
| GET | `/api/history/{id}` | Get full prompt manifest |
| DELETE | `/api/history/{id}` | Delete prompt |
| POST | `/api/history/bulk-delete` | Bulk delete |

---

## Keyboard Shortcuts

| Shortcut | Action |
|---|---|
| `⌘↵` / `Ctrl+↵` | Generate prompt |
| `Alt+B` | Toggle sidebar |
| `Alt+T` | Toggle light/dark theme |
| `Alt+1–4` | Navigate between pages |
| `?` | Show shortcuts panel |
| `Esc` | Close modal / cancel |

---

## Available Personas

| Value | Description |
|---|---|
| `default` | Auto-detects from instruction keywords |
| `senior_dev` | Senior full-stack Software Engineer |
| `data_scientist` | ML / statistics / data pipelines |
| `tech_writer` | Technical documentation specialist |
| `product_mgr` | User-centric product management |
| `security_eng` | OWASP, threat modelling, secure-by-design |
| `devops_eng` | CI/CD, Kubernetes, cloud-native (**new**) |
| `ml_engineer` | LLM fine-tuning, MLOps, PEFT (**new**) |
| `custom` | Any free-text persona |

---

## Cloud Deployment

### Hugging Face Spaces (Dockerfile)

```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY backend/ ./backend/
COPY frontend/ ./frontend/
EXPOSE 7860
CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "7860"]
```

### Railway / Render / Fly.io

```bash
# Set start command:
uvicorn backend.main:app --host 0.0.0.0 --port $PORT
```

Set `HF_API_KEY` and/or `GOOGLE_API_KEY` as environment variables in your dashboard.

---

## Security Notes

- API keys entered in the UI are **never logged or persisted** server-side.
- CORS is open (`*`) by default — restrict `allow_origins` for production.
- All environment variables are read at startup; no secrets in source code.
- Input lengths are validated via Pydantic; all outputs are HTML-escaped in the UI.

---

## License

MIT — use freely, contribute back.