Setup Development Environment

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 development environment where you can run RecoAgent examples and build applications.

⚡ 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 packages.rag import HybridRetriever; 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.

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 recoagent-dev
cd recoagent-dev

# 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

# 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: 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 6: 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 7: 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 8: Documentation Setup

Install Documentation Dependencies

# Navigate to docs directory
cd docs

# Install Node.js dependencies
npm install

# Verify installation
npm list

Start Documentation Server

# Start development server
npm run docs:start

# Open browser to http://localhost:3000

Step 9: Verification

Create Test Script

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

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 main():
    """Run all tests."""
    print("🧪 Testing RecoAgent Development Environment")
    print("=" * 50)
    
    tests = [
        test_python_version,
        test_imports,
        test_environment_variables,
        test_vector_store_connection
    ]
    
    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" + "=" * 50)
    print(f"📊 Test Results: {passed}/{total} tests passed")
    
    if passed == total:
        print("🎉 Environment setup successful!")
        return True
    else:
        print("❌ Environment 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

Step 10: Create Development Scripts

Create Makefile

cat > Makefile << EOF
.PHONY: help install test lint format clean dev docs

help: ## Show this help message
	@echo 'Usage: make [target]'
	@echo ''
	@echo 'Targets:'
	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-15s %s\\n", $$1, $$2}' $(MAKEFILE_LIST)

install: ## Install dependencies
	pip install -e .
	pip install -r requirements-dev.txt

test: ## Run tests
	pytest tests/ -v --cov=recoagent --cov-report=html

lint: ## Run linters
	flake8 .
	mypy .

format: ## Format code
	black .
	isort .

clean: ## Clean up
	find . -type f -name "*.pyc" -delete
	find . -type d -name "__pycache__" -delete
	find . -type d -name "*.egg-info" -exec rm -rf {} +
	rm -rf build/
	rm -rf dist/
	rm -rf .coverage
	rm -rf htmlcov/

dev: ## Start development environment
	docker-compose up -d
	source venv/bin/activate

docs: ## Start documentation server
	cd docs && npm run docs:start

build: ## Build package
	python -m build

publish: ## Publish package
	twine upload dist/*
EOF

Create Development Requirements

cat > requirements-dev.txt << EOF
# Development dependencies
black>=23.3.0
isort>=5.12.0
flake8>=6.0.0
mypy>=1.3.0
pre-commit>=3.3.0

# Testing
pytest>=7.3.0
pytest-cov>=4.1.0
pytest-mock>=3.10.0
pytest-asyncio>=0.21.0

# Documentation
sphinx>=6.2.0
sphinx-rtd-theme>=1.2.0

# Build tools
build>=0.10.0
twine>=4.0.0
EOF

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! You can:

🚀 Quickstart Guide - Build your first agent
📚 Browse Examples - See working implementations
🔧 How-To Guides - Learn specific 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)
✅ 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 with RecoAgent!

Ready to start coding? Head to the Quickstart Guide to build your first agent!

🎯 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: Development Tools Setup​

Code Quality Tools​

Pre-commit Hooks​

Step 6: IDE Configuration​

VS Code Setup​

PyCharm Setup​

Step 7: Testing Setup​

Install Testing Dependencies​

Create Test Configuration​

Create Sample Test​

Step 8: Documentation Setup​

Install Documentation Dependencies​

Start Documentation Server​

Step 9: Verification​

Create Test Script​

Step 10: Create Development Scripts​

Create Makefile​

Create Development Requirements​

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: Development Tools Setup

Code Quality Tools

Pre-commit Hooks

Step 6: IDE Configuration

VS Code Setup

PyCharm Setup

Step 7: Testing Setup

Install Testing Dependencies

Create Test Configuration

Create Sample Test

Step 8: Documentation Setup

Install Documentation Dependencies

Start Documentation Server

Step 9: Verification

Create Test Script

Step 10: Create Development Scripts

Create Makefile

Create Development Requirements

Troubleshooting

Common Issues

Getting Help

Next Steps

Summary