@backtest-kit/ollama 0.0.1 → 0.0.2

package/README.md

@@ -1,205 +1,206 @@
-# 🤖 @backtest-kit/ollama
-
-> Multi-provider LLM inference library for AI-powered trading strategies. Supports 10+ providers including OpenAI, Claude, DeepSeek, Grok, and more with unified API and automatic token rotation.
-
-![bots](https://raw.githubusercontent.com/tripolskypetr/backtest-kit/HEAD/assets/bots.png)
-
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tripolskypetr/backtest-kit)
-[![npm](https://img.shields.io/npm/v/@backtest-kit/ollama.svg?style=flat-square)](https://npmjs.org/package/@backtest-kit/ollama)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)]()
-
-Transform technical analysis into trading decisions with multi-provider LLM support, structured output, and built-in risk management.
-
-📚 **[Backtest Kit Docs](https://backtest-kit.github.io/documents/example_02_first_backtest.html)** | 🌟 **[GitHub](https://github.com/tripolskypetr/backtest-kit)**
-
-## ✨ Features
-
-- 🔌 **10+ LLM Providers**: OpenAI, Claude, DeepSeek, Grok, Mistral, Perplexity, Cohere, Alibaba, Hugging Face, Ollama
-- 🔄 **Token Rotation**: Automatic API key rotation for Ollama (others throw clear errors)
-- 🎯 **Structured Output**: Enforced JSON schema for trading signals (position, price levels, risk notes)
-- 🔑 **Flexible Auth**: Context-based API keys or environment variables
-- ⚡ **Unified API**: Single interface across all providers
-- 📊 **Trading-First**: Built for backtest-kit with position sizing and risk management
-- 🛡️ **Type Safe**: Full TypeScript support with exported types
-
-## 📋 What It Does
-
-`@backtest-kit/ollama` provides a unified interface to call multiple LLM providers and receive structured trading signals:
-
-| Provider | Function | Base URL |
-|----------|----------|----------|
-| **OpenAI** | `gpt5()` | api.openai.com |
-| **Claude** | `claude()` | api.anthropic.com |
-| **DeepSeek** | `deepseek()` | api.deepseek.com |
-| **Grok** | `grok()` | api.x.ai |
-| **Mistral** | `mistral()` | api.mistral.ai |
-| **Perplexity** | `perplexity()` | api.perplexity.ai |
-| **Cohere** | `cohere()` | api.cohere.ai |
-| **Alibaba** | `alibaba()` | dashscope-intl.aliyuncs.com/compatible-mode/v1 |
-| **Hugging Face** | `hf()` | router.huggingface.co/v1 |
-| **Ollama** | `ollama()` | ollama.com |
-
-**Output Schema:**
-
-```typescript
-{
-  id: string;              // Unique signal ID
-  position: "long" | "short";  // Trading direction
-  minuteEstimatedTime: number; // Hold duration estimate
-  priceStopLoss: number;       // Stop loss price
-  priceTakeProfit: number;     // Take profit price
-  note: string;                // Risk assessment note
-  priceOpen: number;           // Entry price
-}
-```
-
-## 🚀 Installation
-
-```bash
-npm install @backtest-kit/ollama agent-swarm-kit backtest-kit
-```
-
-## 📖 Usage
-
-### Quick Start - OpenAI
-
-```typescript
-import { gpt5 } from '@backtest-kit/ollama';
-import { commitHistorySetup } from '@backtest-kit/signals';
-
-// Build context with technical analysis
-const messages = [
-  {
-    role: 'system',
-    content: 'You are a trading bot. Analyze indicators and return JSON: { position: "long"|"short", priceStopLoss, priceTakeProfit, minuteEstimatedTime, priceOpen, note }'
-  }
-];
-
-await commitHistorySetup('BTCUSDT', messages);
-
-// Get trading signal from GPT-5
-const signal = await gpt5(messages, 'gpt-4o', process.env.CC_OPENAI_API_KEY);
-
-console.log(signal);
-// {
-//   id: "abc-123",
-//   position: "long",
-//   priceStopLoss: 49000,
-//   priceTakeProfit: 51000,
-//   minuteEstimatedTime: 60,
-//   priceOpen: 50000,
-//   note: "Strong bullish momentum with RSI oversold recovery"
-// }
-```
-
-### Multi-Provider Strategy
-
-```typescript
-import { gpt5, claude, deepseek } from '@backtest-kit/ollama';
-import { addStrategy } from 'backtest-kit';
-import { commitHistorySetup } from '@backtest-kit/signals';
-
-addStrategy({
-  strategyName: 'multi-llm',
-  interval: '5m',
-  riskName: 'aggressive',
-  getSignal: async (symbol) => {
-    const messages = [
-      {
-        role: 'system',
-        content: 'Analyze technical data and return trading signal as JSON'
-      }
-    ];
-
-    await commitHistorySetup(symbol, messages);
-
-    // Try multiple providers with fallback
-    try {
-      return await deepseek(messages, 'deepseek-chat');
-    } catch (err) {
-      console.warn('DeepSeek failed, trying Claude:', err);
-      try {
-        return await claude(messages, 'claude-3-5-sonnet-20241022');
-      } catch (err2) {
-        console.warn('Claude failed, using GPT-5:', err2);
-        return await gpt5(messages, 'gpt-4o');
-      }
-    }
-  }
-});
-```
-
-### Token Rotation (Ollama Only)
-
-Ollama supports automatic API key rotation by passing an array:
-
-```typescript
-import { ollama } from '@backtest-kit/ollama';
-
-const signal = await ollama(
-  messages,
-  'llama3.3:70b',
-  ['key1', 'key2', 'key3']  // Rotates through keys
-);
-
-// Other providers throw error:
-// "Claude provider does not support token rotation"
-```
-
-### Custom Logger
-
-Enable logging for debugging:
-
-```typescript
-import { setLogger } from '@backtest-kit/ollama';
-
-setLogger({
-  log: console.log,
-  debug: console.debug,
-  info: console.info,
-  warn: console.warn,
-});
-```
-
-## 💡 Why Use @backtest-kit/ollama?
-
-Instead of manually integrating LLM SDKs:
-
-```typescript
-// ❌ Without ollama (manual work)
-import OpenAI from 'openai';
-import Anthropic from '@anthropic-ai/sdk';
-
-const openai = new OpenAI({ apiKey: process.env.OPENAI_KEY });
-const response = await openai.chat.completions.create({
-  model: 'gpt-4o',
-  messages,
-  response_format: { type: 'json_object' }
-});
-const signal = JSON.parse(response.choices[0].message.content);
-// ... manual schema validation
-// ... manual error handling
-// ... no fallback
-```
-
-```typescript
-// ✅ With ollama (one line)
-const signal = await gpt5(messages, 'gpt-4o');
-```
-
-**Benefits:**
-
-- ⚡ Unified API across 10+ providers
-- 🎯 Enforced JSON schema (no parsing errors)
-- 🔄 Built-in token rotation (Ollama)
-- 🔑 Context-based API keys
-- 🛡️ Type-safe TypeScript interfaces
-- 📊 Trading-specific output format
-
-## 🤝 Contribute
-
-Fork/PR on [GitHub](https://github.com/tripolskypetr/backtest-kit).
-
-## 📜 License
-
-MIT © [tripolskypetr](https://github.com/tripolskypetr)
+# 🤖 @backtest-kit/ollama
+
+> Multi-provider LLM inference library for AI-powered trading strategies. Supports 10+ providers including OpenAI, Claude, DeepSeek, Grok, and more with unified API and automatic token rotation.
+
+![bots](https://raw.githubusercontent.com/tripolskypetr/backtest-kit/HEAD/assets/bots.png)
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tripolskypetr/backtest-kit)
+[![npm](https://img.shields.io/npm/v/@backtest-kit/ollama.svg?style=flat-square)](https://npmjs.org/package/@backtest-kit/ollama)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)]()
+
+Transform technical analysis into trading decisions with multi-provider LLM support, structured output, and built-in risk management.
+
+📚 **[Backtest Kit Docs](https://backtest-kit.github.io/documents/example_02_first_backtest.html)** | 🌟 **[GitHub](https://github.com/tripolskypetr/backtest-kit)**
+
+## ✨ Features
+
+- 🔌 **10+ LLM Providers**: OpenAI, Claude, DeepSeek, Grok, Mistral, Perplexity, Cohere, Alibaba, Hugging Face, Ollama
+- 🔄 **Token Rotation**: Automatic API key rotation for Ollama (others throw clear errors)
+- 🎯 **Structured Output**: Enforced JSON schema for trading signals (position, price levels, risk notes)
+- 🔑 **Flexible Auth**: Context-based API keys or environment variables
+- ⚡ **Unified API**: Single interface across all providers
+- 📊 **Trading-First**: Built for backtest-kit with position sizing and risk management
+- 🛡️ **Type Safe**: Full TypeScript support with exported types
+
+## 📋 What It Does
+
+`@backtest-kit/ollama` provides a unified interface to call multiple LLM providers and receive structured trading signals:
+
+| Provider | Function | Base URL |
+|----------|----------|----------|
+| **OpenAI** | `gpt5()` | api.openai.com |
+| **Claude** | `claude()` | api.anthropic.com |
+| **DeepSeek** | `deepseek()` | api.deepseek.com |
+| **Grok** | `grok()` | api.x.ai |
+| **Mistral** | `mistral()` | api.mistral.ai |
+| **Perplexity** | `perplexity()` | api.perplexity.ai |
+| **Cohere** | `cohere()` | api.cohere.ai |
+| **Alibaba** | `alibaba()` | dashscope-intl.aliyuncs.com/compatible-mode/v1 |
+| **Hugging Face** | `hf()` | router.huggingface.co/v1 |
+| **Ollama** | `ollama()` | cloud.ollama.com |
+| **Z.ai** | `glm4()` | api.z.ai/api/paas/v4 |
+
+**Output Schema:**
+
+```typescript
+{
+  id: string;              // Unique signal ID
+  position: "long" | "short";  // Trading direction
+  minuteEstimatedTime: number; // Hold duration estimate
+  priceStopLoss: number;       // Stop loss price
+  priceTakeProfit: number;     // Take profit price
+  note: string;                // Risk assessment note
+  priceOpen: number;           // Entry price
+}
+```
+
+## 🚀 Installation
+
+```bash
+npm install @backtest-kit/ollama agent-swarm-kit backtest-kit
+```
+
+## 📖 Usage
+
+### Quick Start - OpenAI
+
+```typescript
+import { gpt5 } from '@backtest-kit/ollama';
+import { commitHistorySetup } from '@backtest-kit/signals';
+
+// Build context with technical analysis
+const messages = [
+  {
+    role: 'system',
+    content: 'You are a trading bot. Analyze indicators and return JSON: { position: "long"|"short", priceStopLoss, priceTakeProfit, minuteEstimatedTime, priceOpen, note }'
+  }
+];
+
+await commitHistorySetup('BTCUSDT', messages);
+
+// Get trading signal from GPT-5
+const signal = await gpt5(messages, 'gpt-4o', process.env.CC_OPENAI_API_KEY);
+
+console.log(signal);
+// {
+//   id: "abc-123",
+//   position: "long",
+//   priceStopLoss: 49000,
+//   priceTakeProfit: 51000,
+//   minuteEstimatedTime: 60,
+//   priceOpen: 50000,
+//   note: "Strong bullish momentum with RSI oversold recovery"
+// }
+```
+
+### Multi-Provider Strategy
+
+```typescript
+import { gpt5, claude, deepseek } from '@backtest-kit/ollama';
+import { addStrategy } from 'backtest-kit';
+import { commitHistorySetup } from '@backtest-kit/signals';
+
+addStrategy({
+  strategyName: 'multi-llm',
+  interval: '5m',
+  riskName: 'aggressive',
+  getSignal: async (symbol) => {
+    const messages = [
+      {
+        role: 'system',
+        content: 'Analyze technical data and return trading signal as JSON'
+      }
+    ];
+
+    await commitHistorySetup(symbol, messages);
+
+    // Try multiple providers with fallback
+    try {
+      return await deepseek(messages, 'deepseek-chat');
+    } catch (err) {
+      console.warn('DeepSeek failed, trying Claude:', err);
+      try {
+        return await claude(messages, 'claude-3-5-sonnet-20241022');
+      } catch (err2) {
+        console.warn('Claude failed, using GPT-5:', err2);
+        return await gpt5(messages, 'gpt-4o');
+      }
+    }
+  }
+});
+```
+
+### Token Rotation (Ollama Only)
+
+Ollama supports automatic API key rotation by passing an array:
+
+```typescript
+import { ollama } from '@backtest-kit/ollama';
+
+const signal = await ollama(
+  messages,
+  'llama3.3:70b',
+  ['key1', 'key2', 'key3']  // Rotates through keys
+);
+
+// Other providers throw error:
+// "Claude provider does not support token rotation"
+```
+
+### Custom Logger
+
+Enable logging for debugging:
+
+```typescript
+import { setLogger } from '@backtest-kit/ollama';
+
+setLogger({
+  log: console.log,
+  debug: console.debug,
+  info: console.info,
+  warn: console.warn,
+});
+```
+
+## 💡 Why Use @backtest-kit/ollama?
+
+Instead of manually integrating LLM SDKs:
+
+```typescript
+// ❌ Without ollama (manual work)
+import OpenAI from 'openai';
+import Anthropic from '@anthropic-ai/sdk';
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_KEY });
+const response = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages,
+  response_format: { type: 'json_object' }
+});
+const signal = JSON.parse(response.choices[0].message.content);
+// ... manual schema validation
+// ... manual error handling
+// ... no fallback
+```
+
+```typescript
+// ✅ With ollama (one line)
+const signal = await gpt5(messages, 'gpt-4o');
+```
+
+**Benefits:**
+
+- ⚡ Unified API across 10+ providers
+- 🎯 Enforced JSON schema (no parsing errors)
+- 🔄 Built-in token rotation (Ollama)
+- 🔑 Context-based API keys
+- 🛡️ Type-safe TypeScript interfaces
+- 📊 Trading-specific output format
+
+## 🤝 Contribute
+
+Fork/PR on [GitHub](https://github.com/tripolskypetr/backtest-kit).
+
+## 📜 License
+
+MIT © [tripolskypetr](https://github.com/tripolskypetr)