@celljs/ai-pi 0.0.0-stage → 4.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.
Files changed (158) hide show
  1. package/README.md +69 -2
  2. package/cell.yml +7 -0
  3. package/esm/node/chat/index.d.ts +3 -0
  4. package/esm/node/chat/index.js +4 -0
  5. package/esm/node/chat/index.js.map +1 -0
  6. package/esm/node/chat/pi-chat-model.d.ts +27 -0
  7. package/esm/node/chat/pi-chat-model.js +86 -0
  8. package/esm/node/chat/pi-chat-model.js.map +1 -0
  9. package/esm/node/chat/pi-chat-options.d.ts +9 -0
  10. package/esm/node/chat/pi-chat-options.js +2 -0
  11. package/esm/node/chat/pi-chat-options.js.map +1 -0
  12. package/esm/node/chat/pi-message-util.d.ts +11 -0
  13. package/esm/node/chat/pi-message-util.js +104 -0
  14. package/esm/node/chat/pi-message-util.js.map +1 -0
  15. package/esm/node/error/errors.d.ts +14 -0
  16. package/esm/node/error/errors.js +21 -0
  17. package/esm/node/error/errors.js.map +1 -0
  18. package/esm/node/error/index.d.ts +1 -0
  19. package/esm/node/error/index.js +2 -0
  20. package/esm/node/error/index.js.map +1 -0
  21. package/esm/node/index.d.ts +5 -0
  22. package/esm/node/index.js +6 -0
  23. package/esm/node/index.js.map +1 -0
  24. package/esm/node/models/index.d.ts +1 -0
  25. package/esm/node/models/index.js +2 -0
  26. package/esm/node/models/index.js.map +1 -0
  27. package/esm/node/models/pi-endpoint-util.d.ts +9 -0
  28. package/esm/node/models/pi-endpoint-util.js +51 -0
  29. package/esm/node/models/pi-endpoint-util.js.map +1 -0
  30. package/esm/node/models/pi-models-provider.d.ts +10 -0
  31. package/esm/node/models/pi-models-provider.js +80 -0
  32. package/esm/node/models/pi-models-provider.js.map +1 -0
  33. package/esm/node/module.d.ts +3 -0
  34. package/esm/node/module.js +4 -0
  35. package/esm/node/module.js.map +1 -0
  36. package/esm/node/pi/index.d.ts +2 -0
  37. package/esm/node/pi/index.js +3 -0
  38. package/esm/node/pi/index.js.map +1 -0
  39. package/esm/node/pi/pi-ai-util.d.ts +10 -0
  40. package/esm/node/pi/pi-ai-util.js +28 -0
  41. package/esm/node/pi/pi-ai-util.js.map +1 -0
  42. package/esm/node/pi/pi-types.d.ts +10 -0
  43. package/esm/node/pi/pi-types.js +2 -0
  44. package/esm/node/pi/pi-types.js.map +1 -0
  45. package/esm/node/pi-protocol.d.ts +49 -0
  46. package/esm/node/pi-protocol.js +5 -0
  47. package/esm/node/pi-protocol.js.map +1 -0
  48. package/esm/node/test/faux-pi-models.d.ts +29 -0
  49. package/esm/node/test/faux-pi-models.js +36 -0
  50. package/esm/node/test/faux-pi-models.js.map +1 -0
  51. package/esm/node/test/index.d.ts +2 -0
  52. package/esm/node/test/index.js +3 -0
  53. package/esm/node/test/index.js.map +1 -0
  54. package/esm/node/test/test-container.d.ts +13 -0
  55. package/esm/node/test/test-container.js +19 -0
  56. package/esm/node/test/test-container.js.map +1 -0
  57. package/esm/package.json +3 -0
  58. package/lib/node/chat/index.d.ts +4 -0
  59. package/lib/node/chat/index.d.ts.map +1 -0
  60. package/lib/node/chat/index.js +20 -0
  61. package/lib/node/chat/index.js.map +1 -0
  62. package/lib/node/chat/pi-chat-model.d.ts +28 -0
  63. package/lib/node/chat/pi-chat-model.d.ts.map +1 -0
  64. package/lib/node/chat/pi-chat-model.js +89 -0
  65. package/lib/node/chat/pi-chat-model.js.map +1 -0
  66. package/lib/node/chat/pi-chat-model.spec.d.ts +2 -0
  67. package/lib/node/chat/pi-chat-model.spec.d.ts.map +1 -0
  68. package/lib/node/chat/pi-chat-model.spec.js +98 -0
  69. package/lib/node/chat/pi-chat-model.spec.js.map +1 -0
  70. package/lib/node/chat/pi-chat-options.d.ts +10 -0
  71. package/lib/node/chat/pi-chat-options.d.ts.map +1 -0
  72. package/lib/node/chat/pi-chat-options.js +3 -0
  73. package/lib/node/chat/pi-chat-options.js.map +1 -0
  74. package/lib/node/chat/pi-message-util.d.ts +12 -0
  75. package/lib/node/chat/pi-message-util.d.ts.map +1 -0
  76. package/lib/node/chat/pi-message-util.js +107 -0
  77. package/lib/node/chat/pi-message-util.js.map +1 -0
  78. package/lib/node/error/errors.d.ts +15 -0
  79. package/lib/node/error/errors.d.ts.map +1 -0
  80. package/lib/node/error/errors.js +27 -0
  81. package/lib/node/error/errors.js.map +1 -0
  82. package/lib/node/error/index.d.ts +2 -0
  83. package/lib/node/error/index.d.ts.map +1 -0
  84. package/lib/node/error/index.js +18 -0
  85. package/lib/node/error/index.js.map +1 -0
  86. package/lib/node/index.d.ts +6 -0
  87. package/lib/node/index.d.ts.map +1 -0
  88. package/lib/node/index.js +22 -0
  89. package/lib/node/index.js.map +1 -0
  90. package/lib/node/models/index.d.ts +2 -0
  91. package/lib/node/models/index.d.ts.map +1 -0
  92. package/lib/node/models/index.js +18 -0
  93. package/lib/node/models/index.js.map +1 -0
  94. package/lib/node/models/pi-endpoint-util.d.ts +10 -0
  95. package/lib/node/models/pi-endpoint-util.d.ts.map +1 -0
  96. package/lib/node/models/pi-endpoint-util.js +54 -0
  97. package/lib/node/models/pi-endpoint-util.js.map +1 -0
  98. package/lib/node/models/pi-endpoint-util.spec.d.ts +2 -0
  99. package/lib/node/models/pi-endpoint-util.spec.d.ts.map +1 -0
  100. package/lib/node/models/pi-endpoint-util.spec.js +82 -0
  101. package/lib/node/models/pi-endpoint-util.spec.js.map +1 -0
  102. package/lib/node/models/pi-models-provider.d.ts +11 -0
  103. package/lib/node/models/pi-models-provider.d.ts.map +1 -0
  104. package/lib/node/models/pi-models-provider.js +83 -0
  105. package/lib/node/models/pi-models-provider.js.map +1 -0
  106. package/lib/node/module.d.ts +4 -0
  107. package/lib/node/module.d.ts.map +1 -0
  108. package/lib/node/module.js +6 -0
  109. package/lib/node/module.js.map +1 -0
  110. package/lib/node/pi/index.d.ts +3 -0
  111. package/lib/node/pi/index.d.ts.map +1 -0
  112. package/lib/node/pi/index.js +19 -0
  113. package/lib/node/pi/index.js.map +1 -0
  114. package/lib/node/pi/pi-ai-util.d.ts +11 -0
  115. package/lib/node/pi/pi-ai-util.d.ts.map +1 -0
  116. package/lib/node/pi/pi-ai-util.js +31 -0
  117. package/lib/node/pi/pi-ai-util.js.map +1 -0
  118. package/lib/node/pi/pi-types.d.ts +11 -0
  119. package/lib/node/pi/pi-types.d.ts.map +1 -0
  120. package/lib/node/pi/pi-types.js +3 -0
  121. package/lib/node/pi/pi-types.js.map +1 -0
  122. package/lib/node/pi-protocol.d.ts +50 -0
  123. package/lib/node/pi-protocol.d.ts.map +1 -0
  124. package/lib/node/pi-protocol.js +8 -0
  125. package/lib/node/pi-protocol.js.map +1 -0
  126. package/lib/node/test/faux-pi-models.d.ts +30 -0
  127. package/lib/node/test/faux-pi-models.d.ts.map +1 -0
  128. package/lib/node/test/faux-pi-models.js +40 -0
  129. package/lib/node/test/faux-pi-models.js.map +1 -0
  130. package/lib/node/test/index.d.ts +3 -0
  131. package/lib/node/test/index.d.ts.map +1 -0
  132. package/lib/node/test/index.js +19 -0
  133. package/lib/node/test/index.js.map +1 -0
  134. package/lib/node/test/test-container.d.ts +14 -0
  135. package/lib/node/test/test-container.d.ts.map +1 -0
  136. package/lib/node/test/test-container.js +25 -0
  137. package/lib/node/test/test-container.js.map +1 -0
  138. package/package.json +92 -4
  139. package/src/node/chat/index.ts +3 -0
  140. package/src/node/chat/pi-chat-model.spec.ts +113 -0
  141. package/src/node/chat/pi-chat-model.ts +76 -0
  142. package/src/node/chat/pi-chat-options.ts +10 -0
  143. package/src/node/chat/pi-message-util.ts +108 -0
  144. package/src/node/error/errors.ts +28 -0
  145. package/src/node/error/index.ts +1 -0
  146. package/src/node/index.ts +5 -0
  147. package/src/node/models/index.ts +1 -0
  148. package/src/node/models/pi-endpoint-util.spec.ts +88 -0
  149. package/src/node/models/pi-endpoint-util.ts +54 -0
  150. package/src/node/models/pi-models-provider.ts +66 -0
  151. package/src/node/module.ts +4 -0
  152. package/src/node/pi/index.ts +2 -0
  153. package/src/node/pi/pi-ai-util.ts +34 -0
  154. package/src/node/pi/pi-types.ts +12 -0
  155. package/src/node/pi-protocol.ts +57 -0
  156. package/src/node/test/faux-pi-models.ts +53 -0
  157. package/src/node/test/index.ts +2 -0
  158. package/src/node/test/test-container.ts +28 -0
