Configuration Guide

Configuration Guide

Essential configuration patterns for Klira AI SDK across development, staging, and production environments. This guide covers environment variables, configuration files, and deployment-specific settings for enterprise-grade LLM observability.

Configuration Overview

Klira AI SDK uses a hierarchical configuration system that prioritizes:

1. Environment Variables (highest priority)
2. Configuration Files (.env, config files)
3. Programmatic Configuration (runtime settings)
4. Default Values (lowest priority)

This approach ensures secure, flexible configuration management across different deployment scenarios.

Core Configuration

Required Settings

# Essential configuration
KLIRA_API_KEY="klira_prod_your-api-key-here"
KLIRA_APP_NAME="your-application-name"

Basic Initialization

import os
from klira.sdk import Klira

# Minimal configuration
klira = Klira.init(
    app_name="my-app",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True
)

Environment Variables Reference

Core Settings

Variable	Description	Default	Example
KLIRA_API_KEY	Authentication key from klira.tools	Required	klira_prod_abc123...
KLIRA_APP_NAME	Application identifier	"klira-app"	"customer-support-bot"
KLIRA_ENABLED	Enable/disable SDK globally	true	false
KLIRA_ENVIRONMENT	Deployment environment	"development"	"production"

Observability Settings

Variable	Description	Default	Example
KLIRA_TRACING_ENABLED	Enable distributed tracing	true	false
KLIRA_TRACE_CONTENT	Include content in traces	false	true
KLIRA_METRICS_ENABLED	Enable metrics collection	true	false
KLIRA_OPENTELEMETRY_ENDPOINT	Custom OTLP endpoint	Klira AI Cloud	https://otel.company.com

Guardrails Settings

Variable	Description	Default	Example
KLIRA_POLICY_ENFORCEMENT	Enable policy enforcement	true	false
KLIRA_POLICIES_PATH	Custom policies directory	./policies	/app/config/policies
KLIRA_GUARDRAILS_TIMEOUT	Policy evaluation timeout (ms)	5000	10000

Performance Settings

Variable	Description	Default	Example
KLIRA_CACHE_ENABLED	Enable response caching	true	false
KLIRA_CACHE_TTL	Cache TTL in seconds	300	3600
KLIRA_MAX_CONCURRENT_REQUESTS	Concurrent request limit	100	500
KLIRA_REQUEST_TIMEOUT	Request timeout in seconds	30	60

Logging Settings

Variable	Description	Default	Example
KLIRA_LOG_LEVEL	Logging level	INFO	DEBUG
KLIRA_LOG_FORMAT	Log format	structured	json
KLIRA_LOG_FILE	Log file path	None	/var/log/klira.log

Environment-Specific Configurations

Development Environment

.env.development

KLIRA_API_KEY="klira_dev_your-dev-key"
KLIRA_APP_NAME="myapp-dev"
KLIRA_ENVIRONMENT="development"
KLIRA_ENABLED=true
KLIRA_TRACE_CONTENT=true
KLIRA_LOG_LEVEL=DEBUG
KLIRA_POLICY_ENFORCEMENT=false

# Development configuration
import os
from klira.sdk import Klira

klira = Klira.init(
    app_name="myapp-dev",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True,
    verbose=True, # Detailed logging
    trace_content=True, # Include content in traces for debugging
    policy_enforcement=False # Disable policies during development
)

Staging Environment

.env.staging

KLIRA_API_KEY="klira_staging_your-staging-key"
KLIRA_APP_NAME="myapp-staging"
KLIRA_ENVIRONMENT="staging"
KLIRA_ENABLED=true
KLIRA_TRACE_CONTENT=false
KLIRA_LOG_LEVEL=INFO
KLIRA_POLICY_ENFORCEMENT=true
KLIRA_POLICIES_PATH="/app/policies"

# Staging configuration
import os
from klira.sdk import Klira

klira = Klira.init(
    app_name="myapp-staging",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True,
    trace_content=False, # Exclude sensitive content
    policy_enforcement=True, # Test policies in staging
    policies_path="/app/policies"
)

Production Environment

.env.production

KLIRA_API_KEY="klira_prod_your-production-key"
KLIRA_APP_NAME="myapp-prod"
KLIRA_ENVIRONMENT="production"
KLIRA_ENABLED=true
KLIRA_TRACE_CONTENT=false
KLIRA_LOG_LEVEL=WARN
KLIRA_POLICY_ENFORCEMENT=true
KLIRA_POLICIES_PATH="/app/config/policies"
KLIRA_CACHE_ENABLED=true
KLIRA_CACHE_TTL=3600
KLIRA_MAX_CONCURRENT_REQUESTS=1000

