init: project structure with LAION scorer, conda setup, and research docs

2026-08-23 15:31:47 +00:00
commit 4f90f5838a
25 changed files with 1628 additions and 0 deletions
@@ -0,0 +1,85 @@
+# Project Scripts
+
+## Setup Scripts
+
+### `setup.bat` (Windows) / `setup.sh` (Linux/Mac)
+
+Creates a new conda environment and installs all required packages from `requirements.txt`.
+
+**What it does:**
+
+1. Checks that conda is installed
+2. Creates a conda environment named `photo_judgers` with Python 3.11
+3. Installs all packages from `requirements.txt`:
+   - `torch`, `torchvision`, `torchaudio` (PyTorch with CUDA 12.1)
+   - `transformers` (HuggingFace)
+   - `simple-aesthetics-predictor` (LAION aesthetic predictor)
+   - `Pillow` (image processing)
+   - `tqdm` (progress bars)
+   - `numpy` (numerical operations)
+
+**Usage:**
+
+```bash
+# Windows
+setup.bat
+
+# Linux/Mac
+chmod +x setup.sh
+./setup.sh
+```
+
+## Run Scripts
+
+### `run.bat` (Windows) / `run.sh` (Linux/Mac)
+
+Activates the conda environment and runs the scorer.
+
+**What it does:**
+
+1. Activates the `photo_judgers` conda environment
+2. Runs `python -m src.scorer` with any additional arguments passed through
+
+**Usage:**
+
+```bash
+# Windows
+run.bat
+
+# Linux/Mac
+chmod +x run.sh
+./run.sh
+```
+
+**Optional arguments:**
+
+- `--input <path>` — Directory or file to score
+- `--output <path>` — Output JSON file (default: `output.json`)
+- `--threshold <value>` — Score threshold for keep/reject (default: TBD)
+
+## Project Structure
+
+```
+photo_judgers/
+├── src/
+│   ├── __init__.py
+│   ├── scorer.py          # Menu + proxy (entry point)
+│   └── scorers/
+│       ├── __init__.py
+│       ├── base.py         # BaseScorer abstract class
+│       └── laion.py        # LAION V2 implementation
+├── requirements.txt
+├── setup.bat / setup.sh
+├── run.bat / run.sh
+├── output.json             # Generated by scorer
+├── docs/
+├── test/
+└── .pi/
+```
+
+## Adding a New Scorer
+
+1. Create `src/scorers/<name>.py` with a class that follows the LAION pattern
+2. Register it in `src/scorer.py` by adding to the `SCORERS` list
+3. Add any new dependencies to `requirements.txt`
+4. Update `src/scorers/__init__.py` to export the new class