From 9540b6c1260d6b9930c8968ad53ef1f89dd0a4c5 Mon Sep 17 00:00:00 2001
From: Rafayel Latif <74052861+Rafipilot@users.noreply.github.com>
Date: Sat, 8 Nov 2025 10:28:27 +0000
Subject: [PATCH] Document methods for using Ollama with TimeCopilot

Added instructions for using open-source models with TimeCopilot.
---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/README.md b/README.md
index 8622726..9d5c263 100644
--- a/README.md
+++ b/README.md
@@ -266,6 +266,60 @@ from timecopilot import TimeCopilot
 tc = TimeCopilot(llm="ollama:gpt-oss:20b")
 ```
 
+---
+## Using open-source models (Ollama + `gpt-oss`)
+
+* Method 1: pass the model name directly to `TimeCopilot` (simple).
+* Method 2: construct an `OpenAIChatModel` instance with an `OllamaProvider` and pass it to `TimeCopilot` (explicit provider).
+
+### Prerequisites
+
+* Ollama running locally (or reachable) — the examples below assume `http://localhost:11434/v1`.
+* You want to use the `gpt-oss` models (we used `gpt-oss:20b` in examples).
+
+---
+
+### 1. Quick method (set base URL + pass model string)
+
+1. Set the Ollama base URL in your shell:
+
+```bash
+export OLLAMA_BASE_URL='http://localhost:11434/v1'
+```
+
+2. Initialize the forecasting agent:
+
+```python
+from timecopilot import TimeCopilot
+
+# Pass the Ollama model directly by name
+tc = TimeCopilot(llm="ollama:gpt-oss:20b")
+```
+
+---
+
+### 2. Explicit provider method (construct model + provider)
+
+1. Construct an `OpenAIChatModel` that uses an `OllamaProvider`:
+
+```python
+from some_module import OpenAIChatModel, OllamaProvider  # adjust imports to your package layout
+
+llm = OpenAIChatModel(
+    model_name="llama3.1:latest",
+    provider=OllamaProvider(base_url="http://localhost:11434/v1"),
+)
+```
+
+> **Note:** remove any stray trailing spaces in model names (e.g., `"llama3.1:latest "` → `"llama3.1:latest"`).
+
+2. Initialize the forecasting agent with that model:
+
+```python
+from timecopilot import TimeCopilot
+
+tc = TimeCopilot(llm=llm)
+```
 ---
 
 ## Ask about the future