Add LLM provider support (Ollama/OpenAI) with new configuration, processor, docs, examples, and updated dependencies.

Author: margostino

.env.example

@@ -13,5 +13,16 @@ REDIS_PASSWORD=
 JWT_SECRET=your-secret-key-here
 JWT_EXPIRATION=7d
 
-# OpenAI Configuration
-OPENAI_API_KEY=your-openai-api-key-here
+# LLM Provider Configuration
+# Choose which LLM provider to use:
+# - ollama: Local models via Ollama (gpt-oss:20b, deepseek-r1:7b, llama2:latest)
+# - openai: OpenAI cloud API (gpt-4o, gpt-4o-mini, etc.)
+LLM_PROVIDER=ollama
+
+# Ollama Configuration (for local models)
+# Runs models like: gpt-oss:20b, deepseek-r1:7b, llama2:latest
+OLLAMA_URL=http://localhost:11434/v1
+
+# OpenAI Configuration (OPTIONAL - only if using OpenAI proprietary cloud models)
+# OPENAI_API_KEY=sk-your-openai-api-key-here
+# OPENAI_BASE_URL=https://api.openai.com/v1

LLM_PROVIDERS.md

@@ -0,0 +1,214 @@
+# LLM Provider Configuration Guide
+
+## Overview
+
+Autobox Engine supports two LLM providers through the Vercel AI SDK:
+1. **Ollama** - Local models running on your machine (default)
+2. **OpenAI** - OpenAI proprietary cloud API (optional)
+
+## Supported Providers
+
+### 1. **Ollama (Local Models)** - Default ✅
+
+Runs models locally on your machine at `localhost:11434`.
+
+**Supported Models:**
+- `gpt-oss:20b` - OpenAI-compatible OSS model
+- `deepseek-r1:7b` - DeepSeek reasoning model (local)
+- `llama2:latest` - Meta's Llama 2
+- Any other model available in your local Ollama installation
+
+**Configuration:**
+```bash
+LLM_PROVIDER=ollama
+OLLAMA_URL=http://localhost:11434/v1
+```
+
+**Usage:**
+```json
+// In your simulation config
+{
+  "workers": [
+    {
+      "name": "ANA",
+      "llm": { "model": "deepseek-r1:7b" }
+    }
+  ]
+}
+```
+
+---
+
+### 2. **OpenAI (Cloud API)** - Optional
+
+Use OpenAI's proprietary cloud models.
+
+**Supported Models:**
+- `gpt-4o` - Latest GPT-4 Omni
+- `gpt-4o-mini` - Smaller, faster GPT-4 Omni
+- `gpt-3.5-turbo` - GPT-3.5 Turbo
+- Any official OpenAI model
+
+**Configuration:**
+```bash
+LLM_PROVIDER=openai
+OPENAI_API_KEY=sk-your-real-openai-api-key
+# OPENAI_BASE_URL=https://api.openai.com/v1  # Optional
+```
+
+**Usage:**
+```json
+// In your simulation config
+{
+  "workers": [
+    {
+      "name": "ANA",
+      "llm": { "model": "gpt-4o-mini" }
+    }
+  ]
+}
+```
+
+---
+
+## Quick Start
+
+### Option 1: Running with Ollama (Default) ✅
+
+1. **Install Ollama:**
+   ```bash
+   # macOS
+   brew install ollama
+
+   # Or download from https://ollama.com
+   ```
+
+2. **Pull models:**
+   ```bash
+   ollama pull gpt-oss:20b
+   ollama pull deepseek-r1:7b
+   ollama pull llama2:latest
+   ```
+
+3. **Start Ollama server:**
+   ```bash
+   ollama serve
+   ```
+
+4. **Configure `.env`:**
+   ```bash
+   LLM_PROVIDER=ollama
+   OLLAMA_URL=http://localhost:11434/v1
+   ```
+
+5. **Run simulation:**
+   ```bash
+   yarn dev --simulation-name=gift_choice_2
+   ```
+
+---
+
+### Option 2: Switching to OpenAI Cloud
+
+1. **Update `.env`:**
+   ```bash
+   LLM_PROVIDER=openai
+   OPENAI_API_KEY=sk-your-real-openai-api-key
+   ```
+
+2. **Update simulation config (optional):**
+   ```json
+   {
+     "workers": [
+       {
+         "name": "ANA",
+         "llm": { "model": "gpt-4o-mini" }
+       }
+     ]
+   }
+   ```
+
+3. **Run simulation:**
+   ```bash
+   yarn dev --simulation-name=gift_choice_2
+   ```
+
+---
+
+## Important Notes
+
+### 💡 Provider Comparison
+
+| Feature | Ollama (Local) | OpenAI (Cloud) |
+|---------|---------------|----------------|
+| Cost | Free | Paid per token |
+| Speed | Depends on hardware | Fast |
+| Privacy | 100% local | Data sent to OpenAI |
+| Models | gpt-oss:20b, deepseek-r1:7b, llama2 | gpt-4o, gpt-4o-mini, etc. |
+
+### 🔧 Per-Agent Configuration
+
+You can specify different models for different agents:
+
+```json
+{
+  "planner": {
+    "llm": { "model": "gpt-oss:20b" }
+  },
+  "workers": [
+    {
+      "name": "ANA",
+      "llm": { "model": "deepseek-r1:7b" }
+    },
+    {
+      "name": "JOHN",
+      "llm": { "model": "llama2:latest" }
+    }
+  ]
+}
+```
+
+**Note:** All agents use the same `LLM_PROVIDER` - you cannot mix Ollama and OpenAI in a single simulation.
+
+---
+
+## Troubleshooting
+
+### Error: "Cannot connect to Ollama"
+```bash
+# Ensure Ollama is running:
+ollama serve
+
+# Verify models are available:
+ollama list
+```
+
+### Error: "Invalid API key" (OpenAI)
+```bash
+# Verify your .env file:
+echo $OPENAI_API_KEY
+
+# Key should start with "sk-"
+```
+
+### Error: "Model not found"
+```bash
+# For Ollama: Pull the model first
+ollama pull deepseek-r1:7b
+
+# For OpenAI: Check model name is correct
+# Valid: gpt-4o-mini, gpt-4o
+# Invalid: gpt-5-nano (doesn't exist on OpenAI cloud)
+```
+
+---
+
+## Architecture
+
+Built with **Vercel AI SDK** (version 5), providing:
+- ✅ Unified API for Ollama and OpenAI
+- ✅ Type-safe model configuration
+- ✅ Automatic streaming support
+- ✅ Built-in error handling
+
+See `src/core/llm/createAiProcessor.ts` for implementation.

