CoolFace
Apppublic

monish563/NU-Kiosk

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
App README

title: NU Kiosk emoji: 🏫 colorFrom: purple colorTo: indigo sdk: docker sdkversion: "latest" appfile: Dockerfile pinned: false ---

CS Kiosk

Conversational kiosk for the Northwestern CS department. The backend aggregates local datasets, selects task-specific tools, and forwards responses through your configured LLM provider while a React front-end presents the chat experience.

Prerequisites

  • —Python 3.11+
  • —Node.js 18+ with npm (for the React web client)
  • —API keys for the LLM providers you want to enable (Anthropic by default; Gemini/OpenAI optional)

Quick Start

  1. 1.Create and populate a virtual environment
bash
   cd /path/to/kiosk
   python -m venv .venv
   source .venv/bin/activate  # or .venv\Scripts\activate on Windows
   pip install -r requirements.txt
  1. 1.Install the React frontend dependencies
bash
   cd frontend
   npm install
  1. 1.Run the backend
bash
   cd ..
   python -m backend.main

The FastAPI server starts on http://127.0.0.1:5050.

  1. 1.Run the React web client
bash
   cd frontend
   npm run dev

The Vite dev server proxies /api/* calls to http://127.0.0.1:5050, so the web client talks to the same FastAPI backend without additional configuration. Set VITE_API_BASE_URL if you need to point the frontend at a remote backend during npm run build.

Hostable React Frontend

The frontend/ directory contains a React + Vite application that can be deployed to any static host.

  • —Local development: npm run dev (automatically proxies /api to 127.0.0.1:5050).
  • —Environment override: Create frontend/.env with VITE_API_BASE_URL=https://your-backend.example.com to target a different origin (required if the frontend and backend are not served from the same domain).
  • —Production build: npm run build emits static assets in frontend/dist/. Serve those files from your hosting provider and point them at the FastAPI backend via VITE_API_BASE_URL or a reverse proxy.

When hosting the frontend separately from the backend, either configure the backend with the proper CORS policy or serve both behind the same origin/reverse proxy so relative /api calls remain valid.

Environment Template

The repository includes a .env file at the root with the following structure. Replace placeholder values with your actual API keys before running the kiosk:

bash
# Copy this file to your local secrets manager and replace the placeholders.
# Do NOT commit real API keys into version control.

# Framework defaults
KIOSK_LLM_PROVIDER=anthropic
KIOSK_LLM_MODEL=claude-haiku-4-5
KIOSK_LLM_SYSTEM_PROMPT=You are a conversational receptionist for the Northwestern CS Kiosk whose responses are spoken aloud. Speak naturally and never include stage directions or annotations.
KIOSK_LLM_STYLE=Be very brief. One or two sentences max. No long lists—summarize top 2-3 items only.

# OpenAI
OPENAI_API_KEY=your-openai-key
OPENAI_MODEL=gpt-4.1-mini

# Anthropic Claude
ANTHROPIC_API_KEY=your-anthropic-key
ANTHROPIC_MODEL=claude-haiku-4-5

# Google Gemini
GEMINI_API_KEY=your-google-cloud-key
GEMINI_MODEL=gemini-2.0-flash

# Hugging Face Inference
HF_API_KEY=your-huggingface-token
HF_MODEL=meta-llama/Meta-Llama-3-8B-Instruct

Hugging Face Sync (Optional)

Set these variables to mirror storage/chat_history.jsonl and storage/usage_metrics.jsonl to a Hugging Face dataset; leave them unset to keep data local. On restart, both files are downloaded from the dataset so chat history persists across deploys.

  • —KIOSK_HF_DATASET_REPO – dataset repo ID (for example username/kiosk-metrics). Required to enable syncing.
  • —KIOSK_HF_TOKEN – token with write access to the dataset (falls back to HF_KIOSK_HF_TOKEN or HF_TOKEN when provided via HF Spaces secrets).
  • —KIOSK_HF_DATASET_PATH – optional destination subfolder inside the repo (defaults to chat_history).
  • —KIOSK_HF_SYNC_INTERVAL_MINUTES – push cadence in minutes (defaults to 10).

Project Structure

kiosk/
├── .env                # Environment variables (filled with local keys)
├── Archive/            # Local CSV feeds used by blueprints
├── backend/
│   ├── data/              # Catalog loading, data utilities
│   ├── mcp/               # Planner actions, schemas, and tool executor
│   ├── providers/         # LLM provider clients (Anthropic, OpenAI, Gemini, Echo)
│   ├── tools/             # Blueprint implementations backing each chat tool
│   ├── responders.py      # LLM responder and metadata handling
│   └── main.py            # FastAPI entry point and orchestrator wiring
├── frontend/           # React web client (Vite)
│   ├── src/              # Chat UI, API hooks, and styles
│   ├── public/           # Static assets
│   └── vite.config.js    # Dev server + build configuration
└── README.md              # This guide

Development Notes

  • —The planner uses KIOSK_PLANNER_PROVIDER / KIOSK_PLANNER_MODEL if set; otherwise it falls back to KIOSK_LLM_PROVIDER.
  • —Store secrets responsibly. The provided .env file is committed for convenience; update the keys locally before running the kiosk, but keep sensitive values private if you publish your fork.
  • —To add a new provider, implement the BaseLLM interface in backend/providers/, register it in _PROVIDER_REGISTRY, and add the relevant environment entry in PROVIDER_ENV_SETTINGS.

======= emoji: 📉 colorFrom: pink colorTo: purple sdk: docker pinned: false short_description: Conversational CS kiosk with a FastAPI backend and React fro