Setup Development Environment & Quickstart

Difficulty: ⭐ Beginner | Time: 30-45 minutes

🎯 The Problem

You want to start building with RecoAgent but don't have the development environment configured. You need Python, dependencies, vector stores, and tools all working together - but setting this up from scratch is time-consuming and error-prone.

This guide solves: Getting from zero to a working RecoAgent application with your first RAG agent in 30-45 minutes.

⚡ TL;DR - Quick Start

# 1. Create virtual environment
python -m venv venv && source venv/bin/activate

# 2. Install RecoAgent
pip install recoagent

# 3. Set environment variables
export OPENAI_API_KEY="your-key"
export LANGSMITH_API_KEY="your-key"

# 4. Start local OpenSearch (optional)
docker-compose up -d opensearch

# 5. Test installation
python -c "from recoagent import RecoAgent; print('✅ Ready!')"

Expected result: "✅ Ready!" message means you're set up!

Full Setup Guide

This guide will walk you through setting up a complete development environment for RecoAgent, including Python, dependencies, vector stores, and development tools, then build your first RAG agent.

Prerequisites

Before starting, ensure you have:

Python 3.8+ installed
Node.js 18+ (for documentation)
Git for version control
Docker (optional, for local services)
API Keys for your chosen providers

Step 1: Python Environment Setup

Install Python

macOS (using Homebrew):

brew install python@3.11

Ubuntu/Debian:

sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-pip

Windows: Download from python.org or use:

winget install Python.Python.3.11

Verify Installation

python --version
# Should show Python 3.8 or higher
pip --version

Create Virtual Environment

# Create project directory
mkdir my-recoagent-project
cd my-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 activation (should show venv path)
which python

Step 2: Install RecoAgent

Install Core Package

# Install RecoAgent
pip install recoagent

# Install development dependencies
pip install recoagent[dev]

# Install additional tools
pip install black isort flake8 mypy pytest pytest-cov pre-commit

Verify Installation

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

Step 3: Configure API Keys

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_dev

# 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-dev-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

# Development Settings
DEBUG=true
LOG_LEVEL=INFO

Test API Keys

# Test OpenAI API key
python -c "
import openai
import os
from dotenv import load_dotenv
load_dotenv()
openai.api_key = os.getenv('OPENAI_API_KEY')
print('OpenAI API key valid!' if openai.api_key else 'OpenAI API key not set')
"

Step 4: Set Up Vector Store

Option A: OpenSearch (Recommended for Development)

Using Docker Compose:

# Create docker-compose.yml
cat > docker-compose.yml << EOF
version: '3.8'
services:
  opensearch:
    image: opensearchproject/opensearch:2.11.0
    container_name: opensearch
    environment:
      - discovery.type=single-node
      - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
      - "DISABLE_INSTALL_DEMO_CONFIG=true"
      - "DISABLE_SECURITY_PLUGIN=true"
    ports:
      - 9200:9200
      - 9600:9600
    volumes:
      - opensearch-data:/usr/share/opensearch/data

  opensearch-dashboards:
    image: opensearchproject/opensearch-dashboards:2.11.0
    container_name: opensearch-dashboards
    ports:
      - 5601:5601
    environment:
      - 'OPENSEARCH_HOSTS=["http://opensearch:9200"]'
    depends_on:
      - opensearch

volumes:
  opensearch-data:
EOF

# Start OpenSearch
docker-compose up -d

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

Manual Installation:

# Download and install OpenSearch
wget https://artifacts.opensearch.org/releases/bundle/opensearch/2.11.0/opensearch-2.11.0-linux-x64.tar.gz
tar -xzf opensearch-2.11.0-linux-x64.tar.gz
cd opensearch-2.11.0

# Start OpenSearch
./bin/opensearch

Option B: Azure AI Search

# Install Azure CLI
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Login to Azure
az login

# Create resource group
az group create --name recoagent-rg --location eastus

# Create search service
az search service create \
  --resource-group recoagent-rg \
  --name recoagent-search \
  --sku Standard \
  --partition-count 1 \
  --replica-count 1

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

# Enable APIs
gcloud services enable aiplatform.googleapis.com

Step 5: Create Your First Agent

Now let's build your first RAG agent! Create a file called quickstart.py:

import os
from dotenv import load_dotenv
from recoagent import RecoAgent, DocumentLoader
from recoagent.retrievers import HybridRetriever
from recoagent.agents import RAGAgent

# Load environment variables
load_dotenv()

# Initialize the agent
agent = RecoAgent(
    llm_provider="openai",
    embedding_model="text-embedding-ada-002",
    vector_store="opensearch"  # or "azure" or "vertex"
)

