A CLI tool and Streamlit web UI that takes a raw biosensor file (signal or image) plus a plain-English description of the sensor and goal, audits it (deterministic math for signals, vision model + CV fallback for images), then generates, self-tests, and containerizes a custom preprocessing pipeline — with a self-healing retry loop if generated code fails.

Built for OpenAI Build Week 2026, using OpenAI's models in two distinct roles:

Development — Codex was used throughout development to generate and refine project files and code, including scaffolding the CLI structure and generated- pipeline templates, refactoring the sandboxing and self-test generation flow, and sharpening ideas during iteration (tightening error handling, fixing test isolation issues, improving the audit-report generator).

Runtime — GPT-5.6 is supported as one of several interchangeable, OpenAI- compatible LLM providers (see "LLM providers" below). When configured, it is used for interpreting biosensor files during audit (vision-based image analysis, signal reasoning), selecting preprocessing stages based on the sensor description and audit results, and explaining quality-impact metrics in plain language. If no LLM is configured, or a call fails/times out, the tool falls back to deterministic, offline-safe logic automatically.

Core (always installed):

• numpy >= 1.26 — array math
• scipy >= 1.11 — signal processing (bandpass, PSD, Savitzky-Golay)
• opencv-python-headless >= 4.8 — image processing
• pillow >= 10.0 — image I/O
• typer >= 0.12 — CLI framework
• pytest >= 8.0 — test runner
• rich >= 13.0 — styled terminal output

Optional — LLM support:

• openai >= 1.40 — enables LLM-powered stage selection and metric annotations

Optional — Web UI:

• streamlit >= 1.30 — browser-based interface with file upload, preview, and downloads

Optional — file watcher:

• watchdog >= 4.0 — efficient file change detection for watch mode

git clone https://github.com/KharfiIslam/BioPrep-AI.git
cd BioPrep-AI-main

python --version
# Must show 3.11 or higher

If you don't have Python 3.11+, download it from https://www.python.org/downloads/

Windows (double-click run.bat): A launcher menu will appear — pick option 3 to install, then 1 or 2 to run.

Or run from terminal:

# Install everything (core + LLM + web UI):
python -m pip install -e ".[ui,llm]"

# Or install only core (no LLM, no web UI):
python -m pip install -e .

# Or use requirements.txt directly:
python -m pip install -r requirements.txt

python scripts/make_samples.py

This creates demo files in samples/ (EEG CSV, ECG NPY, lateral-flow JPG).

python -m pytest tests/ -v
# Should show all tests passing

Windows: Double-click run.bat — a menu appears:

============================================
   preprocess-ops launcher
============================================

  Choose an option:

    1) CLI menu (terminal)
    2) Web UI (browser)
    3) Install / update dependencies
    4) Run tests
    5) Quit

  Enter number (1-5):

Pick 1 for the terminal menu, 2 for the browser UI.

Linux / macOS:

chmod +x run.sh
./run.sh

python -m preprocess_ops

A rich terminal menu guides you through:

1. Audit a file
2. Generate a pipeline (audit + sandbox + self-heal)
3. Full demo (generate → test → build → report)
4. Run tests
5. Build Dockerfile
6. Configure LLM
7. Launch web UI
8. Quit

# Audit a signal file:
python -m preprocess_ops audit samples/eeg_sample.csv \
  --describe "3-electrode dry EEG, want it clean for seizure classification"

# Generate a pipeline (offline, no LLM):
python -m preprocess_ops generate samples/eeg_sample.csv \
  --describe "dry EEG cleanup" --offline

# Generate with LLM + full report:
python -m preprocess_ops generate samples/lateral_flow_strip.jpg \
  --describe "lateral flow strip quantification" --offline

# Run all tests:
python -m preprocess_ops test

# Build Docker image:
python -m preprocess_ops build --run

# Batch process a directory:
python -m preprocess_ops batch samples/ --describe "batch cleanup" --offline

# Watch for file changes:
python -m preprocess_ops watch samples/eeg_sample.csv --poll 2

python -m streamlit run preprocess_ops/ui/streamlit_app.py

Opens http://localhost:8501 with four pages:

Every pipeline run creates these files in output/:

Every run computes before/after quality deltas:

