💻 Installation & Setup

This guide covers everything you need to install and configure Haive Agents for development and production use.

System Requirements

Python Version

  • Python 3.9+ (recommended: 3.11+)

  • Poetry 1.4+ (for development)

Operating Systems

  • Linux (Ubuntu 20.04+, CentOS 8+)

  • macOS 12+ (Intel and Apple Silicon)

  • Windows 10+ (with WSL2 recommended)

Memory and Storage

  • Minimum: 4GB RAM, 2GB disk space

  • Recommended: 8GB+ RAM, 5GB+ disk space

  • Production: 16GB+ RAM, SSD storage

Optional Dependencies

  • PostgreSQL 13+ (for persistent storage)

  • Redis 6+ (for caching and queues)

  • Neo4j 5+ (for graph-based memory)

  • Docker (for containerized deployment)

Quick Installation

Option 1: pip (Recommended for Users)

# Install latest stable version
pip install haive-agents

# Or with all optional dependencies
pip install haive-agents[all]

# Verify installation
python -c "from haive.agents import SimpleAgent; print('✅ Installation successful')"

Option 2: Poetry (Recommended for Development)

# Clone repository
git clone https://github.com/pr1m8/haive-agents.git
cd haive-agents

# Install with poetry
poetry install

# Activate environment
poetry shell

# Verify installation
poetry run python -c "from haive.agents import SimpleAgent; print('✅ Installation successful')"

Option 3: Development Setup

# Clone with submodules (full development)
git clone --recursive https://github.com/pr1m8/haive.git
cd haive/packages/haive-agents

# Install in development mode
poetry install --all-extras

# Install pre-commit hooks
poetry run pre-commit install

# Run tests to verify setup
poetry run pytest tests/ -x

Installation Options

Core Package (Minimal)

pip install haive-agents
Includes:

  • SimpleAgent and ReactAgent

  • Basic multi-agent coordination

  • Core engine and tools

  • LangChain integration

With Memory Systems

pip install haive-agents[memory]
Adds:

  • Vector stores (Chroma, FAISS)

  • Graph databases (Neo4j)

  • Advanced retrieval systems

  • Memory classification

With Advanced Features

pip install haive-agents[advanced]
Adds:

  • Self-modification capabilities

  • Dynamic supervision

  • Provider switching

  • Performance monitoring

Complete Installation

pip install haive-agents[all]
Includes:

  • All optional dependencies

  • Development tools

  • Testing frameworks

  • Documentation tools

Environment Setup

1. Environment Variables

Create a .env file in your project root:

# LLM Provider Configuration
OPENAI_API_KEY=your_openai_key_here
AZURE_OPENAI_API_KEY=your_azure_key_here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
ANTHROPIC_API_KEY=your_anthropic_key_here

# Database Configuration (Optional)
DATABASE_URL=postgresql://user:password@localhost:5432/haive_agents
REDIS_URL=redis://localhost:6379/0
NEO4J_URI=neo4j://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_neo4j_password

# Monitoring and Logging
LOG_LEVEL=INFO
ENABLE_TRACING=true
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langchain_key

2. Load Environment in Python

import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Verify configuration
required_vars = ["OPENAI_API_KEY"]
missing = [var for var in required_vars if not os.getenv(var)]

if missing:
    print(f"❌ Missing required environment variables: {', '.join(missing)}")
else:
    print("✅ Environment configuration complete")

3. Configuration File (Optional)

Create haive_config.yaml for advanced configuration:

# Haive Agents Configuration
agents:
  default_temperature: 0.7
  max_tokens: 2000
  enable_streaming: true

memory:
  enable_persistence: true
  vector_store: chroma
  graph_store: neo4j
  consolidation_interval: 3600  # 1 hour

monitoring:
  enable_metrics: true
  trace_conversations: true
  log_tool_usage: true

performance:
  max_concurrent_agents: 10
  timeout_seconds: 300
  enable_caching: true

Provider Configuration

OpenAI Configuration

from haive.core.engine.aug_llm import AugLLMConfig

# Basic OpenAI configuration
config = AugLLMConfig(
    provider="openai",
    model="gpt-4",
    api_key=os.getenv("OPENAI_API_KEY"),
    temperature=0.7,
    max_tokens=2000
)

Azure OpenAI Configuration

config = AugLLMConfig(
    provider="azure",
    model="gpt-4",
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    api_base=os.getenv("AZURE_OPENAI_ENDPOINT"),
    api_version="2024-02-15-preview",
    deployment_name="gpt-4-deployment"
)

