Installation Guide

This comprehensive tutorial will guide you through setting up a complete RecoAgent development environment from scratch. By the end, you'll have everything needed to build and deploy RecoAgent applications.

What You'll Learn

How to set up Python development environment
How to install RecoAgent and dependencies
How to configure vector stores and LLM providers
How to verify your installation
How to set up development tools

Prerequisites

Before starting, ensure you have:

Python 3.8+ - Check with python --version
Node.js 18+ (for documentation) - Check with node --version
Git - For version control
API Keys for your chosen LLM provider (OpenAI, Anthropic, etc.)
Vector Store Access (OpenSearch, Azure AI Search, or Vertex AI)

Step 1: Python Environment Setup

Create Virtual Environment

# Create project directory
mkdir recoagent-project
cd recoagent-project

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

Verify Python Installation

python --version
# Should show Python 3.8 or higher

Step 2: Install RecoAgent

Install Core Package

# Install RecoAgent
pip install recoagent

# Install development dependencies
pip install recoagent[dev]

Verify Installation

python -c "import recoagent; print('RecoAgent installed successfully!')"

Step 3: Configure Environment Variables

Create Environment File

# Create .env file
touch .env

Add Configuration

# .env file contents
# LLM Configuration
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4-turbo-preview
OPENAI_TEMPERATURE=0.1

# Alternative LLM Providers
ANTHROPIC_API_KEY=your_anthropic_key_here
GOOGLE_API_KEY=your_google_key_here

# Vector Store Configuration
VECTOR_STORE_TYPE=opensearch  # opensearch, azure_ai_search, vertex_ai
OPENSEARCH_URL=http://localhost:9200
OPENSEARCH_INDEX_NAME=recoagent_kb

# Azure AI Search (if using)
AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_KEY=your_search_key_here
AZURE_SEARCH_INDEX_NAME=recoagent-index

# Vertex AI (if using)
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1

# Observability
LANGSMITH_API_KEY=your_langsmith_key_here
LANGSMITH_PROJECT=recoagent-development
LANGSMITH_TRACING=true

# Safety & Performance
GUARDRAILS_ENABLED=true
MAX_COST_PER_QUERY=0.10
MAX_LATENCY_MS=5000

Step 4: Set Up Vector Store

Option A: OpenSearch (Recommended for Development)

# Using Docker Compose
curl -O https://raw.githubusercontent.com/recohut/recoagent/main/docker-compose.opensearch.yml
docker-compose -f docker-compose.opensearch.yml up -d

# Verify OpenSearch is running
curl -X GET "localhost:9200/_cluster/health?pretty"

Option B: Azure AI Search

# No local setup needed - use cloud service
# Just ensure your Azure credentials are in .env

Option C: Vertex AI Vector Search

# Install Google Cloud CLI
curl https://sdk.cloud.google.com | bash
exec -l $SHELL

# Authenticate
gcloud auth application-default login

# Set project
gcloud config set project your-project-id

Step 5: Install Development Tools

Code Quality Tools

# Install development tools
pip install black isort flake8 mypy pytest pytest-cov

# Install pre-commit hooks
pip install pre-commit
pre-commit install

Documentation Tools

# Install documentation dependencies
cd docs
npm install

# Start documentation server
npm run docs:start

Step 6: Verify Installation

Test Basic Functionality

Create a test file test_installation.py:

import os
from dotenv import load_dotenv
from recoagent import RecoAgent

# Load environment variables
load_dotenv()

def test_basic_setup():
    """Test basic RecoAgent setup."""
    try:
        # Initialize RecoAgent
        agent = RecoAgent()
        print("✅ RecoAgent initialized successfully")
        
        # Test document addition
        agent.add_documents(["Test document for installation verification"])
        print("✅ Document addition works")
        
        # Test basic query
        response = agent.ask("What is this document about?")
        print(f"✅ Query response: {response.answer[:50]}...")
        
        return True
        
    except Exception as e:
        print(f"❌ Installation test failed: {e}")
        return False

if __name__ == "__main__":
    success = test_basic_setup()
    if success:
        print("\n🎉 Installation verification successful!")
        print("You're ready to start building with RecoAgent!")
    else:
        print("\n❌ Installation verification failed.")
        print("Please check your configuration and try again.")