# Load some sample documents
loader = DocumentLoader()
documents = loader.load_from_text([
    "RecoAgent is an enterprise RAG platform built with LangGraph and LangChain.",
    "It supports hybrid retrieval combining BM25 and vector embeddings.",
    "The platform includes built-in evaluation metrics and safety guardrails.",
    "RecoAgent supports multiple vector stores including OpenSearch, Azure AI Search, and Vertex AI Vector Search.",
    "The platform includes NVIDIA NeMo Guardrails for safety and governance.",
    "RecoAgent provides comprehensive observability with LangSmith integration.",
    "You can evaluate your RAG system using RAGAS metrics like context precision and faithfulness."
])

# Create a simple RAG agent
rag_agent = RAGAgent(
    retriever=HybridRetriever(),
    system_prompt="You are a helpful assistant that answers questions about RecoAgent."
)

print("RecoAgent initialized successfully!")

Step 6: Test Your Agent

Now let's test the agent with a simple question:

# Ask a question
question = "What is RecoAgent?"

# Get the response
response = rag_agent.ask(question)
print(f"Question: {question}")
print(f"Answer: {response.answer}")
print(f"Sources: {response.sources}")

Step 7: Add More Documents

Let's add more documents to make the agent more useful:

# Add more documents
more_docs = [
    "RecoAgent supports multiple vector stores including OpenSearch, Azure AI Search, and Vertex AI Vector Search.",
    "The platform includes NVIDIA NeMo Guardrails for safety and governance.",
    "RecoAgent provides comprehensive observability with LangSmith integration.",
    "You can evaluate your RAG system using RAGAS metrics like context precision and faithfulness."
]

# Update the agent's knowledge base
rag_agent.add_documents(more_docs)

# Test with a more complex question
question = "What vector stores does RecoAgent support and what safety features does it include?"

response = rag_agent.ask(question)
print(f"Question: {question}")
print(f"Answer: {response.answer}")
print(f"Sources: {len(response.sources)} documents referenced")

Step 8: Explore Advanced Features

Let's try a multi-step question that requires reasoning:

# Enable multi-step reasoning
rag_agent.enable_multi_step_reasoning = True

# Ask a complex question
question = "How can I evaluate the quality of my RAG system and what metrics should I focus on?"

response = rag_agent.ask(question)
print(f"Question: {question}")
print(f"Answer: {response.answer}")
print(f"Reasoning steps: {len(response.reasoning_steps)}")
print(f"Confidence score: {response.confidence}")

Step 9: Development Tools Setup

Code Quality Tools

Black (Code Formatter):

# Install Black
pip install black

# Create configuration
cat > pyproject.toml << EOF
[tool.black]
line-length = 88
target-version = ['py38']
include = '\.pyi?$'
extend-exclude = '''
/(
  # directories
  \.eggs
  | \.git
  | \.hg
  | \.mypy_cache
  | \.tox
  | \.venv
  | build
  | dist
)/
'''
EOF

# Test Black
black --check .

isort (Import Sorter):

# Install isort
pip install isort

# Create configuration
cat > .isort.cfg << EOF
[settings]
profile = black
multi_line_output = 3
line_length = 88
known_first_party = recoagent
EOF

# Test isort
isort --check-only .

Flake8 (Linter):

# Install flake8
pip install flake8

# Create configuration
cat > .flake8 << EOF
[flake8]
max-line-length = 88
extend-ignore = E203, W503
exclude = 
    .git,
    __pycache__,
    .venv,
    build,
    dist
EOF

# Test flake8
flake8 .

MyPy (Type Checker):

# Install mypy
pip install mypy

# Create configuration
cat > mypy.ini << EOF
[mypy]
python_version = 3.8
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True
ignore_missing_imports = True
EOF

# Test mypy
mypy .

Pre-commit Hooks

# Install pre-commit
pip install pre-commit

# Create configuration
cat > .pre-commit-config.yaml << EOF
repos:
  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
      - id: black
        language_version: python3

  - repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
      - id: isort

  - repo: https://github.com/pycqa/flake8
    rev: 6.0.0
    hooks:
      - id: flake8

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.3.0
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]
EOF

# Install pre-commit hooks
pre-commit install

# Test pre-commit
pre-commit run --all-files

Step 10: IDE Configuration

VS Code Setup

Install Extensions:

# Install VS Code extensions
code --install-extension ms-python.python
code --install-extension ms-python.black-formatter
code --install-extension ms-python.isort
code --install-extension ms-python.flake8
code --install-extension ms-python.mypy-type-checker
code --install-extension ms-toolsai.jupyter
code --install-extension ms-vscode.vscode-json

Create VS Code Settings:

mkdir -p .vscode
cat > .vscode/settings.json << EOF
{
    "python.defaultInterpreterPath": "./venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.flake8Enabled": true,
    "python.formatting.provider": "black",
    "python.sortImports.args": ["--profile", "black"],
    "python.terminal.activateEnvironment": true,
    "files.exclude": {
        "**/__pycache__": true,
        "**/.pytest_cache": true,
        "**/venv": true,
        "**/.venv": true
    },
    "python.testing.pytestEnabled": true,
    "python.testing.unittestEnabled": false,
    "python.testing.pytestArgs": [
        "tests"
    ]
}
EOF

PyCharm Setup

Open Project: File → Open → Select your project directory
Configure Interpreter: File → Settings → Project → Python Interpreter
Add Virtual Environment: Click gear → Add → Existing Environment → Select venv/bin/python
Configure Code Style: File → Settings → Editor → Code Style → Python
Set Black as Formatter: File → Settings → Tools → External Tools → Add Black

Step 11: Testing Setup

Install Testing Dependencies

pip install pytest pytest-cov pytest-mock pytest-asyncio

Create Test Configuration

# Create pytest configuration
cat > pytest.ini << EOF
[tool:pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts = 
    --verbose
    --tb=short
    --cov=recoagent
    --cov-report=html
    --cov-report=term-missing
    --cov-fail-under=80
EOF

# Create tests directory
mkdir tests
touch tests/__init__.py
touch tests/conftest.py

Create Sample Test

cat > tests/test_basic.py << EOF
import pytest
from recoagent import RecoAgent

def test_recoagent_import():
    """Test that RecoAgent can be imported."""
    assert RecoAgent is not None

def test_recoagent_initialization():
    """Test basic RecoAgent initialization."""
    agent = RecoAgent()
    assert agent is not None

@pytest.mark.asyncio
async def test_async_functionality():
    """Test async functionality."""
    # Your async tests here
    pass
EOF

# Run tests
pytest tests/ -v

Step 12: Verification

Create Test Script

cat > test_environment.py << EOF
#!/usr/bin/env python3
"""Test script to verify environment setup and first agent."""

import os
import sys
from dotenv import load_dotenv

def test_python_version():
    """Test Python version."""
    version = sys.version_info
    assert version.major == 3 and version.minor >= 8, f"Python 3.8+ required, got {version.major}.{version.minor}"
    print(f"✅ Python version: {version.major}.{version.minor}.{version.micro}")

def test_imports():
    """Test required imports."""
    try:
        import recoagent
        print("✅ RecoAgent imported successfully")
    except ImportError as e:
        print(f"❌ RecoAgent import failed: {e}")
        return False
    
    try:
        import openai
        print("✅ OpenAI imported successfully")
    except ImportError as e:
        print(f"❌ OpenAI import failed: {e}")
        return False
    
    return True

def test_environment_variables():
    """Test environment variables."""
    load_dotenv()
    
    required_vars = ['OPENAI_API_KEY']
    missing_vars = []
    
    for var in required_vars:
        if not os.getenv(var):
            missing_vars.append(var)
    
    if missing_vars:
        print(f"❌ Missing environment variables: {missing_vars}")
        return False
    else:
        print("✅ All required environment variables set")
        return True

def test_vector_store_connection():
    """Test vector store connection."""
    load_dotenv()
    
    vector_store_type = os.getenv('VECTOR_STORE_TYPE', 'opensearch')
    
    if vector_store_type == 'opensearch':
        try:
            import requests
            response = requests.get('http://localhost:9200/_cluster/health')
            if response.status_code == 200:
                print("✅ OpenSearch connection successful")
                return True
            else:
                print(f"❌ OpenSearch connection failed: {response.status_code}")
                return False
        except Exception as e:
            print(f"❌ OpenSearch connection failed: {e}")
            return False
    else:
        print(f"ℹ️  Vector store type '{vector_store_type}' - skipping connection test")
        return True

def test_first_agent():
    """Test creating and using first agent."""
    try:
        from recoagent import RecoAgent, DocumentLoader
        from recoagent.retrievers import HybridRetriever
        from recoagent.agents import RAGAgent
        
        # Initialize the agent
        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"❌ First agent test failed: {e}")
        return False

def main():
    """Run all tests."""
    print("🧪 Testing RecoAgent Development Environment & First Agent")
    print("=" * 60)
    
    tests = [
        test_python_version,
        test_imports,
        test_environment_variables,
        test_vector_store_connection,
        test_first_agent
    ]
    
    passed = 0
    total = len(tests)
    
    for test in tests:
        try:
            if test():
                passed += 1
        except Exception as e:
            print(f"❌ {test.__name__} failed: {e}")
    
    print("\n" + "=" * 60)
    print(f"📊 Test Results: {passed}/{total} tests passed")
    
    if passed == total:
        print("🎉 Environment setup and first agent successful!")
        return True
    else:
        print("❌ Setup incomplete. Please fix the issues above.")
        return False

