🧠 dc.omniEmbedding

The Universal Embedding Gateway for InterSystems IRIS

One EMBEDDING() call. Any provider. Same vector space.

🌌 Motivation

InterSystems IRIS 2026 ships a native embeddings runtime — %Embedding.Interface + EMBEDDING() SQL — but each embedding provider has its own quirks:

• Ollama speaks OpenAI-compatible JSON but needs no auth
• OpenAI uses Authorization: Bearer
• Azure OpenAI wants api-key (not Bearer) and a deployment-scoped URL
• Cohere returns embeddings under embeddings.float[0]
• Gemini authenticates via ?key= on the URL itself
• Mistral is OpenAI-shaped but adds output_dimension / output_dtype for Codestral truncation
• Voyage AI adds input_type (query vs document), truncation and int8/binary quantization
• Jina AI requires input as an array (even for one text) and exposes task + late_chunking for coherent long-doc chunks
• AWS Bedrock speaks SigV4 (not Bearer) and switches payload/response shape per family (amazon.titan-embed-* vs cohere.embed-* hosted on Bedrock)
• Google Vertex AI needs region + project in the URL and an OAuth 2.0 access token in the header — the same text-embedding-* family name as OpenAI lives here too

Swapping providers usually means rewriting glue code, and mixing them in fallback flows silently mixes vector spaces — a data-integrity disaster that only surfaces months later, when your similarity searches start returning nonsense.

dc.omniEmbedding changes that.

Plug it in once as your EmbeddingClass and every EMBEDDING('text', 'config') call — from SQL, from ObjectScript, from Interoperability — routes to the right provider, retries transient errors, opens a circuit breaker on failing providers, and refuses to fall back to a config whose vector space differs from the primary.

• ✅ Ten providers, one interface: Ollama · OpenAI · Azure OpenAI · Cohere · Gemini · Mistral (text + code) · Voyage (text + code + domain) · Jina (with late_chunking) · AWS Bedrock (SigV4, Titan + Cohere via Bedrock) · Google Vertex AI (text-embedding + gemini-embedding)
• ✅ Native HTTP: %Net.HttpRequest — no Python required on the hot path
• ✅ Resilient: exponential backoff, Retry-After honored, circuit breaker per provider
• ✅ Safe fallback: vector-space invariance is enforced before any HTTP call
• ✅ Secure by default: apiKey is a credential name, never the raw secret
• ✅ CI-friendly: the whole happy path runs against local Ollama, no cloud keys

🛠️ How It Works

dc.omniEmbedding sits between IRIS’s native embedding runtime and any of the ten supported external providers, applying three architectural pillars:

1. HTTP native first — the happy path uses %Net.HttpRequest end-to-end; Embedded Python is opt-in only (for accurate tiktoken token counts).
2. Polymorphism by class hierarchy — a Template Method in provider.Base fixes the sequence ValidateConfig → SetAuth → GetEmbeddingsUrl → BuildPayload → RetryWithBackoff → ParseResponse; each provider overrides only what differs.
3. Vector-space integrity as a hard invariant — a fallback with a different modelName or dimensions is fatal, never a silent downgrade.

Core Components

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                Any caller — SQL, ObjectScript,              │
│                Interoperability, Embedded Python            │
│                    EMBEDDING('text', 'config')              │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│              %Embedding.Interface (IRIS runtime)            │
│  Reads EmbeddingClass from %Embedding.Config, dispatches:   │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│            dc.omniEmbedding.Interface (bridge)              │
│  ParseConfig · validate input · Engine.Embed()              │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                 dc.omniEmbedding.Engine                     │
│  ResolveProvider · CheckBreaker · RecordSuccess/Failure     │
│  TryFallback (vector-space invariant — fatal on mismatch)   │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│       provider.Base.Execute() — Template Method             │
│  ValidateConfig → SetAuth → GetEmbeddingsUrl →              │
│  BuildPayload → RetryWithBackoff → ParseResponse            │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│   %Net.HttpRequest → { Ollama | OpenAI | Azure | Cohere |   │
│                        Gemini | Mistral | Voyage | Jina |   │
│                        Bedrock (SigV4) | VertexAI (OAuth) } │
└─────────────────────────────────────────────────────────────┘

Resilience Model

• Retry: 429 and 5xx are retried with MIN(baseDelayMs * 2^(attempt-1) + jitter, maxDelayMs) — Retry-After is honored verbatim when present. 4xx (except 429) fast-fail.
• Circuit breaker: per provider|modelName|apiBase key stored in ^omniEmbedding.Breaker. Opens after 5 consecutive failures; 60 s cooldown; half-open lets one probe through.
• Fallback: iterates config.fallbacks in order. Each candidate is refused before any HTTP call if modelName or dimensions differ from the primary — vectors from different spaces never mix.

📋 Prerequisites

• InterSystems IRIS 2026.2+ (native %Embedding.Interface and %Library.Vector are required)
• Docker and Docker Compose (if you use the bundled dev container)
• Optional: Ollama at http://localhost:11434 for zero-cost end-to-end integration tests
• Optional: Embedded Python with tiktoken for exact OpenAI token counts (a conservative floor is used when unavailable)

