Skip to main content

Overview

OrbitAI provides a sophisticated Large Language Model integration layer that enables seamless interaction with multiple AI providers through a unified interface.

Multi-Provider Support

OpenAI, Anthropic, and extensible architecture for custom providers

Intelligent Routing

Automatic provider selection based on latency and success rate

Unified Interface

Single API for all LLM operations regardless of provider

Advanced Features

Streaming, tool calling, structured output, and caching

Performance Monitoring

Built-in metrics tracking and health monitoring

Type Safety

Full Swift type safety with compile-time guarantees

Key Benefits

Switch between providers without code changes. Use the same API regardless of whether you’re calling OpenAI, Anthropic, or a custom provider.
Built-in redundancy and error recovery. If a provider fails or is rate-limited, requests automatically route to backup providers.
Route to optimal providers based on cost and performance criteria. Balance quality with budget constraints automatically.
Simple, consistent API across all providers with full Swift type safety and comprehensive error handling.

Architecture

OrbitAI’s LLM system consists of several key components working together:

LLMManager: The Central Hub

The LLMManager actor serves as the central coordination point for all LLM operations:
  • Provider Management: Register, configure, and manage multiple LLM providers
  • Request Routing: Intelligently route requests to optimal providers
  • Response Caching: Optional in-memory caching for improved performance
  • Metrics & Health: Track performance and monitor provider health
  • Thread Safety: Actor-based design ensures safe concurrent access

Setting Up LLM Providers

1

Configure Environment Variables

Set up your API keys as environment variables:
.env
Never commit your API keys to version control. Always use environment variables or secure key storage.
2

Initialize LLM Manager

Use factory methods for quick setup:
3

Register Providers

For more control, manually register providers:
4

Environment-Based Setup

Use automatic environment configuration:

Provider Configuration

Standard Configuration

Available Models

AI Proxy Configuration

For using AI proxy services:

Integration with Agents

Agent-Level Configuration

Agents can be configured to use specific LLM providers:
The llmID parameter uses type-safe enums to ensure you’re referencing valid providers configured in your system.

Agent Factory

Use AgentFactory for pre-configured agents:

Orbit-Level Integration

Orbits automatically handle LLM provider setup:
For manual configuration:

Custom Endpoints & Local Models

Configure OrbitAI to use Ollama for local models:
Ollama provides a local, OpenAI-compatible API endpoint, making integration seamless.
Implement the LLMProvider protocol for custom APIs:

Best Practices

Provider Selection

GPT-4o

Best for: Complex reasoning, analysis, high-quality outputUse when accuracy and capability are paramount

GPT-4o Mini

Best for: Simple tasks, summaries, classificationCost-effective for high-volume operations

Claude 3.5 Sonnet

Best for: Creative writing, long-form contentExcellent for content generation

Claude 3.5 Haiku

Best for: Fast responses, simple queriesOptimized for speed and efficiency

Intelligent Routing

Use ProviderSelectionCriteria for automatic provider selection:

Context Management

Effective System Messages

Use lower temperatures (0.1-0.3) for analytical tasks and higher temperatures (0.7-0.9) for creative tasks.

Performance Optimization

Caching Strategy

Streaming for Real-Time

Advanced Features

Force LLMs to return structured JSON responses:
Define tools for LLM use:
Process multiple requests concurrently:
Multi-turn conversations with context:

Troubleshooting

Problem: OrbitAIError.configuration("OPENAI_API_KEY missing")Solutions:
Verify your API key format. OpenAI keys start with sk-, Anthropic keys start with sk-ant-.
Problem: OrbitAIError.llmRateLimitExceededSolutions:
Monitor rate limits:
Problem: Requests timing outSolutions:
Diagnostics:
Solutions:
  • Clear stale cache entries
  • Use consistent message formatting
  • Consider provider switching for better performance

Security Considerations

API Key Management

Never hardcode API keys in your source code. Use environment variables or secure key storage solutions.

Request Sanitization

Next Steps

Agents

Learn about agent-specific LLM configuration

Tasks

Explore task-level LLM integration

Tools

Extend LLM capabilities with tools

Orbits

Understand Orbit-level orchestration
For additional support and advanced use cases, consult the GitHub Discussions or check out the Issue Tracker.