@fgv/ts-extras-ollama 5.1.0-34
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/.rush/temp/b70e5f6b6ada97ea70c5583027ea2b58b27bef46.tar.log +54 -0
- package/.rush/temp/chunked-rush-logs/ts-extras-ollama.build.chunks.jsonl +9 -0
- package/.rush/temp/operation/build/all.log +9 -0
- package/.rush/temp/operation/build/log-chunks.jsonl +9 -0
- package/.rush/temp/operation/build/state.json +3 -0
- package/.rush/temp/shrinkwrap-deps.json +681 -0
- package/CHANGELOG.json +4 -0
- package/README.md +105 -0
- package/config/api-extractor.json +38 -0
- package/config/jest.config.json +13 -0
- package/config/rig.json +6 -0
- package/dist/index.js +388 -0
- package/dist/index.js.map +1 -0
- package/dist/test/unit/chatStructured.test.js +287 -0
- package/dist/test/unit/chatStructured.test.js.map +1 -0
- package/dist/test/unit/fixtures/wireFixtures.js +90 -0
- package/dist/test/unit/fixtures/wireFixtures.js.map +1 -0
- package/dist/test/unit/modelManagement.test.js +118 -0
- package/dist/test/unit/modelManagement.test.js.map +1 -0
- package/dist/test/unit/ollamaClient.test.js +38 -0
- package/dist/test/unit/ollamaClient.test.js.map +1 -0
- package/dist/test/unit/pullModel.test.js +202 -0
- package/dist/test/unit/pullModel.test.js.map +1 -0
- package/dist/ts-extras-ollama.d.ts +365 -0
- package/dist/tsdoc-metadata.json +11 -0
- package/eslint.config.js +15 -0
- package/etc/ts-extras-ollama.api.md +139 -0
- package/lib/index.d.ts +341 -0
- package/lib/index.d.ts.map +1 -0
- package/lib/index.js +397 -0
- package/lib/index.js.map +1 -0
- package/lib/test/unit/chatStructured.test.d.ts +2 -0
- package/lib/test/unit/chatStructured.test.d.ts.map +1 -0
- package/lib/test/unit/chatStructured.test.js +289 -0
- package/lib/test/unit/chatStructured.test.js.map +1 -0
- package/lib/test/unit/fixtures/wireFixtures.d.ts +19 -0
- package/lib/test/unit/fixtures/wireFixtures.d.ts.map +1 -0
- package/lib/test/unit/fixtures/wireFixtures.js +93 -0
- package/lib/test/unit/fixtures/wireFixtures.js.map +1 -0
- package/lib/test/unit/modelManagement.test.d.ts +2 -0
- package/lib/test/unit/modelManagement.test.d.ts.map +1 -0
- package/lib/test/unit/modelManagement.test.js +120 -0
- package/lib/test/unit/modelManagement.test.js.map +1 -0
- package/lib/test/unit/ollamaClient.test.d.ts +2 -0
- package/lib/test/unit/ollamaClient.test.d.ts.map +1 -0
- package/lib/test/unit/ollamaClient.test.js +40 -0
- package/lib/test/unit/ollamaClient.test.js.map +1 -0
- package/lib/test/unit/pullModel.test.d.ts +2 -0
- package/lib/test/unit/pullModel.test.d.ts.map +1 -0
- package/lib/test/unit/pullModel.test.js +204 -0
- package/lib/test/unit/pullModel.test.js.map +1 -0
- package/package.json +83 -0
- package/rush-logs/ts-extras-ollama.build.cache.log +3 -0
- package/rush-logs/ts-extras-ollama.build.log +9 -0
- package/src/index.ts +655 -0
- package/src/test/unit/chatStructured.test.ts +330 -0
- package/src/test/unit/fixtures/wireFixtures.ts +95 -0
- package/src/test/unit/modelManagement.test.ts +128 -0
- package/src/test/unit/ollamaClient.test.ts +44 -0
- package/src/test/unit/pullModel.test.ts +220 -0
- package/temp/build/lint/_eslint-5eVG3S6w.json +30 -0
- package/temp/build/typescript/ts_8nwakTlr.json +1 -0
- package/temp/ts-extras-ollama.api.json +2528 -0
- package/temp/ts-extras-ollama.api.md +139 -0
- package/tsconfig.json +8 -0
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
## API Report File for "@fgv/ts-extras-ollama"
|
|
2
|
+
|
|
3
|
+
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
|
|
7
|
+
import { JsonSchema } from '@fgv/ts-json-base';
|
|
8
|
+
import { JsonValue } from '@fgv/ts-json-base';
|
|
9
|
+
import { Ollama } from 'ollama';
|
|
10
|
+
import { Result } from '@fgv/ts-utils';
|
|
11
|
+
|
|
12
|
+
// @public
|
|
13
|
+
export function chatStructured<T>(client: IOllamaClient, params: IChatStructuredParams<T>): Promise<Result<IOllamaChatStructuredResult<T>>>;
|
|
14
|
+
|
|
15
|
+
// @public
|
|
16
|
+
export function createOllamaClient(params?: ICreateOllamaClientParams): Result<IOllamaClient>;
|
|
17
|
+
|
|
18
|
+
// @public
|
|
19
|
+
export function deleteModel(client: IOllamaClient, model: string): Promise<Result<IOllamaDeleteResult>>;
|
|
20
|
+
|
|
21
|
+
// @public
|
|
22
|
+
export interface IChatStructuredParams<T> {
|
|
23
|
+
readonly keepAlive?: string | number;
|
|
24
|
+
readonly messages: ReadonlyArray<IOllamaChatMessage>;
|
|
25
|
+
readonly model: string;
|
|
26
|
+
readonly options?: Readonly<Record<string, JsonValue>>;
|
|
27
|
+
readonly schema: JsonSchema.ISchemaValidator<T>;
|
|
28
|
+
readonly signal?: AbortSignal;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
// @public
|
|
32
|
+
export interface ICreateOllamaClientParams {
|
|
33
|
+
readonly fetch?: typeof fetch;
|
|
34
|
+
readonly headers?: Record<string, string>;
|
|
35
|
+
readonly host?: string;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// @public
|
|
39
|
+
export interface IOllamaChatMessage {
|
|
40
|
+
readonly content: string;
|
|
41
|
+
readonly images?: ReadonlyArray<string>;
|
|
42
|
+
readonly role: 'system' | 'user' | 'assistant' | 'tool';
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
// @public
|
|
46
|
+
export interface IOllamaChatStructuredResult<T> {
|
|
47
|
+
readonly doneReason?: string;
|
|
48
|
+
readonly model: string;
|
|
49
|
+
readonly raw: string;
|
|
50
|
+
readonly value: T;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// @public
|
|
54
|
+
export type IOllamaClient = Ollama;
|
|
55
|
+
|
|
56
|
+
// @public
|
|
57
|
+
export interface IOllamaDeleteResult {
|
|
58
|
+
readonly deleted: true;
|
|
59
|
+
readonly model: string;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// @public
|
|
63
|
+
export interface IOllamaModel extends IOllamaModelBase {
|
|
64
|
+
readonly modifiedAt: Date;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
// @public
|
|
68
|
+
export interface IOllamaModelBase {
|
|
69
|
+
readonly details: IOllamaModelDetail;
|
|
70
|
+
readonly digest: string;
|
|
71
|
+
readonly model: string;
|
|
72
|
+
readonly name: string;
|
|
73
|
+
readonly size: number;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
// @public
|
|
77
|
+
export interface IOllamaModelDetail {
|
|
78
|
+
readonly families?: ReadonlyArray<string>;
|
|
79
|
+
readonly family?: string;
|
|
80
|
+
readonly format?: string;
|
|
81
|
+
readonly parameterSize?: string;
|
|
82
|
+
readonly parentModel?: string;
|
|
83
|
+
readonly quantizationLevel?: string;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
// @public
|
|
87
|
+
export interface IOllamaModelInfo {
|
|
88
|
+
readonly capabilities?: ReadonlyArray<string>;
|
|
89
|
+
readonly details: IOllamaModelDetail;
|
|
90
|
+
readonly modelfile?: string;
|
|
91
|
+
readonly modelInfo?: Readonly<Record<string, JsonValue>>;
|
|
92
|
+
readonly parameters?: string;
|
|
93
|
+
readonly template?: string;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
// @public
|
|
97
|
+
export interface IOllamaPullProgress {
|
|
98
|
+
readonly completed?: number;
|
|
99
|
+
readonly digest?: string;
|
|
100
|
+
readonly status: string;
|
|
101
|
+
readonly total?: number;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// @public
|
|
105
|
+
export interface IOllamaPullResult {
|
|
106
|
+
readonly chunkCount: number;
|
|
107
|
+
readonly finalStatus: string;
|
|
108
|
+
readonly model: string;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
// @public
|
|
112
|
+
export interface IOllamaRunningModel extends IOllamaModelBase {
|
|
113
|
+
readonly expiresAt: Date;
|
|
114
|
+
readonly sizeVram: number;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
// @public
|
|
118
|
+
export interface IPullModelParams {
|
|
119
|
+
readonly insecure?: boolean;
|
|
120
|
+
readonly model: string;
|
|
121
|
+
readonly onProgress?: (progress: IOllamaPullProgress) => void;
|
|
122
|
+
readonly signal?: AbortSignal;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
// @public
|
|
126
|
+
export function listModels(client: IOllamaClient): Promise<Result<ReadonlyArray<IOllamaModel>>>;
|
|
127
|
+
|
|
128
|
+
// @public
|
|
129
|
+
export function listRunning(client: IOllamaClient): Promise<Result<ReadonlyArray<IOllamaRunningModel>>>;
|
|
130
|
+
|
|
131
|
+
// @public
|
|
132
|
+
export function pullModel(client: IOllamaClient, params: IPullModelParams): Promise<Result<IOllamaPullResult>>;
|
|
133
|
+
|
|
134
|
+
// @public
|
|
135
|
+
export function showModel(client: IOllamaClient, model: string, options?: {
|
|
136
|
+
readonly verbose?: boolean;
|
|
137
|
+
}): Promise<Result<IOllamaModelInfo>>;
|
|
138
|
+
|
|
139
|
+
```
|
package/lib/index.d.ts
ADDED
|
@@ -0,0 +1,341 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@fgv/ts-extras-ollama` — Result-integration boundary over the official `ollama` JS library
|
|
3
|
+
* (Node-side).
|
|
4
|
+
*
|
|
5
|
+
* A thin facade that wraps the `ollama` client's native-API calls in `Result<T>` from
|
|
6
|
+
* `@fgv/ts-utils`, mirroring the discipline established by `@fgv/ts-extras-webauthn` and
|
|
7
|
+
* `@fgv/ts-extras-transformers`: one-line `captureResult` / `captureAsyncResult` wrappers around
|
|
8
|
+
* upstream primitives with **no opinionated orchestration** above the boundary.
|
|
9
|
+
*
|
|
10
|
+
* This package owns **exactly and only** the native-Ollama surface that the OpenAI-compatible
|
|
11
|
+
* `/v1` endpoint cannot express: model management (`/api/tags`, `/api/show`, `/api/ps`,
|
|
12
|
+
* `/api/delete`), streamed model pulls (`/api/pull`), and grammar-constrained structured output
|
|
13
|
+
* (`/api/chat` with a full-JSON-schema `format`). The text-completion / streaming / tool-use path
|
|
14
|
+
* is **not** duplicated here — `@fgv/ts-extras/ai-assist` owns it via the `/v1` compat layer
|
|
15
|
+
* (point a provider descriptor's `endpoint` at `http://localhost:11434/v1`).
|
|
16
|
+
*
|
|
17
|
+
* **Explicitly NOT in scope:**
|
|
18
|
+
* - Text completion / free-text chat / streaming chat (ai-assist owns it via `/v1`).
|
|
19
|
+
* - Browser / CORS path (Node-only at v0.1; a future `@fgv/ts-web-extras-ollama` is its home).
|
|
20
|
+
* - Model authoring / publishing (`push`, `create`, `copy`) — use the `ollama` lib directly.
|
|
21
|
+
* - `keep_alive` / model-lifecycle policy — pass-through only, no policy applied.
|
|
22
|
+
* - Pull-progress UI / rendering — `onProgress` hands raw chunks to the consumer.
|
|
23
|
+
* - Multi-host orchestration / connection pooling / retries / backoff — one client = one host.
|
|
24
|
+
*
|
|
25
|
+
* For any of the above, use the `ollama` library directly (with `captureAsyncResult` for your own
|
|
26
|
+
* Result wrapping); the opaque client handle returned by {@link createOllamaClient} is the
|
|
27
|
+
* upstream instance, so nothing this boundary omits is hidden from you.
|
|
28
|
+
*
|
|
29
|
+
* @packageDocumentation
|
|
30
|
+
*/
|
|
31
|
+
import { Ollama } from 'ollama';
|
|
32
|
+
import { type Result } from '@fgv/ts-utils';
|
|
33
|
+
import { type JsonValue, type JsonSchema } from '@fgv/ts-json-base';
|
|
34
|
+
/**
|
|
35
|
+
* Construction parameters for an Ollama client. All optional; defaults match the `ollama` JS
|
|
36
|
+
* library (host `http://127.0.0.1:11434`).
|
|
37
|
+
* @public
|
|
38
|
+
*/
|
|
39
|
+
export interface ICreateOllamaClientParams {
|
|
40
|
+
/** Server address. Defaults to `http://127.0.0.1:11434`. */
|
|
41
|
+
readonly host?: string;
|
|
42
|
+
/**
|
|
43
|
+
* Custom `fetch` implementation. Injecting a fetch is the primary unit-test seam and the hook
|
|
44
|
+
* for a future proxy / browser path.
|
|
45
|
+
*/
|
|
46
|
+
readonly fetch?: typeof fetch;
|
|
47
|
+
/** Custom headers included on every request (e.g. an auth token for a guarded sidecar). */
|
|
48
|
+
readonly headers?: Record<string, string>;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Opaque client handle. Re-export of the upstream `ollama` `Ollama` instance type — consumers
|
|
52
|
+
* retain full access to the upstream API for anything this boundary does not wrap.
|
|
53
|
+
* @public
|
|
54
|
+
*/
|
|
55
|
+
export type IOllamaClient = Ollama;
|
|
56
|
+
/**
|
|
57
|
+
* Constructs an Ollama client. Synchronous (the constructor performs no I/O), so returns
|
|
58
|
+
* `Result<IOllamaClient>` rather than a promise. A malformed `host` (which the upstream
|
|
59
|
+
* constructor rejects) surfaces as `Result.fail`.
|
|
60
|
+
*
|
|
61
|
+
* @param params - Optional {@link ICreateOllamaClientParams}. Omitted fields fall back to the
|
|
62
|
+
* `ollama` library defaults.
|
|
63
|
+
* @returns `Result<IOllamaClient>` wrapping the upstream `Ollama` instance.
|
|
64
|
+
* @public
|
|
65
|
+
*/
|
|
66
|
+
export declare function createOllamaClient(params?: ICreateOllamaClientParams): Result<IOllamaClient>;
|
|
67
|
+
/**
|
|
68
|
+
* GGUF / model detail block, common to `/api/tags`, `/api/ps`, and `/api/show`. All fields
|
|
69
|
+
* optional — Ollama omits any it cannot determine.
|
|
70
|
+
* @public
|
|
71
|
+
*/
|
|
72
|
+
export interface IOllamaModelDetail {
|
|
73
|
+
/** Storage format, e.g. `'gguf'`. */
|
|
74
|
+
readonly format?: string;
|
|
75
|
+
/** Primary architecture family, e.g. `'llama'`. */
|
|
76
|
+
readonly family?: string;
|
|
77
|
+
/** All architecture families this model belongs to. */
|
|
78
|
+
readonly families?: ReadonlyArray<string>;
|
|
79
|
+
/** Human-readable parameter count, e.g. `'8.0B'`. */
|
|
80
|
+
readonly parameterSize?: string;
|
|
81
|
+
/** Quantization level, e.g. `'Q4_0'`. */
|
|
82
|
+
readonly quantizationLevel?: string;
|
|
83
|
+
/** Parent model for fine-tunes / derived models. */
|
|
84
|
+
readonly parentModel?: string;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Fields common to a locally-stored model and a running model.
|
|
88
|
+
* @public
|
|
89
|
+
*/
|
|
90
|
+
export interface IOllamaModelBase {
|
|
91
|
+
/** Tagged name, e.g. `'llama3.1:8b'`. */
|
|
92
|
+
readonly name: string;
|
|
93
|
+
/** Underlying model id (often equal to `name`). */
|
|
94
|
+
readonly model: string;
|
|
95
|
+
/** On-disk size in bytes. */
|
|
96
|
+
readonly size: number;
|
|
97
|
+
/** SHA-256 manifest digest. */
|
|
98
|
+
readonly digest: string;
|
|
99
|
+
/** GGUF / architecture detail. */
|
|
100
|
+
readonly details: IOllamaModelDetail;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* A model present in the local store (`/api/tags`).
|
|
104
|
+
* @public
|
|
105
|
+
*/
|
|
106
|
+
export interface IOllamaModel extends IOllamaModelBase {
|
|
107
|
+
/** Last-modified timestamp, parsed from the RFC3339 wire value. */
|
|
108
|
+
readonly modifiedAt: Date;
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* A model currently loaded into memory (`/api/ps`). Note `/api/ps` does NOT return
|
|
112
|
+
* `modified_at`, so this does not extend {@link IOllamaModel}.
|
|
113
|
+
* @public
|
|
114
|
+
*/
|
|
115
|
+
export interface IOllamaRunningModel extends IOllamaModelBase {
|
|
116
|
+
/** When the model will be unloaded, parsed from the RFC3339 wire value. */
|
|
117
|
+
readonly expiresAt: Date;
|
|
118
|
+
/** Bytes resident in VRAM (0 when fully on CPU). */
|
|
119
|
+
readonly sizeVram: number;
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Full model detail, capabilities, parameters, and template (`POST /api/show`).
|
|
123
|
+
* @public
|
|
124
|
+
*/
|
|
125
|
+
export interface IOllamaModelInfo {
|
|
126
|
+
/** The Modelfile source, when returned. */
|
|
127
|
+
readonly modelfile?: string;
|
|
128
|
+
/** Default parameters string. */
|
|
129
|
+
readonly parameters?: string;
|
|
130
|
+
/** The prompt template. */
|
|
131
|
+
readonly template?: string;
|
|
132
|
+
/** GGUF / architecture detail. */
|
|
133
|
+
readonly details: IOllamaModelDetail;
|
|
134
|
+
/** Low-level model metadata key-value map (`model_info`). */
|
|
135
|
+
readonly modelInfo?: Readonly<Record<string, JsonValue>>;
|
|
136
|
+
/** Declared capabilities, e.g. `['completion', 'tools', 'vision', 'thinking']`. */
|
|
137
|
+
readonly capabilities?: ReadonlyArray<string>;
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Result of a delete. Returns a meaningful value rather than `Result<void>` (per repo standards —
|
|
141
|
+
* `Result<void>` is an anti-pattern).
|
|
142
|
+
* @public
|
|
143
|
+
*/
|
|
144
|
+
export interface IOllamaDeleteResult {
|
|
145
|
+
/** The model that was deleted. */
|
|
146
|
+
readonly model: string;
|
|
147
|
+
/** Always `true` — a failed delete surfaces as `Result.fail`, never `deleted: false`. */
|
|
148
|
+
readonly deleted: true;
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* Lists models in the local store (`GET /api/tags`). Each entry is normalized to
|
|
152
|
+
* {@link IOllamaModel} (camelCase, `modifiedAt` as a `Date`).
|
|
153
|
+
*
|
|
154
|
+
* @param client - A client from {@link createOllamaClient}.
|
|
155
|
+
* @returns `Promise<Result<ReadonlyArray<IOllamaModel>>>`; upstream / transport errors are captured
|
|
156
|
+
* as `Failure`.
|
|
157
|
+
* @public
|
|
158
|
+
*/
|
|
159
|
+
export declare function listModels(client: IOllamaClient): Promise<Result<ReadonlyArray<IOllamaModel>>>;
|
|
160
|
+
/**
|
|
161
|
+
* Lists models currently loaded into memory (`GET /api/ps`). Each entry is normalized to
|
|
162
|
+
* {@link IOllamaRunningModel} (camelCase, `expiresAt` as a `Date`, `sizeVram` in bytes).
|
|
163
|
+
*
|
|
164
|
+
* @param client - A client from {@link createOllamaClient}.
|
|
165
|
+
* @returns `Promise<Result<ReadonlyArray<IOllamaRunningModel>>>`; upstream / transport errors are
|
|
166
|
+
* captured as `Failure`.
|
|
167
|
+
* @public
|
|
168
|
+
*/
|
|
169
|
+
export declare function listRunning(client: IOllamaClient): Promise<Result<ReadonlyArray<IOllamaRunningModel>>>;
|
|
170
|
+
/**
|
|
171
|
+
* Full model detail, capabilities, parameters, and template (`POST /api/show`), normalized to
|
|
172
|
+
* {@link IOllamaModelInfo}.
|
|
173
|
+
*
|
|
174
|
+
* @param client - A client from {@link createOllamaClient}.
|
|
175
|
+
* @param model - The model name to inspect, e.g. `'llama3.1:8b'`.
|
|
176
|
+
* @param options - Optional flags. `verbose: true` requests the full low-level `model_info` block.
|
|
177
|
+
* @returns `Promise<Result<IOllamaModelInfo>>`; upstream / transport errors (e.g. unknown model)
|
|
178
|
+
* are captured as `Failure`.
|
|
179
|
+
* @public
|
|
180
|
+
*/
|
|
181
|
+
export declare function showModel(client: IOllamaClient, model: string, options?: {
|
|
182
|
+
readonly verbose?: boolean;
|
|
183
|
+
}): Promise<Result<IOllamaModelInfo>>;
|
|
184
|
+
/**
|
|
185
|
+
* Deletes a model from the local store (`DELETE /api/delete`). Returns a meaningful
|
|
186
|
+
* {@link IOllamaDeleteResult} rather than `Result<void>`.
|
|
187
|
+
*
|
|
188
|
+
* @param client - A client from {@link createOllamaClient}.
|
|
189
|
+
* @param model - The model name to delete.
|
|
190
|
+
* @returns `Promise<Result<IOllamaDeleteResult>>`; a missing model or transport error surfaces as
|
|
191
|
+
* `Failure`.
|
|
192
|
+
* @public
|
|
193
|
+
*/
|
|
194
|
+
export declare function deleteModel(client: IOllamaClient, model: string): Promise<Result<IOllamaDeleteResult>>;
|
|
195
|
+
/**
|
|
196
|
+
* A single progress chunk from a streamed pull (`/api/pull`). Ollama emits a JSON-lines stream;
|
|
197
|
+
* each line is one of these. Fields map 1:1 from the upstream `ProgressResponse`; the layer fields
|
|
198
|
+
* (`digest`/`total`/`completed`) are `undefined` on the manifest / verify / write phases.
|
|
199
|
+
* @public
|
|
200
|
+
*/
|
|
201
|
+
export interface IOllamaPullProgress {
|
|
202
|
+
/**
|
|
203
|
+
* Phase string, e.g. `'pulling manifest'`, `'pulling <digest>'`, `'verifying sha256 digest'`,
|
|
204
|
+
* `'writing manifest'`, `'success'`.
|
|
205
|
+
*/
|
|
206
|
+
readonly status: string;
|
|
207
|
+
/** Layer digest being transferred (present during `'pulling <digest>'` phases). */
|
|
208
|
+
readonly digest?: string;
|
|
209
|
+
/** Total bytes for the current layer, when known. */
|
|
210
|
+
readonly total?: number;
|
|
211
|
+
/** Bytes transferred so far for the current layer, when known. */
|
|
212
|
+
readonly completed?: number;
|
|
213
|
+
}
|
|
214
|
+
/**
|
|
215
|
+
* Terminal result of a completed pull. Returns a meaningful value (not `Result<void>`): the final
|
|
216
|
+
* status plus a count of progress chunks observed.
|
|
217
|
+
* @public
|
|
218
|
+
*/
|
|
219
|
+
export interface IOllamaPullResult {
|
|
220
|
+
/** The model that was pulled. */
|
|
221
|
+
readonly model: string;
|
|
222
|
+
/** The `status` of the final chunk, normally `'success'`. */
|
|
223
|
+
readonly finalStatus: string;
|
|
224
|
+
/** Number of progress chunks observed (useful for tests and diagnostics). */
|
|
225
|
+
readonly chunkCount: number;
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* Parameters for {@link pullModel}.
|
|
229
|
+
* @public
|
|
230
|
+
*/
|
|
231
|
+
export interface IPullModelParams {
|
|
232
|
+
/** Model to pull, e.g. `'llama3.1:8b'`. */
|
|
233
|
+
readonly model: string;
|
|
234
|
+
/** Allow pulling from insecure (non-TLS) registries. */
|
|
235
|
+
readonly insecure?: boolean;
|
|
236
|
+
/**
|
|
237
|
+
* Progress callback, invoked once per JSON-lines chunk as it arrives. The `Result` returned by
|
|
238
|
+
* {@link pullModel} resolves only after the stream terminates; progress is surfaced here in the
|
|
239
|
+
* interim. A throw from this callback fails the whole pull (it runs inside the captured loop).
|
|
240
|
+
*/
|
|
241
|
+
readonly onProgress?: (progress: IOllamaPullProgress) => void;
|
|
242
|
+
/**
|
|
243
|
+
* Abort signal. Cancels the in-flight pull; the upstream stream throws an `AbortError`, which
|
|
244
|
+
* surfaces as `Result.fail`. An already-aborted signal cancels immediately.
|
|
245
|
+
*/
|
|
246
|
+
readonly signal?: AbortSignal;
|
|
247
|
+
}
|
|
248
|
+
/**
|
|
249
|
+
* Pulls a model with streamed progress (`POST /api/pull`). Drives the upstream JSON-lines stream
|
|
250
|
+
* internally, invoking `params.onProgress` once per chunk, and resolves the `Result` once the
|
|
251
|
+
* stream terminates. Any upstream error — connection drop, registry 404, abort, or a throwing
|
|
252
|
+
* `onProgress` — becomes a single `Failure`; success returns a meaningful {@link IOllamaPullResult}
|
|
253
|
+
* rather than `Result<void>`.
|
|
254
|
+
*
|
|
255
|
+
* @param client - A client from {@link createOllamaClient}.
|
|
256
|
+
* @param params - {@link IPullModelParams} — the model, optional `insecure` flag, optional
|
|
257
|
+
* `onProgress` callback, and optional `AbortSignal`.
|
|
258
|
+
* @returns `Promise<Result<IOllamaPullResult>>`.
|
|
259
|
+
* @public
|
|
260
|
+
*/
|
|
261
|
+
export declare function pullModel(client: IOllamaClient, params: IPullModelParams): Promise<Result<IOllamaPullResult>>;
|
|
262
|
+
/**
|
|
263
|
+
* A chat message in Ollama native shape.
|
|
264
|
+
* @public
|
|
265
|
+
*/
|
|
266
|
+
export interface IOllamaChatMessage {
|
|
267
|
+
/** The message role. */
|
|
268
|
+
readonly role: 'system' | 'user' | 'assistant' | 'tool';
|
|
269
|
+
/** The message text. */
|
|
270
|
+
readonly content: string;
|
|
271
|
+
/** Base64 image data for vision models (no `data:` prefix). */
|
|
272
|
+
readonly images?: ReadonlyArray<string>;
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* Result of a grammar-constrained structured chat. Carries both the validated typed value and the
|
|
276
|
+
* raw JSON text the model emitted, for diagnostics.
|
|
277
|
+
* @public
|
|
278
|
+
*/
|
|
279
|
+
export interface IOllamaChatStructuredResult<T> {
|
|
280
|
+
/** The parsed-and-validated value (validated by the same schema sent on the wire). */
|
|
281
|
+
readonly value: T;
|
|
282
|
+
/** The raw `message.content` JSON string the model emitted (assembled across stream chunks). */
|
|
283
|
+
readonly raw: string;
|
|
284
|
+
/** The model that produced the response. */
|
|
285
|
+
readonly model: string;
|
|
286
|
+
/** Provider-reported finish reason, when present. */
|
|
287
|
+
readonly doneReason?: string;
|
|
288
|
+
}
|
|
289
|
+
/**
|
|
290
|
+
* Parameters for {@link chatStructured}.
|
|
291
|
+
* @public
|
|
292
|
+
*/
|
|
293
|
+
export interface IChatStructuredParams<T> {
|
|
294
|
+
/** The model to chat with, e.g. `'llama3.1:8b'`. */
|
|
295
|
+
readonly model: string;
|
|
296
|
+
/** The conversation so far. */
|
|
297
|
+
readonly messages: ReadonlyArray<IOllamaChatMessage>;
|
|
298
|
+
/**
|
|
299
|
+
* The single source of truth for both the wire schema (`schema.toJson()`, sent as the native
|
|
300
|
+
* `format` field) and the result validator (`schema.validate()`). Author with
|
|
301
|
+
* `JsonSchema.object(...)` from `@fgv/ts-json-base`; `T` is derived via
|
|
302
|
+
* `JsonSchema.Static<typeof schema>`. A runtime-discovered (MCP) schema parsed via
|
|
303
|
+
* `JsonSchema.fromJson(raw)` also works — its `T` is `JsonValue`.
|
|
304
|
+
*/
|
|
305
|
+
readonly schema: JsonSchema.ISchemaValidator<T>;
|
|
306
|
+
/** Native Ollama `options` (temperature, num_ctx, seed, …). Passed verbatim. */
|
|
307
|
+
readonly options?: Readonly<Record<string, JsonValue>>;
|
|
308
|
+
/** Native `keep_alive` (duration string or seconds). Passed verbatim — no policy applied. */
|
|
309
|
+
readonly keepAlive?: string | number;
|
|
310
|
+
/**
|
|
311
|
+
* Abort signal. Cancels the in-flight generation; the upstream stream throws an `AbortError`,
|
|
312
|
+
* which surfaces as `Result.fail`. An already-aborted signal cancels immediately.
|
|
313
|
+
*/
|
|
314
|
+
readonly signal?: AbortSignal;
|
|
315
|
+
}
|
|
316
|
+
/**
|
|
317
|
+
* Single-turn grammar-constrained structured chat (`POST /api/chat` with `format` = full JSON
|
|
318
|
+
* schema). The fidelity win over ai-assist's prompt-and-parse path is **grammar-constrained
|
|
319
|
+
* sampling**: Ollama restricts the token sampler to the supplied schema, so the response is
|
|
320
|
+
* structurally guaranteed to match.
|
|
321
|
+
*
|
|
322
|
+
* The schema is the single source of truth: `schema.toJson()` (draft-07-sanitized) is sent as the
|
|
323
|
+
* wire `format`, and the same `schema.validate()` checks the reply — they cannot drift. `T` flows
|
|
324
|
+
* end-to-end from `JsonSchema.Static<typeof schema>`; no caller-supplied `T`, no cast.
|
|
325
|
+
*
|
|
326
|
+
* Runs over the streaming chat path internally, assembling the full document from the stream
|
|
327
|
+
* chunks and validating it whole — partial JSON has no validation value. (The design §4 sketch
|
|
328
|
+
* said `stream: false`, but the locked OQ-3 amendment requires an `AbortSignal`, and the `ollama`
|
|
329
|
+
* lib only threads a signal on the streaming path — its non-streaming request has no signal
|
|
330
|
+
* plumbing. The streaming `AbortableAsyncIterator.abort()` is "the mechanism that already exists
|
|
331
|
+
* for `pullModel`".) Any upstream error, abort, parse failure, or validation failure surfaces as a
|
|
332
|
+
* single `Failure` with context.
|
|
333
|
+
*
|
|
334
|
+
* @param client - A client from {@link createOllamaClient}.
|
|
335
|
+
* @param params - {@link IChatStructuredParams} — model, messages, the `JsonSchema` schema, and
|
|
336
|
+
* optional `options` / `keepAlive` / `signal`.
|
|
337
|
+
* @returns `Promise<Result<IOllamaChatStructuredResult<T>>>`.
|
|
338
|
+
* @public
|
|
339
|
+
*/
|
|
340
|
+
export declare function chatStructured<T>(client: IOllamaClient, params: IChatStructuredParams<T>): Promise<Result<IOllamaChatStructuredResult<T>>>;
|
|
341
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|