RewardFlow

RewardFlow is an intelligent travel rewards assistant that helps users find the best way to redeem their miles and points. It combines structured database queries (for award charts) with RAG (Retrieval-Augmented Generation) for general knowledge, all accessible via a Telegram bot.

🏗️ System Architecture

The system consists of two main services:

1. Go Gateway (go-gateway):

   • Role: The central brain and API server.
   • Responsibilities:
     • Handles Telegram webhooks.
     • Intention Router: Uses OpenAI to classify user intent (e.g., "Award Search" vs "Knowledge Query") and extract slots (Origin, Destination, Cabin).
     • Context Management: Maintains user session state to handle follow-up questions (e.g., "what about business class?").
     • Database: Queries PostgreSQL for award availability.
   • Tech Stack: Go (Gin), PostgreSQL.

2. Python RAG (python-rag):

   • Role: The knowledge engine.
   • Responsibilities:
     • Ingests markdown files into a vector database (Pinecone).
     • Answers natural language questions using RAG.
     • Strict Mode: Only answers based on internal knowledge; refuses to hallucinate or use general web info.
   • Tech Stack: Python (FastAPI), OpenAI, Pinecone.

🚀 Getting Started

Prerequisites

• Docker & Docker Compose
• make
• ngrok (for exposing local server to Telegram)
• OpenAI API Key
• Telegram Bot Token

1. Environment Setup

Create a .env file or export these variables:

export OPENAI_API_KEY="sk-..."
export TELEGRAM_BOT_TOKEN="123456:ABC-..."
# Optional: Pinecone keys if using RAG
# export PINECONE_API_KEY="..."
# export PINECONE_INDEX="..."

2. Start Services

make start

This will build and start:

• go-gateway (port 8080)
• python-rag (port 8000)
• postgres (port 5433)
• redis (port 6379)

3. Initialize Data

Populate the database with award charts and ingest the knowledge base:

make setup-all

4. Connect Telegram

Expose your local server:

ngrok http 8080

Register the webhook with Telegram:

curl -F "url=https://<YOUR-NGROK-URL>/telegram/webhook" https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook

✨ Features

🧠 Smart Context Awareness

The bot remembers your conversation. You don't need to repeat yourself.

• User: "miles from singapore to malaysia"
• Bot: Shows Economy awards for SIN-KUL
• User: "what about business class?"
• Bot: Shows Business awards for SIN-KUL (remembers the route)
• User: "what about air canada?"
• Bot: Checks Air Canada availability for the same route

🌍 Country-Based Search

Search by country names, not just airport codes.

• User: "miles to Thailand"
• Bot: Searches flights to BKK, HKT, CNX, etc.
• User: "from Japan to UK"
• Bot: Searches HND/NRT to LHR/LGW

📍 Default Origin

If you omit the origin, it assumes Singapore (SIN).

• User: "miles to bangkok"
• Bot: Searches SIN -> BKK

🛡️ Strict RAG Mode

The bot is configured to never hallucinate.

• User: "how to transfer MR to krisflyer" -> Answers from your KB
• User: "who won the world cup?" -> "I don't have this information in my knowledge base."

🛠️ Data Management

Adding Award Data

1. Edit data/award_charts.csv.
2. Run:

   make reload-data

Adding Knowledge

1. Add markdown files to kb/.
2. Run:

   make reload-data

   (Or make force-ingest-kb to force a full re-scan).

📂 Project Structure

• go-gateway/: Main application logic.
  • internal/router/: LLM routing and slot extraction.
  • internal/handlers/: Telegram and API handlers.
  • internal/store/: Database queries.
• python-rag/: RAG service.
  • app/services/: Embedding and retrieval logic.
• data/: CSV files for database seeding.
• kb/: Markdown files for knowledge base.