Installation

This guide covers different ways to install and set up HAP (Haive Agent Protocol).

Requirements

System Requirements:

  • Python 3.12 or higher

  • Poetry (recommended) or pip

  • Git (for development)

Dependencies:

  • pydantic ^2.0 - Data validation and serialization

  • typing-extensions ^4.8 - Extended type hints

  • aiofiles ^23.0 - Async file operations

  • aiohttp ^3.9 - HTTP client/server

  • click ^8.1 - CLI framework

  • rich ^13.0 - Rich text and beautiful formatting

Optional Dependencies:

  • pytest - For running tests

  • httpx - For HTTP testing

  • pytest-asyncio - Async test support

Quick Install

From Source (Recommended):

# Clone the Haive repository
git clone https://github.com/your-org/haive.git
cd haive/packages/haive-hap

# Install with Poetry
poetry install

# Or install with pip
pip install -e .

Development Install:

# Install with development dependencies
poetry install --with dev

# This includes pytest, httpx, and other dev tools

Verify Installation

Test that HAP is installed correctly:

# Test basic import
poetry run python -c "from haive.hap import HAPRuntime; print('✅ HAP installed successfully!')"

# Run the test suite
poetry run pytest tests/ -v

# Check version
poetry run python -c "import haive.hap; print(f'HAP Version: {haive.hap.__version__}')"

Environment Setup

Environment Variables:

HAP requires access to LLM providers. Set up your API keys:

# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Azure OpenAI
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"

Using .env Files:

Create a .env file in your project root:

# .env file
OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here

# Optional: Set default model
HAIVE_DEFAULT_MODEL=gpt-4
HAIVE_DEFAULT_TEMPERATURE=0.7

Loading Environment:

# Load .env file in Python
from dotenv import load_dotenv
load_dotenv()

# Or use in your scripts
import os
api_key = os.getenv("OPENAI_API_KEY")

Docker Installation

Using Docker:

# Pull the Haive image (when available)
docker pull haive/hap:latest

# Or build from source
cd haive/packages/haive-hap
docker build -t haive-hap .

# Run with environment variables
docker run -e OPENAI_API_KEY=$OPENAI_API_KEY haive-hap

Docker Compose:

# docker-compose.yml
version: '3.8'
services:
  hap:
    build: .
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./examples:/app/examples
    ports:
      - "8000:8000"

Production Setup

Production Considerations:

  1. Security: Never hardcode API keys in source code

  2. Logging: Configure proper logging levels

  3. Monitoring: Set up health checks and metrics

  4. Scaling: Use async/await patterns for concurrent execution

Production Environment:

# Use production environment
export ENVIRONMENT=production
export LOG_LEVEL=INFO

# Set resource limits
export MAX_CONCURRENT_AGENTS=10
export TIMEOUT_SECONDS=300

Systemd Service (Linux):

# /etc/systemd/system/hap.service
[Unit]
Description=HAP Service
After=network.target

[Service]
Type=simple
User=hap
WorkingDirectory=/opt/hap
Environment=OPENAI_API_KEY=your-key
ExecStart=/opt/hap/.venv/bin/poetry run python -m haive.hap.server
Restart=always

[Install]
WantedBy=multi-user.target

IDE Configuration

VS Code:

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.formatting.provider": "black",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests/"]
}

PyCharm:

  1. Set interpreter to Poetry virtual environment

  2. Enable pytest as test runner

  3. Configure code style to match project standards

Vim/Neovim:

Add to your config:

" Python LSP
let g:python3_host_prog = './venv/bin/python'

" Async testing
autocmd FileType python nnoremap <leader>t :!poetry run pytest %<CR>

Troubleshooting

Common Issues:

1. Poetry not found:

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

2. Python version issues:

# Check Python version
python --version

# Use specific Python version
poetry env use python3.12

3. Import errors:

# Reinstall dependencies
poetry install --no-cache

# Check installed packages
poetry show

4. API key issues:

# Verify environment variables
echo $OPENAI_API_KEY

# Test API connection
poetry run python -c "
import openai
client = openai.OpenAI()
print('✅ API connection successful!')
"

5. Permission errors:

# Fix poetry permissions
chown -R $USER ~/.local/share/pypoetry

# Or use user install
poetry config virtualenvs.in-project true

Performance Optimization

Memory Usage:

# Configure for memory efficiency
import gc
import asyncio

# Set asyncio loop policy
if hasattr(asyncio, 'WindowsProactorEventLoopPolicy'):
    asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())

# Enable garbage collection
gc.enable()

Concurrent Execution:

# Configure semaphore for concurrent agents
from haive.hap.server.runtime import HAPRuntime

runtime = HAPRuntime(
    graph,
    max_concurrent=5,  # Limit concurrent execution
    timeout=300        # Set execution timeout
)

Development Setup

For Contributors:

# Clone with all submodules
git clone --recursive https://github.com/your-org/haive.git
cd haive/packages/haive-hap

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

# Run full test suite
poetry run pytest tests/ --cov=haive.hap --cov-report=html

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

Testing Different Configurations:

# Test with different Python versions
poetry env use python3.12
poetry install
poetry run pytest

# Test with minimal dependencies
poetry install --no-dev
poetry run python examples/basic_workflow.py

Next Steps

Once HAP is installed:

  1. Quick Start: Follow the Getting Started guide

  2. Examples: Try the examples in the examples/ directory

  3. Documentation: Read the full documentation

  4. Community: Join our community for support

Useful Commands:

# Update HAP
cd haive/packages/haive-hap && git pull && poetry install

# Clean install
poetry env remove python && poetry install

# Development mode
poetry install --with dev,test,docs