Skip to content

Commit 4b35af2

Browse files
atharva557atharva557
committed
Revamp README: new features, Gemma 4 4B prompter example, accurate structure
- Features table covers reasoning-model handling, multi-file tabs/zip, version history with revert, pipeline profiles, context guards, preset auto-suggestion, quick mode, and persistent chats with pipeline handoff - Recommended Prompter is now Gemma 4 4B (~3 GB), with a note that thinking models work out of the box - How-it-works diagram updated: revise/quick-mode at the review step, per-file tabs and version diffs at the output step - Configuration table gains the VRAM swap policy row and corrects the idle auto-unload row (covers both roles, not just the coder) - Project structure adds core/chats.py and core/suggest.py, fixes the stale preset count, and notes the 144-test suite
1 parent 4d7bdf3 commit 4b35af2

1 file changed

Lines changed: 38 additions & 27 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,13 @@ Each role has its own backend, so you can keep the Prompter local and point the
3232
▼
3333
┌──────────────────────────────────────────────────────┐
3434
│ 2. Prompter Model (small / fast) │
35-
│ e.g. Phi-4 Mini · ~4 GB VRAM │
35+
│ e.g. Gemma 4 4B · ~3 GB VRAM │
3636
│ Rewrites your idea into a detailed prompt │
3737
└──────────────────┬───────────────────────────────────┘
3838
▼
3939
┌──────────────────────────────────────────────────────┐
40-
│ 3. You review, edit, or retry the generated prompt │
40+
│ 3. You review, edit, revise, or retry the prompt │
41+
│ (or skip this step entirely with Quick mode) │
4142
└──────────────────┬───────────────────────────────────┘
4243
▼
4344
┌──────────────────────────────────────────────────────┐
@@ -52,29 +53,35 @@ Each role has its own backend, so you can keep the Prompter local and point the
5253
└──────────────────┬───────────────────────────────────┘
5354
▼
5455
┌──────────────────────────────────────────────────────┐
55-
│ 6. Code streams to screen → saved to file │
56+
│ 6. Code streams in → per-file tabs → save/download │
57+
│ Refine in place, diff every version, revert │
5658
└──────────────────────────────────────────────────────┘
5759
```
5860

59-
The free local **review gate** at step 3 is the trick behind the hybrid mode: you fix the prompt on a local model for free, so the one expensive cloud generation lands right more often and you re-roll far less.
61+
The free local **review gate** at step 3 is the trick behind the hybrid mode: you fix the prompt on a local model for free, so the one expensive cloud generation lands right more often and you re-roll far less. After generation, a **refine loop** edits the code in place — every version diffed against the previous one and revertible in a click.
6062

6163
## 🎯 Features
6264

6365
| | Feature | Details |
6466
| --- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
65-
| 🔗 | **Two-model pipeline** | Prompter → review / edit → Coder |
66-
| 📡 | **Real-time streaming** | Token-by-token output via SSE, with tokens/sec stats |
67-
| 🧠 | **VRAM-aware model swapping** | Automatically unloads the Prompter before loading the Coder |
67+
| 🔗 | **Two-model pipeline** | Prompter → review / edit / revise → Coder, with a **Quick mode** that skips the review step entirely |
68+
| 📡 | **Real-time streaming** | Token-by-token SSE with live tokens/sec while it runs; exact billed tokens + a cost estimate for cloud generations |
69+
| 🤔 | **Reasoning models welcome** | `<think>` blocks and reasoning deltas (Qwen3 / DeepSeek-R1 style) stream into a collapsed panel — never into your prompt or code |
70+
| 🧠 | **VRAM-aware model swapping** | Unloads one local model before the other runs; set the policy to *never* if your GPU fits both, and idle models auto-unload after N min |
6871
| 🔌 | **Per-role backends** | Mix local and cloud: LM Studio, Ollama, any OpenAI-compatible server, plus OpenAI, Claude, and Gemini — chosen separately for each role |
6972
| 💸 | **Local Prompter + cloud Coder** | Refine prompts for free on a local model, then send one clean prompt to a frontier cloud Coder — fewer wasted paid generations |
70-
| 🔍 | **Auto model detection** | Installed models are detected and listed automatically |
71-
| 🕘 | **Run history** | Past runs persist across restarts; reopen or delete them from the sidebar |
73+
| 🎛️ | **Pipeline profiles** | Save the whole setup (backends, models, temperatures, system prompts) under a name and switch setups in one click |
74+
| 🗂️ | **Multi-file output** | Several fenced blocks render as per-file tabs, with a zip download and save-all into a timestamped folder; single files get auto language detection and suggested filenames |
75+
| ⏪ | **Version history** | Every refine/regenerate is diffed against the previous code — revert with one click |
7276
| ♻️ | **Refine in place** | Send a follow-up instruction ("make the board bigger") to edit the code without regenerating from scratch |
73-
| 💬 | **Direct chats** | ChatGPT-style pages for just the Prompter or just the Coder when you don't need the full pipeline |
77+
| 🛡️ | **Context guards** | Warns before a refine payload outgrows a small local context window, or a pasted-code task outgrows the Prompter's output budget |
78+
| 💡 | **Preset auto-suggestion** | Task keywords suggest a matching Prompter + Coder preset pair, applied in one click |
7479
| 📋 | **46 built-in presets** | Across General, Web Development, Data & Scripts, Games & Graphics, Systems & CLI, Testing, Debug & Refactor, Languages, and Machine Learning |
7580
| ✏️ | **Presets manager** | Browse and edit every preset; edits to built-ins are saved as overrides (reset to default anytime), plus create/delete your own |
76-
| 🗂️ | **Smart file output** | Auto language detection, suggested filenames, timestamped saves, browser download |
77-
| 🌙 | **Polished dark UI** | Clean Tokyo Night theme; tokens/sec for local runs and exact tokens + a cost estimate for cloud |
81+
| 💬 | **Direct chats** | ChatGPT-style pages for just the Prompter or just the Coder; conversations persist across restarts, and any chat-drafted prompt can jump straight into the pipeline |
82+
| 🕘 | **Run history** | Past runs persist across restarts; reopen or delete them from the sidebar |
83+
| 🔍 | **Auto model detection** | Installed models are detected and listed automatically |
84+
| 🌙 | **Polished dark UI** | Clean Tokyo Night theme |
7885

7986
## 📦 Requirements
8087

@@ -134,9 +141,10 @@ Each role (Prompter / Coder) is configured independently in **Settings**:
134141
| Base URL (per role) | per-backend | Editable for local/custom backends; fixed for cloud providers |
135142
| Model (per role) | — | Auto-detected from the server, or entered manually |
136143
| Temperature (per role) | 0.3 / 0.1 | Lower = more deterministic |
137-
| Max Tokens (per role) | 1024 / 4096 | Max output length |
138-
| Output Folder | `./output` | Where generated code files are saved |
139-
| Auto-unload coder | 5 min | Free local VRAM after the coder sits idle this long (`0` = never; local backends only) |
144+
| Max tokens (per role) | 1024 / 4096 | Max output length — the task page warns when a pasted-code task won't fit the Prompter's budget |
145+
| Output folder | `./output` | Where generated code is saved; multi-file runs get a timestamped subfolder |
146+
| Idle auto-unload | 5 min | Free local VRAM when the resident model (either role) sits idle this long (`0` = never; local backends only) |
147+
| VRAM swap policy | auto | *Auto* unloads one model before running the other; pick *never* if your GPU holds both — skips every unload/reload cycle |
140148

141149
**API keys** for the cloud backends are read from environment variables first — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` — and fall back to keys entered in Settings. Settings (including any typed-in keys) persist in `config.json` (git-ignored).
142150

