Getting Started

Getting Started with Adastrea Director

Welcome! This guide will help you install and set up Adastrea Director on your system.

📋 Table of Contents

• System Requirements
• Installation Methods
• Quick Setup
• Manual Installation
• Configuration
• Next Steps

System Requirements

Minimum Requirements

• Python: 3.9 or higher (3.12+ recommended for best compatibility)
• pip: Package manager (included with Python)
• RAM: 4GB minimum, 8GB+ recommended
• Storage: 2GB free space (more for document databases)
• OS: Windows 10+, macOS 10.14+, Ubuntu 20.04+

Optional Requirements

• GitHub Token: For private repository ingestion
• API Keys: For LLM providers (Gemini or OpenAI)
• Unreal Engine: 5.0+ (for plugin mode only)

Installation Methods

Method 1: Quick Setup (Recommended) ⭐

The automated setup script handles everything for you:

# Clone the repository
git clone https://github.com/Mittenzx/Adastrea-Director.git
cd Adastrea-Director

# Run setup script (Linux/Mac)
./setup.sh

# Run setup script (Windows - use Git Bash or WSL)
bash setup.sh

The setup script will:

• ✅ Check system compatibility
• ✅ Create and activate virtual environment
• ✅ Install all dependencies with platform-specific handling
• ✅ Verify the installation
• ✅ Guide you through initial configuration

💡 Tip: The virtual environment is reusable. Simply activate it with:

source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

Method 2: Smart Installer

If the quick setup doesn't work or you need more control:

# Clone the repository
git clone https://github.com/Mittenzx/Adastrea-Director.git
cd Adastrea-Director

# Run the smart installer
python install_dependencies.py

The smart installer will:

• Detect your platform and architecture
• Handle platform-specific dependencies (especially for Apple Silicon)
• Guide you through any required manual steps
• Verify the installation

Method 3: Manual Installation

For advanced users who want complete control:

# 1. Clone the repository
git clone https://github.com/Mittenzx/Adastrea-Director.git
cd Adastrea-Director

# 2. Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Verify installation
python test_installation.sh

Quick Setup

1. Install Adastrea Director

Choose one of the installation methods above. We recommend the Quick Setup for most users.

2. Configure LLM Provider

Adastrea Director supports multiple LLM providers. You have three options:

Option A: Save to Local Config (Recommended)

Keys are securely stored in ~/.adastrea/config.json:

Via CLI:

python main.py --set-api-key gemini
# Follow the prompts and check "Save API key for future sessions"

Via GUI:

python gui_director.py
# Use Settings dialog (Ctrl+,) to save API keys

Option B: Environment Variables

# For Gemini (recommended - free tier available)
export GEMINI_KEY="your-api-key-here"

# For OpenAI
export OPENAI_API_KEY="your-api-key-here"

Option C: .env File

# Copy the template
cp .env.example .env

# Edit .env and add your keys
GEMINI_KEY=your-api-key-here
OPENAI_API_KEY=your-api-key-here

Priority: Local config → Environment variables → .env file

3. (Optional) Set Up GitHub Token

Only needed for private repository ingestion:

export GITHUB_TOKEN="your-github-token-here"

4. Verify Installation

Run a quick test to ensure everything is working:

# Test the CLI
python main.py --help

# Test the GUI
python gui_director.py

Configuration

Embeddings Configuration

Default (No Setup Required): Adastrea Director uses HuggingFace embeddings by default (works offline, no API key needed).

Optional - OpenAI Embeddings: For better quality embeddings:

1. Set OPENAI_API_KEY environment variable
2. Configure in settings to use OpenAI embeddings

Document Ingestion

Before using Adastrea Director, you should populate the knowledge base:

# Ingest your project documentation
python ingest.py --docs-dir /path/to/your/docs

# For Mittenzx/Adastrea game developers
python ingest_game_repo.py

See the Document Ingestion Guide for more details.

Platform-Specific Notes

macOS (Apple Silicon)

If you encounter issues with ARM-based dependencies:

1. Use the smart installer: python install_dependencies.py
2. It will guide you through any required steps for Apple Silicon compatibility

Windows

• Use Git Bash or WSL for best compatibility with setup scripts
• tkinter is included with Python on Windows
• Some dependencies may require Visual C++ Build Tools

Linux

Ubuntu/Debian:

# Install tkinter if needed
sudo apt-get install python3-tk

# Install build essentials if needed
sudo apt-get install build-essential python3-dev

Fedora/CentOS:

# Install tkinter if needed
sudo dnf install python3-tkinter

Troubleshooting

Common Issues

Problem: "No module named 'tkinter'"

• Solution: Install python3-tk package for your OS (see Platform-Specific Notes)

Problem: "Failed to load embeddings model"

• Solution: Ensure you have internet connection for first-time model download, or check your API key configuration

Problem: "Permission denied" when running setup.sh

• Solution: Make the script executable: chmod +x setup.sh

Problem: Dependencies fail to install on Apple Silicon

• Solution: Use the smart installer: python install_dependencies.py

For more troubleshooting help, see the Troubleshooting Guide.

Next Steps

Now that you have Adastrea Director installed:

1. 📚 Quick Start Tutorial - Learn the basics in 5 minutes
2. 🔍 Context-Aware Assistant - Start asking questions about your project
3. 📋 Planning System - Create implementation plans
4. 🤖 Autonomous Agents - Set up proactive monitoring

Getting Help

• 📖 FAQ - Frequently asked questions
• 🐛 Report Issues - Found a bug?
• 💬 Discussions - Ask questions

---

Next: Quick Start Tutorial →

← Back to Home