UdaPlay

Video game research agent — Queries internal game database with RAG (Retrieval-Augmented Generation), performs web search when needed.

Features

• RAG Pipeline: Semantic game search in ChromaDB vector database
• Web Search: Automatic web search with Tavily when internal DB is insufficient
• Multi-Turn Conversation: Context preservation with session memory
• CLI: Interactive mode, single query, configuration wizard
• Multi-Provider: Support for OpenAI, Google Gemini and local LLM (Ollama)
• Structured Logging: JSON or text format, adjustable log level

Architecture

User Query
    |
    v
[message_prep] -> [retrieval_routing] -> [llm_processor] -> [tool_executor] -> [termination]
                         |                       ^                 |
                   Internal DB                   LLM            [loop]
                   (ChromaDB)
                         |
                   Web Search
                   (Tavily)

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure

On first run, the automatic configuration wizard starts. Or directly:

python main.py config

The wizard asks in order:

1. Provider — OpenAI / Gemini / Local
2. API Key — Selected provider's API key
3. Base URL — Automatically filled, can be changed
4. Model — Recommended based on provider
5. Tavily & Logging — Optional

3. Run

python main.py                    # Interactive mode
python main.py -q "question"      # Single query
python main.py config             # Configuration wizard
python main.py status             # Configuration status
python main.py --help             # Help

Interactive Mode Commands

Command	Description
/help	Help screen
/config	Edit configuration
/reset	Reset conversation history
/status	Show current settings
/quit	Exit

Environment Variables

Variable	Description	Required	Valid Values
LLM_PROVIDER	LLM provider	Yes	openai, gemini, local
LLM_API_KEY	API key	Yes	Provider's API key
LLM_API_BASE	API base URL	No	Default assigned based on provider
LLM_MODEL	Model name	No	Default assigned based on provider
TAVILY_API_KEY	Tavily web search key	No	Tavily key
LOG_LEVEL	Logging level	No	DEBUG, INFO, WARNING, ERROR
LOG_FORMAT	Log format	No	text, json

Provider Defaults

Provider	Base URL	Default Model
openai	https://api.openai.com/v1	gpt-4o-mini
gemini	https://generativelanguage.googleapis.com/v1beta/openai/	gemini-2.5-flash
local	http://localhost:11434/v1	llama3.2

Project Structure

.
├── main.py                    # CLI entry point
├── cli.py                     # CLI interface module (banner, config wizard, formatting)
├── config.env                 # Environment configuration
├── config.env.example         # Configuration template
├── requirements.txt           # Python dependencies
├── lib/
│   ├── agent.py               # Agent orchestrator
│   ├── llm.py                 # LLM wrapper (OpenAI-compatible endpoint)
│   ├── tools.py               # Game research tools
│   ├── rag.py                 # RAG pipeline and VectorStoreManager
│   ├── state_machine.py       # State machine framework
│   ├── memory.py              # Short and long-term memory
│   ├── evaluation.py          # Agent evaluation framework
│   └── ...                    # messages, parsers, tooling, documents, loaders, logging_config, vector_db
├── starter/games/             # Game data (JSON files)
├── Udaplay_01_solution_project.ipynb  # Notebook: RAG setup
└── Udaplay_02_solution_project.ipynb  # Notebook: Agent testing

Python Library Usage

from dotenv import load_dotenv
load_dotenv("config.env")

from lib.agent import Agent
from lib.tools import retrieve_game, game_web_search, init_vector_store

init_vector_store()

agent = Agent(
    instructions="You are a game research assistant.",
    tools=[retrieve_game, game_web_search],
)

run = agent.invoke("What are the best PS5 games?", session_id="demo")
report = agent.analyze_run(run)
print(report["answer"])

Logging

LOG_LEVEL=DEBUG LOG_FORMAT=text python main.py    # Detailed debug
LOG_LEVEL=INFO LOG_FORMAT=json python main.py     # Structured JSON