Context Aware Assistant

Context-Aware Assistant (Phase 1)

The Context-Aware Assistant is the foundation of Adastrea Director, providing intelligent Q&A capabilities powered by Retrieval-Augmented Generation (RAG).

🎯 Overview

The Context-Aware Assistant allows you to:

• 📚 Ask questions about your project documentation
• 🔍 Get answers with source citations
• 💡 Discover relevant information across all documents
• 🎮 Access Unreal Engine and game development knowledge

Status: ✅ Complete and Production-Ready

How It Works

RAG Architecture

The Context-Aware Assistant uses a sophisticated RAG (Retrieval-Augmented Generation) pipeline:

1. Document Ingestion

   • Documents are split into manageable chunks
   • Each chunk is converted to a vector embedding
   • Embeddings are stored in a vector database (ChromaDB)

2. Query Processing

   • Your question is converted to a vector embedding
   • Similar chunks are retrieved from the database
   • Context is assembled from relevant chunks

3. Answer Generation

   • Context + question are sent to the LLM
   • LLM generates a comprehensive answer
   • Sources are cited for verification

User Query → Embedding → Similarity Search → Context Assembly → LLM → Answer

Getting Started

Prerequisites

✅ Adastrea Director installed (Installation Guide) ✅ LLM API key configured (Gemini or OpenAI)

Basic Usage

CLI Mode

# Start the interactive assistant
python main.py

# Ask your questions
> What is the main gameplay loop?
> How do I implement player movement?
> What are the performance requirements?

# Exit when done
> quit

GUI Mode

# Start the GUI
python gui_director.py

# 1. Type your question in the input box
# 2. Press Enter or click "Send"
# 3. View the answer with source citations

Single Query Mode

# Ask a single question
python main.py --query "What is the main character's backstory?"

# Useful for scripts and automation

Document Ingestion

Before asking questions, you need to populate the knowledge base.

Ingest Project Documentation

# Basic ingestion
python ingest.py --docs-dir /path/to/your/docs

# Specify file types
python ingest.py --docs-dir /path/to/docs --file-types .md .txt .rst

# Recursive ingestion (default)
python ingest.py --docs-dir /path/to/docs --recursive

# Update existing database
python ingest.py --docs-dir /path/to/docs --update

Ingest Game Repository

For Mittenzx/Adastrea game developers:

# Set your GitHub token
export GITHUB_TOKEN="ghp_your_token_here"

# Ingest the game repository
python ingest_game_repo.py

Alternative: Use GitHub Actions (Recommended for team)

1. Add GAME_REPO_TOKEN secret in repository settings
2. Go to Actions → "Populate Database with Adastrea Game Repository"
3. Click "Run workflow"

See the Document Ingestion Guide for more details.

Advanced Features

Context Window Management

The assistant intelligently manages context:

• Default: Top 5 most relevant chunks
• Configurable: Adjust in config.json
• Smart Ranking: Uses similarity scores to prioritize content

Source Citations

Every answer includes source citations:

Answer: The player character has three main abilities...

Sources:
- PlayerCharacter.md (lines 45-67)
- GameplayMechanics.md (lines 122-145)

This allows you to:

• ✅ Verify information
• ✅ Dive deeper into specific topics
• ✅ Track down outdated documentation

Query Optimization

Tips for better results:

❌ Too Vague:

> How do I code?

✅ Specific and Clear:

> How do I implement a singleton pattern for the GameManager in C++?

❌ Multiple Questions:

> What is the player character and what are their abilities and how do I implement them?

✅ One Question at a Time:

> What are the player character's abilities?
> How do I implement ability X in C++?

Configuration

LLM Provider Selection

You can choose from multiple LLM providers:

Gemini (Recommended):

export GEMINI_KEY="your-api-key-here"
# or use --set-api-key flag
python main.py --set-api-key gemini

OpenAI:

export OPENAI_API_KEY="your-api-key-here"

Ollama (Local):

