Skip to main content
View as Markdown

AI Eco Routing

Sovrium treats environmental footprint as a first-class platform property. AI inference is one of the most resource-intensive operations a platform can perform, so Sovrium routes AI calls local-first by default: when a local model (Ollama) is reachable, it answers; only when it is not does the call fall back to a configured cloud provider.

This is controlled by a single operator env var — ECO_AI_PROVIDER_PRECEDENCE — never by the app schema. Like every ECO_* variable, its default is the eco-aligned setting; operators opt out, never in.

ECO_AI_PROVIDER_PRECEDENCE=local-first   # the default — usually omit it entirely
AI_PROVIDER=anthropic                    # cloud fallback target
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434   # local provider endpoint

Precedence Modes

Value Behavior
local-first (default) Prefer a reachable local Ollama; fall back to the configured cloud AI_PROVIDER when Ollama is unreachable.
cloud-first Use the configured cloud provider; use a reachable Ollama only when no cloud provider is configured.
local-only Use a local provider exclusively. AI calls have no cloud fallback — when no reachable Ollama is configured, AI is unavailable.

An unset, empty, or unrecognized value resolves to the eco-aligned default, local-first.

How Routing Resolves

The resolver combines three inputs: the active precedence, whether an Ollama endpoint is configured (via OLLAMA_BASE_URL, or AI_BASE_URL when AI_PROVIDER=ollama), and whether the runtime's reachability probe found Ollama usable (configured and responding).

Precedence Ollama usable Cloud configured Routes to Notes
local-first yes — Ollama Preferred local path.
local-first no yes cloud Fallback. Flagged with a reason when Ollama was configured but unreachable.
local-first no no Ollama / none Disabled when no provider is configured at all.
cloud-first — yes cloud Cloud always wins when configured.
cloud-first yes no Ollama Local used only because no cloud is configured.
local-only yes — Ollama Local exclusively.
local-only no — none No fallback — AI unavailable until a reachable Ollama exists.

Observability

The active eco-routing decision is surfaced on the health endpoint (GET /api/health, under body.ai):

Field Meaning
precedence The active ECO_AI_PROVIDER_PRECEDENCE value.
resolvedProvider The canonical provider AI calls are routed to (or absent when AI is disabled).
ollamaReachable Whether the local Ollama probe succeeded.
configured The raw AI_PROVIDER value.
fallbackReason Why the resolver fell back to a non-preferred provider (present only on fallback).

This makes routing auditable: operators can confirm whether a deployment is actually running on its local model or quietly burning cloud tokens.

Configuration Examples

# Frugal default: local Ollama with an Anthropic safety net.
# (ECO_AI_PROVIDER_PRECEDENCE=local-first is the default — shown for clarity.)
ECO_AI_PROVIDER_PRECEDENCE=local-first
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434
AI_MODEL=claude-sonnet-4-5
# Strict local-only deployment — no data ever leaves the host.
ECO_AI_PROVIDER_PRECEDENCE=local-only
AI_PROVIDER=ollama
AI_BASE_URL=http://localhost:11434
AI_MODEL=llama3.1
# Quality-first: always use the cloud provider.
ECO_AI_PROVIDER_PRECEDENCE=cloud-first
AI_PROVIDER=openai
OPENAI_API_KEY=...
AI_MODEL=gpt-4o