@@ -146,10 +154,11 @@ Each role (Prompter / Coder) is configured independently in **Settings**:
146154

147155
### Prompter (small / fast)
148156

149-
| Model | VRAM | Notes |
150-
| -------------------- | ----- | ---------------------------------- |
151-
| Phi-4 Mini Reasoning | ~4 GB | Fast, great at reformulating tasks |
152-
| Qwen 2.5 3B | ~3 GB | Lightweight alternative |
157+
| Model | VRAM | Notes |
158+
| -------------------- | ----- | ------------------------------------------------------------ |
159+
| Gemma 4 4B | ~3 GB | Fast and precise at reformulating tasks — the sweet spot |
160+
| Phi-4 Mini Reasoning | ~4 GB | Reasoning-tuned alternative |
161+
| Qwen 2.5 3B | ~3 GB | Lightweight alternative |
153162

154163
### Coder (larger / code-focused)
155164

@@ -159,7 +168,7 @@ Each role (Prompter / Coder) is configured independently in **Settings**:
159168
| DeepSeek Coder V2 Lite | ~9 GB | Strong alternative |
160169
| Qwen 2.5 Coder 7B | ~5 GB | Good choice for 8 GB VRAM cards |
161170

162-
> **Tip:** Pair a ~3–4 GB Prompter with the largest Coder that fits in your remaining VRAM for the best results.
171+
> **Tips:** Pair a ~3–4 GB Prompter with the largest Coder that fits in your remaining VRAM. Thinking models (Qwen3, DeepSeek-R1 distills) work out of the box — their reasoning streams into a separate collapsed panel and never leaks into the prompt or code.
163172
164173
## 🗂️ Project Structure
165174

@@ -170,21 +179,23 @@ promptchain/
170179
├── run.bat / run.command / run.sh # Double-click launchers (Windows / macOS / Linux)
171180
├── core/
172181
│ ├── api.py # Backend API calls, model unload, cost estimates
173-
│ ├── config.py # Config & preset management
182+
│ ├── config.py # Config, presets & pipeline profiles
174183
│ ├── history.py # Persistent run history (history.json)
175-
│ └── streaming.py # Real-time SSE / SDK token streaming
184+
│ ├── chats.py # Persistent chat conversations (chats.json)
185+
│ ├── suggest.py # Keyword rules → suggested preset pair
186+
│ └── streaming.py # Real-time SSE / SDK token streaming + think-block filtering
176187
├── ui/
177188
│ ├── styles.py # Dark theme CSS + UI components
178189
│ ├── landing.py # Landing page
179190
│ ├── settings.py # Settings page (auto model detection)
180-
│ ├── task_input.py # Task input + preset selector
181-
│ ├── prompt_review.py # Prompt review / edit step
182-
│ ├── code_output.py # Side-by-side prompt/code, save & download
191+
│ ├── task_input.py # Task input, presets, profiles
192+
│ ├── prompt_review.py # Prompt review / edit / revise step
193+
│ ├── code_output.py # Output page: file tabs, versions, refine, save & download
183194
│ ├── chat.py # Direct Prompter / Coder chat pages
184195
│ └── presets.py # Presets manager
185196
├── presets/
186-
│ └── presets.json # 37 built-in system prompt presets
187-
├── tests/ # Pytest suite for the core helpers
197+
│ └── presets.json # 46 built-in system prompt presets
198+
├── tests/ # Pytest suite (144 tests)
188199
├── .streamlit/
189200
│ └── config.toml # Streamlit theme configuration
190201
├── requirements.txt # Runtime deps (+ requirements-dev.txt for tests)

0 commit comments

Comments
 (0)