hivecast-sdk/packages/oracle/core/doc/README.md

# 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:

```bash
# 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

```lisp
;; 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

```lisp
;; 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:

```lisp
(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):

```lisp
;; 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

```typescript
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

```typescript
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 |