# Production configuration
import os
from klira.sdk import Klira

klira = Klira.init(
    app_name="myapp-prod",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True,
    trace_content=False, # Security: no content in traces
    policy_enforcement=True, # Full governance
    cache_enabled=True, # Performance optimization
    max_concurrent_requests=1000 # Scale for production load
)

Configuration Files

.env File Structure

.env

# Core Configuration
KLIRA_API_KEY=your-api-key-here
KLIRA_APP_NAME=my-application
KLIRA_ENVIRONMENT=production

# Observability
KLIRA_TRACING_ENABLED=true
KLIRA_TRACE_CONTENT=false
KLIRA_METRICS_ENABLED=true
KLIRA_OPENTELEMETRY_ENDPOINT=https://your-otlp-endpoint.com

# Guardrails
KLIRA_POLICY_ENFORCEMENT=true
KLIRA_POLICIES_PATH=./policies
KLIRA_GUARDRAILS_TIMEOUT=5000

# Performance
KLIRA_CACHE_ENABLED=true
KLIRA_CACHE_TTL=300
KLIRA_MAX_CONCURRENT_REQUESTS=100

# Logging
KLIRA_LOG_LEVEL=INFO
KLIRA_LOG_FORMAT=json
KLIRA_LOG_FILE=/var/log/klira.log

YAML Configuration File

Create klira.config.yaml:

klira.config.yaml

app:
 name: "customer-support-bot"
 environment: "production"
 version: "1.0.0"

klira:
 api_key: "${KLIRA_API_KEY}" # Reference environment variable
 enabled: true

observability:
 tracing:
 enabled: true
 content_tracing: false
 endpoint: "https://otel.company.com"
 metrics:
 enabled: true
 export_interval: 60
 logging:
 level: "INFO"
 format: "json"
 file: "/var/log/klira.log"

guardrails:
 enabled: true
 policies_path: "./policies"
 timeout_ms: 5000
 cache_policies: true

performance:
 cache:
 enabled: true
 ttl_seconds: 300
 max_size: 1000
 concurrency:
 max_requests: 100
 timeout_seconds: 30

# Framework-specific settings
frameworks:
 langchain:
 callback_enabled: true
 crewai:
 process_monitoring: true
 openai_agents:
 function_tracing: true

Load YAML configuration:

import yaml
from klira.sdk import Klira

def load_config(config_path: str) -> dict:
    with open(config_path, 'r') as file:
    config = yaml.safe_load(file)

    # Expand environment variables
    def expand_env_vars(obj):
    if isinstance(obj, dict):
    return {k: expand_env_vars(v) for k, v in obj.items()}
    elif isinstance(obj, str) and obj.startswith('${') and obj.endswith('}'):
    env_var = obj[2:-1]
    return os.getenv(env_var, obj)
    return obj

    return expand_env_vars(config)

# Initialize with YAML config
config = load_config('klira.config.yaml')
klira = Klira.init(
    app_name=config['app']['name'],
    api_key=config['klira']['api_key'], # Already using config, which expands env vars
    enabled=config['klira']['enabled'],
    # ... other configuration options
)

Framework-Specific Configuration

OpenAI Agents Configuration

import os
from klira.sdk import Klira

klira = Klira.init(
    app_name="openai-agents-app",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True,
    # OpenAI Agents specific settings
    framework_config={
    "openai_agents": {
    "trace_function_calls": True,
    "include_tool_results": True,
    "monitor_streaming": True
    }
    }
)

LangChain Configuration

import os
from klira.sdk import Klira

klira = Klira.init(
    app_name="langchain-app",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True,
    framework_config={
    "langchain": {
    "callback_handler_enabled": True,
    "trace_chains": True,
    "trace_tools": True,
    "include_prompts": False # Security: don't log prompts
    }
    }
)

CrewAI Configuration

import os
from klira.sdk import Klira

klira = Klira.init(
    app_name="crewai-app",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True,
    framework_config={
    "crewai": {
    "trace_crew_execution": True,
    "trace_individual_agents": True,
    "trace_task_delegation": True,
    "include_agent_reasoning": False
    }
    }
)

