Skip to content

Commit 9bfec86

Browse files
apartsinapartsin
committed
Add YAML session config and visual sample checks
1 parent 938a8b1 commit 9bfec86

79 files changed

Lines changed: 3319 additions & 343 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ dist/
3030
# Local environment and secrets
3131
.env
3232
.env.*
33+
.envrc
34+
*.secrets
35+
secrets/
36+
local.env
3337

3438
# Logs
3539
*.log

‎INSTALL.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ Published HTML documentation:
66

77
- [GitHub Pages Docs](https://apartsinprojects.github.io/StableSteering/)
88

9+
Recommended reading before installation:
10+
11+
- [Student Tutorial](./docs/student_tutorial.md)
12+
- [Quick Start](./docs/quick_start.md)
13+
- [User Guide](./docs/user_guide.md)
14+
915
## Requirements
1016

1117
- Windows with PowerShell
@@ -88,6 +94,7 @@ http://127.0.0.1:8000
8894
Useful runtime pages:
8995

9096
- `http://127.0.0.1:8000/`
97+
- `http://127.0.0.1:8000/setup`
9198
- `http://127.0.0.1:8000/diagnostics/view`
9299
- `http://127.0.0.1:8000/sessions/{session_id}/trace-report`
93100

@@ -122,7 +129,9 @@ npm run test:e2e:real
122129

123130
- The normal app runtime is GPU-only and uses the real Diffusers backend.
124131
- The mock generator is reserved for tests and explicit test harnesses only.
132+
- The normal user flow starts from the user's text prompt on `/setup`.
125133
- Round generation and feedback submission run as async jobs with visible progress in the UI.
126134
- Trace logs are written under `data/traces/`.
127135
- Per-session trace bundles and readable `report.html` files are written under `data/traces/sessions/<session_id>/`.
128136
- You can generate a complete real GPU example bundle with `python scripts/create_real_e2e_example.py`.
137+
- The docs site is generated locally with `python scripts/build_pages_site.py`.

‎README.md‎

Lines changed: 140 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,97 @@
1-
# StableSteering
1+
<p align="center">
2+
<img src="./docs/assets/readme_banner.png" alt="StableSteering banner" width="100%">
3+
</p>
24

3-
StableSteering is a research documentation repository for an interactive system that studies prompt-embedding steering for text-to-image diffusion models.
5+
<h1 align="center">StableSteering</h1>
46

5-
The runtime app is now GPU-only by default and expects CUDA-backed Diffusers inference.
7+
<p align="center">
8+
Interactive steering for diffusion image generation, from a user text prompt to preference-guided refinement.
9+
</p>
610

7-
Published HTML documentation:
11+
<p align="center">
12+
<a href="https://apartsinprojects.github.io/StableSteering/">Docs Site</a> ·
13+
<a href="./docs/quick_start.md">Quick Start</a> ·
14+
<a href="./docs/configuration_manual.md">Configuration Manual</a> ·
15+
<a href="./docs/student_tutorial.md">Student Tutorial</a> ·
16+
<a href="./docs/user_guide.md">User Guide</a> ·
17+
<a href="./docs/developer_guide.md">Developer Guide</a>
18+
</p>
819

9-
- [GitHub Pages Docs](https://apartsinprojects.github.io/StableSteering/)
20+
## What It Is
1021

11-
The current repository contains the specification set used to define the project before implementation:
12-
13-
- [Motivation](./docs/motivation.md)
14-
- [Theoretical Background](./docs/theoretical_background.md)
15-
- [System Specification](./docs/system_specification.md)
16-
- [System Test Specification](./docs/system_test_specification.md)
17-
- [Pre-Implementation Blueprint](./docs/pre_implementation_blueprint.md)
18-
- [Documentation Audit Ledger](./docs/document_audit.md)
19-
- [Quick Start](./docs/quick_start.md)
20-
- [User Guide](./docs/user_guide.md)
21-
- [Developer Guide](./docs/developer_guide.md)
22-
- [FAQ](./docs/faq.md)
23-
- [Install Guide](./INSTALL.md)
24-
- [Release Guide](./RELEASE.md)
25-
- [Release Notes v0.1.0](./RELEASE_NOTES_v0.1.0.md)
26-
- [System Improvement Roadmap](./docs/system_improvement_roadmap.md)
27-
- [Research Improvement Roadmap](./docs/research_improvement_roadmap.md)
22+
StableSteering is a research-oriented system for interactive image generation with diffusion models.
2823

29-
## Folder Guides
24+
Instead of relying on one-shot prompt rewriting, the system starts from a user text prompt, proposes multiple candidate directions, records user preferences, updates an internal steering state, and generates the next round from that evolving state.
3025

31-
Per-folder documentation is available in:
26+
The current repository includes both:
3227

33-
- [app/README.md](./app/README.md)
34-
- [app/bootstrap/README.md](./app/bootstrap/README.md)
35-
- [app/core/README.md](./app/core/README.md)
36-
- [app/engine/README.md](./app/engine/README.md)
37-
- [app/feedback/README.md](./app/feedback/README.md)
38-
- [app/frontend/README.md](./app/frontend/README.md)
39-
- [app/frontend/templates/README.md](./app/frontend/templates/README.md)
40-
- [app/frontend/static/README.md](./app/frontend/static/README.md)
41-
- [app/samplers/README.md](./app/samplers/README.md)
42-
- [app/storage/README.md](./app/storage/README.md)
43-
- [app/updaters/README.md](./app/updaters/README.md)
44-
- [tests/README.md](./tests/README.md)
45-
- [tests/e2e/README.md](./tests/e2e/README.md)
46-
- [scripts/README.md](./scripts/README.md)
47-
- [docs/README.md](./docs/README.md)
28+
- the original specification and research documents
29+
- a runnable FastAPI-based MVP with a real GPU-backed Diffusers backend
30+
- Gemini-generated visual assets used to make the Markdown and HTML docs easier to learn
4831

49-
## Repo Status
32+
## Why It Matters
5033

51-
This repository now contains:
34+
Text-to-image generation is powerful, but creative control is still awkward in practice.
35+
Users often know which result is better before they know how to rewrite the prompt that would produce it.
5236

53-
- the original research and specification documents
54-
- a runnable FastAPI-based MVP
55-
- a real GPU-backed Diffusers generation workflow
56-
- a deterministic mock generation path reserved for tests
57-
- rich backend logging and persisted trace events
58-
- per-session HTML trace reports that capture proposed images, user actions, and preference outcomes
59-
- frontend trace capture and visible trace panels
60-
- automated API, lifecycle, and browser tests including replay export smoke coverage
37+
StableSteering is built around that gap. It turns generation into a feedback loop:
6138

62-
## Recommended Reading Order
39+
1. start from a text prompt
40+
2. generate candidate images
41+
3. capture user preference
42+
4. update steering state
43+
5. generate a stronger next round
6344

64-
1. [Motivation](./docs/motivation.md)
65-
2. [Theoretical Background](./docs/theoretical_background.md)
66-
3. [System Specification](./docs/system_specification.md)
67-
4. [System Test Specification](./docs/system_test_specification.md)
68-
5. [Pre-Implementation Blueprint](./docs/pre_implementation_blueprint.md)
69-
6. [Quick Start](./docs/quick_start.md)
70-
7. [System Improvement Roadmap](./docs/system_improvement_roadmap.md)
71-
8. [Research Improvement Roadmap](./docs/research_improvement_roadmap.md)
45+
That makes the project useful both as:
46+
47+
- a research platform for studying human-in-the-loop steering
48+
- a concrete prototype for interactive generative workflows
49+
50+
## Current MVP
51+
52+
The current system includes:
53+
54+
- a FastAPI backend for experiments, sessions, async jobs, replay, diagnostics, and trace reporting
55+
- a real Diffusers-backed runtime on GPU by default
56+
- a mock generator reserved strictly for tests
57+
- SQLite-backed local persistence
58+
- backend and frontend tracing with per-session HTML reports
59+
- browser and backend test coverage
60+
- a real GPU-backed example-run generator with standalone HTML output
61+
62+
## User Flow
7263

73-
## Run Locally
64+
The main workflow is prompt-first:
65+
66+
1. the user opens `/setup`
67+
2. enters a text prompt
68+
3. creates a session
69+
4. generates a round of candidate images
70+
5. submits ratings or preferences
71+
6. waits for the async update job to finish
72+
7. inspects replay and the saved trace report
73+
74+
The normal runtime is GPU-only and uses the real Diffusers backend. If CUDA is unavailable, the app refuses to start instead of silently falling back.
75+
76+
## Getting Started
77+
78+
Install the project:
7479

7580
```bash
7681
python -m pip install -e .[dev]
77-
python scripts/run_dev.py
82+
python -m pip install -e .[dev,inference]
7883
```
7984

80-
Install real inference dependencies:
85+
Prepare model assets:
8186

8287
```bash
83-
python -m pip install -e .[dev,inference]
88+
python scripts/setup_huggingface.py
89+
```
90+
91+
Run the app:
92+
93+
```bash
94+
python scripts/run_dev.py
8495
```
8596

8697
Open:
@@ -89,86 +100,115 @@ Open:
89100
http://127.0.0.1:8000
90101
```
91102

92-
Run tests:
103+
Helpful pages:
104+
105+
- `http://127.0.0.1:8000/setup`
106+
- `http://127.0.0.1:8000/diagnostics/view`
107+
- `http://127.0.0.1:8000/sessions/{session_id}/trace-report`
108+
109+
## Read Next
110+
111+
Recommended reading order:
112+
113+
1. [Motivation](./docs/motivation.md)
114+
2. [Student Tutorial](./docs/student_tutorial.md)
115+
3. [Theoretical Background](./docs/theoretical_background.md)
116+
4. [System Specification](./docs/system_specification.md)
117+
5. [System Test Specification](./docs/system_test_specification.md)
118+
6. [Pre-Implementation Blueprint](./docs/pre_implementation_blueprint.md)
119+
7. [Quick Start](./docs/quick_start.md)
120+
8. [Configuration Manual](./docs/configuration_manual.md)
121+
9. [System Improvement Roadmap](./docs/system_improvement_roadmap.md)
122+
10. [Research Improvement Roadmap](./docs/research_improvement_roadmap.md)
123+
124+
Additional docs:
125+
126+
- [GitHub Pages Docs](https://apartsinprojects.github.io/StableSteering/)
127+
- [Install Guide](./INSTALL.md)
128+
- [Release Guide](./RELEASE.md)
129+
- [Release Notes v0.1.0](./RELEASE_NOTES_v0.1.0.md)
130+
- [Configuration Manual](./docs/configuration_manual.md)
131+
- [FAQ](./docs/faq.md)
132+
133+
## Run Tests
134+
135+
Backend tests:
93136

94137
```bash
95138
python -m pytest
96139
```
97140

98-
Run browser end-to-end tests in Chrome:
141+
Browser tests:
99142

100143
```bash
101144
npm install
102145
npm run test:e2e:chrome
103146
```
104147

105-
Run a headed Chrome debug session:
148+
Headed browser debug:
106149

107150
```bash
108151
npm run test:e2e:debug
109152
```
110153

111-
Prepare Hugging Face assets for the real generator:
154+
Real model smoke:
112155

113156
```bash
114-
python scripts/setup_huggingface.py
157+
python scripts/smoke_real_diffusers.py
115158
```
116159

117-
Bootstrap a fresh local machine:
160+
Real end-to-end example bundle:
118161

119162
```bash
120-
powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1
163+
python scripts/create_real_e2e_example.py
121164
```
122165

123-
Select the real Diffusers backend:
166+
## Repo Guides
124167

125-
```bash
126-
set STABLE_STEERING_GENERATION_BACKEND=diffusers
127-
python scripts/run_dev.py
128-
```
168+
Per-folder documentation is available in:
169+
170+
- [docs/README.md](./docs/README.md)
171+
- [app/README.md](./app/README.md)
172+
- [tests/README.md](./tests/README.md)
173+
- [scripts/README.md](./scripts/README.md)
174+
- [data/README.md](./data/README.md)
175+
- [models/README.md](./models/README.md)
176+
- [output/README.md](./output/README.md)
129177

130-
Real Diffusers inference is GPU-only. The app now targets `cuda` explicitly for
131-
model runs and will fail fast if a CUDA-capable GPU is not available. The
132-
default server runtime also enforces the `diffusers` backend and never falls
133-
back to mock automatically. The mock generator is reserved for explicit test
134-
harnesses only.
178+
## Banner Asset
135179

136-
Trace logs are persisted under `data/traces/`.
137-
Per-session reports are written under `data/traces/sessions/<session_id>/report.html` and are also available in the app at `/sessions/{session_id}/trace-report`.
180+
The README banner is stored at [docs/assets/readme_banner.png](./docs/assets/readme_banner.png).
138181

139-
Run a one-off real-model smoke test:
182+
It can be regenerated with:
140183

141184
```bash
142-
python scripts/smoke_real_diffusers.py
185+
python scripts/generate_readme_banner.py
143186
```
144187

145-
Create a full real GPU-backed example run with a readable HTML walkthrough:
188+
The generation script expects `GEMINI_API_KEY` in the environment and uses the official Gemini image-generation API.
146189

147-
```bash
148-
python scripts/create_real_e2e_example.py
149-
```
190+
## Diagrams And Illustrations
150191

151-
Build an optional release zip:
192+
The documentation layer can include Gemini-generated illustrations to make the Markdown and published HTML easier to scan.
152193

153-
```bash
154-
powershell -ExecutionPolicy Bypass -File scripts/build_release_zip.ps1 -Version v0.1.0
155-
```
194+
Current visual assets include:
156195

157-
Build the static HTML documentation site locally:
196+
- [docs/assets/readme_banner.png](./docs/assets/readme_banner.png)
197+
- [docs/assets/illustrations/steering_loop.png](./docs/assets/illustrations/steering_loop.png)
198+
- [docs/assets/illustrations/system_architecture.png](./docs/assets/illustrations/system_architecture.png)
199+
- [docs/assets/illustrations/trace_report.png](./docs/assets/illustrations/trace_report.png)
200+
201+
They can be regenerated with:
158202

159203
```bash
160-
python scripts/build_pages_site.py
204+
python scripts/generate_readme_banner.py
205+
python scripts/generate_doc_illustrations.py
161206
```
162207

208+
The Pages builder copies these assets into the generated HTML site automatically.
209+
163210
## Legacy Source
164211

165212
The original combined specification is preserved as:
166213

167214
- [Legacy Combined Spec](./docs/system_spec_legacy_combined.md)
168-
169-
## Next Suggested Steps
170-
171-
- expand browser coverage for pairwise and top-k feedback flows
172-
- add export packaging for session trace bundles
173-
- surface richer GPU diagnostics like adapter name and VRAM in the UI
174-
- add CI automation for the release packaging flow

‎RELEASE.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ A release should include:
99
- tagged source in Git
1010
- release notes
1111
- installation instructions
12+
- published HTML documentation
1213
- optional packaged zip artifact
1314
- updated user/developer docs for async jobs, trace reports, and example bundles
1415

@@ -27,14 +28,17 @@ Current release notes:
2728
`python scripts/smoke_real_diffusers.py`
2829
5. If releasing from a CUDA-capable machine, optionally refresh the real example bundle:
2930
`python scripts/create_real_e2e_example.py`
30-
6. Review:
31+
6. Rebuild the documentation site:
32+
`python scripts/build_pages_site.py`
33+
7. Review:
3134
- [INSTALL.md](E:\Projects\StableSteering\INSTALL.md)
3235
- [README.md](E:\Projects\StableSteering\README.md)
36+
- [docs/student_tutorial.md](E:\Projects\StableSteering\docs\student_tutorial.md)
3337
- [RELEASE_NOTES_v0.1.0.md](E:\Projects\StableSteering\RELEASE_NOTES_v0.1.0.md)
34-
7. Build a source zip if needed:
38+
8. Build a source zip if needed:
3539
`powershell -ExecutionPolicy Bypass -File scripts/build_release_zip.ps1 -Version v0.1.0`
36-
8. Create the Git tag.
37-
9. Push the tag and upload the zip if desired.
40+
9. Create the Git tag.
41+
10. Push the tag and upload the zip if desired.
3842

3943
## Suggested Tagging Flow
4044

@@ -53,4 +57,4 @@ The zip is written to `output/releases/`.
5357

5458
## Release Scope
5559

56-
The current release line is a research-oriented MVP. It is suitable for local development, evaluation, and architectural review, but not intended as a production deployment package.
60+
The current release line is a research-oriented MVP. It is suitable for local development, evaluation, teaching, and architectural review, but not intended as a production deployment package.

0 commit comments

Comments
 (0)