TERMINAL_COMMANDS.md

Crisis Command Terminal Runbook

This file is a quick command reference for local development, validation, Docker, Hugging Face Space, and agent training/evaluation.

Note: inference.py and api_diagnostics.py auto-load .env from the repo root.

1) Initial Setup

export REPO_ROOT=/path/to/crisis_comm_env
cd "$REPO_ROOT"
python3.10 -m venv venv
source venv/bin/activate
pip install -r server/requirements.txt

2) Run API Locally (FastAPI)

cd "$REPO_ROOT/server"
source ../venv/bin/activate
uvicorn app:app --host 0.0.0.0 --port 7860

Health check:

curl http://127.0.0.1:7860/health

Reset check:

curl -X POST http://127.0.0.1:7860/reset \
  -H "Content-Type: application/json" \
  -d '{"task_name":"data-breach"}'

3) Project Verification

cd "$REPO_ROOT"
source venv/bin/activate
python3.10 server/verify_project.py

OpenEnv validation:

openenv validate

4) Docker (Local)

Build:

cd "$REPO_ROOT"
docker build -t crisis-comm-local .

Run:

docker run -p 7860:7860 crisis-comm-local

Test Docker container:

curl http://127.0.0.1:7860/health
curl -X POST http://127.0.0.1:7860/reset -H "Content-Type: application/json" -d '{}'

5) Inference (Hackathon Baseline)

Scripted baseline (for reproducible target scores):

cd "$REPO_ROOT"
source venv/bin/activate
python3.10 inference.py --policy scripted

LLM policy (OpenAI-compatible, HF Router default):

export API_BASE_URL="https://router.huggingface.co/v1"
export MODEL_NAME="Qwen/Qwen2.5-72B-Instruct"
export HF_TOKEN="YOUR_HF_TOKEN"
python3.10 inference.py --policy llm

Strategic policy:

python3.10 inference.py --policy strategic

RL policy:

python3.10 inference.py --policy rl

6) Challenge Task Set (Better Reasoning Stress)

Run strategic policy on challenge tasks:

python3.10 inference.py --policy strategic --task-set challenge

Run RL policy on challenge tasks:

python3.10 inference.py --policy rl --task-set challenge

Run all tasks (standard + challenge):

python3.10 inference.py --policy strategic --task-set all

7) RL Training

Train standard RL policy:

python3.10 train_rl.py --episodes 1200 --eval-every 200 --out artifacts/rl_policy.json

Train challenge RL policy:

python3.10 train_rl.py --task-set challenge --episodes 1200 --eval-every 300 \
  --out artifacts/rl_policy_challenge.json

Train all tasks with curriculum:

python3.10 train_rl.py --task-set all --episodes 1600 --eval-every 300 \
  --out artifacts/rl_policy_all.json

8) Policy Evaluation

Compare strategic vs RL on standard + challenge:

python3.10 evaluate_agent.py --policies strategic rl --task-sets standard challenge

Challenge only:

python3.10 evaluate_agent.py --policies strategic rl --task-sets challenge

9) API Diagnostics (Rate-limit / latency / headers)

Probe active endpoint and print status/latency plus rate-limit headers (if provider returns them):

python3.10 api_diagnostics.py

Gemini explicit probe:

export API_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
export MODEL_NAME="gemini-2.5-flash"
export GEMINI_API_KEY="YOUR_GEMINI_KEY"
python3.10 api_diagnostics.py

HF Router explicit probe:

export API_BASE_URL="https://router.huggingface.co/v1"
export MODEL_NAME="Qwen/Qwen2.5-72B-Instruct"
export HF_TOKEN="YOUR_HF_TOKEN"
python3.10 api_diagnostics.py

10) Hugging Face Space Logs

Container logs:

curl -N \
  -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/spaces/Sammy1808/crisis_comm/logs/run"

Build logs:

curl -N \
  -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/spaces/Sammy1808/crisis_comm/logs/build"

11) Submission Validation

cd "$REPO_ROOT"
bash validate-submission.sh https://sammy1808-crisis-comm.hf.space .

12) Git Commit + Push

cd "$REPO_ROOT"
git add .
git commit -m "Your commit message"
git push origin main
git push hf-space main

13) Handy Quick Checks

Show task lists (standard vs challenge):

python3.10 -c "import sys, os; sys.path.insert(0, os.path.join(os.environ['REPO_ROOT'], 'server')); from tasks import list_task_names; print('standard:', list_task_names(include_challenge=False)); print('all:', list_task_names(include_challenge=True))"

Syntax check key files:

python3.10 -m py_compile \
  inference.py train_rl.py evaluate_agent.py api_diagnostics.py agent_policy.py \
  server/app.py server/tasks.py server/crisis_data.py \
  server/environment.py server/grader.py server/models.py