Airline Assistant

An AI engineering project for airline customer-service operations, starting with disrupted journeys and expanding to FAQs, booking support, controlled actions, and human escalation.

A passenger says: “My flight was cancelled. I need to reach Boston before 8 PM. If that is not possible, I want a refund.”

Answering that request requires more than generating text. The assistant must recover the booking, retrieve the applicable policy, check current flight availability, preserve conversation state, and distinguish an explanation from an action that needs approval.

This repository contains the application, evaluation suite, and local development environment. AWS infrastructure and GitOps configuration live in the separate companion airline-assistant-platform repository.

What the system will do

• Authenticate a passenger and load the correct booking, case, and conversation.
• Retrieve cited evidence from the published airline policy.
• Check live booking, flight, weather, and disruption information through controlled tools.
• Propose a rebooking or refund while keeping sensitive actions behind approval.
• Escalate unresolved cases with the evidence and previous attempts attached.
• Evaluate retrieval, responses, tool use, multi-turn behaviour, and action safety before release.
• Trace a production request across the API, retrieval, model, tools, and workers.

Architecture

Passenger / Specialist
          │
          ▼
      FastAPI API
          │
          ▼
    Case workflow
    ├── Policy RAG ───────> S3 + Qdrant
    ├── Live tools ───────> airline systems
    ├── Durable state ────> Postgres
    ├── Coordination ─────> Redis + Celery
    └── Controlled result
        ├── response
        ├── approval → action
        └── escalation

The API and Celery workers will use the same application image with different entry points. This keeps the first implementation cohesive while allowing interactive requests and background work to recover and scale independently in Kubernetes.

Repository structure

airline-assistant/
├── src/airline_assistant/
│   ├── api/              # FastAPI routes and request contracts
│   ├── domain/           # Cases, proposals, approvals, and actions
│   ├── workflows/        # Resolution and escalation workflow
│   ├── rag/              # Document ingestion and retrieval
│   ├── tools/            # Booking, flight, weather, and refund clients
│   ├── workers/          # Celery tasks
│   ├── persistence/      # Postgres and Redis adapters
│   └── observability/    # Traces, metrics, and structured logging
├── tests/
│   ├── unit/
│   ├── integration/
│   └── contract/         # External airline-service contracts
├── evals/
│   ├── datasets/         # Versioned evaluation cases
│   ├── evaluators/       # Deterministic and model-based checks
│   ├── fixtures/         # Synthetic bookings and tool responses
│   └── reports/          # Publishable evaluation results
└── .github/workflows/    # CI, evaluations, and image build

Planned technology

Area	Technology	Why it is here
API	FastAPI	Validated HTTP contracts for chat, cases, and approvals
Background work	Celery and Redis	Document ingestion, notifications, and bounded retries outside the request path
Durable state	PostgreSQL	Cases, proposals, approvals, actions, and audit history
Policy knowledge	S3 and Qdrant	Original documents, searchable passages, and citations
AI workflow	LLM, RAG, and controlled tools	Interpret requests while grounding decisions in policy and live data
Evaluation	Versioned datasets and release gates	Catch retrieval, workflow, and safety regressions before release
Telemetry	OpenTelemetry	Correlate requests across application and AI components

Delivery boundary

This repository owns application behaviour and produces an immutable container image. The separate airline-assistant-platform repository owns Terraform, Helm, Argo CD, environment values, and observability configuration.

Application repository
tests + evaluations → image digest in ECR
                              │
                              ▼
Deployment repository
environment value → Argo CD → Helm → EKS

Build sequence

The build follows the system's required paths and their dependency boundaries. Each stage produces a runnable vertical slice, a success test, a meaningful failure test, and an explanation of the backend abstraction it introduced.

1. Define the passenger-support boundary. Establish the distinction between public FAQs, booking-specific requests, disruption resolution, customer-service approval, and human takeover. Specify the authorization, ownership, recovery, and delivery guarantees before choosing schemas or services.
2. Model the domain and lifecycle. Define tenants, browser sessions, conversations, messages, cases, processing turns, proposals, approvals, handoffs, actions, and evidence. Make the state transitions and invariants explicit so an LLM suggestion cannot silently become an airline action.
3. Make message acceptance durable. Build the application backend's FastAPI boundary for browser identity, validation, deduplication, and message acceptance. Commit the communication and processing checkpoint to PostgreSQL before acknowledging the browser, then exercise duplicate delivery and serving-pod loss.
4. Make conversation recovery correct. Add PostgreSQL migrations, transactional boundaries, conversation history, retryable processing states, and ownership checks. Introduce Redis only as a reconstructable cache or coordination mechanism; a replacement pod must recover critical state from PostgreSQL without sticky sessions.
5. Define the AI service contract. Separate request ownership and durable state in the application backend from context assembly, model invocation, structured output validation, and grounded response generation in the AI pathway. Enforce the PNR and verification gate before booking-specific work and preserve interrupted or stale turns safely.
6. Implement human and approval paths. Persist pending review, customer-service approval, human takeover, canned acknowledgements, specialist replies, and final action results as distinct states and messages. Recheck current ownership and proposal fingerprints before delivering or executing anything.
7. Build the policy ingestion path. Design S3 upload, validation, background processing, parsing, chunking, embedding, Qdrant indexing, document-version publication, and failure recovery. Make ingestion idempotent and keep unpublished or failed versions out of the serving retrieval index.
8. Connect grounded answers and controlled tools. Use published policy evidence for FAQ and disruption answers, then add typed airline-system tools for booking lookup, availability, refund, and rebooking. Keep proposals separate from execution and require explicit authorization for side effects.
9. Prove behaviour before deployment. Add unit, integration, contract, workflow, retrieval, and end-to-end evaluation cases covering duplicate messages, missing or invalid PNRs, unverified access, stale AI output, pod failure, worker retry, approval races, bad documents, retrieval misses, and tool failures. Turn every discovered production failure into a regression case.
10. Operate the separated application and platform. Add traces, metrics, structured logs, alerts, security controls, CI release gates, and immutable image builds in this repository. Deploy the API and workers through the separate airline-assistant-platform repository only after the request, ingestion, safety, and recovery paths have evidence behind them.