Run Installation Test

python test_installation.py

Step 7: Configure Development Environment

IDE Setup (VS Code)

Create .vscode/settings.json:

{
    "python.defaultInterpreterPath": "./venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.flake8Enabled": true,
    "python.formatting.provider": "black",
    "python.sortImports.args": ["--profile", "black"],
    "files.exclude": {
        "**/__pycache__": true,
        "**/.pytest_cache": true,
        "**/venv": true
    }
}

Git Configuration

Create .gitignore:

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg

# Virtual Environment
venv/
env/
ENV/

# Environment Variables
.env
.env.local
.env.*.local

# IDE
.vscode/
.idea/
*.swp
*.swo

# Logs
*.log
logs/

# Temporary files
*.tmp
*.temp

Step 8: Advanced Configuration

Custom Vector Store Configuration

# custom_config.py
from recoagent.config import VectorStoreConfig, LLMConfig

# Custom vector store configuration
vector_config = VectorStoreConfig(
    store_type="opensearch",
    host="localhost",
    port=9200,
    index_name="custom_index",
    embedding_dimension=1536
)

# Custom LLM configuration
llm_config = LLMConfig(
    provider="openai",
    model="gpt-4",
    temperature=0.1,
    max_tokens=2000
)

# Initialize with custom config
agent = RecoAgent(
    vector_store_config=vector_config,
    llm_config=llm_config
)

Performance Optimization

# performance_config.py
from recoagent.config import PerformanceConfig

# Performance configuration
perf_config = PerformanceConfig(
    max_concurrent_requests=10,
    request_timeout=30,
    cache_enabled=True,
    cache_ttl=3600,
    batch_size=100
)

agent = RecoAgent(performance_config=perf_config)

Troubleshooting

Common Issues

Import Error: No module named 'recoagent'

# Ensure virtual environment is activated
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

# Reinstall if needed
pip install --upgrade recoagent

OpenSearch Connection Failed

# Check if OpenSearch is running
curl -X GET "localhost:9200/_cluster/health?pretty"

# If not running, start with Docker
docker-compose -f docker-compose.opensearch.yml up -d

API Key Issues

# Verify API key is set
echo $OPENAI_API_KEY

# Test API key
python -c "import openai; openai.api_key='$OPENAI_API_KEY'; print('API key valid')"

Vector Store Index Issues

# Recreate index
from recoagent.stores import OpenSearchStore

store = OpenSearchStore()
store.recreate_index()

Getting Help

If you encounter issues:

Check the logs - Look for detailed error messages
Verify configuration - Ensure all environment variables are set
Test components - Try individual components separately
Contact support - Email support@recohut.com for assistance

Next Steps

Now that you have RecoAgent installed:

🚀 Quickstart Guide - Build your first agent in 10 minutes
🎯 Understanding RAG - Learn the fundamentals
🤖 Your First Agent - Create a complete agent
📚 Browse Examples - See working implementations

Summary

You've successfully:

✅ Set up Python development environment
✅ Installed RecoAgent and dependencies
✅ Configured vector store and LLM providers
✅ Verified installation with test script
✅ Set up development tools and IDE

You're now ready to start building with RecoAgent! The next tutorial will show you how to create your first agent in just 10 minutes.

Ready to continue? Head to the Quickstart Guide to build your first RecoAgent application!

What You'll Learn​

Prerequisites​

Step 1: Python Environment Setup​

Create Virtual Environment​

Verify Python Installation​

Step 2: Install RecoAgent​

Install Core Package​

Verify Installation​

Step 3: Configure Environment Variables​

Create Environment File​

Add Configuration​

Step 4: Set Up Vector Store​

Option A: OpenSearch (Recommended for Development)​

Option B: Azure AI Search​

Option C: Vertex AI Vector Search​

Step 5: Install Development Tools​

Code Quality Tools​

Documentation Tools​

Step 6: Verify Installation​

Test Basic Functionality​

Run Installation Test​

Step 7: Configure Development Environment​

IDE Setup (VS Code)​

Git Configuration​

Step 8: Advanced Configuration​

Custom Vector Store Configuration​

Performance Optimization​

Troubleshooting​

Common Issues​

Getting Help​

Next Steps​

Summary​