examples/metrics/gift_choice_3.json

@@ -0,0 +1,88 @@
+[
+    {
+        "name": "initial_preference_alignment",
+        "description": "Measures the initial alignment of Ana and John's gift preferences.",
+        "type": "GAUGE",
+        "unit": "percentage",
+        "tags": [
+            {
+                "tag": "agent_name",
+                "description": "The name of the agent (Ana or John)."
+            }
+        ]
+    },
+    {
+        "name": "final_agreement_score",
+        "description": "Evaluates how much the final gift decision aligns with each agent's preferences.",
+        "type": "GAUGE",
+        "unit": "percentage",
+        "tags": [
+            {
+                "tag": "agent_name",
+                "description": "The name of the agent (Ana or John)."
+            }
+        ]
+    },
+    {
+        "name": "decision_iterations",
+        "description": "Tracks the number of iterations or discussions needed to reach a decision.",
+        "type": "COUNTER",
+        "unit": "iterations",
+        "tags": []
+    },
+    {
+        "name": "influence_score",
+        "description": "Measures the influence each agent had on the final gift decision.",
+        "type": "GAUGE",
+        "unit": "percentage",
+        "tags": [
+            {
+                "tag": "agent_name",
+                "description": "The name of the agent (Ana or John)."
+            }
+        ]
+    },
+    {
+        "name": "compromise_index",
+        "description": "Measures how much each agent had to compromise from their initial preferences.",
+        "type": "GAUGE",
+        "unit": "percentage",
+        "tags": [
+            {
+                "tag": "agent_name",
+                "description": "The name of the agent (Ana or John)."
+            }
+        ]
+    },
+    {
+        "name": "satisfaction_score",
+        "description": "Measures each agent's satisfaction with the final gift decision.",
+        "type": "GAUGE",
+        "unit": "score",
+        "tags": [
+            {
+                "tag": "agent_name",
+                "description": "The name of the agent (Ana or John)."
+            }
+        ]
+    },
+    {
+        "name": "flexibility_score",
+        "description": "Measures the willingness of each agent to adapt their preferences during the decision process.",
+        "type": "GAUGE",
+        "unit": "score",
+        "tags": [
+            {
+                "tag": "agent_name",
+                "description": "The name of the agent (Ana or John)."
+            }
+        ]
+    },
+    {
+        "name": "consensus_level",
+        "description": "Indicates the level of agreement between Ana and John on the final gift decision.",
+        "type": "GAUGE",
+        "unit": "percentage",
+        "tags": []
+    }
+]

