@namzu/sdk 0.1.1

package/src/provider/factory.ts

@@ -0,0 +1,173 @@
+import type {
+  ChatCompletionParams,
+  ChatCompletionResponse,
+  LLMProvider,
+  MockProviderConfig,
+  ProviderCapabilities,
+  ProviderFactoryConfig,
+  ProviderFactoryResult,
+  ProviderType,
+  StreamChunk,
+} from '../types/provider/index.js'
+import type { TokenUsage } from '../types/common/index.js'
+import { OpenRouterProvider } from './openrouter/client.js'
+import { BedrockProvider } from './bedrock/client.js'
+
+const FALLBACK_MOCK_MODEL = 'mock-model'
+
+class MockLLMProvider implements LLMProvider {
+  readonly id = 'mock'
+  readonly name = 'Mock LLM Provider'
+
+  private readonly model: string
+  private readonly responseText: string
+  private readonly responseDelayMs: number
+
+  constructor(config: MockProviderConfig) {
+    this.model = config.model ?? FALLBACK_MOCK_MODEL
+    this.responseText = config.responseText ?? 'Mock provider response'
+    this.responseDelayMs = config.responseDelayMs ?? 0
+  }
+
+  private buildUsage(): TokenUsage {
+    return {
+      promptTokens: 0,
+      completionTokens: 0,
+      totalTokens: 0,
+      cachedTokens: 0,
+      cacheWriteTokens: 0,
+    }
+  }
+
+  private async delay(): Promise<void> {
+    if (this.responseDelayMs <= 0) return
+    await new Promise((resolve) => setTimeout(resolve, this.responseDelayMs))
+  }
+
+  private normalizeResponse(params: ChatCompletionParams, message: string): ChatCompletionResponse {
+    return {
+      id: `mock-${Date.now()}-${Math.floor(Math.random() * 1_000_000)}`,
+      model: params.model ?? this.model,
+      message: {
+        role: 'assistant',
+        content: message,
+      },
+      finishReason: 'stop',
+      usage: this.buildUsage(),
+    }
+  }
+
+  async chat(params: ChatCompletionParams): Promise<ChatCompletionResponse> {
+    await this.delay()
+    return this.normalizeResponse(params, this.responseText)
+  }
+
+  async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+    const response = await this.chat(params)
+    const content = response.message.content ?? ''
+    const chunkSize = 8
+
+    for (let i = 0; i < content.length; i += chunkSize) {
+      yield {
+        id: response.id,
+        delta: {
+          content: content.slice(i, i + chunkSize),
+        },
+      }
+    }
+
+    yield {
+      id: response.id,
+      delta: {},
+      finishReason: 'stop',
+      usage: response.usage,
+    }
+  }
+
+  async listModels() {
+    return [
+      {
+        id: this.model,
+        name: 'Mock Model',
+        contextWindow: 32_000,
+        maxOutputTokens: 8_000,
+        inputPrice: 0,
+        outputPrice: 0,
+        supportsToolUse: false,
+        supportsStreaming: true,
+      },
+    ]
+  }
+
+  async healthCheck() {
+    await this.delay()
+    return true
+  }
+}
+
+const PROVIDER_CAPABILITIES: Record<ProviderType, ProviderCapabilities> = {
+  openrouter: {
+    supportsTools: true,
+    supportsStreaming: true,
+    supportsFunctionCalling: true,
+  },
+  bedrock: {
+    supportsTools: true,
+    supportsStreaming: true,
+    supportsFunctionCalling: true,
+  },
+  mock: {
+    supportsTools: false,
+    supportsStreaming: true,
+    supportsFunctionCalling: false,
+  },
+}
+
+export class UnknownProviderError extends Error {
+  readonly providerType: string
+
+  constructor(providerType: string) {
+    super(`Unsupported provider type: ${providerType}`)
+    this.name = 'UnknownProviderError'
+    this.providerType = providerType
+  }
+}
+
+export class ProviderFactory {
+  static create(config: ProviderFactoryConfig): ProviderFactoryResult {
+    const provider = this.createProvider(config)
+    const capabilities = this.getCapabilities(config.type)
+    return { provider, capabilities }
+  }
+
+  static createProvider(config: ProviderFactoryConfig): LLMProvider {
+    if (config.type === 'openrouter') {
+      const { type, ...openrouterConfig } = config
+      return new OpenRouterProvider(openrouterConfig)
+    }
+    if (config.type === 'bedrock') {
+      const { type, ...bedrockConfig } = config
+      return new BedrockProvider(bedrockConfig)
+    }
+    if (config.type === 'mock') {
+      return new MockLLMProvider(config)
+    }
+
+    throw new UnknownProviderError((config as { type: string }).type)
+  }
+
+  static getCapabilities(type: ProviderType): ProviderCapabilities {
+    const capabilities = PROVIDER_CAPABILITIES[type]
+    if (!capabilities) {
+      throw new UnknownProviderError(type)
+    }
+
+    return capabilities
+  }
+
+  static isSupported(type: string): type is ProviderType {
+    return type === 'openrouter' || type === 'bedrock' || type === 'mock'
+  }
+}
+
+export { OpenRouterProvider, BedrockProvider, MockLLMProvider }

