Supporting Reference 1: Install and Setup

This page covers first-time environment preparation for source execution on Windows. Use it after the core path when you need a repeatable install baseline.

R1.1 Prerequisites

• Windows environment with Python 3.13 available as py -3.13.
• A working runtime venv with required dependencies (for example .venv313 or .venv).
• Ollama installed and available from terminal.
• Repository cloned locally (for example \path\to\amir2000_image_automation).
• Quality scoring weight file present in repo root: sac+logos+ava1-l14-linearMSE.pth.

R1.2 Configure environment-specific values

Before first run, set environment-specific values in amir2000_config.py (or environment variables if used in your setup).

• Publish targets: PUBLIC_URL_BASE, REMOTE_BASE.
• Database/FTP values: MySQL and FTP host/user/password/database settings.
• Local path roots: DATA_DIR, INCOMING_DIR, BASE_PICK_DIR, STAGED_DIR, REJECTED_DIR.
• Website path mapping values used by publish integration.
• Ollama host/port/model fields matching your local installation.

Do not run publish with invalid credentials or incorrect path values.

R1.3 Libraries used by the workflow

Base runtime libraries:

• pyinstaller (build tooling)
• pillow
• pyspellchecker
• piexif
• mysql-connector-python

Scoring and ML stack:

• numpy
• tqdm
• opencv-python
• pyiqa
• torch + torchvision (CPU or CUDA wheels, auto-selected by setup script)

These are installed by helpers/setup_venv313_full.ps1 and also validated by preflight.

R1.4 What setup_venv313_full.ps1 does

1. Removes existing .venv313 (clean rebuild).
2. Creates a fresh Python 3.13 virtual environment.
3. Upgrades pip.
4. Installs base runtime libraries.
5. Installs scoring/ML dependencies.
6. Detects NVIDIA via nvidia-smi and installs Torch CUDA wheels (cu121) when available; otherwise CPU wheels.
7. Verifies imports for core scoring libraries before finishing.

R1.5 Create runtime environment (recommended)

Set-Location "\path\to\amir2000_image_automation"
pwsh -NoProfile -ExecutionPolicy Bypass -File .\helpers\setup_venv313_full.ps1

R1.6 Initialize SQLite databases

Set-Location "\path\to\amir2000_image_automation"
.\.venv313\Scripts\Activate.ps1
python .\init_db.py

Creates data/review.db and data/photos_info_revamp.db from init SQL.

R1.7 Pull Ollama models

ollama pull llama3.2-vision:latest
ollama pull minicpm-v:latest

If your config uses different model names, pull those exact names before first run.

R1.8 First smoke run

Set-Location "\path\to\amir2000_image_automation"
.\.venv313\Scripts\Activate.ps1
ollama list
python .\main_set.py

• Import a small test set first.
• Confirm stage progression into review editor.
• Validate logs after run in logs/latest_run.log.

R1.8A EXE runtime pinning (recommended)

For EXE runs, pin the scoring/caption runtime explicitly to your Python 3.13 venv. This avoids mixed-interpreter DLL issues on some Windows setups.

Set-Location "\path\to\amir2000_image_automation"
$env:AMIR_PYTHON = ".\.venv313\Scripts\python.exe"
.\dist\Amir2000ImageAutomation-MultiSet.exe

In stage logs, verify the line Score runtime python: ... (ver=(3, 13)).

R1.9 What preflight_multiset.ps1 checks

This script performs environment and build-readiness validation before packaging.

1. Finds existing venv (.venv313, .venv, or .venv_cuda) or creates .venv313 automatically.
2. Upgrades pip and installs base/scoring dependencies in the venv.
3. Checks required files and folders (entry scripts, config, fonts, utils, vendor).
4. Checks nice-to-have files like caption_review_local.py and scoring weight file.
5. Checks Python version gate (expects Python 3.13.x).
6. Validates imports for runtime/scoring stack (Pillow, piexif, numpy, torch, pyiqa, etc.).
7. Validates builder script sanity (distpath, workpath, specpath flags).
8. Writes report to helpers/preflight_report_YYYYMMDD_HHMMSS.txt and exits non-zero on FAIL items.

BuildProfile behavior:

• Lite: missing heavy scoring imports can be downgraded to WARN.
• Full: stricter; dependency failures are treated as blocking.

R1.10 Optional build path

Set-Location "\path\to\amir2000_image_automation"
pwsh -NoProfile -ExecutionPolicy Bypass -File .\helpers\preflight_multiset.ps1 -BuildProfile Full
pwsh -NoProfile -ExecutionPolicy Bypass -File .\helpers\build_multiset.ps1 -Clean -BuildProfile Lite

Use this path when preparing executable delivery artifacts.

R1.11 Common install-time mistakes

• Skipping config updates and leaving invalid/default credentials.
• Missing model weights or Ollama model pulls before first run.
• Running without DB initialization.
• Running publish tests before validating basic local stage execution.
• Ignoring preflight FAIL results before attempting package build.

R1.12 Continuation path

After environment setup is validated, continue with operator flow instructions.