@kb-labs/adapters 0.5.0

package/packages/adapters-openai/src/llm.ts

@@ -0,0 +1,304 @@
+/**
+ * @module @kb-labs/adapters-openai/llm
+ * OpenAI implementation of ILLM interface.
+ */
+
+import OpenAI from "openai";
+import type {
+  ILLM,
+  LLMOptions,
+  LLMResponse,
+  LLMMessage,
+  LLMToolCallOptions,
+  LLMToolCallResponse,
+  LLMTool,
+  LLMToolCall,
+  LLMProtocolCapabilities,
+} from "@kb-labs/core-platform";
+
+/**
+ * Configuration for OpenAI LLM adapter.
+ */
+export interface OpenAILLMConfig {
+  /** OpenAI API key (defaults to OPENAI_API_KEY env var) */
+  apiKey?: string;
+  /** Base URL for API (optional, for proxies or Azure) */
+  baseURL?: string;
+  /** Default model to use */
+  defaultModel?: string;
+  /** Organization ID (optional) */
+  organization?: string;
+  /** Default max output tokens when caller does not specify. Overrides the API default (4096). */
+  defaultMaxTokens?: number;
+}
+
+/** Default max output tokens — avoids hitting the 4096 API default mid-response. */
+const DEFAULT_MAX_TOKENS = 16_384;
+
+/**
+ * OpenAI implementation of ILLM interface.
+ */
+export class OpenAILLM implements ILLM {
+  private client: OpenAI;
+  private defaultModel: string;
+  private defaultMaxTokens: number;
+
+  constructor(config: OpenAILLMConfig = {}) {
+    this.client = new OpenAI({
+      apiKey: config.apiKey ?? process.env.OPENAI_API_KEY,
+      baseURL: config.baseURL,
+      organization: config.organization,
+    });
+    this.defaultModel = config.defaultModel ?? "gpt-4o-mini";
+    this.defaultMaxTokens = config.defaultMaxTokens ?? DEFAULT_MAX_TOKENS;
+  }
+
+  getProtocolCapabilities(): LLMProtocolCapabilities {
+    return {
+      cache: {
+        supported: true,
+        protocol: "auto_prefix",
+        scopes: ["prefix", "segments"],
+      },
+      stream: {
+        supported: true,
+      },
+    };
+  }
+
+  private buildCacheRequestPatch(options?: LLMOptions): Record<string, unknown> {
+    const cache = options?.execution?.cache;
+    if (!cache) {
+      return {};
+    }
+
+    const patch: Record<string, unknown> = {
+      metadata: {
+        kb_cache_mode: cache.mode ?? "prefer",
+        kb_cache_scope: cache.scope ?? "prefix",
+      },
+    };
+
+    if (typeof cache.ttlSec === "number") {
+      (patch.metadata as Record<string, unknown>).kb_cache_ttl_sec = String(
+        cache.ttlSec,
+      );
+    }
+
+    if (cache.key) {
+      // Best-effort hint: supported by newer OpenAI prompt caching stacks.
+      patch.prompt_cache_key = cache.key;
+      (patch.metadata as Record<string, unknown>).kb_cache_key = cache.key;
+    }
+
+    return patch;
+  }
+
+  async complete(prompt: string, options?: LLMOptions): Promise<LLMResponse> {
+    const model = options?.model ?? this.defaultModel;
+    const messages: OpenAI.ChatCompletionMessageParam[] = [];
+
+    // Add system prompt if provided
+    if (options?.systemPrompt) {
+      messages.push({ role: "system", content: options.systemPrompt });
+    }
+
+    // Add user prompt
+    messages.push({ role: "user", content: prompt });
+
+    const response = await this.client.chat.completions.create({
+      model,
+      messages,
+      temperature: options?.temperature,
+      max_tokens: options?.maxTokens ?? this.defaultMaxTokens,
+      stop: options?.stop,
+      ...(this.buildCacheRequestPatch(options) as Record<string, unknown>),
+    });
+
+    const choice = response.choices[0];
+    const content = choice?.message?.content ?? "";
+
+    return {
+      content,
+      usage: {
+        promptTokens: response.usage?.prompt_tokens ?? 0,
+        completionTokens: response.usage?.completion_tokens ?? 0,
+        cacheReadTokens:
+          (response.usage as unknown as { prompt_tokens_details?: { cached_tokens?: number } })
+            ?.prompt_tokens_details?.cached_tokens ?? 0,
+        providerUsage: response.usage as unknown as Record<string, unknown>,
+      },
+      model: response.model,
+    };
+  }
+
+  async *stream(prompt: string, options?: LLMOptions): AsyncIterable<string> {
+    const model = options?.model ?? this.defaultModel;
+    const messages: OpenAI.ChatCompletionMessageParam[] = [];
+
+    // Add system prompt if provided
+    if (options?.systemPrompt) {
+      messages.push({ role: "system", content: options.systemPrompt });
+    }
+
+    // Add user prompt
+    messages.push({ role: "user", content: prompt });
+
+    const stream = await this.client.chat.completions.create({
+      model,
+      messages,
+      temperature: options?.temperature,
+      max_tokens: options?.maxTokens ?? this.defaultMaxTokens,
+      stop: options?.stop,
+      stream: true,
+      ...(this.buildCacheRequestPatch(options) as Record<string, unknown>),
+    });
+
+    for await (const chunk of stream) {
+      const content = chunk.choices[0]?.delta?.content;
+      if (content) {
+        yield content;
+      }
+    }
+  }
+
+  /**
+   * Chat with native tool calling support.
+   * Uses OpenAI's native function calling API.
+   */
+  // eslint-disable-next-line sonarjs/cognitive-complexity -- Complex due to OpenAI API format conversion (messages, tools, tool_choice)
+  async chatWithTools(
+    messages: LLMMessage[],
+    options: LLMToolCallOptions,
+  ): Promise<LLMToolCallResponse> {
+    const model = options?.model ?? this.defaultModel;
+
+    // Convert LLMMessage[] to OpenAI format
+    const openaiMessages: OpenAI.ChatCompletionMessageParam[] = messages.map(
+      (msg) => {
+        if (msg.role === "tool") {
+          return {
+            role: "tool" as const,
+            content: msg.content,
+            tool_call_id: msg.toolCallId || "",
+          };
+        }
+        if (msg.role === "assistant" && msg.toolCalls && msg.toolCalls.length > 0) {
+          // Assistant message with tool calls
+          return {
+            role: "assistant" as const,
+            content: msg.content || null,
+            tool_calls: msg.toolCalls.map((tc) => ({
+              id: tc.id,
+              type: "function" as const,
+              function: {
+                name: tc.name,
+                arguments: typeof tc.input === "string" ? tc.input : JSON.stringify(tc.input),
+              },
+            })),
+          };
+        }
+        return {
+          role: msg.role as "system" | "user" | "assistant",
+          content: msg.content,
+        };
+      },
+    );
+
+    // Convert LLMTool[] to OpenAI tools format
+    const tools: OpenAI.ChatCompletionTool[] = options.tools.map(
+      (tool: LLMTool) => ({
+        type: "function" as const,
+        function: {
+          name: tool.name,
+          description: tool.description,
+          parameters: tool.inputSchema,
+        },
+      }),
+    );
+
+    // Convert tool choice
+    let tool_choice: OpenAI.ChatCompletionToolChoiceOption | undefined;
+    if (options.toolChoice === "auto") {
+      tool_choice = "auto";
+    } else if (options.toolChoice === "required") {
+      tool_choice = "required";
+    } else if (options.toolChoice === "none") {
+      tool_choice = "none";
+    } else if (options.toolChoice && typeof options.toolChoice === "object") {
+      tool_choice = {
+        type: "function",
+        function: { name: options.toolChoice.function.name },
+      };
+    }
+
+    // Call OpenAI API
+    const response = await this.client.chat.completions.create({
+      model,
+      messages: openaiMessages,
+      tools,
+      tool_choice,
+      temperature: options?.temperature,
+      max_tokens: options?.maxTokens ?? this.defaultMaxTokens,
+      stop: options?.stop,
+      ...(this.buildCacheRequestPatch(options) as Record<string, unknown>),
+    });
+
+    const choice = response.choices[0];
+    const content = choice?.message?.content ?? "";
+
+    // Extract tool calls if any
+    const toolCalls: LLMToolCall[] = [];
+    if (choice?.message?.tool_calls) {
+      for (const tc of choice.message.tool_calls) {
+        try {
+          const input = JSON.parse(tc.function.arguments);
+          toolCalls.push({
+            id: tc.id,
+            name: tc.function.name,
+            input,
+          });
+        } catch (error) {
+          // Failed to parse tool arguments - skip this tool call
+          console.warn("Failed to parse tool arguments", {
+            toolName: tc.function.name,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+    }
+
+    // Map OpenAI finish_reason to normalized stopReason
+    const finishReason = choice?.finish_reason;
+    const stopReason = finishReason === 'stop' ? 'end_turn'
+      : finishReason === 'tool_calls' ? 'tool_use'
+      : finishReason === 'length' ? 'max_tokens'
+      : finishReason ?? undefined;
+
+    return {
+      content,
+      usage: {
+        promptTokens: response.usage?.prompt_tokens ?? 0,
+        completionTokens: response.usage?.completion_tokens ?? 0,
+        cacheReadTokens:
+          (response.usage as unknown as { prompt_tokens_details?: { cached_tokens?: number } })
+            ?.prompt_tokens_details?.cached_tokens ?? 0,
+        providerUsage: response.usage as unknown as Record<string, unknown>,
+      },
+      model: response.model,
+      toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+      stopReason,
+    };
+  }
+}
+
+/**
+ * Create OpenAI LLM adapter.
+ * This is the factory function called by initPlatform() when loading adapters.
+ */
+export function createAdapter(config?: OpenAILLMConfig): OpenAILLM {
+  return new OpenAILLM(config);
+}
+
+// Default export for direct import
+export default createAdapter;

package/packages/adapters-openai/src/manifest.ts

@@ -0,0 +1,47 @@
+/**
+ * @module @kb-labs/adapters-openai/manifest
+ * Adapter manifest for OpenAI LLM.
+ */
+
+import type { AdapterManifest } from "@kb-labs/core-platform";
+
+/**
+ * Adapter manifest for OpenAI LLM.
+ */
+export const manifest: AdapterManifest = {
+  manifestVersion: "1.0.0",
+  id: "openai-llm",
+  name: "OpenAI LLM",
+  version: "1.0.0",
+  description: "OpenAI language model adapter (GPT-4, GPT-3.5, etc.)",
+  author: "KB Labs Team",
+  license: "KBPL-1.1",
+  type: "core",
+  implements: "ILLM",
+  capabilities: {
+    streaming: true,
+    custom: {
+      functionCalling: true,
+    },
+  },
+  configSchema: {
+    apiKey: {
+      type: "string",
+      description: "OpenAI API key (defaults to OPENAI_API_KEY env var)",
+    },
+    model: {
+      type: "string",
+      default: "gpt-4o",
+      description: "Model to use (gpt-4o, gpt-4-turbo, gpt-3.5-turbo, etc.)",
+    },
+    temperature: {
+      type: "number",
+      default: 0.7,
+      description: "Sampling temperature (0.0 to 2.0)",
+    },
+    maxTokens: {
+      type: "number",
+      description: "Maximum tokens to generate",
+    },
+  },
+};

package/packages/adapters-openai/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/packages/adapters-openai/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/packages/adapters-openai/tsup.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  dts: true,
+});

package/packages/adapters-pino/README.md

@@ -0,0 +1,152 @@
+# @kb-labs/adapters-pino
+
+> Part of [KB Labs](https://github.com/KirillBaranov/kb-labs) ecosystem. Works exclusively within KB Labs platform.
+
+Production-ready structured logger based on Pino with streaming and analytics integration.
+
+## Overview
+
+| Property | Value |
+|----------|-------|
+| **Implements** | `ILogger` |
+| **Type** | `core` |
+| **Requires** | None (optional: `analytics`) |
+| **Category** | Logging |
+
+## Features
+
+- **Structured Logging** - JSON-formatted logs with context
+- **High Performance** - Built on Pino (fastest Node.js logger)
+- **Log Levels** - trace, debug, info, warn, error, fatal
+- **Pretty Printing** - Human-readable output for development
+- **Streaming Support** - Buffered log streaming
+
+## Installation
+
+```bash
+pnpm add @kb-labs/adapters-pino
+```
+
+## Configuration
+
+Add to your `kb.config.json`:
+
+```json
+{
+  "platform": {
+    "adapters": {
+      "logger": "@kb-labs/adapters-pino"
+    },
+    "adapterOptions": {
+      "logger": {
+        "level": "info",
+        "pretty": false,
+        "streaming": {
+          "enabled": true,
+          "bufferSize": 1000,
+          "bufferMaxAge": 3600000
+        }
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `level` | `string` | `"info"` | Minimum log level |
+| `pretty` | `boolean` | `false` | Enable pretty printing for development |
+| `streaming.enabled` | `boolean` | `false` | Enable log streaming/buffering |
+| `streaming.bufferSize` | `number` | `1000` | Buffer size for streaming |
+| `streaming.bufferMaxAge` | `number` | `3600000` | Max age of buffered logs (1 hour) |
+
+## Usage
+
+### Via Platform (Recommended)
+
+```typescript
+import { usePlatform } from '@kb-labs/sdk';
+
+const platform = usePlatform();
+
+// Basic logging
+platform.logger.info('Server started', { port: 3000 });
+platform.logger.error('Request failed', { error, requestId });
+
+// With child logger
+const reqLogger = platform.logger.child({ requestId: 'req-123' });
+reqLogger.info('Processing request');
+```
+
+### Standalone (Testing/Development)
+
+```typescript
+import { createAdapter } from '@kb-labs/adapters-pino';
+
+const logger = createAdapter({
+  level: 'debug',
+  pretty: true
+});
+
+logger.info('Hello, world!');
+```
+
+## Adapter Manifest
+
+```typescript
+{
+  id: 'pino-logger',
+  name: 'Pino Logger',
+  version: '1.0.0',
+  implements: 'ILogger',
+  optional: {
+    adapters: ['analytics'],
+  },
+  capabilities: {
+    streaming: true,
+  },
+}
+```
+
+## Log Levels
+
+| Level | When to use |
+|-------|-------------|
+| `trace` | Very detailed debugging info |
+| `debug` | Debugging information |
+| `info` | General operational events |
+| `warn` | Warning conditions |
+| `error` | Error conditions |
+| `fatal` | System is unusable |
+
+## FAQ
+
+<details>
+<summary><strong>Q: How do I enable pretty printing in development?</strong></summary>
+
+Set `pretty: true` in config or use environment:
+
+```bash
+KB_LOG_PRETTY=true pnpm dev
+```
+</details>
+
+<details>
+<summary><strong>Q: How do I send logs to remote service?</strong></summary>
+
+Use `@kb-labs/adapters-pino-http` as a transport to stream logs to REST API.
+</details>
+
+## Related Adapters
+
+| Adapter | Use Case |
+|---------|----------|
+| `@kb-labs/adapters-pino-http` | HTTP transport for remote logging |
+| `@kb-labs/adapters-log-ringbuffer` | In-memory log streaming |
+| `@kb-labs/adapters-log-sqlite` | Persistent log storage |
+
+## License
+
+[KB Public License v1.1](../../LICENSE) - KB Labs Team

package/packages/adapters-pino/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];

package/packages/adapters-pino/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kb-labs/adapters-pino",
+  "version": "0.5.0",
+  "description": "Pino adapter implementing ILogger interface",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "pino": "^9.0.0"
+  },
+  "peerDependencies": {
+    "@kb-labs/core-platform": "*"
+  },
+  "devDependencies": {
+    "@kb-labs/core-platform": "link:../../../../platform/kb-labs-core/packages/core-platform",
+    "@types/node": "^24.3.3",
+    "eslint": "^9",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "rimraf": "^6.0.1"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}

package/packages/adapters-pino/src/index.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from 'vitest';
+import { PinoLoggerAdapter } from './index.js';
+
+describe('PinoLoggerAdapter', () => {
+  it('includes child bindings in onLog records', () => {
+    const logger = new PinoLoggerAdapter({ level: 'debug' });
+    const callback = vi.fn();
+    logger.onLog(callback);
+
+    const child = logger.child({
+      traceId: 'trace-1',
+      requestId: 'req-1',
+      invocationId: 'inv-1',
+    });
+
+    child.info('hello', { step: 'start' });
+
+    expect(callback).toHaveBeenCalledTimes(1);
+    const [record] = callback.mock.calls[0]!;
+    expect(record.fields).toMatchObject({
+      traceId: 'trace-1',
+      requestId: 'req-1',
+      invocationId: 'inv-1',
+      step: 'start',
+    });
+  });
+
+  it('propagates nested child bindings in onLog records', () => {
+    const logger = new PinoLoggerAdapter({ level: 'debug' });
+    const callback = vi.fn();
+    logger.onLog(callback);
+
+    const child = logger.child({ traceId: 'trace-1' }).child({ spanId: 'span-2' });
+    child.debug('nested');
+
+    expect(callback).toHaveBeenCalledTimes(1);
+    const [record] = callback.mock.calls[0]!;
+    expect(record.fields).toMatchObject({
+      traceId: 'trace-1',
+      spanId: 'span-2',
+    });
+  });
+});
+