╭──────────── QUALITY IMPACT ────────────╮
│  Noise (raw)      0.412                │
│  Noise (cleaned)  0.087   ▼ 78.9%      │
│  Sharpness (raw)  152.7                │
│  Sharpness (clean) 210.3   ▲ 37.7%     │
╰─────────────────────────────────────────╯

Metric annotations explain why each metric changed:

• LLM-generated — configured model explains each delta in plain English
• Rule-based — deterministic fallback using a stage-effect knowledge base
• Mixed — LLM explains some metrics, rule-based covers the rest

The HTML report bundles everything into a single shareable document:

1. Audit summary — modality, profiler, shape, sampling rate / lighting / blur / ROI
2. Quality impact — before/after metrics with percent deltas
3. Why metrics changed — LLM or rule-based annotations per metric
4. Sandbox result — pipeline source, attempts, transcript
5. Generated pipeline — full syntax-highlighted code
6. Test results — PASSED/FAILED with pytest output
7. Artifacts — file paths

Generate it with:

python -m preprocess_ops report --output-dir output/

Install LLM support:

python -m pip install -e ".[llm]"

Configure via CLI menu (option 6), web UI (LLM Config page), or environment variables. Settings can be saved to .preprocess_ops_llm.json for reuse.

Common flags: --describe/-d, --sampling-rate/-r, --offline, --output-dir/-o, --run-id, --roi "x,y,w,h", --json, -v/--verbose.

User input: file (CSV/NumPy or PNG/JPG) + free-text description
                    ↓
        [Modality Dispatcher] — routes by file type
        ↓                                    ↓
  [Signal Profiler]                   [Image Profiler]
  deterministic (scipy)               vision model call
  sampling rate, PSD peaks,           → on fail/timeout →
  amplitude, noise floor              CV fallback (OpenCV)
        ↓                                    ↓
              profile.json (unified schema)
                    ↓
        [Pipeline Synthesizer] (any OpenAI-compatible LLM)
        constrained stage plan inside fixed class template
                    ↓
        [Sandbox Execution + Self-Heal]
        run on sample → error/NaN? → retry once → trusted fallback
                    ↓
        [Quality Metrics] — before/after noise, RMS, contrast, sharpness
                    ↓
        [Metric Annotations] — LLM or rule-based explanations
                    ↓
        [Test Generator] → pytest contract test
                    ↓
        [Audit Report] → single HTML page
                    ↓
        [Containerizer] → Dockerfile

preprocess-ops/
├── run.bat                        # Windows launcher (double-click)
├── run.sh                         # Linux/macOS launcher
├── requirements.txt               # Dependency list
├── preprocess_ops/                # Python package
│   ├── cli.py                     # Typer CLI (menu + subcommands)
│   ├── service.py                 # Shared orchestration (run_pipeline)
│   ├── metrics.py                 # Before/after quality proxies
│   ├── annotations.py             # LLM + rule-based metric explanations
│   ├── report.py                  # HTML audit report renderer
│   ├── present.py                 # Rich terminal UI helpers
│   ├── llm.py                     # OpenAI-compatible LLM client
│   ├── audit/                     # Input file profiling
│   ├── filters/                   # Trusted preprocessing stages
│   ├── synth/                     # Pipeline code generation
│   ├── testgen/                   # Contract test generation
│   └── ui/                        # Streamlit web UI
│       └── streamlit_app.py       # 4-page interface
├── tests/                         # Test suite
├── samples/                       # Demo input files
├── docker/Dockerfile.template
├── scripts/make_samples.py
├── output/                        # Generated artifacts
└── pyproject.toml

• Deterministic where precision matters. Signal audit is pure scipy; never LLM-guessed numbers.
• Scaffolded generation. The model chooses stages from a trusted whitelist; method bodies stay inside a fixed class template.
• Self-healing. Sandbox-run every pipeline → one retry with error context → trusted fallback.
• Same contract across modalities. Both profilers emit a shared profile.json shape.
• Quantified proof. Every run produces before/after quality metrics with percent deltas.
• Transparent explanations. Metric annotations show source (LLM / rule-based / mixed).
• Provenance by default. HTML report bundles everything into a single shareable document.