@stravigor/saina 0.4.7

package/src/index.ts

@@ -0,0 +1,38 @@
+export { default, default as SainaManager } from './saina_manager.ts'
+
+// Provider
+export { default as SainaProvider } from './saina_provider.ts'
+export { saina, AgentRunner, Thread } from './helpers.ts'
+export { Agent } from './agent.ts'
+export { defineTool, defineToolbox } from './tool.ts'
+export { Workflow } from './workflow.ts'
+export { AnthropicProvider } from './providers/anthropic_provider.ts'
+export { OpenAIProvider } from './providers/openai_provider.ts'
+export { parseSSE } from './utils/sse_parser.ts'
+export { zodToJsonSchema } from './utils/schema.ts'
+export type {
+  AIProvider,
+  SainaConfig,
+  ProviderConfig,
+  CompletionRequest,
+  CompletionResponse,
+  Message,
+  ContentBlock,
+  ToolCall,
+  ToolDefinition,
+  StreamChunk,
+  Usage,
+  AgentResult,
+  ToolCallRecord,
+  AgentEvent,
+  WorkflowResult,
+  EmbeddingResponse,
+  JsonSchema,
+  SSEEvent,
+  BeforeHook,
+  AfterHook,
+  SerializedThread,
+  OutputSchema,
+} from './types.ts'
+export type { ChatOptions, GenerateOptions, GenerateResult, EmbedOptions } from './helpers.ts'
+export type { WorkflowContext } from './workflow.ts'

package/src/providers/anthropic_provider.ts

