95888-Final_Project

CMU-95888-Final project

Quick Start

1. Create and activate a virtual environment.
2. Install dependencies:

pip install -r requirements.txt

3. Create .env from .env.example and set:

GEMINI_API_KEY=your_key
GEMINI_MODEL=gemini-2.5-flash
SERPAPI_API_KEY=your_serpapi_key

4. Token/cost & robustness control (optional)

Set in .env (defaults are used if omitted):

MAX_TOOL_ROUNDS=3
MAX_TOOL_PAYLOAD_ITEMS=5
MAX_TOOL_PAYLOAD_CHARS=500
MAX_HISTORY_CHARS=8000
MAX_JSON_REPAIR_RETRIES=1

5. Run:

python app.py

Project Structure

• app.py: Main loop (model init, generation loop, tool call handling, cleanup)
• model_connector/: LLM connector abstraction and provider implementations (Cloudflare/Gemini/Groq/OpenRouter)
• plugins/: Plugin abstraction and plugin return standard
• plugins/SerpGoogleFlightsPlugin.py: One-way Google Flights search via SerpAPI (type=2), supports city name or IATA input
• program_logic.md: Intended end-to-end control flow

Output Robustness

• The app requires strict JSON output with top-level keys: tool_calls, user_message, exit.
• If model output looks like markdown/code-fenced JSON or malformed JSON, the app will auto-trigger a JSON repair retry.
• Repair retries are controlled by MAX_JSON_REPAIR_RETRIES.
• If retries are exhausted, the app prints a clear error message and safely exits the current run instead of crashing.

Runtime Fallback Mode

• If model initialization or generation fails at runtime, the app enters a console fallback flow instead of crashing.
• Fallback flow asks user for origin and destination, then collects transport data for flight, train, bus, and driving.
• Train is currently a placeholder route (N/A) and ready for future plugin integration.
• Driving price is intentionally shown as N/A in fallback mode.
• The app prints a user-friendly summary, a price comparison table, a time comparison table, and raw data notes.