Anthropic Claude Configuration

config = AugLLMConfig(
    provider="anthropic",
    model="claude-3-opus-20240229",
    api_key=os.getenv("ANTHROPIC_API_KEY"),
    temperature=0.7,
    max_tokens=4000
)

Multiple Provider Setup

from haive.agents.agent import ProviderSwitchingAgent

# Agent that can switch between providers
multi_provider_agent = ProviderSwitchingAgent(
    name="adaptive_agent",
    providers={
        "fast": AugLLMConfig(provider="openai", model="gpt-3.5-turbo"),
        "smart": AugLLMConfig(provider="openai", model="gpt-4"),
        "creative": AugLLMConfig(provider="anthropic", model="claude-3-opus-20240229")
    }
)

Database Setup (Optional)

PostgreSQL Setup

# Install PostgreSQL
sudo apt-get install postgresql postgresql-contrib  # Ubuntu
brew install postgresql  # macOS

# Create database
sudo -u postgres psql
CREATE DATABASE haive_agents;
CREATE USER haive_user WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE haive_agents TO haive_user;
\q

Redis Setup

# Install Redis
sudo apt-get install redis-server  # Ubuntu
brew install redis  # macOS

# Start Redis
redis-server

# Test connection
redis-cli ping  # Should return PONG

Neo4j Setup

# Using Docker (Recommended)
docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your_password \
  -e NEO4J_PLUGINS='["apoc", "graph-data-science"]' \
  neo4j:5.15

# Access Neo4j Browser: http://localhost:7474

Memory System Configuration

Basic Vector Store

from haive.agents.memory_reorganized import SimpleMemoryAgent

# Simple in-memory vector store
memory_agent = SimpleMemoryAgent(
    name="assistant_with_memory",
    memory_config={
        "store_type": "chroma",
        "persist_directory": "./chroma_db",
        "enable_classification": True
    }
)

Advanced Integrated Memory

from haive.agents.memory_reorganized.coordination import IntegratedMemorySystem

# Full memory system with graph + vector + temporal
memory_config = {
    "mode": "INTEGRATED",
    "enable_classification": True,
    "enable_consolidation": True,
    "chroma_config": {
        "persist_directory": "./memory/chroma",
        "collection_name": "agent_memory"
    },
    "neo4j_config": {
        "uri": os.getenv("NEO4J_URI"),
        "username": os.getenv("NEO4J_USERNAME"),
        "password": os.getenv("NEO4J_PASSWORD")
    },
    "consolidation_schedule": "0 2 * * *"  # Daily at 2 AM
}

Development Tools

Code Quality Tools

# Install development dependencies
poetry install --group dev

# Pre-commit hooks
poetry run pre-commit install

# Code formatting
poetry run black src/ tests/
poetry run isort src/ tests/

# Type checking
poetry run mypy src/

# Linting
poetry run flake8 src/
poetry run pylint src/

Testing Setup

# Run all tests
poetry run pytest tests/

# Run with coverage
poetry run pytest tests/ --cov=haive.agents --cov-report=html

# Run specific test categories
poetry run pytest tests/simple/ -v     # SimpleAgent tests
poetry run pytest tests/react/ -v      # ReactAgent tests
poetry run pytest tests/multi/ -v      # Multi-agent tests

Documentation Building

# Build documentation
cd docs/
poetry run sphinx-build -b html source build/

# Serve locally
python -m http.server 8000 --directory build/
# Visit: http://localhost:8000

Verification and Testing

Quick Smoke Test

import asyncio
from haive.agents import SimpleAgent
from haive.core.engine.aug_llm import AugLLMConfig

async def test_installation():
    """Verify installation works correctly."""
    try:
        # Create agent
        agent = SimpleAgent(
            name="test_agent",
            engine=AugLLMConfig(temperature=0.1)
        )

        # Test execution
        result = await agent.arun("Say 'Installation successful!'")

        if "successful" in result.lower():
            print("✅ Installation verified - agent working correctly")
            return True
        else:
            print("⚠️  Installation may have issues - unexpected response")
            return False

    except Exception as e:
        print(f"❌ Installation verification failed: {e}")
        return False

# Run test
if __name__ == "__main__":
    success = asyncio.run(test_installation())
    exit(0 if success else 1)

Comprehensive System Test

