Configuration Guide¶
This guide covers all configuration options available in haive-games.
Engine Configuration¶
AugLLMConfig Options¶
The AugLLMConfig class provides comprehensive configuration for LLM engines:
from haive.core.engine.aug_llm import AugLLMConfig
# Full configuration example
config = AugLLMConfig(
# Model selection
model="gpt-4", # or "claude-3", "gemini-pro", etc.
# Temperature and sampling
temperature=0.7, # 0.0 (deterministic) to 2.0 (creative)
top_p=0.9, # Nucleus sampling
max_tokens=1000, # Maximum response length
# System configuration
system_message="You are a helpful assistant",
# Tools and functions
tools=["calculator", "web_search"], # Tool names or instances
tool_choice="auto", # "auto", "none", or specific tool
# Structured output
structured_output_model=MyPydanticModel, # For typed responses
# Advanced options
streaming=True, # Enable streaming responses
retry_config={"max_retries": 3, "backoff": 2.0},
timeout=30.0, # Request timeout in seconds
# Provider-specific options
api_key="your-api-key", # Or use environment variable
base_url="https://api.openai.com/v1", # Custom endpoints
)
Model Providers¶
Configure different LLM providers:
OpenAI:
config = AugLLMConfig(
model="gpt-4",
api_key=os.getenv("OPENAI_API_KEY"),
organization=os.getenv("OPENAI_ORG_ID"),
)
Anthropic:
config = AugLLMConfig(
model="claude-3-opus",
api_key=os.getenv("ANTHROPIC_API_KEY"),
)
Google Vertex AI:
config = AugLLMConfig(
model="gemini-pro",
project_id="your-project-id",
location="us-central1",
)
Azure OpenAI:
config = AugLLMConfig(
model="gpt-4",
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
base_url="https://your-resource.openai.azure.com/",
api_version="2024-02-01",
)
State Configuration¶
Custom State Schemas¶
Define custom states with validation:
from haive.core.schema.state_schema import StateSchema
from pydantic import Field, validator
from typing import List, Dict, Optional
class AgentState(StateSchema):
# Basic fields
messages: List[Dict] = Field(
default_factory=list,
description="Conversation history"
)
# Typed fields
user_id: str = Field(..., description="User identifier")
session_id: Optional[str] = Field(None, description="Session ID")
# Complex fields
context: Dict[str, Any] = Field(
default_factory=dict,
description="Additional context"
)
# Validation
@validator("user_id")
def validate_user_id(cls, v):
if not v.strip():
raise ValueError("User ID cannot be empty")
return v
# Custom methods
def add_message(self, role: str, content: str):
self.messages.append({
"role": role,
"content": content,
"timestamp": datetime.now()
})
State Persistence¶
Configure state persistence:
from haive.core.persistence import PersistenceConfig
# File-based persistence
persistence = PersistenceConfig(
backend="file",
path="./agent_states",
format="json"
)
# PostgreSQL persistence
persistence = PersistenceConfig(
backend="postgres",
connection_string="postgresql://user:pass@localhost/haive",
table_name="agent_states"
)
# Redis persistence
persistence = PersistenceConfig(
backend="redis",
host="localhost",
port=6379,
db=0
)
Vector Store Configuration¶
Available Providers¶
Configure different vector store backends:
Chroma:
from haive.core.engine.vectorstore import VectorStoreConfig
vector_config = VectorStoreConfig(
provider="chroma",
collection_name="documents",
persist_directory="./chroma_data",
embedding_model="text-embedding-ada-002"
)
Pinecone:
vector_config = VectorStoreConfig(
provider="pinecone",
api_key=os.getenv("PINECONE_API_KEY"),
environment="us-east-1",
index_name="haive-docs",
embedding_model="text-embedding-ada-002"
)
FAISS:
vector_config = VectorStoreConfig(
provider="faiss",
index_path="./faiss_index",
embedding_model="sentence-transformers/all-MiniLM-L6-v2"
)
PostgreSQL with pgvector:
vector_config = VectorStoreConfig(
provider="postgres",
connection_string="postgresql://user:pass@localhost/haive",
table_name="embeddings",
embedding_model="text-embedding-ada-002"
)
Embedding Configuration¶
Configure embedding models:
from haive.core.engine.embedding import EmbeddingConfig
# OpenAI embeddings
embedding_config = EmbeddingConfig(
provider="openai",
model="text-embedding-ada-002",
api_key=os.getenv("OPENAI_API_KEY")
)
# HuggingFace embeddings
embedding_config = EmbeddingConfig(
provider="huggingface",
model="sentence-transformers/all-MiniLM-L6-v2",
device="cuda" # or "cpu"
)
# Cohere embeddings
embedding_config = EmbeddingConfig(
provider="cohere",
model="embed-english-v3.0",
api_key=os.getenv("COHERE_API_KEY")
)
Tool Configuration¶
Tool Registration¶
Register and configure tools:
from langchain_core.tools import tool
from haive.core.engine.tool import ToolConfig
# Simple tool
@tool
def calculator(expression: str) -> str:
"""Calculate mathematical expressions."""
return str(eval(expression))
# Tool with configuration
tool_config = ToolConfig(
name="web_search",
description="Search the web for information",
parameters={
"max_results": 10,
"safe_search": True
},
rate_limit={"calls": 100, "period": "hour"}
)
Tool Permissions¶
Control tool access:
from haive.core.engine.tool import ToolPermissions
permissions = ToolPermissions(
allowed_tools=["calculator", "web_search"],
blocked_tools=["file_write", "shell_execute"],
require_confirmation=["api_call", "database_query"],
max_tool_calls=10 # Per conversation
)
Graph Configuration¶
Graph Builder Options¶
Configure workflow graphs:
from haive.core.graph import GraphConfig
graph_config = GraphConfig(
# Execution options
max_iterations=10, # Prevent infinite loops
timeout=60.0, # Overall timeout
# Memory options
checkpointing=True, # Enable state checkpoints
checkpoint_interval=5, # Checkpoint every N steps
# Debugging
debug=True, # Enable debug logging
trace_execution=True, # Detailed execution trace
# Parallelization
max_parallel_nodes=4, # Concurrent node execution
thread_pool_size=8
)
Conditional Routing¶
Configure dynamic routing:
from haive.core.graph.routers import ConditionalRouter
router_config = ConditionalRouter(
conditions={
"needs_search": lambda state: "search" in state.user_query,
"needs_calculation": lambda state: any(op in state.user_query for op in ["+", "-", "*", "/"]),
"needs_clarification": lambda state: len(state.messages) < 2
},
default_route="process_general"
)
Environment Variables¶
Core Environment Variables¶
haive-games recognizes these environment variables:
# API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
COHERE_API_KEY=...
# Model Defaults
HAIVE_DEFAULT_MODEL=gpt-4
HAIVE_DEFAULT_TEMPERATURE=0.7
HAIVE_DEFAULT_MAX_TOKENS=1000
# Vector Store
PINECONE_API_KEY=...
PINECONE_ENVIRONMENT=us-east-1
WEAVIATE_URL=http://localhost:8080
QDRANT_URL=http://localhost:6333
# Database
HAIVE_POSTGRES_URL=postgresql://user:pass@localhost/haive
HAIVE_REDIS_URL=redis://localhost:6379
# Debugging
HAIVE_DEBUG=true
HAIVE_LOG_LEVEL=DEBUG
HAIVE_TRACE_EXECUTION=true
Loading Configuration¶
Load from environment files:
from haive.core.config import load_config
# Load from .env file
config = load_config(".env")
# Load from YAML
config = load_config("config.yaml")
# Load from TOML
config = load_config("config.toml")
# Merge multiple sources
config = load_config([".env", "config.yaml", "local.toml"])
Advanced Configuration¶
Custom Providers¶
Add custom LLM providers:
from haive.core.engine.base import BaseEngine
class CustomLLMProvider(BaseEngine):
def __init__(self, api_key: str, **kwargs):
self.api_key = api_key
super().__init__(**kwargs)
def invoke(self, messages):
# Custom implementation
pass
# Register provider
from haive.core.registry import register_provider
register_provider("custom_llm", CustomLLMProvider)
Plugin Configuration¶
Configure plugins:
from haive.core.plugins import PluginConfig
plugin_config = PluginConfig(
enabled_plugins=["monitoring", "caching", "rate_limiting"],
plugin_settings={
"monitoring": {
"endpoint": "http://localhost:9090",
"interval": 60
},
"caching": {
"backend": "redis",
"ttl": 3600
},
"rate_limiting": {
"max_requests": 1000,
"window": "hour"
}
}
)
Performance Tuning¶
Optimize performance:
from haive.core.config import PerformanceConfig
perf_config = PerformanceConfig(
# Batching
batch_size=10,
batch_timeout=1.0,
# Caching
enable_cache=True,
cache_ttl=3600,
cache_size=1000,
# Connection pooling
connection_pool_size=20,
connection_timeout=5.0,
# Memory management
max_memory_mb=1024,
gc_interval=300
)
Configuration Best Practices¶
Use Environment Variables: Keep sensitive data out of code
Layer Configurations: Base → Environment → Runtime
Validate Early: Check configuration at startup
Document Defaults: Make default behavior clear
Version Configurations: Track config changes
Test Configurations: Have test-specific configs
Monitor Performance: Log configuration impacts
Next Steps¶
Review Getting Started for practical examples
Check Core Concepts for architectural overview
See API Reference for detailed options