Advanced Configuration Patterns

Configuration Validation

from dataclasses import dataclass
from typing import Optional, List
import os

@dataclass
class KliraConfig:
    api_key: str
    app_name: str
    enabled: bool = True
    environment: str = "development"
    trace_content: bool = False
    policy_enforcement: bool = True
    policies_path: str = "./policies"
    log_level: str = "INFO"

    @classmethod
    def from_env(cls) -> 'KliraConfig':
    return cls(
    api_key=os.getenv("KLIRA_API_KEY", ""),
    app_name=os.getenv("KLIRA_APP_NAME", "klira-app"),
    enabled=os.getenv("KLIRA_ENABLED", "true").lower() == "true",
    environment=os.getenv("KLIRA_ENVIRONMENT", "development"),
    trace_content=os.getenv("KLIRA_TRACE_CONTENT", "false").lower() == "true",
    policy_enforcement=os.getenv("KLIRA_POLICY_ENFORCEMENT", "true").lower() == "true",
    policies_path=os.getenv("KLIRA_POLICIES_PATH", "./policies"),
    log_level=os.getenv("KLIRA_LOG_LEVEL", "INFO")
    )

    def validate(self) -> List[str]:
    """Validate configuration and return list of errors."""
    errors = []

    if not self.api_key:
    errors.append("KLIRA_API_KEY is required")
    elif not self.api_key.startswith("klira_"):
    errors.append("KLIRA_API_KEY must start with 'klira_'")

    if not self.app_name:
    errors.append("KLIRA_APP_NAME is required")

    if self.log_level not in ["DEBUG", "INFO", "WARN", "ERROR"]:
    errors.append("KLIRA_LOG_LEVEL must be one of: DEBUG, INFO, WARN, ERROR")

    if not os.path.exists(self.policies_path):
    errors.append(f"Policies path does not exist: {self.policies_path}")

    return errors

# Usage
config = KliraConfig.from_env()
errors = config.validate()

if errors:
    raise ValueError(f"Configuration errors: {', '.join(errors)}")

klira = Klira.init(
    app_name=config.app_name,
    api_key=config.api_key,
    enabled=config.enabled,
    trace_content=config.trace_content,
    policy_enforcement=config.policy_enforcement,
    policies_path=config.policies_path
)

Dynamic Configuration Updates

import os
from klira.sdk import Klira

# Initialize with base configuration
klira = Klira.init(
    app_name="dynamic-app",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True
)

# Update configuration at runtime
def update_config_for_user(user_role: str):
    if user_role == "admin":
    # Admins get full tracing
    klira.update_config(trace_content=True, log_level="DEBUG")
    elif user_role == "developer":
    # Developers get standard tracing
    klira.update_config(trace_content=False, log_level="INFO")
    else:
    # Regular users get minimal tracing
    klira.update_config(trace_content=False, log_level="WARN")

# Usage in request handler
@workflow(name="handle_request")
def handle_user_request(user_role: str, request: str):
    update_config_for_user(user_role)
    # Process request with appropriate configuration
    return process_request(request)

Multi-Tenant Configuration

from klira.sdk import Klira
from typing import Dict, Any

class MultiTenantKlira:
    def __init__(self):
    self._instances: Dict[str, Klira] = {}

    def get_instance(self, tenant_id: str) -> Klira:
    if tenant_id not in self._instances:
    self._instances[tenant_id] = self._create_tenant_instance(tenant_id)
    return self._instances[tenant_id]

    def _create_tenant_instance(self, tenant_id: str) -> Klira:
    # Load tenant-specific configuration
    config = self._load_tenant_config(tenant_id)

    return Klira.init(
    app_name=f"app-{tenant_id}",
    api_key=config["api_key"],
    enabled=config.get("enabled", True),
    policies_path=config.get("policies_path", f"./policies/{tenant_id}"),
    organization_id=tenant_id
    )

    def _load_tenant_config(self, tenant_id: str) -> Dict[str, Any]:
    # Load from database, file, or environment
    return {
    "api_key": os.getenv(f"KLIRA_API_KEY_{tenant_id.upper()}"),
    "enabled": True,
    "policies_path": f"./policies/{tenant_id}"
    }

# Usage
multi_tenant_klira = MultiTenantKlira()

@workflow(name="tenant_request")
def handle_tenant_request(tenant_id: str, request: str):
    # Get tenant-specific Klira AI instance
    klira = multi_tenant_klira.get_instance(tenant_id)

    # Process with tenant-specific configuration
    return process_request(request)