package/src/provider/index.ts

@@ -0,0 +1,3 @@
+export { OpenRouterProvider } from './openrouter/client.js'
+export { BedrockProvider } from './bedrock/client.js'
+export { ProviderFactory, MockLLMProvider, UnknownProviderError } from './factory.js'

package/src/provider/openrouter/client.ts

@@ -0,0 +1,396 @@
+import type {
+  ChatCompletionParams,
+  ChatCompletionResponse,
+  LLMProvider,
+  ModelInfo,
+  StreamChunk,
+  ToolChoice,
+} from '../../types/provider/index.js'
+import type { OpenRouterConfig } from '../../types/provider/index.js'
+import type { TokenUsage } from '../../types/common/index.js'
+import { getRootLogger } from '../../utils/logger.js'
+import { toErrorMessage } from '../../utils/error.js'
+import { SpanStatusCode } from '@opentelemetry/api'
+import { getTracer } from '../telemetry/setup.js'
+import {
+  GENAI,
+  NAMZU,
+  chatSpanName,
+} from '../../telemetry/attributes.js'
+
+const logger = getRootLogger().child({ component: 'OpenRouterProvider' })
+
+const OPENROUTER_BASE_URL = process.env.OPENROUTER_BASE_URL ?? 'https://openrouter.ai/api/v1'
+
+interface RawUsage {
+  prompt_tokens: number
+  completion_tokens: number
+  total_tokens: number
+  prompt_tokens_details?: {
+    cached_tokens?: number
+  }
+  cache_discount?: number
+  cache_read_input_tokens?: number
+  cache_creation_input_tokens?: number
+}
+
+function parseUsage(raw?: RawUsage): TokenUsage {
+  if (!raw) {
+    return { promptTokens: 0, completionTokens: 0, totalTokens: 0, cachedTokens: 0, cacheWriteTokens: 0 }
+  }
+  return {
+    promptTokens: raw.prompt_tokens,
+    completionTokens: raw.completion_tokens,
+    totalTokens: raw.total_tokens,
+    cachedTokens: raw.prompt_tokens_details?.cached_tokens ?? raw.cache_read_input_tokens ?? 0,
+    cacheWriteTokens: raw.cache_creation_input_tokens ?? 0,
+  }
+}
+
+function parseCacheDiscount(raw?: RawUsage): number {
+  return raw?.cache_discount ?? 0
+}
+
+function formatToolChoice(tc: ToolChoice): unknown {
+  if (typeof tc === 'string') return tc
+  return tc
+}
+
+export class OpenRouterProvider implements LLMProvider {
+  readonly id = 'openrouter'
+  readonly name = 'OpenRouter'
+
+  private config: OpenRouterConfig
+  private baseUrl: string
+
+  constructor(config: OpenRouterConfig) {
+    if (!config.apiKey) {
+      throw new Error('OpenRouter API key is required. Set OPENROUTER_API_KEY env variable.')
+    }
+    this.config = config
+    this.baseUrl = config.baseUrl ?? OPENROUTER_BASE_URL
+  }
+
+  private getHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${this.config.apiKey}`,
+      'Content-Type': 'application/json',
+    }
+    if (this.config.siteUrl) {
+      headers['HTTP-Referer'] = this.config.siteUrl
+    }
+    if (this.config.siteName) {
+      headers['X-Title'] = this.config.siteName
+    }
+    return headers
+  }
+
+  private formatMessages(messages: ChatCompletionParams['messages']): unknown[] {
+    return messages.map((msg) => {
+      if (msg.role === 'tool') {
+        return {
+          role: 'tool',
+          content: msg.content,
+          tool_call_id: (msg as { toolCallId?: string }).toolCallId,
+        }
+      }
+      if (msg.role === 'assistant' && 'toolCalls' in msg && msg.toolCalls) {
+        return {
+          role: 'assistant',
+          content: msg.content,
+          tool_calls: msg.toolCalls.map((tc) => ({
+            id: tc.id,
+            type: tc.type,
+            function: tc.function,
+          })),
+        }
+      }
+      return { role: msg.role, content: msg.content }
+    })
+  }
+
+  private buildRequestBody(params: ChatCompletionParams, stream: boolean): Record<string, unknown> {
+    const body: Record<string, unknown> = {
+      model: params.model,
+      messages: this.formatMessages(params.messages),
+      stream,
+    }
+
+    if (params.tools && params.tools.length > 0) {
+      body.tools = params.tools
+    }
+    if (params.toolChoice !== undefined) {
+      body.tool_choice = formatToolChoice(params.toolChoice)
+    }
+    if (params.parallelToolCalls !== undefined) {
+      body.parallel_tool_calls = params.parallelToolCalls
+    }
+
+    if (params.temperature !== undefined) body.temperature = params.temperature
+    if (params.maxTokens !== undefined) body.max_tokens = params.maxTokens
+    if (params.topP !== undefined) body.top_p = params.topP
+    if (params.topK !== undefined) body.top_k = params.topK
+    if (params.frequencyPenalty !== undefined) body.frequency_penalty = params.frequencyPenalty
+    if (params.presencePenalty !== undefined) body.presence_penalty = params.presencePenalty
+    if (params.repetitionPenalty !== undefined) body.repetition_penalty = params.repetitionPenalty
+    if (params.stop) body.stop = params.stop
+
+    if (params.cacheControl) {
+      body.cache_control = params.cacheControl
+    }
+
+    if (params.responseFormat) {
+      body.response_format = params.responseFormat
+    }
+
+    return body
+  }
+
+  async chat(params: ChatCompletionParams): Promise<ChatCompletionResponse> {
+    const tracer = getTracer()
+
+    return tracer.startActiveSpan(
+      chatSpanName(params.model),
+      async (span) => {
+        span.setAttributes({
+          [GENAI.OPERATION_NAME]: 'chat',
+          [GENAI.SYSTEM]: 'openrouter',
+          [GENAI.REQUEST_MODEL]: params.model,
+        })
+        if (params.temperature !== undefined) {
+          span.setAttribute(GENAI.REQUEST_TEMPERATURE, params.temperature)
+        }
+        if (params.maxTokens !== undefined) {
+          span.setAttribute(GENAI.REQUEST_MAX_TOKENS, params.maxTokens)
+        }
+
+        try {
+          const body = this.buildRequestBody(params, false)
+
+          logger.debug('Sending chat completion request', { model: params.model })
+
+          const response = await fetch(`${this.baseUrl}/chat/completions`, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.config.timeout ?? 120_000),
+          })
+
+          if (!response.ok) {
+            const errorBody = await response.text()
+            logger.error('OpenRouter API error', {
+              status: response.status,
+              body: errorBody,
+            })
+            throw new Error(
+              `OpenRouter API error (${response.status}): ${errorBody}`,
+            )
+          }
+
+          const data = (await response.json()) as {
+            id: string
+            model: string
+            choices: Array<{
+              message: {
+                role: string
+                content: string | null
+                tool_calls?: Array<{
+                  id: string
+                  type: string
+                  function: { name: string; arguments: string }
+                }>
+              }
+              finish_reason: string
+            }>
+            usage?: RawUsage
+          }
+
+          const choice = data.choices[0]
+          if (!choice) {
+            throw new Error('OpenRouter returned empty choices')
+          }
+
+          const usage = parseUsage(data.usage)
+          const cacheDiscount = parseCacheDiscount(data.usage)
+
+          const result: ChatCompletionResponse = {
+            id: data.id,
+            model: data.model,
+            message: {
+              role: 'assistant',
+              content: choice.message.content,
+              toolCalls: choice.message.tool_calls?.map((tc) => ({
+                id: tc.id,
+                type: 'function' as const,
+                function: tc.function,
+              })),
+            },
+            finishReason: choice.finish_reason as ChatCompletionResponse['finishReason'],
+            usage,
+          }
+
+          span.setAttributes({
+            [GENAI.RESPONSE_ID]: data.id,
+            [GENAI.RESPONSE_MODEL]: data.model,
+            [GENAI.RESPONSE_FINISH_REASONS]: choice.finish_reason,
+            [GENAI.USAGE_INPUT_TOKENS]: usage.promptTokens,
+            [GENAI.USAGE_OUTPUT_TOKENS]: usage.completionTokens,
+            [NAMZU.CACHE_READ_TOKENS]: usage.cachedTokens,
+            [NAMZU.CACHE_WRITE_TOKENS]: usage.cacheWriteTokens,
+            [NAMZU.CACHE_DISCOUNT]: cacheDiscount,
+          })
+          span.setStatus({ code: SpanStatusCode.OK })
+
+          return result
+        } catch (err) {
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: toErrorMessage(err),
+          })
+          span.recordException(err instanceof Error ? err : new Error(String(err)))
+          throw err
+        } finally {
+          span.end()
+        }
+      },
+    )
+  }
+
+  async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+    const body = this.buildRequestBody(params, true)
+
+    const response = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(this.config.timeout ?? 120_000),
+    })
+
+    if (!response.ok) {
+      const errorBody = await response.text()
+      throw new Error(
+        `OpenRouter API error (${response.status}): ${errorBody}`,
+      )
+    }
+
+    if (!response.body) {
+      throw new Error('OpenRouter returned no stream body')
+    }
+
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+
+        buffer += decoder.decode(value, { stream: true })
+        const lines = buffer.split('\n')
+        buffer = lines.pop() ?? ''
+
+        for (const line of lines) {
+          const trimmed = line.trim()
+          if (!trimmed || !trimmed.startsWith('data: ')) continue
+          const data = trimmed.slice(6)
+          if (data === '[DONE]') return
+
+          try {
+            const parsed = JSON.parse(data) as {
+              id: string
+              choices: Array<{
+                delta: {
+                  content?: string
+                  tool_calls?: Array<{
+                    index: number
+                    id?: string
+                    type?: string
+                    function?: { name?: string; arguments?: string }
+                  }>
+                }
+                finish_reason?: string
+              }>
+              usage?: RawUsage
+            }
+
+            const choice = parsed.choices[0]
+            if (!choice) continue
+
+            yield {
+              id: parsed.id,
+              delta: {
+                content: choice.delta.content,
+                toolCalls: choice.delta.tool_calls?.map((tc) => ({
+                  index: tc.index,
+                  id: tc.id,
+                  type: tc.type as 'function' | undefined,
+                  function: tc.function,
+                })),
+              },
+              finishReason: choice.finish_reason as StreamChunk['finishReason'],
+              usage: parsed.usage ? parseUsage(parsed.usage) : undefined,
+            }
+          } catch (parseErr) {
+            logger.warn('Failed to parse streaming chunk', {
+              error: toErrorMessage(parseErr),
+              data: data.slice(0, 200),
+            })
+            yield {
+              id: '',
+              delta: { content: undefined },
+              finishReason: undefined,
+              usage: undefined,
+              error: `Stream parse error: ${toErrorMessage(parseErr)}`,
+            }
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock()
+    }
+  }
+
+  async listModels(): Promise<ModelInfo[]> {
+    const response = await fetch(`${this.baseUrl}/models`, {
+      headers: this.getHeaders(),
+    })
+
+    if (!response.ok) {
+      throw new Error(`Failed to list models: ${response.status}`)
+    }
+
+    const data = (await response.json()) as {
+      data: Array<{
+        id: string
+        name: string
+        context_length: number
+        top_provider?: { max_completion_tokens?: number }
+        pricing?: { prompt: string; completion: string }
+      }>
+    }
+
+    return data.data.map((m) => ({
+      id: m.id,
+      name: m.name,
+      contextWindow: m.context_length,
+      maxOutputTokens: m.top_provider?.max_completion_tokens ?? 4096,
+      inputPrice: Number.parseFloat(m.pricing?.prompt ?? '0') * 1_000_000,
+      outputPrice: Number.parseFloat(m.pricing?.completion ?? '0') * 1_000_000,
+      supportsToolUse: true,
+      supportsStreaming: true,
+    }))
+  }
+
+  async healthCheck(): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.baseUrl}/models`, {
+        headers: this.getHeaders(),
+        signal: AbortSignal.timeout(5000),
+      })
+      return response.ok
+    } catch {
+      return false
+    }
+  }
+}