# Install and run Ollama locally
ollama serve

# Configure to use Ollama
# (Set in config or via GUI settings)

Embedding Provider Selection

Default - HuggingFace (No API Key Required):

# Uses 'sentence-transformers/all-MiniLM-L6-v2'
# Works offline after initial model download

Optional - OpenAI Embeddings:

export OPENAI_API_KEY="your-api-key-here"
# Configure in settings to use OpenAI embeddings

Database Location

By default, the database is stored in ./chroma_db. You can customize this:

# In config.json
{
  "database": {
    "path": "/custom/path/to/chroma_db"
  }
}

Use Cases

1. Onboarding New Team Members

Help new developers quickly understand the project:

> What is the overall architecture of the game?
> Where is the player movement implemented?
> What are the coding standards for this project?
> How is the save system implemented?

2. Debugging and Problem-Solving

Get quick answers while debugging:

> How is the inventory system supposed to work?
> What are the error handling patterns in this codebase?
> Where are network events processed?

3. Documentation Discovery

Find relevant documentation without manual searching:

> What documentation exists about the AI system?
> Show me information about performance optimization
> Where is the build process documented?

4. Code Review Assistance

Understand code context during reviews:

> What design patterns are used in the combat system?
> How should new abilities be structured?
> What are the testing requirements for new features?

Limitations and Best Practices

Current Limitations

• Document Quality: Answers are only as good as ingested documents
• Context Window: Limited to top relevant chunks (not entire codebase)
• Hallucination: LLMs may occasionally generate incorrect information
• Real-time Data: Database must be updated manually (not live)

Best Practices

✅ Do:

• Keep documentation up-to-date and re-ingest regularly
• Ask specific, focused questions
• Verify important information from sources
• Use natural language (write as you would ask a colleague)

❌ Don't:

• Assume all answers are 100% accurate without verification
• Ask questions about code not in the ingested documents
• Expect real-time updates to code changes
• Use for security-sensitive information without validation

Performance Tips

First Query Optimization

The first query is always slower due to model loading:

# Pre-load models by running a test query
python main.py --query "test" > /dev/null

GPU Acceleration

If you have a CUDA-capable GPU:

# HuggingFace embeddings will automatically use GPU
# Check GPU usage:
nvidia-smi

Database Optimization

For large document collections:

# Adjust chunk size in ingestion
python ingest.py --docs-dir /path/to/docs --chunk-size 1500

# Increase overlap for better context
python ingest.py --docs-dir /path/to/docs --chunk-overlap 200

Troubleshooting

No Results Returned

Problem: Query returns "I don't have enough information..."

Solutions:

• ✅ Ensure relevant documents are ingested
• ✅ Try rephrasing your question
• ✅ Check database path is correct
• ✅ Verify documents were processed successfully

Slow Performance

Problem: Queries take too long

Solutions:

• ✅ First query is always slow (model loading) - this is normal
• ✅ Reduce number of retrieved chunks in config
• ✅ Use GPU acceleration if available
• ✅ Consider using lighter embedding models

Incorrect Answers

Problem: Assistant provides wrong information

Solutions:

• ✅ Check source citations - is source document correct?
• ✅ Re-ingest documents if they were recently updated
• ✅ Rephrase question to be more specific
• ✅ Verify LLM API key and configuration

API Reference

For programmatic usage:

from main import AdastreaDirector

# Initialize
director = AdastreaDirector()

# Query
response = director.query("What is the main character?")

# Get sources
sources = director.get_sources(response)

See Code Reference for complete API documentation.

Next Steps

• 📋 Planning System - Create implementation plans (P2)
• 🤖 Autonomous Agents - Set up proactive monitoring (P3)
• 🎮 Unreal Plugin - Use in Unreal Engine

Related Pages

• Document Ingestion Guide - Detailed ingestion instructions
• System Architecture - How RAG works
• Troubleshooting - Common issues

---

← Back to Home | Next: Planning System →