Fix/reproducible local setup

[Noaman-Akhtar]

Summary

This PR makes Sugar-AI easier and more reliable to set up and run locally.

It addresses dependency resolution problems, ambiguous model configuration, Docker startup failures, Starlette template incompatibility, and missing setup documentation while preserving the existing CUDA 12.8 Docker behavior.

Problems addressed

• Default dependency installation could pull CUDA-related packages unnecessarily.
• CPU and CUDA installations were not clearly separated.
• Model/provider selection could result in an empty or ambiguous model name.
• HTML routes were incompatible with the pinned Starlette version.
• Docker dependency downloads could fail with truncated-package or hash-mismatch errors.
• Docker did not receive runtime environment configuration clearly.
• The example environment file contained an inline boolean comment that Docker parsed incorrectly.
• New contributors lacked a complete, verified setup path.

Changes

Dependency setup

• Added a shared direct-dependency profile in requirements/base.txt.
• Added a CPU profile in requirements/cpu.txt.
• Added an explicit CUDA profile in requirements/cuda.txt.
• Made the root requirements.txt select the CPU profile by default.
• Kept accelerator-specific packages such as CUDA-enabled PyTorch and bitsandbytes opt-in.
• Preserved direct version pins to stabilize the supported dependency surface.

These are direct dependency pins, not a complete platform-specific lockfile.

Model and provider configuration

• Made model selection deterministic:

  1. AI_MODEL, when configured.
  2. DEV_MODEL_NAME when DEV_MODE=1.
  3. PROD_MODEL_NAME when DEV_MODE=0.

• Added a clear startup failure when no model is configured.

• Updated .example.env to use the verified SmolLM2-135M-Instruct development model.

• Made DEV_MODE Docker-compatible:

# Use DEV_MODE=1 for local development; use DEV_MODE=0 for the default model.
DEV_MODE=1

Frontend compatibility

• Updated template responses to use the request-first signature required by the pinned Starlette version.
• Fixed HTML routes that previously returned HTTP 500 errors.

Docker

• Preserved the existing NVIDIA CUDA 12.8 builder and runtime images.
• Added retry logic for large PyPI wheel downloads.
• Added offline installation from successfully downloaded wheels.
• Passed .env into the container at runtime instead of baking it into the image.
• Preserved the existing Docker Compose port mapping and runtime behavior.
• Documented Docker and Docker Compose startup commands.
• Added troubleshooting guidance for transient package download failures.

Documentation

Updated the README with a complete setup path covering:

• Virtual environment creation.
• .example.env to .env configuration.
• Default CPU installation.
• Explicit CUDA installation.
• Model and provider configuration.
• Local server startup.
• Docker startup.
• Docker Compose startup.
• Health checks.
• First-start model and document-index downloads.
• Common setup and Docker troubleshooting steps.

Verification

Clean CPU installation

A fresh Python 3.12.5 virtual environment was used for verification.

Results:

CPU profile installed successfully.
pip check: No broken requirements found.
Torch: 2.12.1+cpu
CUDA available: False

Local application startup

Sugar-AI was started using the documented development model and repository documentation paths.

Results:

Application startup complete
GET /        -> HTTP 200
GET /health  -> HTTP 200

Health response:

{
  "status": "healthy",
  "provider": "HuggingFaceProvider",
  "model": "HuggingFaceTB/SmolLM2-135M-Instruct"
}

Docker verification

• Rebuilt the CUDA 12.8 Docker image successfully.
• Started the container using .example.env.
• Verified the application startup marker.
• Verified the root endpoint.
• Verified the health endpoint.
• Confirmed that the corrected DEV_MODE value works with Docker’s environment-file parser.
• Removed temporary verification containers, the test image, and the temporary CPU environment afterward.

Results:

Application startup complete
GET /        -> HTTP 200
GET /health  -> HTTP 200

Known limitation

The verification host does not have an NVIDIA driver.

Therefore:

• CUDA image construction was verified.
• CUDA-enabled dependencies were installed in the image.
• Container startup was verified using CPU fallback.
• Actual GPU execution with torch.cuda.is_available() == True could not be tested.

GPU hardware validation should be performed separately on an NVIDIA-equipped host.

[Noaman-Akhtar]

@mebinthattil and @chimosky can you review this ?

[Noaman-Akhtar]

@mebinthattil @chimosky can you please review this pr ?

[chimosky]

You could just pass requirements/cuda.txt here, which would make the other args redundant.

[Noaman-Akhtar]

Hey @chimosky its addressed in fde4109. The dockerfile now uses requirements/cuda.txt directly

[chimosky]

@mebinthattil please test this.