examples/simulations/gift_choice_3.json

@@ -0,0 +1,75 @@
+{
+  "name": "Gift choice",
+  "max_steps": 150,
+  "timeout_seconds": 120,
+  "shutdown_grace_period_seconds": 5,
+  "description": "This simulation is about two friends that need to decide together a gift for a special occasion.",
+  "task": "The task is VERY simple and should be completed in seconds: Ana and John need to pick a gift for the 30th birthday of another friend called Maria who likes books and reading, mainly fantasy books. She has preferences for Tokien and one book she has never read is 'The Hobbit'. Maria will be happy with any gift, but she will be happier with whatever gift. Ana and John should pick between 'The Hobbit: Illustrated Deluxe Edition, HarperCollins, Alan Lee' and 'The Hobbit, or There and Back Again, J.R.R. Tolkien'. Budget, delivery time, availability and NOTHING else matters, they ONLY need to pick one of the two options. There must not be other discussion, they should pick and that's it.",
+  "evaluator": {
+    "name": "EVALUATOR",
+    "mailbox": {
+      "max_size": 400
+    },
+    "llm": {
+      "model": "llama2:latest"
+    }
+  },
+  "reporter": {
+    "name": "REPORTER",
+    "mailbox": {
+      "max_size": 400
+    },
+    "llm": {
+      "model": "llama2:latest"
+    }
+  },
+  "planner": {
+    "name": "PLANNER",
+    "mailbox": {
+      "max_size": 400
+    },
+    "llm": {
+      "model": "llama2:latest"
+    }
+  },
+  "orchestrator": {
+    "name": "ORCHESTRATOR",
+    "mailbox": {
+      "max_size": 400
+    },
+    "llm": {
+      "model": "llama2:latest"
+    }
+  },
+  "workers": [
+    {
+      "name": "ANA",
+      "description": "this is ana agent",
+      "role": "Ana is Maria's friend. Pick quick no much thinking. She will buy.",
+      "backstory": "She is passionate about reading and books.",
+      "llm": {
+        "model": "llama2:latest"
+      },
+      "mailbox": {
+        "max_size": 100
+      }
+    },
+    {
+      "name": "JOHN",
+      "description": "this is john agent",
+      "role": "John is Maria's friend. Pick quick no much thinking.",
+      "backstory": "He is passionate about books of any kind.",
+      "llm": {
+        "model": "llama2:latest"
+      },
+      "mailbox": {
+        "max_size": 100
+      }
+    }
+  ],
+  "logging": {
+    "verbose": false,
+    "log_path": "logs",
+    "log_file": "gift_choice.log"
+  }
+}