@@ -0,0 +1,108 @@
1
+ import {
2
+ AssistantMessage,
3
+ ChatGenerationMetadata,
4
+ type ChatResponse,
5
+ ChatResponseMetadata,
6
+ type Generation,
7
+ type Message,
8
+ SystemMessage,
9
+ type ToolCall,
10
+ ToolResponseMessage,
11
+ UserMessage,
12
+ } from '@celljs/ai-core';
13
+ import { ByteUtil, IllegalArgumentError } from '@celljs/core';
14
+ import type { PiAssistantMessage, PiContext, PiMessage, PiModel } from '../pi';
15
+ import type { PiChatOptions } from './pi-chat-options';
16
+
17
+ /** Converts between ai-core prompts and responses and pi-ai contexts and assistant messages. */
18
+ export namespace PiMessageUtil {
19
+ export function toContext(messages: Message[], model: PiModel, options: PiChatOptions = {}): PiContext {
20
+ const system: string[] = [];
21
+ const converted: PiMessage[] = [];
22
+ for (const message of messages) {
23
+ if (message instanceof SystemMessage) {
24
+ system.push(message.content);
25
+ } else if (message instanceof UserMessage) {
26
+ converted.push(toUserMessage(message));
27
+ } else if (message instanceof AssistantMessage) {
28
+ converted.push(toAssistantMessage(message, model));
29
+ } else if (message instanceof ToolResponseMessage) {
30
+ for (const response of message.responses) {
31
+ converted.push({
32
+ role: 'toolResult',
33
+ toolCallId: response.id,
34
+ toolName: response.name,
35
+ content: [{ type: 'text', text: response.responseData }],
36
+ isError: false,
37
+ timestamp: Date.now(),
38
+ } as PiMessage);
39
+ }
40
+ } else {
41
+ throw new IllegalArgumentError(`Unsupported message type: ${message.messageType}`);
42
+ }
43
+ }
44
+ return { systemPrompt: system.length ? system.join('\n\n') : undefined, messages: converted, tools: options.tools };
45
+ }
46
+
47
+ function toUserMessage(message: UserMessage): PiMessage {
48
+ if (!message.media?.length) {
49
+ return { role: 'user', content: message.content, timestamp: Date.now() };
50
+ }
51
+ const images = message.media.map(media => ({
52
+ type: 'image' as const,
53
+ data: typeof media.data === 'string' ? media.data : ByteUtil.encodeBase64(media.data),
54
+ mimeType: media.mimeType.toString(),
55
+ }));
56
+ return { role: 'user', content: [{ type: 'text', text: message.content }, ...images], timestamp: Date.now() };
57
+ }
58
+
59
+ function toAssistantMessage(message: AssistantMessage, model: PiModel): PiMessage {
60
+ const toolCalls = (message.toolCalls ?? []).map(call => ({
61
+ type: 'toolCall' as const,
62
+ id: call.id,
63
+ name: call.name,
64
+ arguments: call.arguments ? JSON.parse(call.arguments) : {},
65
+ }));
66
+ return {
67
+ role: 'assistant',
68
+ content: [...(message.content ? [{ type: 'text' as const, text: message.content }] : []), ...toolCalls],
69
+ api: model.api,
70
+ provider: model.provider,
71
+ model: model.id,
72
+ usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
73
+ stopReason: toolCalls.length ? 'toolUse' : 'stop',
74
+ timestamp: Date.now(),
75
+ } as PiMessage;
76
+ }
77
+
78
+ /** The text and tool calls of a pi-ai assistant message; thinking goes to `metadata.thinking`. */
79
+ export function fromAssistantMessage(message: PiAssistantMessage): AssistantMessage {
80
+ let text = '';
81
+ let thinking = '';
82
+ const toolCalls: ToolCall[] = [];
83
+ for (const block of message.content) {
84
+ if (block.type === 'text') {
85
+ text += block.text;
86
+ } else if (block.type === 'thinking') {
87
+ thinking += block.thinking;
88
+ } else if (block.type === 'toolCall') {
89
+ toolCalls.push({ id: block.id, type: 'function', name: block.name, arguments: JSON.stringify(block.arguments) });
90
+ }
91
+ }
92
+ return new AssistantMessage(text, [], thinking ? { thinking } : {}, toolCalls);
93
+ }
94
+
95
+ /** A response for `output`; `message` gives the finish reason (pi-ai's stop reason), usage and model. */
96
+ export function toChatResponse(output: AssistantMessage, message?: PiAssistantMessage): ChatResponse {
97
+ const generation: Generation = { output, metadata: ChatGenerationMetadata.from(message?.stopReason) };
98
+ const metadata = ChatResponseMetadata.createEmpty();
99
+ if (message) {
100
+ metadata.id = message.responseId ?? '';
101
+ metadata.model = message.responseModel ?? message.model;
102
+ metadata.usage = { promptTokens: message.usage.input, generationTokens: message.usage.output, totalTokens: message.usage.totalTokens };
103
+ metadata.extra.provider = message.provider;
104
+ metadata.extra.cost = message.usage.cost;
105
+ }
106
+ return { result: generation, results: [generation], metadata };
107
+ }
108
+ }
@@ -0,0 +1,28 @@
1
+ import { CustomError } from '@celljs/core';
2
+
3
+ export class PiError extends CustomError {}
4
+
5
+ export class PiModelNotFoundError extends PiError {
6
+ constructor(
7
+ readonly model: string,
8
+ readonly available: string[],
9
+ ) {
10
+ super(
11
+ `The model ${model} is not known to pi-ai. Use "<provider>/<model id>"${
12
+ available.length
13
+ ? `, one of: ${available.join(', ')}`
14
+ : '; no model has credentials yet: set the API key of a provider (e.g. ANTHROPIC_API_KEY) or cell.ai.pi.apiKeys'
15
+ }.`,
16
+ );
17
+ }
18
+ }
19
+
20
+ /** The model answered with an error (pi-ai reports provider failures as messages, not exceptions). */
21
+ export class PiModelError extends PiError {
22
+ constructor(
23
+ readonly model: string,
24
+ readonly reason: string,
25
+ ) {
26
+ super(`The model ${model} failed: ${reason}`);
27
+ }
28
+ }
@@ -0,0 +1 @@
1
+ export * from './errors';
@@ -0,0 +1,5 @@
1
+ export * from './chat';
2
+ export * from './error';
3
+ export * from './models';
4
+ export * from './pi';
5
+ export * from './pi-protocol';
@@ -0,0 +1 @@
1
+ export * from './pi-models-provider';
@@ -0,0 +1,88 @@
1
+ import { afterAll, beforeAll, describe, it } from 'bun:test';
2
+ import { createServer, type Server } from 'node:http';
3
+ import type { AddressInfo } from 'node:net';
4
+ import { type ChatModel, PromptTemplate } from '@celljs/ai-core';
5
+ import { expect } from 'chai';
6
+ import { PiChatModel } from '../chat';
7
+ import { PiModelsProvider } from '../pi-protocol';
8
+ import { createPiTestContainer } from '../test';
9
+
10
+ /** An OpenAI-compatible chat completions endpoint that answers "pong" and records the requests. */
11
+ function fakeEndpoint(requests: { authorization?: string; body: any }[]): Server {
12
+ return createServer((req, res) => {
13
+ let body = '';
14
+ req.on('data', chunk => (body += chunk));
15
+ req.on('end', () => {
16
+ requests.push({ authorization: req.headers.authorization, body: JSON.parse(body) });
17
+ const chunk = (delta: object, finish: string | null) => ({
18
+ id: 'c',
19
+ object: 'chat.completion.chunk',
20
+ created: 0,
21
+ model: 'm',
22
+ choices: [{ index: 0, delta, finish_reason: finish }],
23
+ });
24
+ res.writeHead(200, { 'Content-Type': 'text/event-stream' });
25
+ res.write(`data: ${JSON.stringify(chunk({ role: 'assistant', content: 'pong' }, null))}\n\n`);
26
+ res.write(`data: ${JSON.stringify(chunk({}, 'stop'))}\n\n`);
27
+ res.end('data: [DONE]\n\n');
28
+ });
29
+ });
30
+ }
31
+
32
+ describe('cell.ai.pi.endpoints', () => {
33
+ const requests: { authorization?: string; body: any }[] = [];
34
+ const server = fakeEndpoint(requests);
35
+ let baseUrl: string;
36
+
37
+ beforeAll(async () => {
38
+ await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
39
+ baseUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}/v1`;
40
+ });
41
+
42
+ afterAll(() => server.close());
43
+
44
+ it('registers OpenAI-compatible endpoints as providers', async () => {
45
+ const { container } = await createPiTestContainer({
46
+ providers: [],
47
+ endpoints: { local: { baseUrl, apiKey: 'local-key', models: ['small', { id: 'big', reasoning: true, contextWindow: 32000 }] } },
48
+ });
49
+ const models = await container.get<PiModelsProvider>(PiModelsProvider).provide();
50
+ expect(models.getModels('local').map(m => m.id)).to.deep.equal(['small', 'big']);
51
+ expect(models.getModel('local', 'big')).to.include({ reasoning: true, contextWindow: 32000, api: 'openai-completions', baseUrl });
52
+ const prompts = container.get<PromptTemplate>(PromptTemplate);
53
+ const response = await container.get<ChatModel>(PiChatModel).call(await prompts.create('ping', { chatOptions: { model: 'local/small' } }));
54
+ expect(response.result.output.content).to.equal('pong');
55
+ expect(requests.at(-1)).to.deep.include({ authorization: 'Bearer local-key' });
56
+ expect(requests.at(-1)!.body.model).to.equal('small');
57
+ });
58
+
59
+ it('uses the key of cell.ai.pi.apiKeys over the configured one', async () => {
60
+ const { container } = await createPiTestContainer({
61
+ providers: [],
62
+ endpoints: { local: { baseUrl, apiKey: 'configured', models: ['small'] } },
63
+ apiKeys: { local: 'stored' },
64
+ });
65
+ const prompts = container.get<PromptTemplate>(PromptTemplate);
66
+ await container.get<ChatModel>(PiChatModel).call(await prompts.create('ping', { chatOptions: { model: 'local/small' } }));
67
+ expect(requests.at(-1)!.authorization).to.equal('Bearer stored');
68
+ });
69
+
70
+ it('sends a placeholder key to endpoints without one', async () => {
71
+ const { container } = await createPiTestContainer({ providers: [], endpoints: { local: { baseUrl, models: ['small'] } } });
72
+ const prompts = container.get<PromptTemplate>(PromptTemplate);
73
+ await container.get<ChatModel>(PiChatModel).call(await prompts.create('ping', { chatOptions: { model: 'local/small' } }));
74
+ expect(requests.at(-1)!.authorization).to.equal('Bearer no-key');
75
+ });
76
+
77
+ it('rejects unknown wire protocols', async () => {
78
+ const { container } = await createPiTestContainer({ providers: [], endpoints: { local: { baseUrl, api: 'grpc' as any, models: ['small'] } } });
79
+ let error: unknown;
80
+ await container
81
+ .get<PiModelsProvider>(PiModelsProvider)
82
+ .provide()
83
+ .catch(e => (error = e));
84
+ expect((error as Error).message)
85
+ .to.include('openai-completions')
86
+ .and.include('grpc');
87
+ });
88
+ });
@@ -0,0 +1,54 @@
1
+ import { type PiAi, PiAiUtil, type PiProvider } from '../pi';
2
+ import type { PiEndpoint, PiEndpointApi, PiEndpointModel } from '../pi-protocol';
3
+
4
+ type ProviderStreams = Parameters<PiAi['createProvider']>[0]['api'];
5
+
6
+ const API_LOADERS: Record<PiEndpointApi, () => Promise<ProviderStreams>> = {
7
+ 'openai-completions': async () => (await import('@earendil-works/pi-ai/api/openai-completions.lazy')).openAICompletionsApi(),
8
+ 'openai-responses': async () => (await import('@earendil-works/pi-ai/api/openai-responses.lazy')).openAIResponsesApi(),
9
+ 'anthropic-messages': async () => (await import('@earendil-works/pi-ai/api/anthropic-messages.lazy')).anthropicMessagesApi(),
10
+ };
11
+
12
+ /** Turns `cell.ai.pi.endpoints` into pi-ai providers. */
13
+ export namespace PiEndpointUtil {
14
+ export const APIS = Object.keys(API_LOADERS) as PiEndpointApi[];
15
+
16
+ /** The key sent to endpoints configured without one. */
17
+ export const NO_KEY = 'no-key';
18
+
19
+ export async function toProvider(id: string, endpoint: PiEndpoint): Promise<PiProvider> {
20
+ const api = endpoint.api ?? 'openai-completions';
21
+ const load = API_LOADERS[api];
22
+ if (!load) {
23
+ throw new TypeError(`cell.ai.pi.endpoints.${id}.api must be one of ${APIS.join(', ')}, not ${api}.`);
24
+ }
25
+ const ai = await PiAiUtil.load();
26
+ const key = endpoint.apiKey || undefined;
27
+ return ai.createProvider({
28
+ id,
29
+ baseUrl: endpoint.baseUrl,
30
+ // A stored key (cell.ai.pi.apiKeys) wins over the configured one. pi-ai's OpenAI client needs a key,
31
+ // so servers without keys (Ollama, LM Studio) get a placeholder they ignore.
32
+ auth: {
33
+ apiKey: { name: `${id} API key`, resolve: async ({ credential }) => ({ auth: { apiKey: credential?.key ?? key ?? PiEndpointUtil.NO_KEY } }) },
34
+ },
35
+ models: endpoint.models.map(model => toModel(id, endpoint.baseUrl, api, typeof model === 'string' ? { id: model } : model)),
36
+ api: await load(),
37
+ }) as PiProvider;
38
+ }
39
+
40
+ function toModel(provider: string, baseUrl: string, api: PiEndpointApi, model: PiEndpointModel) {
41
+ return {
42
+ id: model.id,
43
+ name: model.name ?? model.id,
44
+ api,
45
+ provider,
46
+ baseUrl,
47
+ reasoning: model.reasoning ?? false,
48
+ input: model.images ? (['text', 'image'] as ('text' | 'image')[]) : (['text'] as ('text' | 'image')[]),
49
+ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
50
+ contextWindow: model.contextWindow ?? 128000,
51
+ maxTokens: model.maxTokens ?? 16384,
52
+ };
53
+ }
54
+ }
@@ -0,0 +1,66 @@
1
+ import { Autowired, Component, Optional, Value } from '@celljs/core';
2
+ import { PiModelNotFoundError } from '../error';
3
+ import { type Models, PiAiUtil, type PiModel } from '../pi';
4
+ import { PI_OPTIONS, PiModelsContribution, PiModelsProvider, type PiOptions } from '../pi-protocol';
5
+ import { PiEndpointUtil } from './pi-endpoint-util';
6
+
7
+ @Component(PiModelsProvider)
8
+ export class DefaultPiModelsProvider implements PiModelsProvider {
9
+ @Value(PI_OPTIONS)
10
+ protected readonly options?: PiOptions;
11
+
12
+ @Autowired(PiModelsContribution)
13
+ @Optional()
14
+ protected readonly contributions: PiModelsContribution[] = [];
15
+
16
+ protected models?: Promise<Models>;
17
+
18
+ provide(): Promise<Models> {
19
+ if (!this.models) {
20
+ const models = this.doProvide();
21
+ this.models = models;
22
+ models.catch(() => {
23
+ if (this.models === models) {
24
+ this.models = undefined;
25
+ }
26
+ });
27
+ }
28
+ return this.models;
29
+ }
30
+
31
+ async resolve(ref: string): Promise<PiModel> {
32
+ const models = await this.provide();
33
+ const index = ref.indexOf('/');
34
+ const model = index > 0 ? models.getModel(ref.slice(0, index), ref.slice(index + 1)) : undefined;
35
+ if (!model) {
36
+ const available = (await models.getAvailable()).map(m => `${m.provider}/${m.id}`);
37
+ throw new PiModelNotFoundError(ref, available);
38
+ }
39
+ return model;
40
+ }
41
+
42
+ protected async doProvide(): Promise<Models> {
43
+ const options = this.options ?? {};
44
+ const [ai, all] = await Promise.all([PiAiUtil.load(), PiAiUtil.loadProviders()]);
45
+ const credentials = new ai.InMemoryCredentialStore();
46
+ const models = ai.createModels({ credentials });
47
+ const wanted = options.providers && options.providers !== 'all' ? new Set(options.providers) : undefined;
48
+ for (const provider of all.builtinProviders()) {
49
+ if (!wanted || wanted.has(provider.id)) {
50
+ models.setProvider(provider);
51
+ }
52
+ }
53
+ for (const [id, endpoint] of Object.entries(options.endpoints ?? {})) {
54
+ models.setProvider(await PiEndpointUtil.toProvider(id, endpoint));
55
+ }
56
+ for (const [provider, key] of Object.entries(options.apiKeys ?? {})) {
57
+ if (key) {
58
+ await credentials.modify(provider, async () => ({ type: 'api_key', key }));
59
+ }
60
+ }
61
+ for (const contribution of this.contributions ?? []) {
62
+ await contribution.configure(models);
63
+ }
64
+ return models;
65
+ }
66
+ }
@@ -0,0 +1,4 @@
1
+ import { autoBind } from '@celljs/core';
2
+ import './index';
3
+
4
+ export default autoBind();
@@ -0,0 +1,2 @@
1
+ export * from './pi-ai-util';
2
+ export * from './pi-types';
@@ -0,0 +1,34 @@
1
+ import { PiError } from '../error';
2
+
3
+ /** The module namespace of `@earendil-works/pi-ai`. */
4
+ export type PiAi = typeof import('@earendil-works/pi-ai', { with: { 'resolution-mode': 'import' }});
5
+
6
+ /** The module namespace of `@earendil-works/pi-ai/providers/all`. */
7
+ export type PiAiProviders = typeof import('@earendil-works/pi-ai/providers/all', { with: { 'resolution-mode': 'import' }});
8
+
9
+ export namespace PiAiUtil {
10
+ let ai: Promise<PiAi> | undefined;
11
+ let providers: Promise<PiAiProviders> | undefined;
12
+
13
+ /** Loads pi-ai once, with a dynamic `import()`: it is an ES module package. */
14
+ export function load(): Promise<PiAi> {
15
+ ai ??= import('@earendil-works/pi-ai').catch(cause => {
16
+ ai = undefined;
17
+ throw notLoaded(cause);
18
+ });
19
+ return ai;
20
+ }
21
+
22
+ /** Loads the factories of pi-ai's built-in providers once. */
23
+ export function loadProviders(): Promise<PiAiProviders> {
24
+ providers ??= import('@earendil-works/pi-ai/providers/all').catch(cause => {
25
+ providers = undefined;
26
+ throw notLoaded(cause);
27
+ });
28
+ return providers;
29
+ }
30
+
31
+ function notLoaded(cause: unknown): PiError {
32
+ return new PiError('Cannot load @earendil-works/pi-ai. Install it next to @celljs/ai-pi; it needs Node.js >= 22.19.0 or Bun.', { cause });
33
+ }
34
+ }
@@ -0,0 +1,12 @@
1
+ // pi-ai is an ES module package: the CommonJS build of this package can only name its types through
2
+ // import types with `resolution-mode`.
3
+ export type Models = import('@earendil-works/pi-ai', { with: { 'resolution-mode': 'import' }}).MutableModels;
4
+ export type PiModel = import('@earendil-works/pi-ai', { with: { 'resolution-mode': 'import' }}).Model<any>;
5
+ export type PiContext = import('@earendil-works/pi-ai', { with: { 'resolution-mode': 'import' }}).Context;
6
+ export type PiMessage = import('@earendil-works/pi-ai', { with: { 'resolution-mode': 'import' }}).Message;
7
+ export type PiAssistantMessage = import('@earendil-works/pi-ai', { with: { 'resolution-mode': 'import' }}).AssistantMessage;
8
+ export type PiAssistantMessageEvent = import('@earendil-works/pi-ai', { with: { 'resolution-mode': 'import' }}).AssistantMessageEvent;
9
+ export type PiTool = import('@earendil-works/pi-ai', { with: { 'resolution-mode': 'import' }}).Tool;
10
+ export type PiThinkingLevel = import('@earendil-works/pi-ai', { with: { 'resolution-mode': 'import' }}).ThinkingLevel;
11
+ export type PiProvider = import('@earendil-works/pi-ai', { with: { 'resolution-mode': 'import' }}).Provider;
12
+ export type CredentialStore = import('@earendil-works/pi-ai', { with: { 'resolution-mode': 'import' }}).CredentialStore;
@@ -0,0 +1,57 @@
1
+ import type { Models, PiModel } from './pi';
2
+
3
+ export const PiModelsProvider = Symbol('PiModelsProvider');
4
+ export const PiModelsContribution = Symbol('PiModelsContribution');
5
+
6
+ /** Configuration key of {@link PiOptions}. */
7
+ export const PI_OPTIONS = 'cell.ai.pi';
8
+
9
+ /** `cell.ai.pi`. */
10
+ export interface PiOptions {
11
+ /** Built-in providers to register: `all`, or provider ids such as `[anthropic, openai]`. Default: all. */
12
+ providers?: 'all' | string[];
13
+ /** Extra providers by id: OpenAI- or Anthropic-compatible endpoints such as Ollama, vLLM, LM Studio or a gateway. */
14
+ endpoints?: Record<string, PiEndpoint>;
15
+ /** API keys by provider id, kept in memory. Empty values are ignored; providers also read their environment variables. */
16
+ apiKeys?: Record<string, string | undefined>;
17
+ }
18
+
19
+ /** Wire protocols {@link PiEndpoint} speaks. */
20
+ export type PiEndpointApi = 'openai-completions' | 'openai-responses' | 'anthropic-messages';
21
+
22
+ /** An endpoint registered as a pi-ai provider; its models are `<endpoint id>/<model id>`. */
23
+ export interface PiEndpoint {
24
+ /** e.g. `http://localhost:11434/v1` for Ollama. */
25
+ baseUrl: string;
26
+ /** Default: openai-completions. */
27
+ api?: PiEndpointApi;
28
+ /** Sent as the API key; empty for servers without keys. `cell.ai.pi.apiKeys.<endpoint id>` works too. */
29
+ apiKey?: string;
30
+ /** Model ids, or models with their limits. */
31
+ models: (string | PiEndpointModel)[];
32
+ }
33
+
34
+ export interface PiEndpointModel {
35
+ id: string;
36
+ name?: string;
37
+ /** Whether the model thinks. Default: false. */
38
+ reasoning?: boolean;
39
+ /** Accepts images. Default: false. */
40
+ images?: boolean;
41
+ /** Default: 128000. */
42
+ contextWindow?: number;
43
+ /** Default: 16384. */
44
+ maxTokens?: number;
45
+ }
46
+
47
+ /** The pi-ai `Models` collection of the application: providers, catalogs and credentials. */
48
+ export interface PiModelsProvider {
49
+ provide(): Promise<Models>;
50
+ /** The model of a `<provider>/<model id>` reference. Throws {@link PiModelNotFoundError}. */
51
+ resolve(ref: string): Promise<PiModel>;
52
+ }
53
+
54
+ /** Configures the `Models` collection once it is created: register providers, set credentials. */
55
+ export interface PiModelsContribution {
56
+ configure(models: Models): void | Promise<void>;
57
+ }
@@ -0,0 +1,53 @@
1
+ import { type Models, type PiAi, PiAiUtil } from '../pi';
2
+ import type { PiModelsContribution } from '../pi-protocol';
3
+
4
+ type FauxHandle = ReturnType<PiAi['fauxProvider']>;
5
+ type FauxStep = Parameters<FauxHandle['setResponses']>[0][number];
6
+ type FauxContext = Parameters<Extract<FauxStep, (...args: any[]) => any>>[0];
7
+
8
+ /** A scripted reply: assistant text, a call of a tool with its arguments, or an error of the model. */
9
+ export type FauxPiReply = string | { tool: string; args: Parameters<PiAi['fauxToolCall']>[1] } | { error: string };
10
+
11
+ /**
12
+ * A scripted model for tests, on pi-ai's faux provider: bind it as a {@link PiModelsContribution} and
13
+ * use {@link FauxPiModels.MODEL}. Each model request takes the next reply; `contexts` records the requests.
14
+ */
15
+ export class FauxPiModels implements PiModelsContribution {
16
+ static readonly MODEL = 'faux/faux-1';
17
+
18
+ static async create(): Promise<FauxPiModels> {
19
+ return new FauxPiModels(await PiAiUtil.load());
20
+ }
21
+
22
+ readonly contexts: FauxContext[] = [];
23
+
24
+ protected readonly faux: FauxHandle;
25
+
26
+ protected constructor(protected readonly ai: PiAi) {
27
+ this.faux = ai.fauxProvider({ provider: 'faux', models: [{ id: 'faux-1' }] });
28
+ }
29
+
30
+ configure(models: Models): void {
31
+ models.setProvider(this.faux.provider);
32
+ }
33
+
34
+ /** Replaces the scripted replies, one per model request. */
35
+ reply(...replies: FauxPiReply[]): void {
36
+ this.faux.setResponses(
37
+ replies.map(reply => (context: FauxContext) => {
38
+ this.contexts.push(context);
39
+ return this.toMessage(reply);
40
+ }),
41
+ );
42
+ }
43
+
44
+ protected toMessage(reply: FauxPiReply) {
45
+ if (typeof reply === 'string') {
46
+ return this.ai.fauxAssistantMessage(reply);
47
+ }
48
+ if ('error' in reply) {
49
+ return this.ai.fauxAssistantMessage('', { stopReason: 'error', errorMessage: reply.error });
50
+ }
51
+ return this.ai.fauxAssistantMessage(this.ai.fauxToolCall(reply.tool, reply.args), { stopReason: 'toolUse' });
52
+ }
53
+ }
@@ -0,0 +1,2 @@
1
+ export * from './faux-pi-models';
2
+ export * from './test-container';
@@ -0,0 +1,28 @@
1
+ import aiCoreModule from '@celljs/ai-core/lib/common/module';
2
+ import { autoBind, ContainerFactory, ContainerProvider, currentThis } from '@celljs/core';
3
+ import { coreTestModule } from '@celljs/core/lib/common/test/test-module';
4
+ import { PiModelsContribution, type PiOptions } from '../pi-protocol';
5
+ import { FauxPiModels } from './faux-pi-models';
6
+ import '../index';
7
+
8
+ const piModule = autoBind();
9
+
10
+ type Container = ReturnType<typeof ContainerFactory.create>;
11
+ type ContainerModule = Parameters<typeof ContainerFactory.create>[number];
12
+
13
+ export interface PiTestContainer {
14
+ container: Container;
15
+ faux: FauxPiModels;
16
+ }
17
+
18
+ /** A container with ai-core, this package and the scripted {@link FauxPiModels}. */
19
+ export async function createPiTestContainer(options: PiOptions = {}, ...modules: ContainerModule[]): Promise<PiTestContainer> {
20
+ currentThis.cellProps = { cell: { ai: { pi: options } } };
21
+ const faux = await FauxPiModels.create();
22
+ // ai-core's module is imported first, so it also holds the components of @celljs/core (autoBind() takes
23
+ // everything registered before it); core's test module then replaces their logger.
24
+ const container = ContainerFactory.create(aiCoreModule, coreTestModule, piModule, ...modules);
25
+ container.bind(PiModelsContribution).toConstantValue(faux);
26
+ ContainerProvider.set(container);
27
+ return { container, faux };
28
+ }