🛠️ Installation

1. Clone the Repository

git clone https://github.com/henryhamon/dc.omniEmbedding.git
cd dc.omniEmbedding

2. Build and Run the Dev Container

docker-compose up -d --build

The IPM module dc-omni-embedding is loaded automatically into the IRISAPP namespace.

3. Or Install as an IPM Package

zpm "install dc-omni-embedding"

4. Wire it into %Embedding.Config

Register dc.omniEmbedding.Interface as your EmbeddingClass, then store a JSON configuration:

INSERT INTO %Embedding.Config (Name, Configuration, EmbeddingClass, VectorLength, Description)
VALUES (
    'ollama-nomic',
    '{"provider":"ollama","modelName":"nomic-embed-text:latest","apiBase":"http://host.docker.internal:11434","dimensions":768}',
    'dc.omniEmbedding.Interface',
    768,
    'Local Ollama (nomic-embed-text)'
)

5. Use It

From SQL:

SELECT EMBEDDING('the quick brown fox', 'ollama-nomic')

From ObjectScript:

Set vec = ##class(dc.omniEmbedding.Interface).Embedding(
    "the quick brown fox",
    "{""provider"":""ollama"",""modelName"":""nomic-embed-text:latest"",""dimensions"":768}"
)

💡 Configuration Reference

Every field is a top-level key on the JSON stored in %Embedding.Config.Configuration.

Common fields (all providers)

Provider-specific extras

• Azure OpenAI: deployment, apiVersion (deployment is optional when apiBase is already deployment-scoped)
• Cohere: inputType (default search_document)
• Gemini: taskType (default RETRIEVAL_DOCUMENT)
• Mistral: outputDimension (truncate — Codestral supports up to 3072), outputDtype (float · int8 · uint8 · binary · ubinary)
• Voyage: inputType (query · document), truncation (bool), outputDimension, outputDtype
• Jina: task (e.g. retrieval.query · retrieval.passage · text-matching · classification), outputDimension (mapped to Jina’s dimensions), lateChunking (bool — coherent long-doc chunks), outputDtype (mapped to Jina’s embedding_type)
• AWS Bedrock: region (required, e.g. us-east-1), sessionTokenCredential (optional, name of a second credential holding an STS token); inputType for Cohere-on-Bedrock family (default search_document); dimensions for Titan family
• Google Vertex AI: region (e.g. us-central1) + project required; apiKey names a credential whose value is a valid OAuth 2.0 access token (rotation is external — service-account JWT auto-refresh is future work); optional taskType (RETRIEVAL_QUERY · RETRIEVAL_DOCUMENT · SEMANTIC_SIMILARITY · CLASSIFICATION · CLUSTERING · CODE_RETRIEVAL_QUERY), title (only meaningful with RETRIEVAL_DOCUMENT), outputDimension (mapped to outputDimensionality), autoTruncate (bool)

Example — Ollama with an OpenAI fallback

{
    "provider": "ollama",
    "modelName": "nomic-embed-text:latest",
    "apiBase": "http://host.docker.internal:11434",
    "dimensions": 768,
    "fallbacks": ["ollama-backup"]
}

An OpenAI config with text-embedding-3-small (1536 dims) as a fallback would be rejected before any HTTP call — different vector space.

Example — AWS Bedrock Titan v2 with a session token

Register two credentials — the AWS access key/secret pair, and the STS session token — then reference both by name:

Set cred = ##class(Ens.Config.Credentials).%New()
Set cred.SystemName = "aws-prod"
Set cred.Username = "aws"
Set cred.Password = "AKIA...prod:wJalrXUtnFEMI/K7MDENG..."   ; accessKeyId:secretAccessKey
Do cred.%Save()
Set tok = ##class(Ens.Config.Credentials).%New()
Set tok.SystemName = "aws-prod-session"
Set tok.Username = "sts"
Set tok.Password = "FQoDYXdz...session-token..."
Do tok.%Save()

{
    "provider": "bedrock",
    "modelName": "amazon.titan-embed-text-v2:0",
    "region": "us-east-1",
    "apiKey": "aws-prod",
    "sessionTokenCredential": "aws-prod-session",
    "dimensions": 1024
}

Bedrock requires provider: "bedrock" explicit — the gateway will NOT infer it from cohere.embed-* or amazon.titan-embed-* prefixes to avoid collision with the direct Cohere provider.

Example — Mistral Codestral for code retrieval, truncated to 1024 dims

{
    "provider": "mistral",
    "modelName": "codestral-embed",
    "apiKey": "mistral-prod",
    "outputDimension": 1024,
    "outputDtype": "float",
    "dimensions": 1024
}

outputDimension tells Mistral to truncate the vector server-side (Codestral supports up to 3072); dimensions is what the gateway enforces on fallbacks and what IRIS stores.

🔐 Credentials

config.apiKey is always a credential name, never the raw secret. The gateway resolves the name via Ens.Config.Credentials.%OpenId(name).Password. Register one from the IRIS terminal:

Set cred = ##class(Ens.Config.Credentials).%New()
Set cred.SystemName = "openai-prod"
Set cred.Username = "apikey"
Set cred.Password = "sk-...your-real-key..."
Do cred.%Save()

Then reference it as "apiKey": "openai-prod" in your config. Exceptions raised for a missing credential carry only the name — never the value. See TestSecurity (Property 15).

🗂️ Project Structure

dc.omniEmbedding/
├── src/dc/omniEmbedding/
│   ├── Interface.cls              # Bridge to %Embedding.Interface
│   ├── Engine.cls                 # Dispatch · breaker · fallback
│   └── provider/
│       ├── Base.cls               # Template Method · retry · ResolveApiKey
│       ├── OpenACompatible.cls    # Shared payload/parse for OpenAI-family
│       ├── Ollama.cls
│       ├── OpenAi.cls
│       ├── AzureOpenAi.cls
│       ├── Cohere.cls
│       ├── Gemini.cls
│       ├── Mistral.cls              # mistral-embed (text) + codestral-embed (code)
│       ├── Voyage.cls               # voyage-3, voyage-code-3, voyage-finance-2, ...
│       ├── Jina.cls                 # jina-embeddings-v3, with late_chunking
│       ├── Bedrock.cls              # Titan + Cohere-via-Bedrock; overrides Execute for SigV4 ordering
│       └── VertexAi.cls             # text-embedding-* + gemini-embedding-*, OAuth 2.0 Bearer
├── src/dc/omniEmbedding/util/
│   └── SigV4.cls                    # AWS Signature V4 signer (isolated, testable)
├── tests/dc/omniEmbedding/
│   ├── TestOpenACompatible.cls    # Payload shape, parse errors, tiktoken floor
│   ├── TestOllama.cls             # URL construction + end-to-end via Ollama
│   ├── TestAzureUrl.cls           # Property 8 — URL composition invariants
│   ├── TestCohere.cls             # Property 10 — nested response parse
│   ├── TestGemini.cls             # Property 10 — auth-in-URL, no-op SetAuth
│   ├── TestMistral.cls            # URL, dispatch, output_dimension/dtype passthrough
│   ├── TestVoyage.cls             # URL, dispatch, inputType enum, all passthroughs
│   ├── TestJina.cls               # Property 17 — input always array; late_chunking; camelCase→wire mapping
│   ├── TestSigV4.cls              # Property 18 — key derivation matches AWS official vector byte-for-byte
│   ├── TestBedrock.cls            # URL, families, ParseResponse per family, credential formats, Property 19 (SigV4 applied), dispatch rules
│   ├── TestVertexAi.cls           # URL, ValidateConfig, Property 20 (parameters block only when needed), dispatch regression (no prefix inference)
│   ├── TestResilience.cls         # Properties 11-14 — backoff & breaker
│   ├── TestFallback.cls           # Properties 4-5 — vector-space invariance
│   ├── TestSecurity.cls           # Property 15 — credentials never leak
│   ├── TestInterface.cls          # Properties 2-3 — validation & no empty vec
│   └── FakeEngine.cls             # Test double for fallback tests
├── module.xml                     # IPM manifest
├── docker-compose.yml
└── README.md

🧪 Testing

Run every suite from the IRIS terminal:

Set ^UnitTestRoot = "/tmp/ut"
Do ##class(%UnitTest.Manager).RunTest(":dc.omniEmbedding.tests.TestOllama", "/nodelete/noload")

Or via IPM:

zpm "test dc-omni-embedding"

The end-to-end integration test in TestOllama auto-probes localhost:11434 then host.docker.internal:11434 and skips gracefully if Ollama is unavailable — CI stays green without any cloud key.

📊 Roadmap

✅ v1.0 — Complete

• %Embedding.Interface bridge & runtime integration
• Provider resolution by explicit name or model-prefix inference
• Ten providers: Ollama, OpenAI, Azure OpenAI, Cohere, Gemini, Mistral (text + code), Voyage (text + code + domain), Jina (with late_chunking), AWS Bedrock (SigV4, Titan + Cohere-on-Bedrock), Google Vertex AI (text-embedding + gemini-embedding)
• Retry with exponential backoff + Retry-After honoring
• Circuit breaker (5 failures / 60 s cooldown / half-open probe)
• Fallback with vector-space invariance (fatal on mismatch)
• Credentials via Ens.Config.Credentials (secret never leaks)
• Polymorphic EstimateTokenCount (tiktoken · Cohere · Gemini formulas)
• Property-based test suite covering every correctness invariant

🔮 Future

• Batching support (multiple inputs per request)
• Vertex AI: automatic OAuth 2.0 access-token refresh via service-account JWT-bearer flow (currently the token is supplied externally through Ens.Config.Credentials)
• Optional in-process embedding cache with TTL

🎖️ Credits

dc.omniEmbedding is designed and developed with 💜 by:

• Henry Pereira — architecture, implementation, testing

📄 License

This project is licensed under the MIT License.