@core-ai/core-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Omnifact (https://omnifact.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @core-ai/core-ai
+
+Type-safe LLM abstraction layer over native provider SDKs.
+
+## Installation
+
+```bash
+npm install @core-ai/core-ai
+```
+
+Provider packages are published separately:
+
+- `@core-ai/openai`
+- `@core-ai/anthropic`
+- `@core-ai/google-genai`
+
+## Usage
+
+```ts
+import { generate } from '@core-ai/core-ai';
+import { createOpenAI } from '@core-ai/openai';
+
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+const model = openai.chatModel('gpt-5-mini');
+
+const result = await generate({
+    model,
+    messages: [{ role: 'user', content: 'Hello!' }],
+});
+
+console.log(result.content);
+```

package/dist/index.d.ts

@@ -0,0 +1,208 @@
+import { z } from 'zod';
+
+type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
+type SystemMessage = {
+    role: 'system';
+    content: string;
+};
+type UserMessage = {
+    role: 'user';
+    content: string | UserContentPart[];
+};
+type UserContentPart = TextPart | ImagePart | FilePart;
+type TextPart = {
+    type: 'text';
+    text: string;
+};
+type ImagePart = {
+    type: 'image';
+    source: {
+        type: 'base64';
+        mediaType: string;
+        data: string;
+    } | {
+        type: 'url';
+        url: string;
+    };
+};
+type FilePart = {
+    type: 'file';
+    data: string;
+    mimeType: string;
+    filename?: string;
+};
+type AssistantMessage = {
+    role: 'assistant';
+    content: string | null;
+    toolCalls?: ToolCall[];
+};
+type ToolCall = {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+};
+type ToolResultMessage = {
+    role: 'tool';
+    toolCallId: string;
+    content: string;
+    isError?: boolean;
+};
+type ToolDefinition = {
+    name: string;
+    description: string;
+    parameters: z.ZodType;
+};
+type ToolSet = Record<string, ToolDefinition>;
+type ToolChoice = 'auto' | 'none' | 'required' | {
+    type: 'tool';
+    toolName: string;
+};
+type ChatModel = {
+    readonly provider: string;
+    readonly modelId: string;
+    generate(options: GenerateOptions): Promise<GenerateResult>;
+    stream(options: GenerateOptions): Promise<StreamResult>;
+};
+type ModelConfig = {
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    stopSequences?: string[];
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+};
+type GenerateOptions = {
+    messages: Message[];
+    tools?: ToolSet;
+    toolChoice?: ToolChoice;
+    config?: ModelConfig;
+    providerOptions?: Record<string, unknown>;
+    signal?: AbortSignal;
+};
+type GenerateResult = {
+    content: string | null;
+    toolCalls: ToolCall[];
+    finishReason: FinishReason;
+    usage: ChatUsage;
+};
+type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'unknown';
+/**
+ * Token usage reported by the model after a chat completion.
+ *
+ * `outputTokens` is the **total** output token count, including both visible
+ * text and any internal reasoning/thinking the model performed.
+ * `reasoningTokens` is the subset of `outputTokens` consumed by reasoning.
+ * For non-reasoning models (or providers that don't report it separately)
+ * this will be `0`.
+ *
+ * Provider mapping:
+ * - **OpenAI**: `reasoningTokens` comes from `completion_tokens_details.reasoning_tokens`.
+ * - **Google Gemini**: `reasoningTokens` comes from `thoughtsTokenCount`;
+ *   `outputTokens` = `candidatesTokenCount + thoughtsTokenCount`.
+ * - **Anthropic**: `reasoningTokens` is always `0` (thinking tokens are
+ *   included in `output_tokens` but not reported separately by the API).
+ */
+type ChatUsage = {
+    /** Number of tokens in the input prompt. */
+    inputTokens: number;
+    /** Total output tokens, including both visible text and reasoning. */
+    outputTokens: number;
+    /** Tokens consumed by internal reasoning/thinking. Subset of `outputTokens`. */
+    reasoningTokens: number;
+    /** Sum of all tokens (`inputTokens + outputTokens`). */
+    totalTokens: number;
+};
+type StreamEvent = {
+    type: 'content-delta';
+    text: string;
+} | {
+    type: 'tool-call-start';
+    toolCallId: string;
+    toolName: string;
+} | {
+    type: 'tool-call-delta';
+    toolCallId: string;
+    argumentsDelta: string;
+} | {
+    type: 'tool-call-end';
+    toolCall: ToolCall;
+} | {
+    type: 'finish';
+    finishReason: FinishReason;
+    usage: ChatUsage;
+};
+type StreamResult = AsyncIterable<StreamEvent> & {
+    toResponse(): Promise<GenerateResult>;
+};
+type EmbeddingModel = {
+    readonly provider: string;
+    readonly modelId: string;
+    embed(options: EmbedOptions): Promise<EmbedResult>;
+};
+type EmbedOptions = {
+    input: string | string[];
+    dimensions?: number;
+    providerOptions?: Record<string, unknown>;
+};
+type EmbedResult = {
+    embeddings: number[][];
+    usage: EmbeddingUsage;
+};
+type EmbeddingUsage = {
+    inputTokens: number;
+};
+type ImageModel = {
+    readonly provider: string;
+    readonly modelId: string;
+    generate(options: ImageGenerateOptions): Promise<ImageGenerateResult>;
+};
+type ImageGenerateOptions = {
+    prompt: string;
+    n?: number;
+    size?: string;
+    providerOptions?: Record<string, unknown>;
+};
+type ImageGenerateResult = {
+    images: GeneratedImage[];
+};
+type GeneratedImage = {
+    base64?: string;
+    url?: string;
+    revisedPrompt?: string;
+};
+
+declare class LLMError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+declare class ProviderError extends LLMError {
+    readonly provider: string;
+    readonly statusCode?: number;
+    constructor(message: string, provider: string, statusCode?: number, cause?: unknown);
+}
+
+declare function defineTool(options: ToolDefinition): ToolDefinition;
+
+type GenerateParams = GenerateOptions & {
+    model: ChatModel;
+};
+declare function generate(params: GenerateParams): Promise<GenerateResult>;
+
+type StreamParams = GenerateOptions & {
+    model: ChatModel;
+};
+declare function stream(params: StreamParams): Promise<StreamResult>;
+
+declare function createStreamResult(source: AsyncIterable<StreamEvent>): StreamResult;
+
+type EmbedParams = EmbedOptions & {
+    model: EmbeddingModel;
+};
+declare function embed(params: EmbedParams): Promise<EmbedResult>;
+
+type GenerateImageParams = ImageGenerateOptions & {
+    model: ImageModel;
+};
+declare function generateImage(params: GenerateImageParams): Promise<ImageGenerateResult>;
+
+export { type AssistantMessage, type ChatModel, type ChatUsage, type EmbedOptions, type EmbedResult, type EmbeddingModel, type EmbeddingUsage, type FilePart, type FinishReason, type GenerateOptions, type GenerateResult, type GeneratedImage, type ImageGenerateOptions, type ImageGenerateResult, type ImageModel, type ImagePart, LLMError, type Message, type ModelConfig, ProviderError, type StreamEvent, type StreamResult, type SystemMessage, type TextPart, type ToolCall, type ToolChoice, type ToolDefinition, type ToolResultMessage, type ToolSet, type UserContentPart, type UserMessage, createStreamResult, defineTool, embed, generate, generateImage, stream };

package/dist/index.js

@@ -0,0 +1,132 @@
+// src/errors.ts
+var LLMError = class extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "LLMError";
+    this.cause = cause;
+  }
+};
+var ProviderError = class extends LLMError {
+  provider;
+  statusCode;
+  constructor(message, provider, statusCode, cause) {
+    super(message, cause);
+    this.name = "ProviderError";
+    this.provider = provider;
+    this.statusCode = statusCode;
+  }
+};
+
+// src/tool.ts
+import { zodToJsonSchema } from "zod-to-json-schema";
+function defineTool(options) {
+  return options;
+}
+
+// src/generate.ts
+async function generate(params) {
+  if (params.messages.length === 0) {
+    throw new LLMError("messages must not be empty");
+  }
+  const { model, ...options } = params;
+  return model.generate(options);
+}
+
+// src/stream-chat.ts
+async function stream(params) {
+  if (params.messages.length === 0) {
+    throw new LLMError("messages must not be empty");
+  }
+  const { model, ...options } = params;
+  return model.stream(options);
+}
+
+// src/stream.ts
+function createStreamResult(source) {
+  let resolveResponse;
+  const responsePromise = new Promise((resolve) => {
+    resolveResponse = resolve;
+  });
+  let iteratorCreated = false;
+  async function* iterate() {
+    let content = "";
+    const toolCalls = [];
+    let finishReason = "unknown";
+    let usage = {
+      inputTokens: 0,
+      outputTokens: 0,
+      reasoningTokens: 0,
+      totalTokens: 0
+    };
+    for await (const event of source) {
+      if (event.type === "content-delta") {
+        content += event.text;
+      } else if (event.type === "tool-call-end") {
+        toolCalls.push(event.toolCall);
+      } else if (event.type === "finish") {
+        finishReason = event.finishReason;
+        usage = event.usage;
+      }
+      yield event;
+    }
+    resolveResponse?.({
+      content: content.length > 0 ? content : null,
+      toolCalls,
+      finishReason,
+      usage
+    });
+  }
+  const generator = iterate();
+  return {
+    [Symbol.asyncIterator]() {
+      if (iteratorCreated) {
+        throw new Error("Stream can only be iterated once");
+      }
+      iteratorCreated = true;
+      return generator;
+    },
+    toResponse() {
+      if (!iteratorCreated) {
+        iteratorCreated = true;
+        (async () => {
+          for await (const _event of generator) {
+          }
+        })();
+      }
+      return responsePromise;
+    }
+  };
+}
+
+// src/embed.ts
+async function embed(params) {
+  const { input } = params;
+  if (typeof input === "string" && input.length === 0) {
+    throw new LLMError("input must not be empty");
+  }
+  if (Array.isArray(input) && input.length === 0) {
+    throw new LLMError("input must not be empty");
+  }
+  const { model, ...options } = params;
+  return model.embed(options);
+}
+
+// src/generate-image.ts
+async function generateImage(params) {
+  if (params.prompt.length === 0) {
+    throw new LLMError("prompt must not be empty");
+  }
+  const { model, ...options } = params;
+  return model.generate(options);
+}
+export {
+  LLMError,
+  ProviderError,
+  createStreamResult,
+  defineTool,
+  embed,
+  generate,
+  generateImage,
+  stream
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@core-ai/core-ai",
+    "version": "0.1.0",
+    "description": "Type-safe LLM abstraction layer over native provider SDKs",
+    "license": "MIT",
+    "author": "Omnifact (https://omnifact.ai)",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/agdevhq/ai-core.git",
+        "directory": "packages/core-ai"
+    },
+    "keywords": ["llm", "ai", "sdk", "openai", "anthropic", "google-genai"],
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": ["dist", "README.md", "LICENSE"],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "tsup",
+        "lint": "eslint src/ --max-warnings 0",
+        "check-types": "tsc --noEmit",
+        "prepublishOnly": "npm run build",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "dependencies": {
+        "zod": "^3.25.76",
+        "zod-to-json-schema": "^3.24.5"
+    },
+    "devDependencies": {
+        "@core-ai/eslint-config": "^0.0.0",
+        "@core-ai/typescript-config": "^0.0.0",
+        "typescript": "^5.7.3",
+        "vitest": "^3.2.4"
+    }
+}