llmspy 0.0.0-stage → 0.4.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.
@@ -0,0 +1,197 @@
1
+ import { toLlmError } from './error.js';
2
+ import { asArray, asNumber, asRecord, asString, isRecord, parseJsonOrKeep, } from './json.js';
3
+ // Anthropic Messages API: POST /v1/messages.
4
+ /** A tool result's content as text; non-text blocks become `[type]`. */
5
+ function toolResultText(content) {
6
+ if (typeof content === 'string')
7
+ return content;
8
+ return asArray(content)
9
+ .map((block) => {
10
+ const b = asRecord(block);
11
+ return b.type === 'text'
12
+ ? (asString(b.text) ?? '')
13
+ : `[${asString(b.type) ?? 'block'}]`;
14
+ })
15
+ .join('\n');
16
+ }
17
+ function toPart(block) {
18
+ const b = asRecord(block);
19
+ switch (b.type) {
20
+ case 'text':
21
+ return { type: 'text', text: asString(b.text) ?? '' };
22
+ case 'thinking':
23
+ return { type: 'thinking', text: asString(b.thinking) ?? '' };
24
+ case 'tool_use':
25
+ return {
26
+ type: 'tool_call',
27
+ id: asString(b.id) ?? '',
28
+ name: asString(b.name) ?? '',
29
+ input: b.input,
30
+ };
31
+ case 'tool_result': {
32
+ const part = {
33
+ type: 'tool_result',
34
+ id: asString(b.tool_use_id) ?? '',
35
+ content: toolResultText(b.content),
36
+ };
37
+ if (b.is_error === true)
38
+ part.isError = true;
39
+ return part;
40
+ }
41
+ case 'image':
42
+ return { type: 'image' };
43
+ default:
44
+ return { type: 'other', raw: block };
45
+ }
46
+ }
47
+ /** Message content is a string or an array of blocks. */
48
+ function toParts(content) {
49
+ if (typeof content === 'string')
50
+ return [{ type: 'text', text: content }];
51
+ return asArray(content).map(toPart);
52
+ }
53
+ function toMessage(message) {
54
+ const m = asRecord(message);
55
+ return {
56
+ role: m.role === 'assistant' ? 'assistant' : 'user',
57
+ parts: toParts(m.content),
58
+ };
59
+ }
60
+ /** `system` is a string or an array of text blocks. */
61
+ function systemText(system) {
62
+ if (typeof system === 'string')
63
+ return system;
64
+ const texts = asArray(system)
65
+ .map((block) => asString(asRecord(block).text))
66
+ .filter((text) => text !== undefined);
67
+ return texts.length > 0 ? texts.join('\n\n') : undefined;
68
+ }
69
+ function toUsage(usage) {
70
+ if (!isRecord(usage))
71
+ return undefined;
72
+ return {
73
+ input: asNumber(usage.input_tokens),
74
+ output: asNumber(usage.output_tokens),
75
+ cacheRead: asNumber(usage.cache_read_input_tokens),
76
+ cacheWrite: asNumber(usage.cache_creation_input_tokens),
77
+ };
78
+ }
79
+ function parseRequest(body) {
80
+ const b = asRecord(body);
81
+ const tools = asArray(b.tools).map((tool) => {
82
+ const t = asRecord(tool);
83
+ return {
84
+ name: asString(t.name) ?? '',
85
+ description: asString(t.description),
86
+ };
87
+ });
88
+ return {
89
+ model: asString(b.model),
90
+ stream: b.stream === true,
91
+ system: systemText(b.system),
92
+ messages: asArray(b.messages).map(toMessage),
93
+ tools: tools.length > 0 ? tools : undefined,
94
+ };
95
+ }
96
+ function parseResponse(body) {
97
+ const b = asRecord(body);
98
+ return {
99
+ model: asString(b.model),
100
+ output: { role: 'assistant', parts: toParts(b.content) },
101
+ stopReason: asString(b.stop_reason),
102
+ usage: toUsage(b.usage),
103
+ };
104
+ }
105
+ /** Adds a delta to its block: text and thinking to the block, tool input JSON to the side. */
106
+ function addDelta(state, event) {
107
+ const index = asNumber(event.index);
108
+ if (index === undefined || !state.blocks[index])
109
+ return;
110
+ const block = state.blocks[index];
111
+ const delta = asRecord(event.delta);
112
+ const piece = (field) => asString(delta[field]) ?? '';
113
+ switch (delta.type) {
114
+ case 'text_delta':
115
+ block.text = (asString(block.text) ?? '') + piece('text');
116
+ break;
117
+ case 'thinking_delta':
118
+ block.thinking =
119
+ (asString(block.thinking) ?? '') + piece('thinking');
120
+ break;
121
+ case 'input_json_delta':
122
+ state.toolInputs[index] =
123
+ (state.toolInputs[index] ?? '') + piece('partial_json');
124
+ break;
125
+ }
126
+ }
127
+ /** Stream events, and what each one changes. Other events are ignored. */
128
+ const EVENTS = {
129
+ message_start: (state, event) => {
130
+ state.started = true;
131
+ const message = asRecord(event.message);
132
+ state.model = asString(message.model);
133
+ Object.assign(state.usage, numbersOnly(message.usage));
134
+ },
135
+ content_block_start: (state, event) => {
136
+ const index = asNumber(event.index);
137
+ if (index !== undefined) {
138
+ state.blocks[index] = { ...asRecord(event.content_block) };
139
+ }
140
+ },
141
+ content_block_delta: addDelta,
142
+ message_delta: (state, event) => {
143
+ state.stopReason =
144
+ asString(asRecord(event.delta).stop_reason) ?? state.stopReason;
145
+ Object.assign(state.usage, numbersOnly(event.usage));
146
+ },
147
+ error: (state, event) => {
148
+ state.error = toLlmError(event.error) ?? { message: '' };
149
+ },
150
+ };
151
+ /**
152
+ * Rebuilds the content blocks from `content_block_start` and the deltas that
153
+ * follow, then reads them as a normal response. Usage starts from
154
+ * `message_start` and is updated by `message_delta`. An `error` event ends
155
+ * the reply part-way; what came before it is kept.
156
+ */
157
+ function parseStream(events) {
158
+ const state = {
159
+ started: false,
160
+ usage: {},
161
+ blocks: [],
162
+ toolInputs: [],
163
+ };
164
+ for (const raw of events) {
165
+ const event = asRecord(raw);
166
+ const type = asString(event.type) ?? '';
167
+ if (Object.hasOwn(EVENTS, type))
168
+ EVENTS[type]?.(state, event);
169
+ }
170
+ const { started, model, stopReason, error, usage, blocks } = state;
171
+ if (!started)
172
+ return error ? { error } : {};
173
+ state.toolInputs.forEach((json, index) => {
174
+ const block = blocks[index];
175
+ if (block && json !== '')
176
+ block.input = parseJsonOrKeep(json);
177
+ });
178
+ return {
179
+ model,
180
+ output: {
181
+ role: 'assistant',
182
+ parts: blocks.filter(Boolean).map(toPart),
183
+ },
184
+ stopReason,
185
+ usage: toUsage(usage),
186
+ ...(error && { error }),
187
+ };
188
+ }
189
+ /** The numeric fields of an object, so a later `null` never hides an earlier count. */
190
+ function numbersOnly(value) {
191
+ return Object.fromEntries(Object.entries(asRecord(value)).filter(([, field]) => asNumber(field) !== undefined));
192
+ }
193
+ export const anthropicMessages = {
194
+ parseRequest,
195
+ parseResponse,
196
+ parseStream,
197
+ };
@@ -0,0 +1,17 @@
1
+ import { asString, isRecord } from './json.js';
2
+ /**
3
+ * Reads a provider error object: `{ type, message }` (Anthropic) or
4
+ * `{ message, type, code }` (OpenAI). Returns `undefined` when the value is
5
+ * not an object with a message, type or code.
6
+ */
7
+ export function toLlmError(value) {
8
+ if (!isRecord(value))
9
+ return undefined;
10
+ const type = asString(value.type) ?? asString(value.code);
11
+ const message = asString(value.message);
12
+ if (type === undefined && message === undefined)
13
+ return undefined;
14
+ return type === undefined
15
+ ? { message: message ?? '' }
16
+ : { type, message: message ?? '' };
17
+ }
@@ -0,0 +1,98 @@
1
+ import { anthropicMessages } from './anthropic.js';
2
+ import { openaiChat } from './openai-chat.js';
3
+ import { openaiResponses } from './openai-responses.js';
4
+ import { isEventStream, parseSseJson } from './sse.js';
5
+ const PARSERS = {
6
+ 'anthropic-messages': anthropicMessages,
7
+ 'openai-chat': openaiChat,
8
+ 'openai-responses': openaiResponses,
9
+ };
10
+ /**
11
+ * Which LLM API a request calls, from its method and path. The path, not the
12
+ * upstream name, so a custom upstream that speaks a known API is parsed too.
13
+ */
14
+ export function detectFormat(method, path) {
15
+ if (method !== 'POST')
16
+ return undefined;
17
+ const pathname = new URL(path, 'http://x').pathname.replace(/\/+$/, '');
18
+ if (pathname.endsWith('/v1/messages'))
19
+ return 'anthropic-messages';
20
+ if (pathname.endsWith('/chat/completions'))
21
+ return 'openai-chat';
22
+ if (pathname.endsWith('/responses'))
23
+ return 'openai-responses';
24
+ return undefined;
25
+ }
26
+ function readRequest(captured) {
27
+ const format = detectFormat(captured.method, captured.path);
28
+ if (!format)
29
+ return undefined;
30
+ try {
31
+ return {
32
+ format,
33
+ fields: PARSERS[format].parseRequest(JSON.parse(captured.body)),
34
+ };
35
+ }
36
+ catch (error) {
37
+ return { format, error: `request: ${error.message}` };
38
+ }
39
+ }
40
+ /**
41
+ * Reads a captured exchange as an LLM API call. Returns `undefined` when the
42
+ * path is not a known API. A body that cannot be parsed is noted in
43
+ * `parseError`; whatever else could be read is kept. Only successful (2xx)
44
+ * responses are parsed: error bodies are left to the raw view.
45
+ */
46
+ export function parseExchange(captured) {
47
+ return readExchange(captured, readRequest(captured));
48
+ }
49
+ /**
50
+ * `parseExchange` for one call that is read many times while its reply
51
+ * streams. The request body does not change by then, and can be large, so it
52
+ * is parsed again only when it does.
53
+ */
54
+ export function exchangeParser() {
55
+ let body;
56
+ let request;
57
+ return (captured) => {
58
+ if (captured.body !== body) {
59
+ body = captured.body;
60
+ request = readRequest(captured);
61
+ }
62
+ return readExchange(captured, request);
63
+ };
64
+ }
65
+ function readExchange(captured, request) {
66
+ if (!request)
67
+ return undefined;
68
+ const { format } = request;
69
+ const parser = PARSERS[format];
70
+ const exchange = {
71
+ format,
72
+ stream: false,
73
+ messages: [],
74
+ ...request.fields,
75
+ };
76
+ const errors = request.error ? [request.error] : [];
77
+ const response = captured.response;
78
+ if (response && response.status >= 200 && response.status < 300) {
79
+ try {
80
+ const streamed = isEventStream(response.headers['content-type']);
81
+ const { model, ...rest } = streamed
82
+ ? parser.parseStream(parseSseJson(response.body))
83
+ : parser.parseResponse(JSON.parse(response.body));
84
+ Object.assign(exchange, rest);
85
+ // The response names the model that answered, which can differ from an alias asked for.
86
+ if (model)
87
+ exchange.model = model;
88
+ if (streamed)
89
+ exchange.stream = true;
90
+ }
91
+ catch (error) {
92
+ errors.push(`response: ${error.message}`);
93
+ }
94
+ }
95
+ if (errors.length > 0)
96
+ exchange.parseError = errors.join('; ');
97
+ return exchange;
98
+ }
@@ -0,0 +1,31 @@
1
+ // Narrowing helpers for JSON of unknown shape: parsers read bodies that may
2
+ // not match the API, and must never throw because of it.
3
+ export function isRecord(value) {
4
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
5
+ }
6
+ export function asRecord(value) {
7
+ return isRecord(value) ? value : {};
8
+ }
9
+ export function asArray(value) {
10
+ return Array.isArray(value) ? value : [];
11
+ }
12
+ export function asString(value) {
13
+ return typeof value === 'string' ? value : undefined;
14
+ }
15
+ /**
16
+ * Parsed JSON, or the text as received when it is not valid JSON: tool
17
+ * arguments a cut stream left incomplete, or a model that wrote bad JSON.
18
+ */
19
+ export function parseJsonOrKeep(json) {
20
+ try {
21
+ return JSON.parse(json);
22
+ }
23
+ catch {
24
+ return json;
25
+ }
26
+ }
27
+ export function asNumber(value) {
28
+ return typeof value === 'number' && Number.isFinite(value)
29
+ ? value
30
+ : undefined;
31
+ }
@@ -0,0 +1,222 @@
1
+ import { toLlmError } from './error.js';
2
+ import { asArray, asNumber, asRecord, asString, isRecord, parseJsonOrKeep, } from './json.js';
3
+ import { partsText, toRequest } from './openai-common.js';
4
+ // OpenAI Chat Completions API: POST /v1/chat/completions. Many other servers
5
+ // (Ollama, vLLM and others) speak it too, some with a `reasoning_content` or
6
+ // `reasoning` field for the model's thinking, which is read as well.
7
+ /** Message content is a string, an array of parts, or null. */
8
+ function contentParts(content) {
9
+ if (typeof content === 'string')
10
+ return [{ type: 'text', text: content }];
11
+ return asArray(content).map((part) => {
12
+ const p = asRecord(part);
13
+ switch (p.type) {
14
+ case 'text':
15
+ return { type: 'text', text: asString(p.text) ?? '' };
16
+ case 'image_url':
17
+ return { type: 'image' };
18
+ default:
19
+ return { type: 'other', raw: part };
20
+ }
21
+ });
22
+ }
23
+ /** Content as text; non-text parts become `[type]`. */
24
+ function contentText(content) {
25
+ return partsText(contentParts(content));
26
+ }
27
+ /** A function or custom tool call. Function arguments are a JSON string. */
28
+ function toolCall(call) {
29
+ const c = asRecord(call);
30
+ if (c.type === 'custom') {
31
+ const custom = asRecord(c.custom);
32
+ return {
33
+ type: 'tool_call',
34
+ id: asString(c.id) ?? '',
35
+ name: asString(custom.name) ?? '',
36
+ input: custom.input,
37
+ };
38
+ }
39
+ const fn = asRecord(c.function);
40
+ const args = fn.arguments;
41
+ return {
42
+ type: 'tool_call',
43
+ id: asString(c.id) ?? '',
44
+ name: asString(fn.name) ?? '',
45
+ input: typeof args === 'string' ? parseJsonOrKeep(args) : args,
46
+ };
47
+ }
48
+ /** An assistant message in order: thinking, text, refusal, tool calls. */
49
+ function assistantParts(message) {
50
+ const parts = [];
51
+ const reasoning = asString(message.reasoning_content) ?? asString(message.reasoning);
52
+ if (reasoning)
53
+ parts.push({ type: 'thinking', text: reasoning });
54
+ // A reply that only calls tools has `content: null` or `""`.
55
+ if (message.content !== '')
56
+ parts.push(...contentParts(message.content));
57
+ const refusal = asString(message.refusal);
58
+ if (refusal)
59
+ parts.push({ type: 'text', text: refusal });
60
+ for (const call of asArray(message.tool_calls))
61
+ parts.push(toolCall(call));
62
+ // Deprecated single `function_call`, which has no id.
63
+ if (isRecord(message.function_call)) {
64
+ parts.push(toolCall({ function: message.function_call }));
65
+ }
66
+ return parts;
67
+ }
68
+ function toUsage(usage) {
69
+ if (!isRecord(usage))
70
+ return undefined;
71
+ return {
72
+ input: asNumber(usage.prompt_tokens),
73
+ output: asNumber(usage.completion_tokens),
74
+ cacheRead: asNumber(asRecord(usage.prompt_tokens_details).cached_tokens),
75
+ reasoning: asNumber(asRecord(usage.completion_tokens_details).reasoning_tokens),
76
+ };
77
+ }
78
+ function toTool(tool) {
79
+ const t = asRecord(tool);
80
+ // `tools` entries wrap the definition; deprecated `functions` entries are it.
81
+ const definition = asRecord(t.type === 'custom' ? t.custom : (t.function ?? tool));
82
+ return {
83
+ name: asString(definition.name) ?? '',
84
+ description: asString(definition.description),
85
+ };
86
+ }
87
+ function parseRequest(body) {
88
+ const b = asRecord(body);
89
+ const system = [];
90
+ const messages = [];
91
+ for (const raw of asArray(b.messages)) {
92
+ const m = asRecord(raw);
93
+ switch (m.role) {
94
+ case 'system':
95
+ case 'developer':
96
+ system.push(contentText(m.content));
97
+ break;
98
+ case 'assistant':
99
+ messages.push({ role: 'assistant', parts: assistantParts(m) });
100
+ break;
101
+ case 'tool':
102
+ case 'function':
103
+ messages.push({
104
+ role: 'tool',
105
+ parts: [
106
+ {
107
+ type: 'tool_result',
108
+ // Deprecated `function` messages name the function instead of a call id.
109
+ id: asString(m.tool_call_id) ??
110
+ asString(m.name) ??
111
+ '',
112
+ content: contentText(m.content),
113
+ },
114
+ ],
115
+ });
116
+ break;
117
+ default:
118
+ messages.push({ role: 'user', parts: contentParts(m.content) });
119
+ }
120
+ }
121
+ const tools = [...asArray(b.tools), ...asArray(b.functions)].map(toTool);
122
+ return toRequest(b, system, messages, tools);
123
+ }
124
+ /** Only the first choice is read; `n` > 1 is rare. */
125
+ function parseResponse(body) {
126
+ const b = asRecord(body);
127
+ const choice = asRecord(asArray(b.choices)[0]);
128
+ return {
129
+ model: asString(b.model),
130
+ output: {
131
+ role: 'assistant',
132
+ parts: assistantParts(asRecord(choice.message)),
133
+ },
134
+ stopReason: asString(choice.finish_reason),
135
+ usage: toUsage(b.usage),
136
+ };
137
+ }
138
+ /** Tool call pieces join by `index`; the id and name come in the first one. */
139
+ function addCallPieces(calls, pieces) {
140
+ for (const piece of asArray(pieces)) {
141
+ const p = asRecord(piece);
142
+ const fn = asRecord(p.function);
143
+ const index = asNumber(p.index) ?? 0;
144
+ calls[index] ??= { id: '', name: '', arguments: '' };
145
+ const call = calls[index];
146
+ call.id ||= asString(p.id) ?? '';
147
+ call.name ||= asString(fn.name) ?? '';
148
+ call.arguments += asString(fn.arguments) ?? '';
149
+ }
150
+ }
151
+ /** Adds a chunk's delta for the first choice, if it has one. */
152
+ function addChoiceDelta(state, chunk) {
153
+ const choice = asArray(chunk.choices)
154
+ .map(asRecord)
155
+ .find((c) => (asNumber(c.index) ?? 0) === 0);
156
+ if (!choice)
157
+ return;
158
+ state.stopReason = asString(choice.finish_reason) ?? state.stopReason;
159
+ const delta = asRecord(choice.delta);
160
+ state.content += asString(delta.content) ?? '';
161
+ state.reasoning +=
162
+ asString(delta.reasoning_content) ?? asString(delta.reasoning) ?? '';
163
+ state.refusal += asString(delta.refusal) ?? '';
164
+ addCallPieces(state.calls, delta.tool_calls);
165
+ }
166
+ /** The joined deltas as a message `assistantParts` can read. */
167
+ function choiceMessage(state) {
168
+ return {
169
+ reasoning_content: state.reasoning,
170
+ content: state.content,
171
+ refusal: state.refusal,
172
+ tool_calls: state.calls.filter(Boolean).map((call) => ({
173
+ id: call.id,
174
+ function: { name: call.name, arguments: call.arguments },
175
+ })),
176
+ };
177
+ }
178
+ /**
179
+ * Joins the deltas of the first choice into one message: text pieces in
180
+ * order, tool calls by their `index` with the id and name from the first
181
+ * delta and the argument pieces appended. Usage comes in a last chunk with
182
+ * no choices, only when the request asked for it (`stream_options`). A
183
+ * failure part-way is a chunk holding an `error` object and no choices.
184
+ */
185
+ function parseStream(events) {
186
+ if (events.length === 0)
187
+ return {};
188
+ let model;
189
+ let usage;
190
+ let error;
191
+ const state = {
192
+ content: '',
193
+ reasoning: '',
194
+ refusal: '',
195
+ calls: [],
196
+ };
197
+ for (const raw of events) {
198
+ const chunk = asRecord(raw);
199
+ model = asString(chunk.model) ?? model;
200
+ if (isRecord(chunk.usage))
201
+ usage = chunk.usage;
202
+ if (isRecord(chunk.error)) {
203
+ error = toLlmError(chunk.error) ?? { message: '' };
204
+ }
205
+ addChoiceDelta(state, chunk);
206
+ }
207
+ return {
208
+ model,
209
+ output: {
210
+ role: 'assistant',
211
+ parts: assistantParts(choiceMessage(state)),
212
+ },
213
+ stopReason: state.stopReason,
214
+ usage: toUsage(usage),
215
+ ...(error && { error }),
216
+ };
217
+ }
218
+ export const openaiChat = {
219
+ parseRequest,
220
+ parseResponse,
221
+ parseStream,
222
+ };
@@ -0,0 +1,18 @@
1
+ import { asString } from './json.js';
2
+ // Helpers shared by the OpenAI Chat Completions and Responses parsers.
3
+ /** Parts as text; non-text parts become `[type]`. */
4
+ export function partsText(parts) {
5
+ return parts
6
+ .map((part) => (part.type === 'text' ? part.text : `[${part.type}]`))
7
+ .join('\n');
8
+ }
9
+ /** The request as read: system texts joined, empty lists left out. */
10
+ export function toRequest(body, system, messages, tools) {
11
+ return {
12
+ model: asString(body.model),
13
+ stream: body.stream === true,
14
+ system: system.length > 0 ? system.join('\n\n') : undefined,
15
+ messages,
16
+ tools: tools.length > 0 ? tools : undefined,
17
+ };
18
+ }