local_setup.md

# Local Setup and Run Guide

This guide explains how to set up, run, test, and execute inference for this project end-to-end on your local machine.

## 1) Prerequisites

Install and verify:

- Python 3.10+
- Docker Desktop (running)
- `openenv` CLI
- `curl`

Quick checks:

```bash
python3 --version
docker --version
openenv --help >/dev/null && echo "openenv OK"
curl --version | head -n 1
```

## 2) Project Directory

```bash
cd /Users/aksudhak/Documents/Akhil/POC/Scaler/OpenENV
```

## 3) Optional: Local Python test dependencies

If `pytest` is not installed:

```bash
python3 -m pip install pytest
```

## 4) Environment Variables for Inference

Set these before running `inference.py`:

```bash
export HF_TOKEN="<YOUR_NEW_HF_TOKEN>"
export API_BASE_URL="https://router.huggingface.co/v1"
export MODEL_NAME="Qwen/Qwen2.5-72B-Instruct"
export LOCAL_IMAGE_NAME="b2b_support_triage_env-env:latest"
```

Notes:
- `HF_TOKEN` is required.
- `API_BASE_URL`, `MODEL_NAME`, and `LOCAL_IMAGE_NAME` have defaults in code, but export them explicitly for submission clarity.

## 5) Build Docker Image

```bash
docker build -t b2b_support_triage_env-env:latest -f server/Dockerfile .
```

## 6) Run Application Locally

```bash
docker run --rm -p 8000:8000 b2b_support_triage_env-env:latest
```

Keep this terminal running. Open a second terminal for API checks.

## 7) API Smoke Test

### Health

```bash
curl -s http://127.0.0.1:8000/health
```

### Reset

```bash
curl -s -X POST http://127.0.0.1:8000/reset \
  -H "Content-Type: application/json" \
  -d '{"task_id":"easy","seed":1}'
```

### Step

```bash
curl -s -X POST http://127.0.0.1:8000/step \
  -H "Content-Type: application/json" \
  -d '{"action":{"action_type":"classify","ticket_id":"T-EASY-1001","payload":{"category":"billing"}}}'
```

### State

```bash
curl -s http://127.0.0.1:8000/state
```

## 8) Run Unit + Spec Validation

```bash
pytest -q
openenv validate -v
```

## 9) Run Inference Directly

```bash
python3 inference.py
```

Expected log pattern in stdout:
- `[START] ...`
- multiple `[STEP] ...`
- `[END] ...`
- final aggregate score line

## 10) Recommended Helper Scripts

### A) Full local checks (tests + validate + docker + endpoint checks + optional inference)

```bash
./run_all_checks.sh
```

Options:

```bash
RUN_INFERENCE=no ./run_all_checks.sh
RUN_INFERENCE=yes ./run_all_checks.sh
```

### B) Inference helper with token prompt

If `HF_TOKEN` is missing, this script prompts securely for it.

```bash
./run_inference.sh
```

It also sets defaults for:
- `API_BASE_URL`
- `MODEL_NAME`
- `LOCAL_IMAGE_NAME`

## 11) Common Issues

### Docker daemon not running
Start Docker Desktop and retry.

### Token error
Use a fresh valid Hugging Face token and re-export `HF_TOKEN`.

### Port 8000 already in use
Run container on a different host port:

```bash
docker run --rm -p 8001:8000 b2b_support_triage_env-env:latest
```

Then use `http://127.0.0.1:8001` in curl commands.