Documentation
¶
Overview ¶
Package orchestrator provides the core orchestrator service for AleutianLocal.
This package contains the main Orchestrator type that coordinates all components of the service: HTTP routing, LLM clients, policy engine, vector database, and observability infrastructure.
Enterprise Integration ¶
The orchestrator supports dependency injection via extensions.ServiceOptions, enabling AleutianEnterprise to provide custom implementations of:
- AuthProvider: Custom authentication (JWT, API keys)
- AuthzProvider: Role-based access control
- AuditLogger: Compliance audit logging
- MessageFilter: PII detection and redaction
Usage ¶
Open source (uses no-op defaults):
cfg := orchestrator.Config{Port: 12210}
svc, err := orchestrator.New(cfg, nil)
if err != nil {
log.Fatal(err)
}
svc.Run()
Enterprise (with custom implementations):
opts := &extensions.ServiceOptions{
AuthProvider: enterpriseAuth,
AuditLogger: enterpriseAudit,
}
svc, err := orchestrator.New(cfg, opts)
Import Path ¶
Enterprise imports this package as:
import "github.com/AleutianAI/AleutianFOSS/services/orchestrator"
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Port is the HTTP server port. Default: 12210
Port int
// LLMBackend specifies the LLM provider.
// Valid values: "local", "openai", "ollama", "claude", "anthropic"
// Default: "local"
LLMBackend string
// WeaviateURL is the Weaviate vector database URL.
// If empty, vector DB features are disabled.
// Example: "http://localhost:8080"
WeaviateURL string
// OTelEndpoint is the OpenTelemetry collector endpoint.
// Default: "aleutian-otel-collector:4317"
OTelEndpoint string
// EnableMetrics enables Prometheus metrics endpoint.
// Default: true
EnableMetrics bool
// GinMode sets the Gin framework mode.
// Valid values: "debug", "release", "test"
// Default: uses GIN_MODE env var or "debug"
GinMode string
// TTLCleanupInterval is how often the TTL scheduler runs cleanup.
// Default: 1 hour
TTLCleanupInterval time.Duration
// TTLLogPath is the path to the TTL audit log file.
// Default: "/tmp/aleutian/logs/ttl_cleanup.log"
TTLLogPath string
// TTLEnabled enables the background TTL cleanup scheduler.
// Default: true (when Weaviate is configured)
TTLEnabled bool
}
Config holds orchestrator configuration options.
Description ¶
Config centralizes all configuration for the orchestrator service. Values can be populated from environment variables, config files, or programmatically for testing.
Required Fields ¶
None - all fields have sensible defaults.
Optional Fields ¶
All fields are optional with defaults applied by New().
Examples ¶
// Minimal config (uses all defaults)
cfg := Config{}
// Custom port and LLM backend
cfg := Config{
Port: 8080,
LLMBackend: "claude",
}
// Full configuration
cfg := Config{
Port: 12210,
LLMBackend: "openai",
WeaviateURL: "http://localhost:8080",
OTelEndpoint: "localhost:4317",
EnableMetrics: true,
}
Example (Custom) ¶
ExampleConfig_custom demonstrates custom configuration.
cfg := Config{
Port: 8080,
LLMBackend: "claude",
WeaviateURL: "http://weaviate:8080",
}
result := applyConfigDefaults(cfg)
_ = result
// Output port: 8080, backend: claude
Example (Minimal) ¶
ExampleConfig_minimal demonstrates minimal configuration.
cfg := Config{}
result := applyConfigDefaults(cfg)
_ = result
// Output port: 12210, backend: local
type Service ¶
type Service interface {
// Run starts the HTTP server and blocks until shutdown or error.
//
// # Description
//
// Starts the Gin HTTP server on the configured port. This method
// blocks until the server stops (due to error or shutdown signal).
//
// # Inputs
//
// None (configuration provided at construction time).
//
// # Outputs
//
// - error: Non-nil if server fails to start or encounters fatal error
//
// # Examples
//
// if err := svc.Run(); err != nil {
// log.Fatalf("server error: %v", err)
// }
//
// # Limitations
//
// - Blocks until server stops
// - No graceful shutdown support yet
//
// # Assumptions
//
// - Service was successfully created via New()
// - Port is available and not in use
Run() error
// Router returns the underlying Gin engine for testing.
//
// # Description
//
// Provides access to the configured Gin router, primarily for
// integration testing where direct HTTP calls are needed.
//
// # Outputs
//
// - *gin.Engine: The configured router with all routes registered
//
// # Limitations
//
// - Should not be used to modify routes after construction
//
// # Assumptions
//
// - Caller will not modify the router
Router() *gin.Engine
}
Service defines the contract for the orchestrator service.
Description ¶
Service abstracts the orchestrator lifecycle, enabling testing and alternative implementations. The interface follows the minimal surface area principle - only essential lifecycle methods are exposed.
Thread Safety ¶
Implementations must be safe for concurrent use. Run() blocks and should only be called once per instance.
Limitations ¶
- No graceful shutdown method yet (planned for future)
- Run() blocks until server error
Assumptions ¶
- Service is fully initialized before Run() is called
- Run() is called at most once per Service instance
func New ¶
func New(cfg Config, opts *extensions.ServiceOptions) (Service, error)
New creates a new orchestrator Service with the given configuration.
Description ¶
New initializes all orchestrator components:
- Applies default configuration for missing values
- Initializes OpenTelemetry tracing
- Initializes Prometheus metrics
- Creates LLM client based on backend type
- Creates Weaviate client if URL provided
- Initializes policy engine
- Sets up HTTP routes with extension options
If opts is nil, DefaultOptions() is used (no-op implementations).
Inputs ¶
- cfg: Service configuration. Zero values use defaults.
- opts: Extension options for enterprise features. May be nil.
Outputs ¶
- Service: Ready-to-run orchestrator service
- error: Non-nil if initialization fails
Examples ¶
// Open source usage (no-op extensions)
cfg := Config{Port: 12210, LLMBackend: "ollama"}
svc, err := New(cfg, nil)
if err != nil {
log.Fatal(err)
}
log.Fatal(svc.Run())
// Enterprise usage (custom extensions)
opts := &extensions.ServiceOptions{
AuthProvider: myAuthProvider,
AuditLogger: myAuditLogger,
}
svc, err := New(cfg, opts)
Limitations ¶
- LLM client creation may fail if provider is unreachable
- Weaviate connection is optional but schema check runs if connected
Assumptions ¶
- Environment variables are set for LLM providers (API keys, URLs)
- Network is available for external service connections
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package conversation provides semantic memory capabilities for conversation history.
|
Package conversation provides semantic memory capabilities for conversation history. |
|
Package handlers provides HTTP handlers for the orchestrator service.
|
Package handlers provides HTTP handlers for the orchestrator service. |
|
Package middleware provides HTTP middleware for the orchestrator service.
|
Package middleware provides HTTP middleware for the orchestrator service. |
|
Package observability provides metrics and instrumentation for the orchestrator.
|
Package observability provides metrics and instrumentation for the orchestrator. |
|
Package services provides business logic services for the orchestrator.
|
Package services provides business logic services for the orchestrator. |
|
Package ttl provides time-to-live (TTL) management for documents and sessions in the Aleutian RAG system.
|
Package ttl provides time-to-live (TTL) management for documents and sessions in the Aleutian RAG system. |