async def comprehensive_test():
    """Test all major components."""
    from haive.agents import SimpleAgent, ReactAgent, MultiAgent
    from langchain_core.tools import tool

    @tool
    def test_calculator(expression: str) -> str:
        """Simple calculator for testing."""
        return str(eval(expression))

    # Test 1: Simple Agent
    simple = SimpleAgent(name="simple", engine=AugLLMConfig())
    result1 = await simple.arun("What is 2+2?")
    assert "4" in result1
    print("✅ SimpleAgent test passed")

    # Test 2: React Agent with Tools
    react = ReactAgent(
        name="react",
        engine=AugLLMConfig(),
        tools=[test_calculator]
    )
    result2 = await react.arun("Calculate 15 * 7")
    assert "105" in result2
    print("✅ ReactAgent with tools test passed")

    # Test 3: Multi-Agent
    multi = MultiAgent(
        name="multi",
        agents=[simple, react],
        execution_mode="sequential"
    )
    result3 = await multi.arun("Hello from the team!")
    assert len(result3) > 0
    print("✅ MultiAgent test passed")

    print("🎉 All tests passed - installation fully verified!")

Performance Benchmark

import time
import asyncio

async def benchmark_performance():
    """Basic performance benchmark."""
    agent = SimpleAgent(
        name="benchmark",
        engine=AugLLMConfig(temperature=0.1)
    )

    # Warm-up
    await agent.arun("Hello")

    # Benchmark
    start_time = time.time()
    tasks = [agent.arun(f"Count to {i}") for i in range(1, 6)]
    results = await asyncio.gather(*tasks)
    end_time = time.time()

    total_time = end_time - start_time
    avg_time = total_time / len(tasks)

    print(f"📊 Benchmark Results:")
    print(f"   Total time: {total_time:.2f}s")
    print(f"   Average per request: {avg_time:.2f}s")
    print(f"   Requests per second: {len(tasks)/total_time:.2f}")

    if avg_time < 10.0:
        print("✅ Performance: Good")
    elif avg_time < 30.0:
        print("⚠️  Performance: Acceptable")
    else:
        print("❌ Performance: Poor - check your setup")

Troubleshooting

Common Issues

“No module named ‘haive’”

# Ensure proper installation
pip install --upgrade haive-agents

# Or for development
poetry install
poetry shell

“OpenAI API Key not found”

# Set environment variable
export OPENAI_API_KEY="your_key_here"

# Or create .env file
echo "OPENAI_API_KEY=your_key_here" > .env

“Connection refused” errors

# Check database services
systemctl status postgresql  # Linux
brew services list | grep postgres  # macOS

# Check Redis
redis-cli ping

# Check Neo4j
docker ps | grep neo4j

Memory issues with large models

# Use streaming for large responses
config = AugLLMConfig(
    model="gpt-4",
    max_tokens=1000,  # Smaller chunks
    stream=True
)

Performance issues

# Enable caching
config = AugLLMConfig(
    enable_caching=True,
    cache_ttl=3600  # 1 hour
)

# Use faster models for simple tasks
fast_config = AugLLMConfig(model="gpt-3.5-turbo")

Getting Help

If you encounter issues:

  1. Check the logs: Enable debug logging with LOG_LEVEL=DEBUG

  2. Search issues: Check GitHub Issues

  3. Join Discord: Get help from the community

  4. Create an issue: Provide full error details and system information

System Information Script

import sys
import platform
import pkg_resources

def print_system_info():
    print("🔍 System Information")
    print(f"   Python: {sys.version}")
    print(f"   Platform: {platform.platform()}")
    print(f"   Architecture: {platform.architecture()}")

    try:
        version = pkg_resources.get_distribution("haive-agents").version
        print(f"   Haive Agents: {version}")
    except:
        print("   Haive Agents: Not installed")

    print("\n📦 Key Dependencies")
    deps = ["langchain", "openai", "anthropic", "pydantic"]
    for dep in deps:
        try:
            version = pkg_resources.get_distribution(dep).version
            print(f"   {dep}: {version}")
        except:
            print(f"   {dep}: Not installed")

Next Steps

Now that you have Haive Agents installed and configured:

  1. Try the Quick Start: 🚀 Quick Start Guide - Build your first agents

  2. Explore Examples: Check the examples/ directory

  3. Read the Guides: Agent Types and Memory Systems

  4. Join the Community: Discord, GitHub Discussions

  5. Build Something Amazing: Start your first agent project!

Tip

Start with a simple agent and gradually add complexity. The modular design makes it easy to enhance your agents as your requirements grow.

Note

For production deployments, consider using Docker containers and managed databases for better scalability and reliability.