OptiRoute

OptiRoute is a production-style MVP for AI-assisted travel optimization. It is not a generic chatbot; it is a deterministic decision engine that evaluates user-provided itineraries against hard constraints and soft preferences, then transparently ranks options with score breakdowns.

Why OptiRoute

Travel decisions are tradeoffs. OptiRoute helps users optimize across:

• cost
• total travel time
• number of stops
• layover quality
• airport transfer inconvenience
• airline preferences
• schedule fit and comfort/value tradeoffs
• risk indicators (self-transfer, low buffer, separate tickets)

Architecture

optiroute/
  backend/
    app/
      api/
        routes/
      core/
      models/
      services/
      agents/
      scoring/
      tests/
      data/
    requirements.txt
  frontend/
  docs/
  README.md

Core design principles

1. Deterministic source-of-truth for validity, scoring, and ranking.
2. LLM layer is replaceable and cannot invent flight data.
3. Hard constraints are strict: violated itineraries are rejected.
4. Soft preferences are tradable: influence ranking but do not invalidate options.
5. Explanations are grounded in computed score breakdowns.

Backend setup

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

API docs: http://localhost:8000/docs

API Endpoints

• GET /health
• POST /parse-preferences
• POST /score-itineraries
• POST /recommend

POST /recommend request shape

{
  "preferences": {"origin": "JFK", "destination": "SFO", "hard_constraints": {"max_budget": 550}},
  "itineraries": [
    {
      "itinerary_id": "OPT-101",
      "provider": "MockFlights",
      "total_price": 420,
      "total_duration_minutes": 510,
      "stops": 1,
      "segments": [...],
      "origin": "JFK",
      "destination": "SFO",
      "airlines": ["DL"]
    }
  ]
}

POST /recommend response includes

• parsed preferences
• rejected itineraries with explicit reasons
• ranked valid itineraries with score breakdowns
• recommendation buckets: best overall / cheapest / best value / best comfort
• final recommendation and grounded explanation text
• uncertainty notes

Scoring model (deterministic)

The scoring engine computes weighted components:

• price_score
• duration_score
• stop_penalty
• bad_layover_penalty
• airport_inconvenience_penalty
• airline_preference_bonus
• schedule_fit_bonus
• stopover_bonus
• risk_penalty

Final score is a weighted combination of normalized terms. Weights are configurable via preference payload (scoring_weights).

Claude integration points

backend/app/agents/claude_client.py provides hooks for:

• extract_preferences(user_text)
• generate_explanation(context)

In production, this adapter should call Claude API. Deterministic modules still own scoring/ranking/validation.

Sample data and tests

• mock itineraries: backend/app/data/mock_itineraries.json
• sample preferences: backend/app/data/sample_preference_payload.json
• unit tests: backend/app/tests/

Run tests:

cd backend
PYTHONPATH=. pytest app/tests -q

MVP status

This implementation prioritizes:

1. schemas
2. scoring engine
3. recommend endpoint
4. explanation integration
5. frontend shell (API-first)