Skip to main content

api

API Reference

IOA Core provides comprehensive APIs for governed AI orchestration. This section covers the main APIs and their usage.

Core API​

Governance Engine​

The governance engine provides runtime policy enforcement and compliance checking.

from ioa_core.governance import GovernanceEngine

# Initialize governance engine
engine = GovernanceEngine()

# Validate action against policies
result = engine.validate_action(
    action="generate_text",
    context={"model": "gpt-4", "user": "researcher"},
    policies=["law_transparency", "law_accountability"]
)

Memory Fabric​

The memory fabric provides multi-tier storage with hot and cold layers.

from ioa_core.memory import MemoryFabric

# Initialize memory fabric
memory = MemoryFabric()

# Store data
memory.store(
    key="conversation_123",
    data={"messages": [...], "metadata": {...}},
    tier="hot"
)

# Retrieve data
data = memory.retrieve("conversation_123")

LLM Provider Interface​

Unified interface for all supported LLM providers.

from ioa_core.providers import ProviderManager

# Initialize provider manager
pm = ProviderManager()

# Generate text
response = pm.generate(
    prompt="Explain quantum computing",
    model="gpt-4",
    provider="openai",
    audit_id="audit_123"
)

REST API​

IOA Core also provides REST APIs for integration.

Health Check​

GET /api/v1/health

Response:

{
  "status": "healthy",
  "version": "2.5.2",
  "uptime": 3600
}

Governance Validation​

POST /api/v1/governance/validate
Content-Type: application/json

{
  "action": "generate_text",
  "context": {
    "model": "claude-3",
    "user_id": "user_123"
  },
  "policies": ["transparency", "privacy"]
}

Memory Operations​

POST /api/v1/memory/store
Content-Type: application/json

{
  "key": "session_456",
  "data": {"conversation": [...], "metadata": {...}},
  "tier": "hot"
}

CLI Reference​

Core Commands​

# Initialize project
ioa init my-project

# Health check
ioa doctor

# List providers
ioa providers list

# Validate governance
ioa governance validate --action generate_text --model gpt-4

Memory Commands​

# Store data
ioa memory store --key my_key --data '{"test": "data"}'

# Retrieve data
ioa memory get my_key

# List keys
ioa memory list

Configuration​

Environment Variables​

# Required
IOA_AUDIT_LEVEL=full
IOA_ENCRYPTION_KEY=your-key-here

# Optional
IOA_PROVIDER_DEFAULT=openai
IOA_MEMORY_BACKEND=sqlite
IOA_LOG_LEVEL=INFO

Configuration File​

# ioa.yaml
version: "2.5"
governance:
  laws: ["transparency", "accountability", "ethics"]
  audit_level: full

memory:
  backend: sqlite
  hot_ttl: 3600
  cold_compression: true

providers:
  default: openai
  fallback: [anthropic, gemini]

Error Codes​

Governance Errors​

  • GOV001: Policy violation detected
  • GOV002: Insufficient audit evidence
  • GOV003: System law violation

Memory Errors​

  • MEM001: Storage backend unavailable
  • MEM002: Data corruption detected
  • MEM003: Tier migration failed

Provider Errors​

  • PRV001: Provider authentication failed
  • PRV002: Rate limit exceeded
  • PRV003: Model not available

Rate Limits​

  • Free tier: 100 requests/hour
  • Pro tier: 10,000 requests/hour
  • Enterprise: Unlimited

Rate limits apply per API key and are reset hourly.

Authentication​

All API requests require authentication via API key:

Authorization: Bearer your-api-key-here

API keys can be generated in the dashboard or via CLI:

ioa auth create-key --name "production-key"