hivecast-sdk/packages/oracle/core/doc

OmegaLLM Oracle Interface

This directory contains the unified LLM inference layer for OmegaLLM.

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│  Lisp Interface                                                      │
│  ─────────────                                                       │
│  (effect infer.op "prompt")           ;; Use default model           │
│  (effect infer.op (with-model "gpt-4o" "prompt"))  ;; Specific model │
│  (effect infer.op (with-plugin "anthropic" "claude-opus" "prompt"))  │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│  ModelSelectorAdapter (TypeScript)                                   │
│  ─────────────────────────────                                       │
│  - Parses model/plugin from payload                                  │
│  - Routes to appropriate OraclePlugin                                │
│  - Caches adapter instances                                          │
│  - Auto-detects available plugins from API keys                      │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Plugin Registry                                                     │
│  ───────────────                                                     │
│  anthropic: AnthropicOracleAdapter (ANTHROPIC_API_KEY)              │
│  openai:    OpenAIOracleAdapter (OPENAI_API_KEY)                    │
│  ollama:    OllamaOracleAdapter (local, no key needed)              │
└─────────────────────────────────────────────────────────────────────┘

API Keys

Set environment variables for the providers you want to use:

# Anthropic (Claude models)
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI (GPT models)
export OPENAI_API_KEY=sk-...

# Ollama runs locally, no key needed

Keys should be in .gitignore - never commit them!

Lisp API

Basic Inference

;; Use default model (auto-detected from available API keys)
(effect infer.op "What is 2 + 2?")

;; Returns a Meaning value with the response

Model Selection

;; Select a specific model
(effect infer.op (with-model "gpt-4o" "Explain quantum computing"))

;; Select model with explicit plugin
(effect infer.op (with-plugin "anthropic" "claude-opus-4-20250514" "Write a poem"))

;; Model string format: "plugin:model" also works
(effect infer.op (with-model "openai:gpt-4-turbo" "Complex task"))

Smart Inference (lib/oracle/smart-infer.lisp)

Smart inference provides automatic model escalation with backtracking:

(require 'oracle/smart-infer)

;; Try cheap models first, escalate if response is poor
(cheap-first-infer "Simple question")

;; Go straight to premium models
(premium-infer "Complex analysis task")

;; With custom validator
(smart-infer "Write code" all-models-by-cost
  (lambda (r) (min-length? r 100)))

ChatGPT Browser Automation

ChatGPT Pro uses a separate transport (browser automation):

;; Instant/fast mode
(effect chatgpt.infer.op "question" "instant")

;; Auto mode (default)
(effect chatgpt.infer.op "question" "auto")

;; Pro mode (extended thinking)
(effect chatgpt.infer.op "question" "pro")

;; Thinking mode (shows reasoning)
(effect chatgpt.infer.op "question" "thinking")

TypeScript API

OmegaRuntime Configuration

import { OmegaRuntime } from "omega-llm";

// Auto-detect adapter from API keys
const omega = new OmegaRuntime();

// Explicit model configuration
const omega = new OmegaRuntime({
  modelSelection: {
    defaultModel: "claude-sonnet-4-20250514",
    defaultPlugin: "anthropic",
  },
});

// Disable auto-detection (fail if no explicit adapter)
const omega = new OmegaRuntime({
  disableAutoAdapter: true,
});

Direct Plugin Access

import { createModelSelector, createPluginSelector } from "omega-llm";

// Multi-model selector
const selector = createModelSelector({
  defaultModel: "gpt-4o",
  defaultPlugin: "openai",
});

// Single-plugin selector
const anthropicOnly = createPluginSelector("anthropic", "claude-sonnet-4-20250514");

Available Models

OpenAI (plugin: "openai")

• gpt-4o - Most capable, balanced
• gpt-4o-mini - Fast, cost-effective
• gpt-4-turbo - Previous generation flagship

Anthropic (plugin: "anthropic")

• claude-opus-4-20250514 - Most capable
• claude-sonnet-4-20250514 - Balanced
• claude-3-haiku-20240307 - Fast, efficient

Ollama (plugin: "ollama")

• llama3.1 - Default local model
• Any model installed via ollama pull

ChatGPT Browser (separate transport)

• chatgpt-instant - Fast responses
• chatgpt-auto - Default
• chatgpt-pro - Extended thinking
• chatgpt-thinking - Shows reasoning

File Reference

File	Purpose
smart-infer.lisp	amb-based model selection with fallback
../cache/cached-infer.lisp	Semantic caching layer
src/core/oracle/plugins/	TypeScript plugin implementations
src/core/oracle/plugins/modelSelector.ts	Model routing logic
src/core/oracle/plugins/registry.ts	Plugin registration