Member Data Question-Answering API

A REST API service that accepts natural-language questions about member data and returns answers using LLM-based natural language processing.

Features

• Natural Language Q&A: Ask questions like "When is Layla planning her trip to London?"
• Multiple LLM Providers: Support for Google Gemini, OpenAI GPT, and Anthropic Claude
• Agentic Architecture: LangGraph ReAct agent with intelligent tool selection
• Rate Limiting: Built-in IP-based rate limiting to control costs
• Advanced Analytics: Member activity analysis, entity extraction, sentiment analysis

Quick Start

Prerequisites

• Python 3.11+
• One of:
  • Google Cloud project with Vertex AI enabled
  • OpenAI API key
  • Anthropic API key

Installation

# Clone the repository
git clone https://github.com/danielphan-dp/genai-search-api.git
cd genai-search-api

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your API credentials

Running Locally

uv run uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Testing the API

# Ask a question
curl -X POST http://localhost:8000/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "When is Layla planning her trip to London?"}'

# Health check
curl http://localhost:8000/health

API Endpoints

Endpoint	Method	Description
/ask	POST	Submit a question and receive an answer
/health	GET	Check service health status
/docs	GET	Interactive API documentation (Swagger UI)

POST /ask

Request:

{
  "question": "When is Layla planning her trip to London?"
}

Response:

{
  "answer": "Layla is planning her trip to London on March 15, 2025."
}

Architecture

The API uses a LangGraph ReAct (Reasoning + Acting) agent that intelligently decides which data to retrieve based on the question.

User Question
     ↓
┌─────────────────────────────────────────────┐
│           LangGraph ReAct Agent             │
│  ┌─────────────────────────────────────┐    │
│  │    Reasoning Step (LLM)             │    │
│  │    "I need Layla's trip messages"   │    │
│  └──────────────┬──────────────────────┘    │
│                 ↓                            │
│  ┌─────────────────────────────────────┐    │
│  │    Tool Selection & Execution       │    │
│  └──────────────┬──────────────────────┘    │
│                 ↓                            │
│  ┌─────────────────────────────────────┐    │
│  │    Final Answer Generation (LLM)    │    │
│  └─────────────────────────────────────┘    │
└─────────────────────────────────────────────┘
     ↓
{ "answer": "..." }

Agent Tools

Tool	Purpose
search_messages	Find messages by member name and/or keywords
list_members	Get all unique member names
get_member_messages	Get all messages for a specific member
analyze_member_activity	Get activity statistics for members
extract_entities	Extract locations, preferences, dates
analyze_trends	Analyze topic frequency over time
sentiment_analysis	Analyze sentiment distribution
compare_members	Side-by-side member comparison
get_movies	Search movie catalog for recommendations

Configuration

Variable	Description	Default
LLM_PROVIDER	LLM provider ("google", "openai", or "anthropic")	google
GOOGLE_CLOUD_PROJECT	GCP project ID (required for google provider)	-
LLM_API_KEY	API key (required for openai/anthropic)	-
LLM_MODEL	Model name	Provider default
MESSAGES_API_URL	External messages API URL	-
REQUEST_TIMEOUT	Request timeout in seconds	30.0

Rate Limiting

Setting	Default	Description
RATE_LIMIT_REQUESTS	20	Maximum requests per minute
RATE_LIMIT_WINDOW	60	Window duration in seconds
RATE_LIMIT_DAILY	1000	Maximum requests per day

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src

License

MIT