Start Pixel Detective

Use this skill to run Pixel Detective locally with the right subset of services.

Quickstart

• Full stack: powershell -ExecutionPolicy Bypass -File skills\\start-pixel-detective\\scripts\\startpixeldetective.ps1 -Mode full
• Backend only (+ optional GPU UMAP): powershell -ExecutionPolicy Bypass -File skills\\start-pixel-detective\\scripts\\startpixeldetective.ps1 -Mode backend -UseGpuUmap

Workflow

1. Confirm repo root

• Require frontend/package.json and startpixeldetective.ps1.
• If missing, stop and ask for the correct working directory.

1. Decide the requested mode

• full: all services plus frontend
• backend: Qdrant + ML + ingestion (optional UMAP)
• services: just Docker services (Qdrant and optional GPU UMAP)
• frontend: only Next.js dev server
• status: report what is running
• stop: stop Docker services and list any remaining processes

1. Docker preflight

• Check Docker CLI and Docker Compose:

- docker version - docker compose version

• If Docker is installed but not running, say so and stop.

1. Start sequence

• full: run .\startpixeldetective.ps1
• backend:

- docker compose up -d qdrantdb - optional GPU UMAP: docker compose -f backend/gpuumapservice/docker-compose.dev.yml up -d --build - start ML service: uvicorn backend.mlinferencefastapiapp.main:app --port 8001 --reload - start ingestion: uvicorn backend.ingestionorchestrationfastapi_app.main:app --port 8002 --reload

• services:

- docker compose up -d qdrant_db - optional GPU UMAP (same command as above)

• frontend:

- cd frontend then npm run dev

When launching uvicorn or npm, use new terminal windows so the main session stays responsive.

1. Status checks

• docker compose ps
• The script prints a port readiness summary (6333/8001/8002/8003/3000).
• Report URLs:

- http://localhost:3000 - http://localhost:8002/docs - http://localhost:8001/docs - http://localhost:8003/docs - http://localhost:6333/dashboard

1. Stop sequence

• docker compose down
• The script attempts to close uvicorn and npm windows tied to this repo.

Notes

• The GPU UMAP service can fail without blocking the rest. Treat it as optional.
• Use existing startup scripts whenever possible to stay aligned with repo behavior.
• Qdrant is the only required Docker service for Pixel Detective; ML and ingestion run on the host.
• If port 3000 is already in use, Next.js will choose 3001 or another port; report the actual port from the terminal output.
• If the ML or ingestion uvicorn process exits immediately, check for missing Python dependencies or a virtualenv not being activated.

Script

• Run: powershell -ExecutionPolicy Bypass -File skills\\start-pixel-detective\\scripts\\startpixeldetective.ps1 -Mode full
• Backend only: -Mode backend -UseGpuUmap
• Frontend + open page: -Mode frontend -Open -Page /search
• Note: -Open is required to open a browser; -Page alone will not open anything.