monish563/NU-KIOSK-API

1---2title: Northwestern CS Kiosk API3emoji: 🎙️4colorFrom: blue5colorTo: indigo6sdk: docker7sdk_version: "latest"8app_file: Dockerfile9pinned: false10---11 12# Northwestern CS Kiosk API13 14REST API backend for the Northwestern CS Department Kiosk. This is a stripped-down version optimized for integration with external systems (e.g., speech-to-text/text-to-speech).15 16## Quick Start17 18### 1. Install Dependencies19 20```bash21pip install -r requirements.txt22```23 24### 2. Configure Environment25 26```bash27cp .env.example .env28# Edit .env and add your API key29```30 31### 3. Run the Server32 33```bash34python -m backend.main35```36 37The API will be available at `http://0.0.0.0:8000`38 39---40 41## Deploy to Hugging Face Spaces42 43Deploy this API as a public endpoint so your manager (or STT/TTS systems) can send requests from anywhere.44 45### 1. Create a new Space46 471. Go to [huggingface.co/spaces](https://huggingface.co/spaces)482. Click **Create new Space**493. Choose **Docker** SDK, **Blank** template504. Name it (e.g. `monish563/NU-Kiosk-API`)515. Create, then push this `kiosk-api` folder to the Space repo52 53### 2. Add secrets (Settings → Variables and secrets → Secrets Private)54 55| Secret | Required | Description |56|--------|----------|-------------|57| `ANTHROPIC_API_KEY` | **Yes*** | Anthropic API key (starts with `sk-ant-api03-...`) |58| `KIOSK_LLM_PROVIDER` | No | Default: `anthropic` |59| `KIOSK_LLM_MODEL` | No | Default: `claude-haiku-4-5` |60| `KIOSK_LLM_SYSTEM_PROMPT` | No | Custom system prompt for the receptionist |61| `KIOSK_LLM_STYLE` | No | Style guidelines for TTS-friendly responses |62| `OPENAI_API_KEY` | No | If using `provider: "openai"` |63| `GEMINI_API_KEY` | No | If using `provider: "gemini"` |64| `KIOSK_HF_DATASET_REPO` | No | HF dataset for persistence (e.g. `monish563/kiosk-api-metrics`) |65| `KIOSK_HF_TOKEN` | No* | HF token with write access (required if dataset repo is set) |66 67*At least one LLM API key is required. `KIOSK_HF_TOKEN` is required if `KIOSK_HF_DATASET_REPO` is set.68 69### 3. Endpoint URL for your manager70 71Once the Space is built and running, the base URL will be:72 73```74https://<your-username>-<space-name>.hf.space75```76 77**Main endpoint (for STT → TTS flow):**78 79```80POST https://<your-username>-<space-name>.hf.space/api/query81Content-Type: application/json82 83{"question": "Where is Professor Hammond's office?"}84```85 86**Response:** `{"answer": "...", ...}` — send `answer` to your TTS system.87 88---89 90## API Reference91 92### Health Check93 94```95GET /96```97 98**Response:**99```json100{101  "status": "ok",102  "service": "Northwestern CS Kiosk API"103}104```105 106---107 108### Query (Main Endpoint)109 110```111POST /api/query112```113 114This is the primary endpoint for speech integration.115 116**Request Body:**117```json118{119  "question": "Where is Professor Hammond's office?",120  "session_id": "optional-session-id",121  "provider": "anthropic"122}123```124 125| Field | Type | Required | Description |126|-------|------|----------|-------------|127| `question` | string | **Yes** | The user's question (from speech-to-text) |128| `session_id` | string | No | Session ID for conversation continuity (default: "default") |129| `provider` | string | No | LLM provider: `anthropic`, `openai`, `gemini` |130 131**Response:**132```json133{134  "session_id": "default",135  "session_title": "Chat – Jan 23, 10:30 AM",136  "question": "Where is Professor Hammond's office?",137  "answer": "Professor Kristian Hammond's office is located in Mudd 3225.",138  "blueprint": "location",139  "facts": [...],140  "notes": [],141  "usage": {142    "provider": "anthropic",143    "model": "claude-haiku-4-5",144    "tokens": 512145  },146  "action": {147    "type": "lookup_location",148    "arguments": { "name": "Kristian Hammond" }149  }150}151```152 153**Key Fields:**154- `answer` - The response text (send to text-to-speech)155- `question` - Echo of the input question156- `blueprint` - Which tool was used internally157- `facts` - Structured data retrieved158- `usage` - Token/model metadata159 160---161 162### List Providers163 164```165GET /api/providers166```167 168Returns available LLM providers and their configuration status.169 170**Response:**171```json172{173  "providers": {174    "claude": {175      "name": "Claude",176      "configured": true,177      "default_model": "claude-haiku-4-5"178    },179    "gpt": {180      "name": "GPT",181      "configured": false,182      "note": "Set OPENAI_API_KEY before using this provider."183    }184  },185  "default_provider": "claude"186}187```188 189---190 191### Get History192 193```194GET /api/history?session_id=default195```196 197Returns conversation history for a session.198 199**Response:**200```json201{202  "session_id": "default",203  "title": "Chat – Jan 23, 10:30 AM",204  "history": [205    {206      "timestamp": 1706012345.123,207      "question": "Who is Kristian Hammond?",208      "answer": "Professor Kristian Hammond is...",209      "blueprint": "person_lookup"210    }211  ]212}213```214 215---216 217### List Sessions218 219```220GET /api/sessions221```222 223Returns all conversation sessions.224 225**Response:**226```json227{228  "sessions": [229    {230      "session_id": "default",231      "title": "Chat – Jan 23, 10:30 AM",232      "created_at": 1706012345.123,233      "updated_at": 1706012400.456234    }235  ]236}237```238 239---240 241## Integration Example242 243### cURL244 245```bash246curl -X POST "http://localhost:8000/api/query" \247  -H "Content-Type: application/json" \248  -d '{"question": "Where is Professor Hammond?"}'249```250 251### Python252 253```python254import requests255 256response = requests.post(257    "http://localhost:8000/api/query",258    json={"question": "Where is Professor Hammond?"}259)260data = response.json()261answer = data["answer"]  # Send this to text-to-speech262```263 264### JavaScript265 266```javascript267const response = await fetch("http://localhost:8000/api/query", {268  method: "POST",269  headers: { "Content-Type": "application/json" },270  body: JSON.stringify({ question: "Where is Professor Hammond?" })271});272const data = await response.json();273const answer = data.answer;  // Send this to text-to-speech274```275 276---277 278## Speech Integration Flow279 280```281┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐282│  Microphone │ ──▶ │   STT API   │ ──▶ │ Kiosk API   │ ──▶ │   TTS API   │283│             │     │ (Speech to  │     │ /api/query  │     │ (Text to    │284│             │     │   Text)     │     │             │     │  Speech)    │285└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘286                           │                   │                   │287                           ▼                   ▼                   ▼288                      "Where is           {"answer":          [Audio]289                       Prof X?"           "Prof X is           🔊290                                          in Mudd..."}291```292 293---294 295## Available Query Types296 297| Query Type | Example Questions |298|------------|-------------------|299| Person lookup | "Who is Kristian Hammond?", "Tell me about Katie Winters" |300| Location | "Where is Professor X's office?", "Where does student Y sit?" |301| Research topics | "Who researches AI?", "Faculty working on machine learning?" |302| Advisors | "Who advises student X?", "Who does Prof Y advise?" |303| Centers | "Who leads the Center for Deep Learning?" |304| Staff support | "Who handles reimbursements?", "Academic advising contact?" |305| Office hours | "When are CS 211 office hours?" |306| Events | "Any upcoming AI events?" |307 308---309 310## Environment Variables311 312| Variable | Required | Default | Description |313|----------|----------|---------|-------------|314| `ANTHROPIC_API_KEY` | Yes* | - | Anthropic API key |315| `OPENAI_API_KEY` | Yes* | - | OpenAI API key |316| `GEMINI_API_KEY` | Yes* | - | Google Gemini API key |317| `KIOSK_LLM_PROVIDER` | No | `anthropic` | Default LLM provider |318| `KIOSK_HOST` | No | `0.0.0.0` | Server host |319| `KIOSK_PORT` | No | `8000` | Server port |320| `KIOSK_LLM_TIMEOUT` | No | `60` | LLM timeout (seconds) |321 322*At least one API key is required.323 324---325 326## Project Structure327 328```329kiosk-api/330├── Archive/              # Data files (CSV)331├── backend/332│   ├── data/             # Data loading utilities333│   ├── mcp/              # LLM planner & tool execution334│   ├── providers/        # LLM provider implementations335│   ├── tools/            # Query blueprints336│   ├── main.py           # FastAPI application337│   └── responders.py     # Response generation338├── .env.example          # Environment template339├── requirements.txt      # Python dependencies340└── README.md             # This file341```342