@@ -0,0 +1,278 @@
+import { parseSSE } from '../utils/sse_parser.ts'
+import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
+import type {
+  AIProvider,
+  CompletionRequest,
+  CompletionResponse,
+  StreamChunk,
+  ProviderConfig,
+  Message,
+  ToolCall,
+  Usage,
+} from '../types.ts'
+
+/**
+ * Anthropic Messages API provider.
+ *
+ * Translates the framework's normalized CompletionRequest/Response
+ * to/from the Anthropic wire format. Uses raw `fetch()`.
+ */
+export class AnthropicProvider implements AIProvider {
+  readonly name: string
+  private apiKey: string
+  private baseUrl: string
+  private defaultModel: string
+  private defaultMaxTokens: number
+
+  constructor(config: ProviderConfig) {
+    this.name = 'anthropic'
+    this.apiKey = config.apiKey
+    this.baseUrl = (config.baseUrl ?? 'https://api.anthropic.com').replace(/\/$/, '')
+    this.defaultModel = config.model
+    this.defaultMaxTokens = config.maxTokens ?? 4096
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const body = this.buildRequestBody(request, false)
+
+    const response = await fetch(`${this.baseUrl}/v1/messages`, {
+      method: 'POST',
+      headers: this.buildHeaders(),
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new ExternalServiceError('Anthropic', response.status, text)
+    }
+
+    const data: any = await response.json()
+    return this.parseResponse(data)
+  }
+
+  async *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
+    const body = this.buildRequestBody(request, true)
+
+    const response = await fetch(`${this.baseUrl}/v1/messages`, {
+      method: 'POST',
+      headers: this.buildHeaders(),
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new ExternalServiceError('Anthropic', response.status, text)
+    }
+
+    if (!response.body) {
+      throw new ExternalServiceError('Anthropic', undefined, 'No stream body returned')
+    }
+
+    let currentBlockIndex = -1
+
+    for await (const sse of parseSSE(response.body)) {
+      if (sse.data === '[DONE]') break
+
+      let parsed: any
+      try {
+        parsed = JSON.parse(sse.data)
+      } catch {
+        continue
+      }
+
+      const type = parsed.type ?? sse.event
+
+      if (type === 'content_block_start') {
+        currentBlockIndex = parsed.index ?? currentBlockIndex + 1
+        const block = parsed.content_block
+        if (block?.type === 'tool_use') {
+          yield {
+            type: 'tool_start',
+            toolCall: { id: block.id, name: block.name },
+            toolIndex: currentBlockIndex,
+          }
+        }
+      } else if (type === 'content_block_delta') {
+        const delta = parsed.delta
+        if (delta?.type === 'text_delta') {
+          yield { type: 'text', text: delta.text }
+        } else if (delta?.type === 'input_json_delta') {
+          yield {
+            type: 'tool_delta',
+            text: delta.partial_json,
+            toolIndex: parsed.index ?? currentBlockIndex,
+          }
+        }
+      } else if (type === 'content_block_stop') {
+        // If we were accumulating a tool call, signal end
+        if (currentBlockIndex >= 0) {
+          yield { type: 'tool_end', toolIndex: parsed.index ?? currentBlockIndex }
+        }
+      } else if (type === 'message_delta') {
+        const usage = parsed.usage
+        if (usage) {
+          yield {
+            type: 'usage',
+            usage: {
+              inputTokens: usage.input_tokens ?? 0,
+              outputTokens: usage.output_tokens ?? 0,
+              totalTokens: (usage.input_tokens ?? 0) + (usage.output_tokens ?? 0),
+            },
+          }
+        }
+      } else if (type === 'message_stop') {
+        yield { type: 'done' }
+      }
+    }
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────────────
+
+  private buildHeaders(): Record<string, string> {
+    return {
+      'content-type': 'application/json',
+      'x-api-key': this.apiKey,
+      'anthropic-version': '2023-06-01',
+    }
+  }
+
+  private buildRequestBody(request: CompletionRequest, stream: boolean): Record<string, unknown> {
+    const body: Record<string, unknown> = {
+      model: request.model ?? this.defaultModel,
+      max_tokens: request.maxTokens ?? this.defaultMaxTokens,
+      messages: this.mapMessages(request.messages),
+    }
+
+    if (stream) body.stream = true
+    if (request.system) body.system = request.system
+    if (request.temperature !== undefined) body.temperature = request.temperature
+    if (request.stopSequences?.length) body.stop_sequences = request.stopSequences
+
+    // Tools
+    if (request.tools?.length) {
+      body.tools = request.tools.map(t => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.parameters,
+      }))
+    }
+
+    // Tool choice
+    if (request.toolChoice) {
+      if (request.toolChoice === 'auto') {
+        body.tool_choice = { type: 'auto' }
+      } else if (request.toolChoice === 'required') {
+        body.tool_choice = { type: 'any' }
+      } else {
+        body.tool_choice = { type: 'tool', name: request.toolChoice.name }
+      }
+    }
+
+    // Structured output
+    if (request.schema) {
+      body.output_format = { type: 'json_schema', schema: request.schema }
+    }
+
+    return body
+  }
+
+  private mapMessages(messages: Message[]): any[] {
+    const result: any[] = []
+
+    for (const msg of messages) {
+      if (msg.role === 'tool') {
+        // Tool results go as user messages with tool_result content blocks
+        result.push({
+          role: 'user',
+          content: [
+            {
+              type: 'tool_result',
+              tool_use_id: msg.toolCallId,
+              content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+            },
+          ],
+        })
+      } else if (msg.role === 'assistant') {
+        const content: any[] = []
+
+        // Add text content if present
+        const text = typeof msg.content === 'string' ? msg.content : ''
+        if (text) {
+          content.push({ type: 'text', text })
+        }
+
+        // Add tool use blocks
+        if (msg.toolCalls?.length) {
+          for (const tc of msg.toolCalls) {
+            content.push({
+              type: 'tool_use',
+              id: tc.id,
+              name: tc.name,
+              input: tc.arguments,
+            })
+          }
+        }
+
+        result.push({
+          role: 'assistant',
+          content: content.length === 1 && content[0].type === 'text' ? content[0].text : content,
+        })
+      } else {
+        // User messages
+        result.push({
+          role: 'user',
+          content: typeof msg.content === 'string' ? msg.content : msg.content,
+        })
+      }
+    }
+
+    return result
+  }
+
+  private parseResponse(data: any): CompletionResponse {
+    let content = ''
+    const toolCalls: ToolCall[] = []
+
+    if (Array.isArray(data.content)) {
+      for (const block of data.content) {
+        if (block.type === 'text') {
+          content += block.text
+        } else if (block.type === 'tool_use') {
+          toolCalls.push({
+            id: block.id,
+            name: block.name,
+            arguments: block.input ?? {},
+          })
+        }
+      }
+    }
+
+    const usage: Usage = {
+      inputTokens: data.usage?.input_tokens ?? 0,
+      outputTokens: data.usage?.output_tokens ?? 0,
+      totalTokens: (data.usage?.input_tokens ?? 0) + (data.usage?.output_tokens ?? 0),
+    }
+
+    let stopReason: CompletionResponse['stopReason'] = 'end'
+    switch (data.stop_reason) {
+      case 'tool_use':
+        stopReason = 'tool_use'
+        break
+      case 'max_tokens':
+        stopReason = 'max_tokens'
+        break
+      case 'stop_sequence':
+        stopReason = 'stop_sequence'
+        break
+    }
+
+    return {
+      id: data.id ?? '',
+      content,
+      toolCalls,
+      stopReason,
+      usage,
+      raw: data,
+    }
+  }
+}

package/src/providers/openai_provider.ts

