@mariozechner/pi-ai 0.5.10

package/README.md

@@ -0,0 +1,231 @@
+# @mariozechner/pi-ai
+
+Unified LLM API with automatic model discovery, provider configuration, token and cost tracking, and simple context persistence and hand-off to other models mid-session.
+
+## Supported Providers
+
+- **OpenAI**
+- **Anthropic**
+- **Google**
+- **Groq**
+- **Cerebras**
+- **xAI**
+- **OpenRouter**
+- **Any OpenAI-compatible API**: Ollama, vLLM, LM Studio, etc.
+
+## Installation
+
+```bash
+npm install @mariozechner/pi-ai
+```
+
+## Quick Start
+
+```typescript
+import { createLLM } from '@mariozechner/pi-ai';
+
+const llm = createLLM('openai', 'gpt-4o-mini');
+
+const response = await llm.complete({
+  messages: [{ role: 'user', content: 'Hello!' }]
+});
+
+console.log(response.content);
+```
+
+## Image Input
+
+```typescript
+import { readFileSync } from 'fs';
+
+const imageBuffer = readFileSync('image.png');
+const base64Image = imageBuffer.toString('base64');
+
+const response = await llm.complete({
+  messages: [{
+    role: 'user',
+    content: [
+      { type: 'text', text: 'What is in this image?' },
+      { type: 'image', data: base64Image, mimeType: 'image/png' }
+    ]
+  }]
+});
+```
+
+## Tool Calling
+
+```typescript
+const tools = [{
+  name: 'get_weather',
+  description: 'Get current weather for a location',
+  parameters: {
+    type: 'object',
+    properties: {
+      location: { type: 'string' }
+    },
+    required: ['location']
+  }
+}];
+
+const messages = [];
+messages.push({ role: 'user', content: 'What is the weather in Paris?' });
+
+const response = await llm.complete({ messages, tools });
+messages.push(response);
+
+if (response.toolCalls) {
+  for (const call of response.toolCalls) {
+    // Call your actual function
+    const result = await getWeather(call.arguments.location);
+    
+    // Add tool result to context
+    messages.push({ 
+      role: 'toolResult', 
+      content: JSON.stringify(result), 
+      toolCallId: call.id, 
+      isError: false 
+    });
+  }
+  
+  // Continue conversation with tool results
+  const followUp = await llm.complete({ messages, tools });
+  messages.push(followUp);
+  console.log(followUp.content);
+}
+```
+
+## Streaming
+
+```typescript
+const response = await llm.complete({
+  messages: [{ role: 'user', content: 'Write a story' }]
+}, {
+  onText: (chunk, complete) => {
+    process.stdout.write(chunk);
+    if (complete) console.log('\n[Text streaming complete]');
+  },
+  onThinking: (chunk, complete) => {
+    process.stderr.write(chunk);
+    if (complete) console.error('\n[Thinking complete]');
+  }
+});
+```
+
+## Abort Signal
+
+```typescript
+const controller = new AbortController();
+
+// Abort after 5 seconds
+setTimeout(() => controller.abort(), 5000);
+
+try {
+  const response = await llm.complete({
+    messages: [{ role: 'user', content: 'Write a long story' }]
+  }, {
+    signal: controller.signal,
+    onText: (chunk) => process.stdout.write(chunk)
+  });
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log('Request was aborted');
+  }
+}
+```
+
+## Provider-Specific Options
+
+### OpenAI Reasoning (o1, o3)
+```typescript
+const llm = createLLM('openai', 'o1-mini');
+
+await llm.complete(context, {
+  reasoningEffort: 'medium'  // 'minimal' | 'low' | 'medium' | 'high'
+});
+```
+
+### Anthropic Thinking
+```typescript
+const llm = createLLM('anthropic', 'claude-3-7-sonnet-latest');
+
+await llm.complete(context, {
+  thinking: {
+    enabled: true,
+    budgetTokens: 2048  // Optional thinking token limit
+  }
+});
+```
+
+### Google Gemini Thinking
+```typescript
+const llm = createLLM('google', 'gemini-2.0-flash-thinking-exp');
+
+await llm.complete(context, {
+  thinking: { enabled: true }
+});
+```
+
+## Custom Models
+
+### Local Models (Ollama, vLLM, etc.)
+```typescript
+import { OpenAICompletionsLLM } from '@mariozechner/pi-ai';
+
+const model = {
+  id: 'llama3.1:8b',
+  provider: 'ollama',
+  baseUrl: 'http://localhost:11434/v1',
+  reasoning: false,
+  input: ['text'],
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: 8192,
+  maxTokens: 4096,
+  name: 'Llama 3.1 8B'
+};
+
+const llm = new OpenAICompletionsLLM(model, 'dummy-key');
+```
+
+### Custom OpenAI-Compatible Endpoints
+```typescript
+const model = {
+  id: 'custom-model',
+  provider: 'custom',
+  baseUrl: 'https://your-api.com/v1',
+  reasoning: true,
+  input: ['text', 'image'],
+  cost: { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: 32768,
+  maxTokens: 8192,
+  name: 'Custom Model'
+};
+
+const llm = new OpenAICompletionsLLM(model, 'your-api-key');
+```
+
+## Environment Variables
+
+Set these environment variables to use `createLLM` without passing API keys:
+
+```bash
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GEMINI_API_KEY=...
+GROQ_API_KEY=gsk_...
+CEREBRAS_API_KEY=csk-...
+XAI_API_KEY=xai-...
+OPENROUTER_API_KEY=sk-or-...
+```
+
+When set, you can omit the API key parameter:
+```typescript
+// Uses OPENAI_API_KEY from environment
+const llm = createLLM('openai', 'gpt-4o-mini');
+
+// Or pass explicitly
+const llm = createLLM('openai', 'gpt-4o-mini', 'sk-...');
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export declare const version = "0.5.8";
+export { PROVIDERS } from "./models.generated.js";
+export { type AnthropicModel, type CerebrasModel, createLLM, type GoogleModel, type GroqModel, type Model, type OpenAIModel, type OpenRouterModel, PROVIDER_CONFIG, type ProviderModels, type ProviderToLLM, type XAIModel, } from "./models.js";
+export { AnthropicLLM } from "./providers/anthropic.js";
+export { GoogleLLM } from "./providers/google.js";
+export { OpenAICompletionsLLM } from "./providers/openai-completions.js";
+export { OpenAIResponsesLLM } from "./providers/openai-responses.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,SAAS,EACT,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,QAAQ,GACb,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAGrE,mBAAmB,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+// @mariozechner/pi-ai - Unified LLM API with automatic model discovery
+// This package provides a common interface for working with multiple LLM providers
+export const version = "0.5.8";
+// Export generated models data
+export { PROVIDERS } from "./models.generated.js";
+// Export models utilities and types
+export { createLLM, PROVIDER_CONFIG, } from "./models.js";
+// Export providers
+export { AnthropicLLM } from "./providers/anthropic.js";
+export { GoogleLLM } from "./providers/google.js";
+export { OpenAICompletionsLLM } from "./providers/openai-completions.js";
+export { OpenAIResponsesLLM } from "./providers/openai-responses.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,mFAAmF;AAEnF,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,+BAA+B;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,oCAAoC;AACpC,OAAO,EAGN,SAAS,EAMT,eAAe,GAIf,MAAM,aAAa,CAAC;AAErB,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/models.d.ts

@@ -0,0 +1,72 @@
+import { PROVIDERS } from "./models.generated.js";
+import { AnthropicLLM } from "./providers/anthropic.js";
+import { GoogleLLM } from "./providers/google.js";
+import { OpenAICompletionsLLM } from "./providers/openai-completions.js";
+import { OpenAIResponsesLLM } from "./providers/openai-responses.js";
+import type { Model, Usage } from "./types.js";
+export declare const PROVIDER_CONFIG: {
+    readonly google: {
+        readonly envKey: "GEMINI_API_KEY";
+        readonly create: (model: Model, apiKey: string) => GoogleLLM;
+    };
+    readonly openai: {
+        readonly envKey: "OPENAI_API_KEY";
+        readonly create: (model: Model, apiKey: string) => OpenAIResponsesLLM;
+    };
+    readonly anthropic: {
+        readonly envKey: "ANTHROPIC_API_KEY";
+        readonly create: (model: Model, apiKey: string) => AnthropicLLM;
+    };
+    readonly xai: {
+        readonly envKey: "XAI_API_KEY";
+        readonly create: (model: Model, apiKey: string) => OpenAICompletionsLLM;
+    };
+    readonly groq: {
+        readonly envKey: "GROQ_API_KEY";
+        readonly create: (model: Model, apiKey: string) => OpenAICompletionsLLM;
+    };
+    readonly cerebras: {
+        readonly envKey: "CEREBRAS_API_KEY";
+        readonly create: (model: Model, apiKey: string) => OpenAICompletionsLLM;
+    };
+    readonly openrouter: {
+        readonly envKey: "OPENROUTER_API_KEY";
+        readonly create: (model: Model, apiKey: string) => OpenAICompletionsLLM;
+    };
+};
+export type ProviderToLLM = {
+    google: GoogleLLM;
+    openai: OpenAIResponsesLLM;
+    anthropic: AnthropicLLM;
+    xai: OpenAICompletionsLLM;
+    groq: OpenAICompletionsLLM;
+    cerebras: OpenAICompletionsLLM;
+    openrouter: OpenAICompletionsLLM;
+};
+export type GoogleModel = keyof typeof PROVIDERS.google.models;
+export type OpenAIModel = keyof typeof PROVIDERS.openai.models;
+export type AnthropicModel = keyof typeof PROVIDERS.anthropic.models;
+export type XAIModel = keyof typeof PROVIDERS.xai.models;
+export type GroqModel = keyof typeof PROVIDERS.groq.models;
+export type CerebrasModel = keyof typeof PROVIDERS.cerebras.models;
+export type OpenRouterModel = keyof typeof PROVIDERS.openrouter.models;
+export type ProviderModels = {
+    google: GoogleModel;
+    openai: OpenAIModel;
+    anthropic: AnthropicModel;
+    xai: XAIModel;
+    groq: GroqModel;
+    cerebras: CerebrasModel;
+    openrouter: OpenRouterModel;
+};
+export declare function createLLM<P extends keyof typeof PROVIDERS, M extends keyof (typeof PROVIDERS)[P]["models"]>(provider: P, model: M, apiKey?: string): ProviderToLLM[P];
+export declare function getModel<P extends keyof typeof PROVIDERS>(provider: P, modelId: keyof (typeof PROVIDERS)[P]["models"]): Model | undefined;
+export declare function calculateCost(model: Model, usage: Usage): {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+};
+export type { Model };
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAG/C,eAAO,MAAM,eAAe;;;iCAGV,KAAK,UAAU,MAAM;;;;iCAIrB,KAAK,UAAU,MAAM;;;;iCAIrB,KAAK,UAAU,MAAM;;;;iCAIrB,KAAK,UAAU,MAAM;;;;iCAIrB,KAAK,UAAU,MAAM;;;;iCAIrB,KAAK,UAAU,MAAM;;;;iCAIrB,KAAK,UAAU,MAAM;;CAE7B,CAAC;AAGX,MAAM,MAAM,aAAa,GAAG;IAC3B,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,SAAS,EAAE,YAAY,CAAC;IACxB,GAAG,EAAE,oBAAoB,CAAC;IAC1B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,UAAU,EAAE,oBAAoB,CAAC;CACjC,CAAC;AAGF,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC;AAC/D,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC;AAC/D,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC;AACrE,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC;AACzD,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC;AACnE,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC;AAGvE,MAAM,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,cAAc,CAAC;IAC1B,GAAG,EAAE,QAAQ,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,UAAU,EAAE,eAAe,CAAC;CAC5B,CAAC;AAGF,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,OAAO,SAAS,EAAE,CAAC,SAAS,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAC1G,QAAQ,EAAE,CAAC,EACX,KAAK,EAAE,CAAC,EACR,MAAM,CAAC,EAAE,MAAM,GACb,aAAa,CAAC,CAAC,CAAC,CAgBlB;AAGD,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,OAAO,SAAS,EACxD,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAC5C,KAAK,GAAG,SAAS,CAKnB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;;;;;;EAOvD;AAGD,YAAY,EAAE,KAAK,EAAE,CAAC"}