Security Configuration

API Key Management

# Use different keys for different environments
KLIRA_API_KEY_DEV="klira_dev_development-key"
KLIRA_API_KEY_STAGING="klira_staging_staging-key"
KLIRA_API_KEY_PROD="klira_prod_production-key"

# Runtime key selection
KLIRA_API_KEY="${KLIRA_API_KEY_PROD}"

Content Security

# Production security settings
import os
from klira.sdk import Klira

klira = Klira.init(
    app_name="secure-app",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True,

    # Security: Disable content tracing in production
    trace_content=False,

    # Security: Enable policy enforcement
    policy_enforcement=True,

    # Security: Use secure policies path
    policies_path="/app/secure/policies",

    # Security: Minimal logging
    log_level="WARN",

    # Security: Secure headers
    custom_headers={
    "X-Klira-Environment": "production",
    "X-Klira-Security-Level": "high"
    }
)

Network Security

# Configure for secure network environments
import os
from klira.sdk import Klira

klira = Klira.init(
    app_name="network-secure-app",
    api_key=os.getenv("KLIRA_API_KEY"),
    enabled=True,

    # Use internal OTLP endpoint
    opentelemetry_endpoint="https://internal-otel.company.com",

    # Configure TLS
    tls_config={
    "cert_file": "/app/certs/client.crt",
    "key_file": "/app/certs/client.key",
    "ca_file": "/app/certs/ca.crt"
    },

    # Network timeouts
    request_timeout=10,
    connection_timeout=5
)

Troubleshooting Configuration

Configuration Validation

def validate_klira_config():
    """Validate Klira configuration and report issues."""
    issues = []

    # Check required environment variables
    required_vars = ["KLIRA_API_KEY", "KLIRA_APP_NAME"]
    for var in required_vars:
    if not os.getenv(var):
    issues.append(f"Missing required environment variable: {var}")

    # Check API key format
    api_key = os.getenv("KLIRA_API_KEY", "")
    if api_key and not api_key.startswith("klira_"):
    issues.append("KLIRA_API_KEY should start with 'klira_'")

    # Check policies path
    policies_path = os.getenv("KLIRA_POLICIES_PATH", "./policies")
    if not os.path.exists(policies_path):
    issues.append(f"Policies path does not exist: {policies_path}")

    # Check log level
    log_level = os.getenv("KLIRA_LOG_LEVEL", "INFO")
    if log_level not in ["DEBUG", "INFO", "WARN", "ERROR"]:
    issues.append(f"Invalid log level: {log_level}")

    return issues

# Usage
issues = validate_klira_config()
if issues:
    print("Configuration issues found:")
    for issue in issues:
    print(f" - {issue}")
    exit(1)

Configuration Debug Information

def print_klira_config():
    """Print current Klira configuration for debugging."""
    print("Klira AI SDK Configuration:")
    print(f" API Key: {'***' + os.getenv('KLIRA_API_KEY', '')[-4:] if os.getenv('KLIRA_API_KEY') else 'Not set'}")
    print(f" App Name: {os.getenv('KLIRA_APP_NAME', 'Not set')}")
    print(f" Environment: {os.getenv('KLIRA_ENVIRONMENT', 'development')}")
    print(f" Enabled: {os.getenv('KLIRA_ENABLED', 'true')}")
    print(f" Tracing: {os.getenv('KLIRA_TRACING_ENABLED', 'true')}")
    print(f" Policy Enforcement: {os.getenv('KLIRA_POLICY_ENFORCEMENT', 'true')}")
    print(f" Policies Path: {os.getenv('KLIRA_POLICIES_PATH', './policies')}")
    print(f" Log Level: {os.getenv('KLIRA_LOG_LEVEL', 'INFO')}")

# Usage
if __name__ == "__main__":
    print_klira_config()

Next Steps

Production Deployment

• Production Setup Guide - Complete production deployment
• Security Best Practices - Secure your deployment
• Performance Tuning - Optimize for scale

Advanced Configuration

• Custom Policies - Create custom governance rules
• Observability Setup - Advanced monitoring configuration
• Framework Integration - Framework-specific settings

---

Configuration is critical for production success. Take time to properly configure Klira AI SDK for your environment and security requirements.

Need help with configuration? Check our troubleshooting guide or contact support.