@@ -0,0 +1,351 @@
+import { parseSSE } from '../utils/sse_parser.ts'
+import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
+import type {
+  AIProvider,
+  CompletionRequest,
+  CompletionResponse,
+  StreamChunk,
+  EmbeddingResponse,
+  ProviderConfig,
+  Message,
+  ToolCall,
+  Usage,
+} from '../types.ts'
+
+/**
+ * OpenAI Chat Completions API provider.
+ *
+ * Also serves DeepSeek and any OpenAI-compatible API by setting `baseUrl`
+ * in the provider config. Uses raw `fetch()`.
+ */
+export class OpenAIProvider implements AIProvider {
+  readonly name: string
+  private apiKey: string
+  private baseUrl: string
+  private defaultModel: string
+  private defaultMaxTokens?: number
+
+  constructor(config: ProviderConfig, name?: string) {
+    this.name = name ?? 'openai'
+    this.apiKey = config.apiKey
+    this.baseUrl = (config.baseUrl ?? 'https://api.openai.com').replace(/\/$/, '')
+    this.defaultModel = config.model
+    this.defaultMaxTokens = config.maxTokens
+  }
+
+  /** Whether this provider supports OpenAI's native json_schema response format. */
+  private get supportsJsonSchema(): boolean {
+    return this.baseUrl === 'https://api.openai.com'
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const body = this.buildRequestBody(request, false)
+
+    const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+      method: 'POST',
+      headers: this.buildHeaders(),
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new ExternalServiceError('OpenAI', response.status, text)
+    }
+
+    const data: any = await response.json()
+    return this.parseResponse(data)
+  }
+
+  async *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
+    const body = this.buildRequestBody(request, true)
+
+    const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+      method: 'POST',
+      headers: this.buildHeaders(),
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new ExternalServiceError('OpenAI', response.status, text)
+    }
+
+    if (!response.body) {
+      throw new ExternalServiceError('OpenAI', undefined, 'No stream body returned')
+    }
+
+    // Track in-progress tool calls for tool_start vs tool_delta distinction
+    const seenTools = new Set<number>()
+
+    for await (const sse of parseSSE(response.body)) {
+      if (sse.data === '[DONE]') {
+        yield { type: 'done' }
+        break
+      }
+
+      let parsed: any
+      try {
+        parsed = JSON.parse(sse.data)
+      } catch {
+        continue
+      }
+
+      const choice = parsed.choices?.[0]
+      if (!choice) continue
+
+      const delta = choice.delta
+      if (!delta) continue
+
+      // Text content
+      if (delta.content) {
+        yield { type: 'text', text: delta.content }
+      }
+
+      // Tool calls
+      if (delta.tool_calls) {
+        for (const tc of delta.tool_calls) {
+          const index: number = tc.index ?? 0
+
+          if (!seenTools.has(index)) {
+            // First chunk for this tool — emit tool_start
+            seenTools.add(index)
+            yield {
+              type: 'tool_start',
+              toolCall: { id: tc.id, name: tc.function?.name },
+              toolIndex: index,
+            }
+          }
+
+          // Argument fragments
+          if (tc.function?.arguments) {
+            yield {
+              type: 'tool_delta',
+              text: tc.function.arguments,
+              toolIndex: index,
+            }
+          }
+        }
+      }
+
+      // Finish reason
+      if (choice.finish_reason) {
+        if (choice.finish_reason === 'tool_calls') {
+          // Emit tool_end for all tracked tools
+          for (const idx of seenTools) {
+            yield { type: 'tool_end', toolIndex: idx }
+          }
+        }
+
+        // Usage in final chunk (if stream_options.include_usage is set)
+        if (parsed.usage) {
+          yield {
+            type: 'usage',
+            usage: {
+              inputTokens: parsed.usage.prompt_tokens ?? 0,
+              outputTokens: parsed.usage.completion_tokens ?? 0,
+              totalTokens: parsed.usage.total_tokens ?? 0,
+            },
+          }
+        }
+      }
+    }
+  }
+
+  async embed(input: string | string[], model?: string): Promise<EmbeddingResponse> {
+    const body = {
+      input: Array.isArray(input) ? input : [input],
+      model: model ?? 'text-embedding-3-small',
+    }
+
+    const response = await fetch(`${this.baseUrl}/v1/embeddings`, {
+      method: 'POST',
+      headers: this.buildHeaders(),
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new ExternalServiceError('OpenAI', response.status, text)
+    }
+
+    const data: any = await response.json()
+
+    return {
+      embeddings: data.data.map((d: any) => d.embedding),
+      model: data.model,
+      usage: { totalTokens: data.usage?.total_tokens ?? 0 },
+    }
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────────────
+
+  private buildHeaders(): Record<string, string> {
+    return {
+      'content-type': 'application/json',
+      authorization: `Bearer ${this.apiKey}`,
+    }
+  }
+
+  private buildRequestBody(request: CompletionRequest, stream: boolean): Record<string, unknown> {
+    const body: Record<string, unknown> = {
+      model: request.model ?? this.defaultModel,
+      messages: this.mapMessages(request.messages, request.system),
+    }
+
+    if (stream) body.stream = true
+    if (request.maxTokens ?? this.defaultMaxTokens) {
+      body.max_tokens = request.maxTokens ?? this.defaultMaxTokens
+    }
+    if (request.temperature !== undefined) body.temperature = request.temperature
+    if (request.stopSequences?.length) body.stop = request.stopSequences
+
+    // Tools
+    if (request.tools?.length) {
+      body.tools = request.tools.map(t => ({
+        type: 'function',
+        function: {
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters,
+        },
+      }))
+    }
+
+    // Tool choice
+    if (request.toolChoice) {
+      if (typeof request.toolChoice === 'string') {
+        body.tool_choice = request.toolChoice
+      } else {
+        body.tool_choice = {
+          type: 'function',
+          function: { name: request.toolChoice.name },
+        }
+      }
+    }
+
+    // Structured output
+    if (request.schema) {
+      if (this.supportsJsonSchema) {
+        body.response_format = {
+          type: 'json_schema',
+          json_schema: {
+            name: 'response',
+            schema: request.schema,
+            strict: true,
+          },
+        }
+      } else {
+        // Fallback for providers that don't support json_schema (e.g. DeepSeek)
+        body.response_format = { type: 'json_object' }
+        // Inject schema into system prompt so the model knows the expected format
+        const schemaHint = `\n\nYou MUST respond with valid JSON matching this schema:\n${JSON.stringify(request.schema, null, 2)}`
+        const messages = body.messages as any[]
+        if (messages[0]?.role === 'system') {
+          messages[0].content += schemaHint
+        } else {
+          messages.unshift({ role: 'system', content: `Respond with valid JSON.${schemaHint}` })
+        }
+      }
+    }
+
+    return body
+  }
+
+  private mapMessages(messages: Message[], system?: string): any[] {
+    const result: any[] = []
+
+    // System prompt as first message
+    if (system) {
+      result.push({ role: 'system', content: system })
+    }
+
+    for (const msg of messages) {
+      if (msg.role === 'tool') {
+        result.push({
+          role: 'tool',
+          tool_call_id: msg.toolCallId,
+          content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+        })
+      } else if (msg.role === 'assistant') {
+        const mapped: any = {
+          role: 'assistant',
+          content: typeof msg.content === 'string' ? msg.content : null,
+        }
+
+        if (msg.toolCalls?.length) {
+          mapped.tool_calls = msg.toolCalls.map(tc => ({
+            id: tc.id,
+            type: 'function',
+            function: {
+              name: tc.name,
+              arguments: JSON.stringify(tc.arguments),
+            },
+          }))
+        }
+
+        result.push(mapped)
+      } else {
+        result.push({
+          role: 'user',
+          content: typeof msg.content === 'string' ? msg.content : msg.content,
+        })
+      }
+    }
+
+    return result
+  }
+
+  private parseResponse(data: any): CompletionResponse {
+    const choice = data.choices?.[0]
+    const message = choice?.message
+
+    const content: string = message?.content ?? ''
+    const toolCalls: ToolCall[] = []
+
+    if (message?.tool_calls) {
+      for (const tc of message.tool_calls) {
+        let args: Record<string, unknown> = {}
+        try {
+          args = JSON.parse(tc.function.arguments)
+        } catch {
+          // Invalid JSON from the model — pass as-is in a wrapper
+          args = { _raw: tc.function.arguments }
+        }
+
+        toolCalls.push({
+          id: tc.id,
+          name: tc.function.name,
+          arguments: args,
+        })
+      }
+    }
+
+    const usage: Usage = {
+      inputTokens: data.usage?.prompt_tokens ?? 0,
+      outputTokens: data.usage?.completion_tokens ?? 0,
+      totalTokens: data.usage?.total_tokens ?? 0,
+    }
+
+    let stopReason: CompletionResponse['stopReason'] = 'end'
+    switch (choice?.finish_reason) {
+      case 'tool_calls':
+        stopReason = 'tool_use'
+        break
+      case 'length':
+        stopReason = 'max_tokens'
+        break
+      case 'stop':
+        stopReason = 'end'
+        break
+    }
+
+    return {
+      id: data.id ?? '',
+      content,
+      toolCalls,
+      stopReason,
+      usage,
+      raw: data,
+    }
+  }
+}