@aeye/ollama 0.8.0 → 0.8.1

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.
Files changed (3) hide show
  1. package/README.md +54 -54
  2. package/aeye-ollama.md +93 -93
  3. package/package.json +72 -72
package/README.md CHANGED
@@ -1,54 +1,54 @@
1
- # @aeye/ollama
2
-
3
- Ollama provider for the @aeye (AI TypeScript) framework: local (or cloud) Ollama models for chat, embeddings, and System One decisions.
4
-
5
- ## Features
6
-
7
- - **Chat and embeddings** through Ollama's OpenAI-compatible `/v1`, with system messages sent as `system` (Ollama's templates drop OpenAI's `developer` role)
8
- - **Decisions** through `/v1/systemone` (Ollama v0.35+): predicates, choices, and scores, with images and `keep_alive`
9
- - **Honest model list** from `/api/tags` and `/api/show`: what each model does (`completion`, `tools`, `thinking`, `vision`, `embedding`, `decision`) and the context window it is really served with
10
- - **Decision limits**: decision models carry `maxQuestions` (64) and `maxRequestBytes` (64 KiB); larger calls are refused, never split
11
- - **Extends OpenAI**: built on `@aeye/openai`'s `OpenAIProvider`
12
-
13
- ## Installation
14
-
15
- ```bash
16
- npm install @aeye/ollama @aeye/openai @aeye/ai @aeye/core openai
17
- ```
18
-
19
- Requires Node >= 22 and the `openai` SDK v7.
20
-
21
- ## Quick Start
22
-
23
- ```typescript
24
- import { AI } from '@aeye/ai';
25
- import { OllamaProvider } from '@aeye/ollama';
26
-
27
- const ollama = new OllamaProvider({ keepAlive: '10m' });
28
- const ai = AI.with().providers({ ollama }).create();
29
-
30
- const response = await ai.chat.get([{ role: 'user', content: 'Hello!' }], { metadata: { model: 'qwen2.5:3b' } });
31
-
32
- const { answers } = await ai.decide.get({
33
- input: 'The printer is on fire.',
34
- questions: { urgent: { type: 'predicate', instructions: 'Is this urgent?' } },
35
- }, { metadata: { model: 'nimble' } });
36
- ```
37
-
38
- ## Configuration
39
-
40
- | Option | Meaning |
41
- |--------|---------|
42
- | `baseURL` | Ollama's root, not `/v1` (default `http://127.0.0.1:11434`) |
43
- | `apiKey` | A key, for Ollama's cloud |
44
- | `contextWindow` | The window the server serves models with no `num_ctx` at (as `OLLAMA_CONTEXT_LENGTH` sets) |
45
- | `maxContextWindow` | The most window assumed when `contextWindow` is unset |
46
- | `keepAlive` | How long a decision model stays loaded (`'5m'`, seconds, `0` unloads, below 0 keeps) |
47
- | `decisionModels` | Decision models, for servers whose `/api/show` lists no capabilities |
48
- | `fetch` | The `fetch` every call goes through |
49
-
50
- See the [Ollama provider docs](https://github.com/ClickerMonkey/aeye/tree/main/packages/docs/providers/ollama.md) and the [decisions guide](https://github.com/ClickerMonkey/aeye/tree/main/packages/docs/guides/decisions.md).
51
-
52
- ## License
53
-
54
- GPL-3.0
1
+ # @aeye/ollama
2
+
3
+ Ollama provider for the @aeye (AI TypeScript) framework: local (or cloud) Ollama models for chat, embeddings, and System One decisions.
4
+
5
+ ## Features
6
+
7
+ - **Chat and embeddings** through Ollama's OpenAI-compatible `/v1`, with system messages sent as `system` (Ollama's templates drop OpenAI's `developer` role)
8
+ - **Decisions** through `/v1/systemone` (Ollama v0.35+): predicates, choices, and scores, with images and `keep_alive`
9
+ - **Honest model list** from `/api/tags` and `/api/show`: what each model does (`completion`, `tools`, `thinking`, `vision`, `embedding`, `decision`) and the context window it is really served with
10
+ - **Decision limits**: decision models carry `maxQuestions` (64) and `maxRequestBytes` (64 KiB); larger calls are refused, never split
11
+ - **Extends OpenAI**: built on `@aeye/openai`'s `OpenAIProvider`
12
+
13
+ ## Installation
14
+
15
+ ```bash
16
+ npm install @aeye/ollama @aeye/openai @aeye/ai @aeye/core openai
17
+ ```
18
+
19
+ Requires Node >= 22 and the `openai` SDK v7.
20
+
21
+ ## Quick Start
22
+
23
+ ```typescript
24
+ import { AI } from '@aeye/ai';
25
+ import { OllamaProvider } from '@aeye/ollama';
26
+
27
+ const ollama = new OllamaProvider({ keepAlive: '10m' });
28
+ const ai = AI.with().providers({ ollama }).create();
29
+
30
+ const response = await ai.chat.get([{ role: 'user', content: 'Hello!' }], { metadata: { model: 'qwen2.5:3b' } });
31
+
32
+ const { answers } = await ai.decide.get({
33
+ input: 'The printer is on fire.',
34
+ questions: { urgent: { type: 'predicate', instructions: 'Is this urgent?' } },
35
+ }, { metadata: { model: 'nimble' } });
36
+ ```
37
+
38
+ ## Configuration
39
+
40
+ | Option | Meaning |
41
+ |--------|---------|
42
+ | `baseURL` | Ollama's root, not `/v1` (default `http://127.0.0.1:11434`) |
43
+ | `apiKey` | A key, for Ollama's cloud |
44
+ | `contextWindow` | The window the server serves models with no `num_ctx` at (as `OLLAMA_CONTEXT_LENGTH` sets) |
45
+ | `maxContextWindow` | The most window assumed when `contextWindow` is unset |
46
+ | `keepAlive` | How long a decision model stays loaded (`'5m'`, seconds, `0` unloads, below 0 keeps) |
47
+ | `decisionModels` | Decision models, for servers whose `/api/show` lists no capabilities |
48
+ | `fetch` | The `fetch` every call goes through |
49
+
50
+ See the [Ollama provider docs](https://github.com/ClickerMonkey/aeye/tree/main/packages/docs/providers/ollama.md) and the [decisions guide](https://github.com/ClickerMonkey/aeye/tree/main/packages/docs/guides/decisions.md).
51
+
52
+ ## License
53
+
54
+ GPL-3.0
package/aeye-ollama.md CHANGED
@@ -1,93 +1,93 @@
1
- # @aeye/ollama
2
-
3
- One-line purpose: Ollama provider for `@aeye/ai` — local (or cloud) Ollama models for chat, embeddings and System One decisions, with the model list, capabilities and the context window each model is really served with read from Ollama's native API. Built as a subclass of `@aeye/openai`'s `OpenAIProvider`.
4
-
5
- ## When to use
6
-
7
- - You run models on a local Ollama (or Ollama's cloud) and want them in the same `AI` instance as other providers.
8
- - You want fast typed decisions (`ai.decide`) from an Ollama System One model (`/v1/systemone`, Ollama v0.35+), optionally over images.
9
- - You need honest context windows: Ollama silently cuts the front of a prompt longer than the window it serves (`num_ctx`), whatever the model was trained to.
10
-
11
- ## Install / import
12
-
13
- ```bash
14
- npm install @aeye/ollama
15
- ```
16
-
17
- `@aeye/openai`, `@aeye/ai`, `@aeye/core`, and `openai` (v7) ship as dependencies. Requires Node >= 22.
18
-
19
- ```typescript
20
- import {
21
- OllamaProvider,
22
- type OllamaConfig,
23
- type OllamaOptions,
24
- OLLAMA_SYSTEM_ONE_LIMITS,
25
- capabilitiesOf,
26
- // native API and served-window helpers
27
- OllamaApi,
28
- type OllamaShow,
29
- type OllamaTags,
30
- OLLAMA_BASE_URL,
31
- numCtxOf,
32
- trainedLengthOf,
33
- servedDefault,
34
- unsetWindow,
35
- servedWindow,
36
- takesTools,
37
- reasons,
38
- } from '@aeye/ollama';
39
- ```
40
-
41
- The provider's registry name is `ollama`.
42
-
43
- ## Register with an `@aeye/ai` instance
44
-
45
- ```typescript
46
- import { AI } from '@aeye/ai';
47
- import { OllamaProvider } from '@aeye/ollama';
48
-
49
- const ollama = new OllamaProvider({ keepAlive: '10m' });
50
- const ai = AI.with().providers({ ollama }).create();
51
- await ai.models.refresh(); // lists the server's models
52
-
53
- await ai.chat.get([{ role: 'user', content: 'Hi' }], { metadata: { model: 'qwen2.5:3b' } });
54
-
55
- const { answers } = await ai.decide.get({
56
- input: 'The printer is on fire.',
57
- images: [photo], // optional, needs a `vision` decision model
58
- questions: { urgent: { type: 'predicate', instructions: 'Is this urgent?' } },
59
- }, { metadata: { model: 'nimble' } });
60
- ```
61
-
62
- ## Configuration (`OllamaConfig`)
63
-
64
- `OllamaConfig extends OpenAIConfig`; `apiKey` is optional (a local server takes none; a key is sent as a bearer token, for Ollama's cloud).
65
-
66
- | Option | Meaning |
67
- |--------|---------|
68
- | `baseURL` | Ollama's root, not `/v1` (default `http://127.0.0.1:11434`) |
69
- | `contextWindow` | The window the server serves models whose Modelfile sets no `num_ctx` (as `OLLAMA_CONTEXT_LENGTH` does) |
70
- | `maxContextWindow` | The most window assumed when `contextWindow` is unset |
71
- | `keepAlive` | Sent as `keep_alive` on decisions: a duration (`'5m'`) or seconds (`0` unloads, below 0 keeps loaded) |
72
- | `decisionModels` | Decision models, for servers whose `/api/show` lists no capabilities |
73
- | `fetch` | The `fetch` every call goes through (native API and `/v1`) |
74
-
75
- ## Models and capabilities
76
-
77
- `listModels()` reads `/api/tags`, then `/api/show` per model and `/api/version`:
78
-
79
- - Capabilities come from `/api/show`'s `capabilities` when listed: `completion` → `chat`, `streaming`, `json`; plus `embedding` (text only: Ollama's embed endpoints take no images, so no model gets `imageEmbedding` and an image input throws `ImageEmbeddingError`), `decision`, `vision`; `tools` and `reasoning` for chat models. A server that lists none: a model named in `decisionModels` (with or without `:latest`) is a decision model, every other one a chat model (tools from the template, reasoning from the template or name).
80
- - `contextWindow` is the served window: the Modelfile's `num_ctx`, else `contextWindow`, else Ollama's default for the server's version (2048 before 0.6, 4096 after) held to `maxContextWindow`, never above the trained length.
81
- - Pricing is zero; tier is `efficient`.
82
- - Decision models carry `OLLAMA_SYSTEM_ONE_LIMITS`: `maxQuestions: 64` and `maxRequestBytes: 65536`.
83
-
84
- ## Decisions (`/v1/systemone`)
85
-
86
- `decide()` sends System One's shape (shared with OpenRouter, from `@aeye/openai`'s `toSystemOneParams`): `state` (text, or the conversation as chat messages with `system` roles), `questions` (`noul` / `choice` / `score`), `images` as plain base64, and `keep_alive` from `keepAlive`. The request's `extra` overrides any of them. Answers are parsed with `fromSystemOneAnswers`: score probabilities come back keyed by level index and are put in level order.
87
-
88
- ## Gotchas
89
-
90
- - **No splitting.** A decision call over `maxQuestions` (64) or `maxRequestBytes` (64 KiB of state and questions; images don't count) is refused with `DecisionLimitError` before anything is sent. The caller splits its questions by `model.maxQuestions`.
91
- - System messages go to Ollama as `system`, not OpenAI's `developer` role, which Ollama's chat templates drop without a word.
92
- - Ollama's OpenAI-compatible endpoint takes no `num_ctx`: set it in the Modelfile or with `OLLAMA_CONTEXT_LENGTH` on the server, and tell the provider with `contextWindow`.
93
- - No model is assumed: there are no default models; pass `metadata.model` or let selection pick from the listed ones.
1
+ # @aeye/ollama
2
+
3
+ One-line purpose: Ollama provider for `@aeye/ai` — local (or cloud) Ollama models for chat, embeddings and System One decisions, with the model list, capabilities and the context window each model is really served with read from Ollama's native API. Built as a subclass of `@aeye/openai`'s `OpenAIProvider`.
4
+
5
+ ## When to use
6
+
7
+ - You run models on a local Ollama (or Ollama's cloud) and want them in the same `AI` instance as other providers.
8
+ - You want fast typed decisions (`ai.decide`) from an Ollama System One model (`/v1/systemone`, Ollama v0.35+), optionally over images.
9
+ - You need honest context windows: Ollama silently cuts the front of a prompt longer than the window it serves (`num_ctx`), whatever the model was trained to.
10
+
11
+ ## Install / import
12
+
13
+ ```bash
14
+ npm install @aeye/ollama
15
+ ```
16
+
17
+ `@aeye/openai`, `@aeye/ai`, `@aeye/core`, and `openai` (v7) ship as dependencies. Requires Node >= 22.
18
+
19
+ ```typescript
20
+ import {
21
+ OllamaProvider,
22
+ type OllamaConfig,
23
+ type OllamaOptions,
24
+ OLLAMA_SYSTEM_ONE_LIMITS,
25
+ capabilitiesOf,
26
+ // native API and served-window helpers
27
+ OllamaApi,
28
+ type OllamaShow,
29
+ type OllamaTags,
30
+ OLLAMA_BASE_URL,
31
+ numCtxOf,
32
+ trainedLengthOf,
33
+ servedDefault,
34
+ unsetWindow,
35
+ servedWindow,
36
+ takesTools,
37
+ reasons,
38
+ } from '@aeye/ollama';
39
+ ```
40
+
41
+ The provider's registry name is `ollama`.
42
+
43
+ ## Register with an `@aeye/ai` instance
44
+
45
+ ```typescript
46
+ import { AI } from '@aeye/ai';
47
+ import { OllamaProvider } from '@aeye/ollama';
48
+
49
+ const ollama = new OllamaProvider({ keepAlive: '10m' });
50
+ const ai = AI.with().providers({ ollama }).create();
51
+ await ai.models.refresh(); // lists the server's models
52
+
53
+ await ai.chat.get([{ role: 'user', content: 'Hi' }], { metadata: { model: 'qwen2.5:3b' } });
54
+
55
+ const { answers } = await ai.decide.get({
56
+ input: 'The printer is on fire.',
57
+ images: [photo], // optional, needs a `vision` decision model
58
+ questions: { urgent: { type: 'predicate', instructions: 'Is this urgent?' } },
59
+ }, { metadata: { model: 'nimble' } });
60
+ ```
61
+
62
+ ## Configuration (`OllamaConfig`)
63
+
64
+ `OllamaConfig extends OpenAIConfig`; `apiKey` is optional (a local server takes none; a key is sent as a bearer token, for Ollama's cloud).
65
+
66
+ | Option | Meaning |
67
+ |--------|---------|
68
+ | `baseURL` | Ollama's root, not `/v1` (default `http://127.0.0.1:11434`) |
69
+ | `contextWindow` | The window the server serves models whose Modelfile sets no `num_ctx` (as `OLLAMA_CONTEXT_LENGTH` does) |
70
+ | `maxContextWindow` | The most window assumed when `contextWindow` is unset |
71
+ | `keepAlive` | Sent as `keep_alive` on decisions: a duration (`'5m'`) or seconds (`0` unloads, below 0 keeps loaded) |
72
+ | `decisionModels` | Decision models, for servers whose `/api/show` lists no capabilities |
73
+ | `fetch` | The `fetch` every call goes through (native API and `/v1`) |
74
+
75
+ ## Models and capabilities
76
+
77
+ `listModels()` reads `/api/tags`, then `/api/show` per model and `/api/version`:
78
+
79
+ - Capabilities come from `/api/show`'s `capabilities` when listed: `completion` → `chat`, `streaming`, `json`; plus `embedding` (text only: Ollama's embed endpoints take no images, so no model gets `imageEmbedding` and an image input throws `ImageEmbeddingError`), `decision`, `vision`; `tools` and `reasoning` for chat models. A server that lists none: a model named in `decisionModels` (with or without `:latest`) is a decision model, every other one a chat model (tools from the template, reasoning from the template or name).
80
+ - `contextWindow` is the served window: the Modelfile's `num_ctx`, else `contextWindow`, else Ollama's default for the server's version (2048 before 0.6, 4096 after) held to `maxContextWindow`, never above the trained length.
81
+ - Pricing is zero; tier is `efficient`.
82
+ - Decision models carry `OLLAMA_SYSTEM_ONE_LIMITS`: `maxQuestions: 64` and `maxRequestBytes: 65536`.
83
+
84
+ ## Decisions (`/v1/systemone`)
85
+
86
+ `decide()` sends System One's shape (shared with OpenRouter, from `@aeye/openai`'s `toSystemOneParams`): `state` (text, or the conversation as chat messages with `system` roles), `questions` (`noul` / `choice` / `score`), `images` as plain base64, and `keep_alive` from `keepAlive`. The request's `extra` overrides any of them. Answers are parsed with `fromSystemOneAnswers`: score probabilities come back keyed by level index and are put in level order.
87
+
88
+ ## Gotchas
89
+
90
+ - **No splitting.** A decision call over `maxQuestions` (64) or `maxRequestBytes` (64 KiB of state and questions; images don't count) is refused with `DecisionLimitError` before anything is sent. The caller splits its questions by `model.maxQuestions`.
91
+ - System messages go to Ollama as `system`, not OpenAI's `developer` role, which Ollama's chat templates drop without a word.
92
+ - Ollama's OpenAI-compatible endpoint takes no `num_ctx`: set it in the Modelfile or with `OLLAMA_CONTEXT_LENGTH` on the server, and tell the provider with `contextWindow`.
93
+ - No model is assumed: there are no default models; pass `metadata.model` or let selection pick from the listed ones.
package/package.json CHANGED
@@ -1,72 +1,72 @@
1
- {
2
- "name": "@aeye/ollama",
3
- "version": "0.8.0",
4
- "description": "@aeye Ollama - local and cloud Ollama models for @aeye: chat, embeddings, and System One decisions",
5
- "type": "module",
6
- "main": "dist/index.js",
7
- "types": "dist/index.d.ts",
8
- "exports": {
9
- ".": {
10
- "import": {
11
- "types": "./dist/index.d.ts",
12
- "default": "./dist/index.js"
13
- },
14
- "require": {
15
- "types": "./dist/index.d.ts",
16
- "default": "./dist/index.js"
17
- },
18
- "default": "./dist/index.js"
19
- }
20
- },
21
- "scripts": {
22
- "build": "tsc",
23
- "test": "jest",
24
- "test:unit": "jest --testPathIgnorePatterns=__integration__",
25
- "test:integration": "jest --testPathPattern=__integration__",
26
- "test:coverage": "jest --coverage --testPathIgnorePatterns=__integration__",
27
- "test:watch": "jest --watch",
28
- "clean": "rimraf dist tsconfig.tsbuildinfo",
29
- "typecheck": "tsc --noEmit"
30
- },
31
- "keywords": [
32
- "ai",
33
- "ollama",
34
- "typescript",
35
- "local-llm"
36
- ],
37
- "author": "ClickerMonkey",
38
- "license": "GPL-3.0",
39
- "repository": {
40
- "type": "git",
41
- "url": "https://github.com/ClickerMonkey/aeye.git",
42
- "directory": "packages/ollama"
43
- },
44
- "files": [
45
- "dist",
46
- "README.md",
47
- "LICENSE",
48
- "aeye-*.md"
49
- ],
50
- "dependencies": {
51
- "@aeye/ai": "^0.8.0",
52
- "@aeye/core": "^0.8.0",
53
- "@aeye/openai": "^0.8.0",
54
- "openai": "^7.45.1"
55
- },
56
- "devDependencies": {
57
- "@types/jest": "^30.0.0",
58
- "jest": "^30.2.0",
59
- "ts-jest": "^29.4.5",
60
- "typescript": "^5.9.3"
61
- },
62
- "publishConfig": {
63
- "access": "public"
64
- },
65
- "engines": {
66
- "node": ">=22.0.0"
67
- },
68
- "homepage": "https://github.com/ClickerMonkey/aeye#readme",
69
- "bugs": {
70
- "url": "https://github.com/ClickerMonkey/aeye/issues"
71
- }
72
- }
1
+ {
2
+ "name": "@aeye/ollama",
3
+ "version": "0.8.1",
4
+ "description": "@aeye Ollama - local and cloud Ollama models for @aeye: chat, embeddings, and System One decisions",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "import": {
11
+ "types": "./dist/index.d.ts",
12
+ "default": "./dist/index.js"
13
+ },
14
+ "require": {
15
+ "types": "./dist/index.d.ts",
16
+ "default": "./dist/index.js"
17
+ },
18
+ "default": "./dist/index.js"
19
+ }
20
+ },
21
+ "scripts": {
22
+ "build": "tsc",
23
+ "test": "jest",
24
+ "test:unit": "jest --testPathIgnorePatterns=__integration__",
25
+ "test:integration": "jest --testPathPattern=__integration__",
26
+ "test:coverage": "jest --coverage --testPathIgnorePatterns=__integration__",
27
+ "test:watch": "jest --watch",
28
+ "clean": "rimraf dist tsconfig.tsbuildinfo",
29
+ "typecheck": "tsc --noEmit"
30
+ },
31
+ "keywords": [
32
+ "ai",
33
+ "ollama",
34
+ "typescript",
35
+ "local-llm"
36
+ ],
37
+ "author": "ClickerMonkey",
38
+ "license": "GPL-3.0",
39
+ "repository": {
40
+ "type": "git",
41
+ "url": "https://github.com/ClickerMonkey/aeye.git",
42
+ "directory": "packages/ollama"
43
+ },
44
+ "files": [
45
+ "dist",
46
+ "README.md",
47
+ "LICENSE",
48
+ "aeye-*.md"
49
+ ],
50
+ "dependencies": {
51
+ "@aeye/ai": "^0.8.1",
52
+ "@aeye/core": "^0.8.1",
53
+ "@aeye/openai": "^0.8.1",
54
+ "openai": "^7.45.1"
55
+ },
56
+ "devDependencies": {
57
+ "@types/jest": "^30.0.0",
58
+ "jest": "^30.2.0",
59
+ "ts-jest": "^29.4.5",
60
+ "typescript": "^5.9.3"
61
+ },
62
+ "publishConfig": {
63
+ "access": "public"
64
+ },
65
+ "engines": {
66
+ "node": ">=22.0.0"
67
+ },
68
+ "homepage": "https://github.com/ClickerMonkey/aeye#readme",
69
+ "bugs": {
70
+ "url": "https://github.com/ClickerMonkey/aeye/issues"
71
+ }
72
+ }