if __name__ == "__main__":
    success = main()
    sys.exit(0 if success else 1)
EOF

# Run environment test
python test_environment.py

What You've Accomplished

Congratulations! In 30-45 minutes, you've:

✅ Set up development environment - Python, virtual environment, dependencies
✅ Installed RecoAgent - Core package and development tools
✅ Configured vector store - OpenSearch, Azure AI Search, or Vertex AI
✅ Created your first agent - Built a working RAG system
✅ Added knowledge - Loaded documents into the agent
✅ Tested functionality - Asked questions and got answers
✅ Explored advanced features - Used multi-step reasoning
✅ Set up development tools - Code quality, testing, IDE configuration
✅ Verified installation - Confirmed everything works correctly

Troubleshooting

Common Issues

Python Version Issues:

# Check Python version
python --version

# If wrong version, create new venv with correct version
python3.11 -m venv venv
source venv/bin/activate

Virtual Environment Issues:

# Deactivate and recreate
deactivate
rm -rf venv
python -m venv venv
source venv/bin/activate
pip install --upgrade pip

OpenSearch Connection Issues:

# Check if OpenSearch is running
docker ps | grep opensearch

# Check logs
docker logs opensearch

# Restart OpenSearch
docker-compose restart opensearch

API Key Issues:

# Verify .env file exists and has correct format
cat .env

# Test API key
python -c "
import os
from dotenv import load_dotenv
load_dotenv()
print('API Key set:', bool(os.getenv('OPENAI_API_KEY')))
"

Import Errors:

# Ensure virtual environment is activated
which python

# Reinstall packages
pip install --upgrade -r requirements.txt
pip install --upgrade recoagent

Getting Help

If you encounter issues:

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

Next Steps

Your development environment is now ready and you have your first agent working! You can:

🚀 First Agent Tutorial - Build a more sophisticated agent
📚 Browse Examples - See working implementations
🔧 Setup Guides - Learn specific configuration tasks
📖 API Reference - Explore the full API

Summary

You've successfully set up:

✅ Python 3.8+ with virtual environment
✅ RecoAgent and all dependencies
✅ API keys and configuration
✅ Vector store (OpenSearch/Azure/Vertex AI)
✅ First RAG agent - Working question-answering system
✅ Development tools (Black, isort, flake8, mypy)
✅ Testing framework (pytest)
✅ Documentation (Docusaurus)
✅ IDE configuration (VS Code/PyCharm)
✅ Pre-commit hooks for code quality

You're ready to start building sophisticated RecoAgent applications!

Ready to continue? Head to the First Agent tutorial to build a more sophisticated RecoAgent application!

🎯 The Problem​

⚡ TL;DR - Quick Start​

Full Setup Guide​

Prerequisites​

Step 1: Python Environment Setup​

Install Python​

Verify Installation​

Create Virtual Environment​

Step 2: Install RecoAgent​

Install Core Package​

Verify Installation​

Step 3: Configure API Keys​

Create Environment File​

Add Configuration​

Test API Keys​

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: Create Your First Agent​

Step 6: Test Your Agent​

Step 7: Add More Documents​

Step 8: Explore Advanced Features​

Step 9: Development Tools Setup​

Code Quality Tools​

Pre-commit Hooks​

Step 10: IDE Configuration​

VS Code Setup​

PyCharm Setup​

Step 11: Testing Setup​

Install Testing Dependencies​

Create Test Configuration​

Create Sample Test​

Step 12: Verification​

Create Test Script​

What You've Accomplished​

Troubleshooting​

Common Issues​

Getting Help​

Next Steps​

Summary​

🎯 The Problem

⚡ TL;DR - Quick Start

Full Setup Guide

Prerequisites

Step 1: Python Environment Setup

Install Python

Verify Installation

Create Virtual Environment

Step 2: Install RecoAgent

Install Core Package

Verify Installation

Step 3: Configure API Keys

Create Environment File

Add Configuration

Test API Keys

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: Create Your First Agent

Step 6: Test Your Agent

Step 7: Add More Documents

Step 8: Explore Advanced Features

Step 9: Development Tools Setup

Code Quality Tools

Pre-commit Hooks

Step 10: IDE Configuration

VS Code Setup

PyCharm Setup

Step 11: Testing Setup

Install Testing Dependencies

Create Test Configuration

Create Sample Test

Step 12: Verification

Create Test Script

What You've Accomplished

Troubleshooting

Common Issues

Getting Help

Next Steps

Summary