@backtest-kit/ollama 14.1.0 โ 15.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +287 -287
- package/build/index.cjs +224 -160
- package/build/index.mjs +226 -162
- package/package.json +114 -112
- package/types.d.ts +16 -14
package/README.md
CHANGED
|
@@ -1,287 +1,287 @@
|
|
|
1
|
-
<img src="https://github.com/tripolskypetr/backtest-kit/raw/refs/heads/master/assets/monade.svg" height="45px" align="right">
|
|
2
|
-
|
|
3
|
-
# ๐ค @backtest-kit/ollama
|
|
4
|
-
|
|
5
|
-
> Universal LLM adapter for [backtest-kit](https://www.npmjs.com/package/backtest-kit) trading strategies. One higher-order-function API across **12 providers**, schema-enforced structured output, userspace prompt modules, token rotation โ plus an **LLM strategy optimizer** that generates runnable strategy code.
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
[](https://deepwiki.com/tripolskypetr/backtest-kit)
|
|
10
|
-
[](https://npmjs.org/package/@backtest-kit/ollama)
|
|
11
|
-
[]()
|
|
12
|
-
|
|
13
|
-
๐ **[Docs](https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html)** ยท ๐ **[Reference implementation](https://github.com/tripolskypetr/backtest-kit/tree/master/example)** ยท ๐ **[GitHub](https://github.com/tripolskypetr/backtest-kit)**
|
|
14
|
-
|
|
15
|
-
```bash
|
|
16
|
-
npm install @backtest-kit/ollama backtest-kit agent-swarm-kit
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
---
|
|
20
|
-
|
|
21
|
-
## Why
|
|
22
|
-
|
|
23
|
-
AI strategies normally mean per-provider SDK boilerplate and JSON you can't trust. This package collapses all of it: wrap any async function with a provider HOF and it runs inside that provider's inference context โ swap `deepseek()` โ `claude()` โ `gpt5()` with no other change. Structured output is schema-enforced (Zod or JSON schema via `agent-swarm-kit`'s `addOutline`), prompts live as memoized userspace modules
|
|
24
|
-
|
|
25
|
-
- ๐ **12 providers** โ OpenAI, Claude, DeepSeek, Grok, Groq, Mistral, Perplexity, Cohere, Alibaba, Hugging Face, Ollama (local), GLM-4 (Z.ai).
|
|
26
|
-
- โก **Higher-order functions** โ wrap an async fn with inference context via `di-scoped`; same signature in, same out.
|
|
27
|
-
- ๐ฏ **Userspace schema** โ define your own Zod or JSON schema; structured output enforced with auto-retry + custom validations.
|
|
28
|
-
- ๐ **Userspace prompts** โ load from `.cjs` modules in `config/prompt/`, or inline; memoized via `functools-kit`.
|
|
29
|
-
- ๐ **Token rotation** โ pass an array of API keys for automatic rotation.
|
|
30
|
-
- ๐งฌ **Strategy optimizer** โ `Optimizer` generates *complete executable strategy code* from LLM analysis across training ranges.
|
|
31
|
-
|
|
32
|
-
---
|
|
33
|
-
|
|
34
|
-
## The provider HOF
|
|
35
|
-
|
|
36
|
-
The whole adapter is one shape, repeated for 12 providers: `provider(fn, model, apiKey?) => fn`. It returns a function with the **same signature** as `fn`, executed inside the provider's inference context (so any `agent-swarm-kit` completion inside resolves to that provider).
|
|
37
|
-
|
|
38
|
-
```typescript
|
|
39
|
-
import { deepseek } from '@backtest-kit/ollama';
|
|
40
|
-
import { addStrategy } from 'backtest-kit';
|
|
41
|
-
|
|
42
|
-
addStrategy({
|
|
43
|
-
strategyName: 'llm-signal', interval: '5m',
|
|
44
|
-
// swap deepseek() โ claude() / gpt5() / ollama() / groq() with no other change
|
|
45
|
-
getSignal: deepseek(getSignal, 'deepseek-chat', process.env.DEEPSEEK_API_KEY),
|
|
46
|
-
});
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
<details>
|
|
50
|
-
<summary>All 12 providers, base URLs & token rotation</summary>
|
|
51
|
-
|
|
52
|
-
| Provider | Function | Inference | Base URL |
|
|
53
|
-
|----------|----------|-----------|----------|
|
|
54
|
-
| OpenAI | `gpt5()` | `gpt5_inference` | `https://api.openai.com/v1/` |
|
|
55
|
-
| Claude | `claude()` | `claude_inference` | `https://api.anthropic.com/v1/` |
|
|
56
|
-
| DeepSeek | `deepseek()` | `deepseek_inference` | `https://api.deepseek.com/` |
|
|
57
|
-
| Grok (xAI) | `grok()` | `grok_inference` | `https://api.x.ai/v1/` |
|
|
58
|
-
| Groq | `groq()` | `groq_inference` | `https://api.groq.com/` |
|
|
59
|
-
| Mistral | `mistral()` | `mistral_inference` | `https://api.mistral.ai/v1/` |
|
|
60
|
-
| Perplexity | `perplexity()` | `perplexity_inference` | `https://api.perplexity.ai/` |
|
|
61
|
-
| Cohere | `cohere()` | `cohere_inference` | `https://api.cohere.ai/compatibility/v1/` |
|
|
62
|
-
| Alibaba (Qwen) | `alibaba()` | `alibaba_inference` | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1/` |
|
|
63
|
-
| Hugging Face | `hf()` | `hf_inference` | `https://router.huggingface.co/v1/` |
|
|
64
|
-
| Ollama (local) | `ollama()` | `ollama_inference` | `http://localhost:11434/` |
|
|
65
|
-
| GLM-4 (Z.ai) | `glm4()` | `glm4_inference` | `https://open.bigmodel.cn/api/paas/v4/` |
|
|
66
|
-
|
|
67
|
-
```typescript
|
|
68
|
-
// apiKey accepts a single key OR an array โ automatic rotation across calls
|
|
69
|
-
const wrappedFn = ollama(myFn, 'llama3.3:70b', ['key1', 'key2', 'key3']);
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
All twelve share one signature โ `<T>(fn: T, model: string, apiKey?: string | string[]) => T` โ and run `fn` inside `ContextService.runInContext({ apiKey, inference, model })`. The matching `InferenceName` enum + per-provider `client/*Provider.client.ts` + `config/*.ts` resolve the actual SDK call.
|
|
73
|
-
|
|
74
|
-
</details>
|
|
75
|
-
|
|
76
|
-
---
|
|
77
|
-
|
|
78
|
-
## Structured output
|
|
79
|
-
|
|
80
|
-
Define a schema (Zod or raw JSON), register it as an outline against this package's `CompletionName`, and the LLM is forced to return valid JSON โ with custom validations that reject bad signals (e.g. "SL must be below entry for LONG").
|
|
81
|
-
|
|
82
|
-
<details>
|
|
83
|
-
<summary>Zod outline</summary>
|
|
84
|
-
|
|
85
|
-
```typescript
|
|
86
|
-
// schema/Signal.schema.ts
|
|
87
|
-
import { z } from 'zod';
|
|
88
|
-
export const SignalSchema = z.object({
|
|
89
|
-
position: z.enum(['long', 'short', 'wait']).describe('long: bullish ยท short: bearish ยท wait: unclear'),
|
|
90
|
-
price_open: z.number().describe('Entry price in USD'),
|
|
91
|
-
price_stop_loss: z.number().describe('LONG: below entry ยท SHORT: above entry'),
|
|
92
|
-
price_take_profit: z.number().describe('LONG: above entry ยท SHORT: below entry'),
|
|
93
|
-
minute_estimated_time: z.number().describe('Estimated minutes to reach TP'),
|
|
94
|
-
risk_note: z.string().describe('Whale manipulation, order-book imbalance, divergences โ with numbers'),
|
|
95
|
-
});
|
|
96
|
-
export type TSignalSchema = z.infer<typeof SignalSchema>;
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
```typescript
|
|
100
|
-
// outline/signal.outline.ts
|
|
101
|
-
import { addOutline } from 'agent-swarm-kit';
|
|
102
|
-
import { zodResponseFormat } from 'openai/helpers/zod';
|
|
103
|
-
import { SignalSchema, TSignalSchema } from '../schema/Signal.schema';
|
|
104
|
-
import { CompletionName } from '@backtest-kit/ollama';
|
|
105
|
-
|
|
106
|
-
addOutline<TSignalSchema>({
|
|
107
|
-
outlineName: 'SignalOutline',
|
|
108
|
-
completion: CompletionName.RunnerOutlineCompletion,
|
|
109
|
-
format: zodResponseFormat(SignalSchema, 'position_decision'),
|
|
110
|
-
getOutlineHistory: async ({ history, param: messages = [] }) => { await history.push(messages); },
|
|
111
|
-
validations: [{
|
|
112
|
-
validate: ({ data }) => {
|
|
113
|
-
if (data.position === 'long' && data.price_stop_loss >= data.price_open) throw new Error('LONG: SL must be below entry');
|
|
114
|
-
if (data.position === 'short' && data.price_stop_loss <= data.price_open) throw new Error('SHORT: SL must be above entry');
|
|
115
|
-
},
|
|
116
|
-
}],
|
|
117
|
-
});
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
</details>
|
|
121
|
-
|
|
122
|
-
<details>
|
|
123
|
-
<summary>Raw JSON-schema outline (no Zod)</summary>
|
|
124
|
-
|
|
125
|
-
```typescript
|
|
126
|
-
import { addOutline, IOutlineFormat } from 'agent-swarm-kit';
|
|
127
|
-
import { CompletionName } from '@backtest-kit/ollama';
|
|
128
|
-
|
|
129
|
-
const format: IOutlineFormat = {
|
|
130
|
-
type: 'object',
|
|
131
|
-
properties: {
|
|
132
|
-
take_profit_price: { type: 'number', description: 'Take profit price in USD' },
|
|
133
|
-
stop_loss_price: { type: 'number', description: 'Stop-loss price in USD' },
|
|
134
|
-
description: { type: 'string', description: 'User-friendly risk explanation, min 10 sentences' },
|
|
135
|
-
reasoning: { type: 'string', description: 'Technical analysis, min 15 sentences' },
|
|
136
|
-
},
|
|
137
|
-
required: ['take_profit_price', 'stop_loss_price', 'description', 'reasoning'],
|
|
138
|
-
};
|
|
139
|
-
|
|
140
|
-
addOutline({
|
|
141
|
-
outlineName: 'SignalOutline', format, completion: CompletionName.RunnerOutlineCompletion,
|
|
142
|
-
prompt: 'Generate crypto trading signals from price & volume indicators in JSON.',
|
|
143
|
-
getOutlineHistory: async ({ history, param }) => {
|
|
144
|
-
const report = await ioc.signalReportService.getSignalReport(param);
|
|
145
|
-
await commitReports(history, report);
|
|
146
|
-
await history.push({ role: 'user', content: 'Generate JSON based on reports.' });
|
|
147
|
-
},
|
|
148
|
-
validations: [
|
|
149
|
-
{ docDescription: 'Stop-loss vs max loss %', validate: ({ data }) => { if (data.action === 'buy' && percentDiff(data.current_price, data.stop_loss_price) > CC_LADDER_STOP_LOSS) throw new Error(`SL must not exceed -${CC_LADDER_STOP_LOSS}%`); } },
|
|
150
|
-
{ docDescription: 'Take-profit vs max profit %', validate: ({ data }) => { if (data.action === 'buy' && percentDiff(data.current_price, data.take_profit_price) > CC_LADDER_TAKE_PROFIT) throw new Error(`TP must not exceed +${CC_LADDER_TAKE_PROFIT}%`); } },
|
|
151
|
-
],
|
|
152
|
-
});
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
</details>
|
|
156
|
-
|
|
157
|
-
---
|
|
158
|
-
|
|
159
|
-
## Prompts
|
|
160
|
-
|
|
161
|
-
Prompt modules receive trading context automatically. `system` may be a string array or a function of `(symbol, strategyName, exchangeName, frameName, backtest)`; `user` likewise.
|
|
162
|
-
|
|
163
|
-
<details>
|
|
164
|
-
<summary>Module file, inline prompt & commitPrompt</summary>
|
|
165
|
-
|
|
166
|
-
```javascript
|
|
167
|
-
// config/prompt/signal.prompt.cjs
|
|
168
|
-
module.exports = {
|
|
169
|
-
system: (symbol, strategyName, exchangeName, frameName, backtest) => [
|
|
170
|
-
`You are analyzing ${symbol} on ${exchangeName}`,
|
|
171
|
-
`Strategy: ${strategyName}, Timeframe: ${frameName}`,
|
|
172
|
-
backtest ? 'Backtest mode' : 'Live mode',
|
|
173
|
-
],
|
|
174
|
-
user: (symbol) => `Analyze ${symbol} and return a trading decision`,
|
|
175
|
-
};
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
```typescript
|
|
179
|
-
import { Module, Prompt, commitPrompt, MessageModel } from '@backtest-kit/ollama';
|
|
180
|
-
|
|
181
|
-
// from a .cjs module (default baseDir: {cwd}/config/prompt/), memoized
|
|
182
|
-
const signalModule = Module.fromPath('./signal.prompt.cjs');
|
|
183
|
-
// or inline
|
|
184
|
-
const inline = Prompt.fromPrompt({ system: ['You are a trading bot'], user: (symbol) => `Trend for ${symbol}?` });
|
|
185
|
-
|
|
186
|
-
const messages: MessageModel[] = [];
|
|
187
|
-
await commitPrompt(signalModule, messages); // pushes rendered system + user messages with context
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
Full strategy: register the outline, build messages from a prompt, request structured JSON, wrap with a provider HOF:
|
|
191
|
-
|
|
192
|
-
```typescript
|
|
193
|
-
import './outline/signal.outline';
|
|
194
|
-
import { deepseek, Module, commitPrompt, MessageModel } from '@backtest-kit/ollama';
|
|
195
|
-
import { addStrategy } from 'backtest-kit';
|
|
196
|
-
import { json } from 'agent-swarm-kit';
|
|
197
|
-
|
|
198
|
-
const signalModule = Module.fromPath('./signal.prompt.cjs');
|
|
199
|
-
const getSignal = async () => {
|
|
200
|
-
const messages: MessageModel[] = [];
|
|
201
|
-
await commitPrompt(signalModule, messages);
|
|
202
|
-
const { data } = await json('SignalOutline', messages);
|
|
203
|
-
return data;
|
|
204
|
-
};
|
|
205
|
-
addStrategy({ strategyName: 'llm-signal', interval: '5m',
|
|
206
|
-
getSignal: deepseek(getSignal, 'deepseek-chat', process.env.DEEPSEEK_API_KEY) });
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
</details>
|
|
210
|
-
|
|
211
|
-
---
|
|
212
|
-
|
|
213
|
-
## Debugging โ dump the conversation
|
|
214
|
-
|
|
215
|
-
`dumpSignalData(signalId, history, signal, outputDir?)` archives the full LLM conversation attached to a signal, so an opaque model decision becomes a readable record. Skips if the directory already exists (never overwrites prior runs).
|
|
216
|
-
|
|
217
|
-
<details>
|
|
218
|
-
<summary>What it writes</summary>
|
|
219
|
-
|
|
220
|
-
Into `{outputDir}/{signalId}/` (default `./dump/strategy`): `00_system_prompt.md` (system messages + output summary), numbered `XX_user_message.md` / `XX_assistant_message.md` per turn, and a final `XX_llm_output.md` with the signal DTO. Call it from `getSignal` right before returning the signal.
|
|
221
|
-
|
|
222
|
-
</details>
|
|
223
|
-
|
|
224
|
-
---
|
|
225
|
-
|
|
226
|
-
## Strategy optimizer โ generate runnable strategy code
|
|
227
|
-
|
|
228
|
-
The most powerful piece, and the one the rest of the package feeds: `Optimizer` uses an LLM to analyze a symbol across training ranges and emit a **complete, executable strategy file** โ imports, helpers, strategies, walker, and launcher โ that you can run with backtest-kit directly.
|
|
229
|
-
|
|
230
|
-
<details>
|
|
231
|
-
<summary>Optimizer API + addOptimizerSchema + progress events</summary>
|
|
232
|
-
|
|
233
|
-
```typescript
|
|
234
|
-
import { Optimizer, addOptimizerSchema, listenOptimizerProgress } from '@backtest-kit/ollama';
|
|
235
|
-
|
|
236
|
-
// describe sources, training ranges, strategy/template generation (see IOptimizer* interfaces)
|
|
237
|
-
addOptimizerSchema({ optimizerName: 'my-optimizer', /* sources, ranges, strategy, template */ });
|
|
238
|
-
|
|
239
|
-
listenOptimizerProgress((p) => console.log(p)); // ProgressOptimizerContract
|
|
240
|
-
|
|
241
|
-
const strategies = await Optimizer.getData('BTCUSDT', { optimizerName: 'my-optimizer' }); // metadata + LLM context per range
|
|
242
|
-
const code = await Optimizer.getCode('BTCUSDT', { optimizerName: 'my-optimizer' }); // full TS/JS source as string
|
|
243
|
-
await Optimizer.dump('BTCUSDT', { optimizerName: 'my-optimizer' }, './output'); // writes {optimizerName}_{symbol}.mjs
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
`getData` fetches from all sources and builds the LLM conversation per training range; `getCode` assembles the executable strategy; `dump` writes it to `{optimizerName}_{symbol}.mjs`. Companion registry functions: `getOptimizerSchema`, `listOptimizerSchema`, and `listenError`. The engine behind it is `common/ClientOptimizer.ts` driven by the `IOptimizer*` interfaces (`IOptimizerSchema`, `IOptimizerSource`, `IOptimizerStrategy`, `IOptimizerTemplate`, `IOptimizerRange`, `IOptimizerData`, `IOptimizerFetchArgs`, `IOptimizerFilterArgs`, `IOptimizerCallbacks`).
|
|
247
|
-
|
|
248
|
-
</details>
|
|
249
|
-
|
|
250
|
-
---
|
|
251
|
-
|
|
252
|
-
## API reference
|
|
253
|
-
|
|
254
|
-
| Export | Description |
|
|
255
|
-
|--------|-------------|
|
|
256
|
-
| `ollama` `gpt5` `claude` `deepseek` `grok` `groq` `mistral` `perplexity` `cohere` `alibaba` `hf` `glm4` | Provider HOFs โ `(fn, model, apiKey?) => fn` |
|
|
257
|
-
| `CompletionName` | Completion-name enum for `agent-swarm-kit` outlines (`RunnerOutlineCompletion`, โฆ) |
|
|
258
|
-
| `Module.fromPath(path, baseDir?)` | Load a prompt `.cjs` module (default baseDir `{cwd}/config/prompt/`) |
|
|
259
|
-
| `Prompt.fromPrompt(source)` | Build a prompt from an inline `PromptModel` |
|
|
260
|
-
| `commitPrompt(source, history)` | Render a Module/Prompt's system+user messages into `history` |
|
|
261
|
-
| `dumpSignalData(id, history, signal, dir?)` | Archive the LLM conversation for one signal |
|
|
262
|
-
| `validate(...)` | Validate an outline result |
|
|
263
|
-
| `Optimizer` | `.getData` / `.getCode` / `.dump` โ LLM strategy-code generation |
|
|
264
|
-
| `addOptimizerSchema` ยท `getOptimizerSchema` ยท `listOptimizerSchema` | Optimizer schema registry |
|
|
265
|
-
| `listenOptimizerProgress` ยท `listenError` | Optimizer progress / error events |
|
|
266
|
-
| `MessageModel` `MessageRole` `PromptModel` | Message & prompt models |
|
|
267
|
-
| `IOptimizer*` ยท `ProgressOptimizerContract` | Optimizer interfaces & progress contract |
|
|
268
|
-
| `lib` | The internal engine (IoC container) for advanced use |
|
|
269
|
-
|
|
270
|
-
<details>
|
|
271
|
-
<summary>Complete source map</summary>
|
|
272
|
-
|
|
273
|
-
- `function/signal.function.ts` โ the 12 provider HOFs. `function/{add,get,list,event,setup,validate,history,dump,signal}.ts` โ registry, events, `setLogger`, `commitPrompt`, `dumpSignalData`.
|
|
274
|
-
- `client/*Provider.client.ts` (12) โ per-provider SDK adapters. `config/*.ts` โ per-provider base URLs/params, `ollama.rotate.ts` (token rotation), `params.ts`, `emitters.ts`.
|
|
275
|
-
- `classes/` โ `Module`, `Prompt`, `Optimizer`. `common/ClientOptimizer.ts` โ the optimizer engine.
|
|
276
|
-
- `enum/` โ `InferenceName` (12), `CompletionName`. `interface/Optimizer.interface.ts`, `contract/ProgressOptimizer.contract.ts`, `model/{Message,Prompt}.model.ts`.
|
|
277
|
-
- `helpers/{toLintMarkdown,toPlainString}.ts`, `lib/` (IoC: `core/{di,provide,types}`, services). Nothing in `src/` is undocumented.
|
|
278
|
-
|
|
279
|
-
</details>
|
|
280
|
-
|
|
281
|
-
## ๐ค Contribute
|
|
282
|
-
|
|
283
|
-
Fork / PR on [GitHub](https://github.com/tripolskypetr/backtest-kit).
|
|
284
|
-
|
|
285
|
-
## ๐ License
|
|
286
|
-
|
|
287
|
-
MIT ยฉ [tripolskypetr](https://github.com/tripolskypetr)
|
|
1
|
+
<img src="https://github.com/tripolskypetr/backtest-kit/raw/refs/heads/master/assets/monade.svg" height="45px" align="right">
|
|
2
|
+
|
|
3
|
+
# ๐ค @backtest-kit/ollama
|
|
4
|
+
|
|
5
|
+
> Universal LLM adapter for [backtest-kit](https://www.npmjs.com/package/backtest-kit) trading strategies. One higher-order-function API across **12 providers**, schema-enforced structured output, userspace prompt modules, token rotation โ plus an **LLM strategy optimizer** that generates runnable strategy code.
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
[](https://deepwiki.com/tripolskypetr/backtest-kit)
|
|
10
|
+
[](https://npmjs.org/package/@backtest-kit/ollama)
|
|
11
|
+
[]()
|
|
12
|
+
|
|
13
|
+
๐ **[Docs](https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html)** ยท ๐ **[Reference implementation](https://github.com/tripolskypetr/backtest-kit/tree/master/example)** ยท ๐ **[GitHub](https://github.com/tripolskypetr/backtest-kit)**
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install @backtest-kit/ollama backtest-kit agent-swarm-kit
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Why
|
|
22
|
+
|
|
23
|
+
AI strategies normally mean per-provider SDK boilerplate and JSON you can't trust. This package collapses all of it: wrap any async function with a provider HOF and it runs inside that provider's inference context โ swap `deepseek()` โ `claude()` โ `gpt5()` with no other change. Structured output is schema-enforced (Zod or JSON schema via `agent-swarm-kit`'s `addOutline`), prompts live as memoized userspace modules
|
|
24
|
+
|
|
25
|
+
- ๐ **12 providers** โ OpenAI, Claude, DeepSeek, Grok, Groq, Mistral, Perplexity, Cohere, Alibaba, Hugging Face, Ollama (local), GLM-4 (Z.ai).
|
|
26
|
+
- โก **Higher-order functions** โ wrap an async fn with inference context via `di-scoped`; same signature in, same out.
|
|
27
|
+
- ๐ฏ **Userspace schema** โ define your own Zod or JSON schema; structured output enforced with auto-retry + custom validations.
|
|
28
|
+
- ๐ **Userspace prompts** โ load from `.cjs` modules in `config/prompt/`, or inline; memoized via `functools-kit`.
|
|
29
|
+
- ๐ **Token rotation** โ pass an array of API keys for automatic rotation.
|
|
30
|
+
- ๐งฌ **Strategy optimizer** โ `Optimizer` generates *complete executable strategy code* from LLM analysis across training ranges.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## The provider HOF
|
|
35
|
+
|
|
36
|
+
The whole adapter is one shape, repeated for 12 providers: `provider(fn, model, apiKey?) => fn`. It returns a function with the **same signature** as `fn`, executed inside the provider's inference context (so any `agent-swarm-kit` completion inside resolves to that provider).
|
|
37
|
+
|
|
38
|
+
```typescript
|
|
39
|
+
import { deepseek } from '@backtest-kit/ollama';
|
|
40
|
+
import { addStrategy } from 'backtest-kit';
|
|
41
|
+
|
|
42
|
+
addStrategy({
|
|
43
|
+
strategyName: 'llm-signal', interval: '5m',
|
|
44
|
+
// swap deepseek() โ claude() / gpt5() / ollama() / groq() with no other change
|
|
45
|
+
getSignal: deepseek(getSignal, 'deepseek-chat', process.env.DEEPSEEK_API_KEY),
|
|
46
|
+
});
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
<details>
|
|
50
|
+
<summary>All 12 providers, base URLs & token rotation</summary>
|
|
51
|
+
|
|
52
|
+
| Provider | Function | Inference | Base URL |
|
|
53
|
+
|----------|----------|-----------|----------|
|
|
54
|
+
| OpenAI | `gpt5()` | `gpt5_inference` | `https://api.openai.com/v1/` |
|
|
55
|
+
| Claude | `claude()` | `claude_inference` | `https://api.anthropic.com/v1/` |
|
|
56
|
+
| DeepSeek | `deepseek()` | `deepseek_inference` | `https://api.deepseek.com/` |
|
|
57
|
+
| Grok (xAI) | `grok()` | `grok_inference` | `https://api.x.ai/v1/` |
|
|
58
|
+
| Groq | `groq()` | `groq_inference` | `https://api.groq.com/` |
|
|
59
|
+
| Mistral | `mistral()` | `mistral_inference` | `https://api.mistral.ai/v1/` |
|
|
60
|
+
| Perplexity | `perplexity()` | `perplexity_inference` | `https://api.perplexity.ai/` |
|
|
61
|
+
| Cohere | `cohere()` | `cohere_inference` | `https://api.cohere.ai/compatibility/v1/` |
|
|
62
|
+
| Alibaba (Qwen) | `alibaba()` | `alibaba_inference` | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1/` |
|
|
63
|
+
| Hugging Face | `hf()` | `hf_inference` | `https://router.huggingface.co/v1/` |
|
|
64
|
+
| Ollama (local) | `ollama()` | `ollama_inference` | `http://localhost:11434/` |
|
|
65
|
+
| GLM-4 (Z.ai) | `glm4()` | `glm4_inference` | `https://open.bigmodel.cn/api/paas/v4/` |
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
// apiKey accepts a single key OR an array โ automatic rotation across calls
|
|
69
|
+
const wrappedFn = ollama(myFn, 'llama3.3:70b', ['key1', 'key2', 'key3']);
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
All twelve share one signature โ `<T>(fn: T, model: string, apiKey?: string | string[]) => T` โ and run `fn` inside `ContextService.runInContext({ apiKey, inference, model })`. The matching `InferenceName` enum + per-provider `client/*Provider.client.ts` + `config/*.ts` resolve the actual SDK call.
|
|
73
|
+
|
|
74
|
+
</details>
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## Structured output
|
|
79
|
+
|
|
80
|
+
Define a schema (Zod or raw JSON), register it as an outline against this package's `CompletionName`, and the LLM is forced to return valid JSON โ with custom validations that reject bad signals (e.g. "SL must be below entry for LONG").
|
|
81
|
+
|
|
82
|
+
<details>
|
|
83
|
+
<summary>Zod outline</summary>
|
|
84
|
+
|
|
85
|
+
```typescript
|
|
86
|
+
// schema/Signal.schema.ts
|
|
87
|
+
import { z } from 'zod';
|
|
88
|
+
export const SignalSchema = z.object({
|
|
89
|
+
position: z.enum(['long', 'short', 'wait']).describe('long: bullish ยท short: bearish ยท wait: unclear'),
|
|
90
|
+
price_open: z.number().describe('Entry price in USD'),
|
|
91
|
+
price_stop_loss: z.number().describe('LONG: below entry ยท SHORT: above entry'),
|
|
92
|
+
price_take_profit: z.number().describe('LONG: above entry ยท SHORT: below entry'),
|
|
93
|
+
minute_estimated_time: z.number().describe('Estimated minutes to reach TP'),
|
|
94
|
+
risk_note: z.string().describe('Whale manipulation, order-book imbalance, divergences โ with numbers'),
|
|
95
|
+
});
|
|
96
|
+
export type TSignalSchema = z.infer<typeof SignalSchema>;
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
```typescript
|
|
100
|
+
// outline/signal.outline.ts
|
|
101
|
+
import { addOutline } from 'agent-swarm-kit';
|
|
102
|
+
import { zodResponseFormat } from 'openai/helpers/zod';
|
|
103
|
+
import { SignalSchema, TSignalSchema } from '../schema/Signal.schema';
|
|
104
|
+
import { CompletionName } from '@backtest-kit/ollama';
|
|
105
|
+
|
|
106
|
+
addOutline<TSignalSchema>({
|
|
107
|
+
outlineName: 'SignalOutline',
|
|
108
|
+
completion: CompletionName.RunnerOutlineCompletion,
|
|
109
|
+
format: zodResponseFormat(SignalSchema, 'position_decision'),
|
|
110
|
+
getOutlineHistory: async ({ history, param: messages = [] }) => { await history.push(messages); },
|
|
111
|
+
validations: [{
|
|
112
|
+
validate: ({ data }) => {
|
|
113
|
+
if (data.position === 'long' && data.price_stop_loss >= data.price_open) throw new Error('LONG: SL must be below entry');
|
|
114
|
+
if (data.position === 'short' && data.price_stop_loss <= data.price_open) throw new Error('SHORT: SL must be above entry');
|
|
115
|
+
},
|
|
116
|
+
}],
|
|
117
|
+
});
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
</details>
|
|
121
|
+
|
|
122
|
+
<details>
|
|
123
|
+
<summary>Raw JSON-schema outline (no Zod)</summary>
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
import { addOutline, IOutlineFormat } from 'agent-swarm-kit';
|
|
127
|
+
import { CompletionName } from '@backtest-kit/ollama';
|
|
128
|
+
|
|
129
|
+
const format: IOutlineFormat = {
|
|
130
|
+
type: 'object',
|
|
131
|
+
properties: {
|
|
132
|
+
take_profit_price: { type: 'number', description: 'Take profit price in USD' },
|
|
133
|
+
stop_loss_price: { type: 'number', description: 'Stop-loss price in USD' },
|
|
134
|
+
description: { type: 'string', description: 'User-friendly risk explanation, min 10 sentences' },
|
|
135
|
+
reasoning: { type: 'string', description: 'Technical analysis, min 15 sentences' },
|
|
136
|
+
},
|
|
137
|
+
required: ['take_profit_price', 'stop_loss_price', 'description', 'reasoning'],
|
|
138
|
+
};
|
|
139
|
+
|
|
140
|
+
addOutline({
|
|
141
|
+
outlineName: 'SignalOutline', format, completion: CompletionName.RunnerOutlineCompletion,
|
|
142
|
+
prompt: 'Generate crypto trading signals from price & volume indicators in JSON.',
|
|
143
|
+
getOutlineHistory: async ({ history, param }) => {
|
|
144
|
+
const report = await ioc.signalReportService.getSignalReport(param);
|
|
145
|
+
await commitReports(history, report);
|
|
146
|
+
await history.push({ role: 'user', content: 'Generate JSON based on reports.' });
|
|
147
|
+
},
|
|
148
|
+
validations: [
|
|
149
|
+
{ docDescription: 'Stop-loss vs max loss %', validate: ({ data }) => { if (data.action === 'buy' && percentDiff(data.current_price, data.stop_loss_price) > CC_LADDER_STOP_LOSS) throw new Error(`SL must not exceed -${CC_LADDER_STOP_LOSS}%`); } },
|
|
150
|
+
{ docDescription: 'Take-profit vs max profit %', validate: ({ data }) => { if (data.action === 'buy' && percentDiff(data.current_price, data.take_profit_price) > CC_LADDER_TAKE_PROFIT) throw new Error(`TP must not exceed +${CC_LADDER_TAKE_PROFIT}%`); } },
|
|
151
|
+
],
|
|
152
|
+
});
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
</details>
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Prompts
|
|
160
|
+
|
|
161
|
+
Prompt modules receive trading context automatically. `system` may be a string array or a function of `(symbol, strategyName, exchangeName, frameName, backtest)`; `user` likewise.
|
|
162
|
+
|
|
163
|
+
<details>
|
|
164
|
+
<summary>Module file, inline prompt & commitPrompt</summary>
|
|
165
|
+
|
|
166
|
+
```javascript
|
|
167
|
+
// config/prompt/signal.prompt.cjs
|
|
168
|
+
module.exports = {
|
|
169
|
+
system: (symbol, strategyName, exchangeName, frameName, backtest) => [
|
|
170
|
+
`You are analyzing ${symbol} on ${exchangeName}`,
|
|
171
|
+
`Strategy: ${strategyName}, Timeframe: ${frameName}`,
|
|
172
|
+
backtest ? 'Backtest mode' : 'Live mode',
|
|
173
|
+
],
|
|
174
|
+
user: (symbol) => `Analyze ${symbol} and return a trading decision`,
|
|
175
|
+
};
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
```typescript
|
|
179
|
+
import { Module, Prompt, commitPrompt, MessageModel } from '@backtest-kit/ollama';
|
|
180
|
+
|
|
181
|
+
// from a .cjs module (default baseDir: {cwd}/config/prompt/), memoized
|
|
182
|
+
const signalModule = Module.fromPath('./signal.prompt.cjs');
|
|
183
|
+
// or inline
|
|
184
|
+
const inline = Prompt.fromPrompt({ system: ['You are a trading bot'], user: (symbol) => `Trend for ${symbol}?` });
|
|
185
|
+
|
|
186
|
+
const messages: MessageModel[] = [];
|
|
187
|
+
await commitPrompt(signalModule, messages); // pushes rendered system + user messages with context
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Full strategy: register the outline, build messages from a prompt, request structured JSON, wrap with a provider HOF:
|
|
191
|
+
|
|
192
|
+
```typescript
|
|
193
|
+
import './outline/signal.outline';
|
|
194
|
+
import { deepseek, Module, commitPrompt, MessageModel } from '@backtest-kit/ollama';
|
|
195
|
+
import { addStrategy } from 'backtest-kit';
|
|
196
|
+
import { json } from 'agent-swarm-kit';
|
|
197
|
+
|
|
198
|
+
const signalModule = Module.fromPath('./signal.prompt.cjs');
|
|
199
|
+
const getSignal = async () => {
|
|
200
|
+
const messages: MessageModel[] = [];
|
|
201
|
+
await commitPrompt(signalModule, messages);
|
|
202
|
+
const { data } = await json('SignalOutline', messages);
|
|
203
|
+
return data;
|
|
204
|
+
};
|
|
205
|
+
addStrategy({ strategyName: 'llm-signal', interval: '5m',
|
|
206
|
+
getSignal: deepseek(getSignal, 'deepseek-chat', process.env.DEEPSEEK_API_KEY) });
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
</details>
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## Debugging โ dump the conversation
|
|
214
|
+
|
|
215
|
+
`dumpSignalData(signalId, history, signal, outputDir?)` archives the full LLM conversation attached to a signal, so an opaque model decision becomes a readable record. Skips if the directory already exists (never overwrites prior runs).
|
|
216
|
+
|
|
217
|
+
<details>
|
|
218
|
+
<summary>What it writes</summary>
|
|
219
|
+
|
|
220
|
+
Into `{outputDir}/{signalId}/` (default `./dump/strategy`): `00_system_prompt.md` (system messages + output summary), numbered `XX_user_message.md` / `XX_assistant_message.md` per turn, and a final `XX_llm_output.md` with the signal DTO. Call it from `getSignal` right before returning the signal.
|
|
221
|
+
|
|
222
|
+
</details>
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## Strategy optimizer โ generate runnable strategy code
|
|
227
|
+
|
|
228
|
+
The most powerful piece, and the one the rest of the package feeds: `Optimizer` uses an LLM to analyze a symbol across training ranges and emit a **complete, executable strategy file** โ imports, helpers, strategies, walker, and launcher โ that you can run with backtest-kit directly.
|
|
229
|
+
|
|
230
|
+
<details>
|
|
231
|
+
<summary>Optimizer API + addOptimizerSchema + progress events</summary>
|
|
232
|
+
|
|
233
|
+
```typescript
|
|
234
|
+
import { Optimizer, addOptimizerSchema, listenOptimizerProgress } from '@backtest-kit/ollama';
|
|
235
|
+
|
|
236
|
+
// describe sources, training ranges, strategy/template generation (see IOptimizer* interfaces)
|
|
237
|
+
addOptimizerSchema({ optimizerName: 'my-optimizer', /* sources, ranges, strategy, template */ });
|
|
238
|
+
|
|
239
|
+
listenOptimizerProgress((p) => console.log(p)); // ProgressOptimizerContract
|
|
240
|
+
|
|
241
|
+
const strategies = await Optimizer.getData('BTCUSDT', { optimizerName: 'my-optimizer' }); // metadata + LLM context per range
|
|
242
|
+
const code = await Optimizer.getCode('BTCUSDT', { optimizerName: 'my-optimizer' }); // full TS/JS source as string
|
|
243
|
+
await Optimizer.dump('BTCUSDT', { optimizerName: 'my-optimizer' }, './output'); // writes {optimizerName}_{symbol}.mjs
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
`getData` fetches from all sources and builds the LLM conversation per training range; `getCode` assembles the executable strategy; `dump` writes it to `{optimizerName}_{symbol}.mjs`. Companion registry functions: `getOptimizerSchema`, `listOptimizerSchema`, and `listenError`. The engine behind it is `common/ClientOptimizer.ts` driven by the `IOptimizer*` interfaces (`IOptimizerSchema`, `IOptimizerSource`, `IOptimizerStrategy`, `IOptimizerTemplate`, `IOptimizerRange`, `IOptimizerData`, `IOptimizerFetchArgs`, `IOptimizerFilterArgs`, `IOptimizerCallbacks`).
|
|
247
|
+
|
|
248
|
+
</details>
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## API reference
|
|
253
|
+
|
|
254
|
+
| Export | Description |
|
|
255
|
+
|--------|-------------|
|
|
256
|
+
| `ollama` `gpt5` `claude` `deepseek` `grok` `groq` `mistral` `perplexity` `cohere` `alibaba` `hf` `glm4` | Provider HOFs โ `(fn, model, apiKey?) => fn` |
|
|
257
|
+
| `CompletionName` | Completion-name enum for `agent-swarm-kit` outlines (`RunnerOutlineCompletion`, โฆ) |
|
|
258
|
+
| `Module.fromPath(path, baseDir?)` | Load a prompt `.cjs` module (default baseDir `{cwd}/config/prompt/`) |
|
|
259
|
+
| `Prompt.fromPrompt(source)` | Build a prompt from an inline `PromptModel` |
|
|
260
|
+
| `commitPrompt(source, history)` | Render a Module/Prompt's system+user messages into `history` |
|
|
261
|
+
| `dumpSignalData(id, history, signal, dir?)` | Archive the LLM conversation for one signal |
|
|
262
|
+
| `validate(...)` | Validate an outline result |
|
|
263
|
+
| `Optimizer` | `.getData` / `.getCode` / `.dump` โ LLM strategy-code generation |
|
|
264
|
+
| `addOptimizerSchema` ยท `getOptimizerSchema` ยท `listOptimizerSchema` | Optimizer schema registry |
|
|
265
|
+
| `listenOptimizerProgress` ยท `listenError` | Optimizer progress / error events |
|
|
266
|
+
| `MessageModel` `MessageRole` `PromptModel` | Message & prompt models |
|
|
267
|
+
| `IOptimizer*` ยท `ProgressOptimizerContract` | Optimizer interfaces & progress contract |
|
|
268
|
+
| `lib` | The internal engine (IoC container) for advanced use |
|
|
269
|
+
|
|
270
|
+
<details>
|
|
271
|
+
<summary>Complete source map</summary>
|
|
272
|
+
|
|
273
|
+
- `function/signal.function.ts` โ the 12 provider HOFs. `function/{add,get,list,event,setup,validate,history,dump,signal}.ts` โ registry, events, `setLogger`, `commitPrompt`, `dumpSignalData`.
|
|
274
|
+
- `client/*Provider.client.ts` (12) โ per-provider SDK adapters. `config/*.ts` โ per-provider base URLs/params, `ollama.rotate.ts` (token rotation), `params.ts`, `emitters.ts`.
|
|
275
|
+
- `classes/` โ `Module`, `Prompt`, `Optimizer`. `common/ClientOptimizer.ts` โ the optimizer engine.
|
|
276
|
+
- `enum/` โ `InferenceName` (12), `CompletionName`. `interface/Optimizer.interface.ts`, `contract/ProgressOptimizer.contract.ts`, `model/{Message,Prompt}.model.ts`.
|
|
277
|
+
- `helpers/{toLintMarkdown,toPlainString}.ts`, `lib/` (IoC: `core/{di,provide,types}`, services). Nothing in `src/` is undocumented.
|
|
278
|
+
|
|
279
|
+
</details>
|
|
280
|
+
|
|
281
|
+
## ๐ค Contribute
|
|
282
|
+
|
|
283
|
+
Fork / PR on [GitHub](https://github.com/tripolskypetr/backtest-kit).
|
|
284
|
+
|
|
285
|
+
## ๐ License
|
|
286
|
+
|
|
287
|
+
MIT ยฉ [tripolskypetr](https://github.com/tripolskypetr)
|