package/src/provider/telemetry/setup.ts

@@ -0,0 +1,135 @@
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { Resource } from '@opentelemetry/resources'
+import { SimpleSpanProcessor, ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
+import {
+  MeterProvider,
+  PeriodicExportingMetricReader,
+  ConsoleMetricExporter,
+} from '@opentelemetry/sdk-metrics'
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'
+import { trace, metrics, type Tracer, type Meter } from '@opentelemetry/api'
+import type { TelemetryConfig } from '../../types/telemetry/index.js'
+import { getRootLogger } from '../../utils/logger.js'
+import { toErrorMessage } from '../../utils/error.js'
+import { VERSION } from '../../version.js'
+
+const logger = getRootLogger().child({ component: 'TelemetryProvider' })
+
+export class TelemetryProvider {
+  private sdk: NodeSDK | null = null
+  private meterProvider: MeterProvider | null = null
+  private config: TelemetryConfig
+  private _tracer: Tracer | null = null
+  private _meter: Meter | null = null
+
+  constructor(config: TelemetryConfig) {
+    this.config = config
+  }
+
+  get tracer(): Tracer {
+    if (!this._tracer) {
+      this._tracer = trace.getTracer(
+        this.config.serviceName,
+        this.config.serviceVersion ?? VERSION,
+      )
+    }
+    return this._tracer
+  }
+
+  get meter(): Meter {
+    if (!this._meter) {
+      this._meter = metrics.getMeter(
+        this.config.serviceName,
+        this.config.serviceVersion ?? VERSION,
+      )
+    }
+    return this._meter
+  }
+
+  async start(): Promise<void> {
+    if (this.config.exporterType === 'none') {
+      logger.info('Telemetry disabled (exporterType=none)')
+      return
+    }
+
+    const resource = new Resource({
+      'service.name': this.config.serviceName,
+      'service.version': this.config.serviceVersion ?? VERSION,
+    })
+
+    const traceExporter =
+      this.config.exporterType === 'otlp'
+        ? new OTLPTraceExporter({
+            url: this.config.otlpEndpoint
+              ? `${this.config.otlpEndpoint}/v1/traces`
+              : undefined,
+            headers: this.config.otlpHeaders,
+          })
+        : new ConsoleSpanExporter()
+
+    const metricExporter =
+      this.config.exporterType === 'otlp'
+        ? new OTLPMetricExporter({
+            url: this.config.otlpEndpoint
+              ? `${this.config.otlpEndpoint}/v1/metrics`
+              : undefined,
+            headers: this.config.otlpHeaders,
+          })
+        : new ConsoleMetricExporter()
+
+    this.meterProvider = new MeterProvider({
+      resource,
+      readers: [
+        new PeriodicExportingMetricReader({
+          exporter: metricExporter,
+          exportIntervalMillis: this.config.metricExportIntervalMs ?? 10_000,
+        }),
+      ],
+    })
+    metrics.setGlobalMeterProvider(this.meterProvider)
+
+    this.sdk = new NodeSDK({
+      resource,
+      spanProcessor: new SimpleSpanProcessor(traceExporter),
+    })
+
+    this.sdk.start()
+    logger.info(`Telemetry started (exporter=${this.config.exporterType})`)
+  }
+
+  async shutdown(): Promise<void> {
+    try {
+      if (this.meterProvider) {
+        await this.meterProvider.shutdown()
+      }
+      if (this.sdk) {
+        await this.sdk.shutdown()
+      }
+      logger.info('Telemetry shutdown complete')
+    } catch (err) {
+      logger.error('Telemetry shutdown error', {
+        error: toErrorMessage(err),
+      })
+    }
+  }
+}
+
+let _globalProvider: TelemetryProvider | null = null
+
+export function initTelemetry(config: TelemetryConfig): TelemetryProvider {
+  _globalProvider = new TelemetryProvider(config)
+  return _globalProvider
+}
+
+export function getTelemetry(): TelemetryProvider | null {
+  return _globalProvider
+}
+
+export function getTracer(): Tracer {
+  return _globalProvider?.tracer ?? trace.getTracer('namzu')
+}
+
+export function getMeter(): Meter {
+  return _globalProvider?.meter ?? metrics.getMeter('namzu')
+}