@stravigor/saina 0.4.7 → 0.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravigor/saina",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "type": "module",
   "description": "AI module for the Strav framework",
   "license": "MIT",

package/src/helpers.ts

@@ -216,6 +216,7 @@ export class AgentRunner<T extends Agent = Agent> {
   private _context: Record<string, unknown> = {}
   private _provider?: string
   private _model?: string
+  private _tools?: ToolDefinition[]
 
   constructor(private AgentClass: new () => T) {}
 
@@ -238,11 +239,22 @@ export class AgentRunner<T extends Agent = Agent> {
     return this
   }
 
+  /** Set or override the tools available to the agent for this run. */
+  tools(tools: ToolDefinition[]): this {
+    this._tools = tools
+    return this
+  }
+
   /** Run the agent to completion. */
   async run(): Promise<AgentResult> {
     const agent = new this.AgentClass()
     const config = SainaManager.config
 
+    // Runner-level tools override agent-level tools
+    if (this._tools) {
+      agent.tools = this._tools
+    }
+
     const providerName = this._provider ?? agent.provider ?? config.default
     const providerConfig = config.providers[providerName]
     const model = this._model ?? agent.model ?? providerConfig?.model ?? ''
@@ -369,6 +381,11 @@ export class AgentRunner<T extends Agent = Agent> {
     const agent = new this.AgentClass()
     const config = SainaManager.config
 
+    // Runner-level tools override agent-level tools
+    if (this._tools) {
+      agent.tools = this._tools
+    }
+
     const providerName = this._provider ?? agent.provider ?? config.default
     const providerConfig = config.providers[providerName]
     const model = this._model ?? agent.model ?? providerConfig?.model ?? ''

package/src/providers/anthropic_provider.ts

@@ -1,4 +1,5 @@
 import { parseSSE } from '../utils/sse_parser.ts'
+import { retryableFetch, type RetryOptions } from '../utils/retry.ts'
 import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
 import type {
   AIProvider,
@@ -23,6 +24,7 @@ export class AnthropicProvider implements AIProvider {
   private baseUrl: string
   private defaultModel: string
   private defaultMaxTokens: number
+  private retryOptions: RetryOptions
 
   constructor(config: ProviderConfig) {
     this.name = 'anthropic'
@@ -30,21 +32,21 @@ export class AnthropicProvider implements AIProvider {
     this.baseUrl = (config.baseUrl ?? 'https://api.anthropic.com').replace(/\/$/, '')
     this.defaultModel = config.model
     this.defaultMaxTokens = config.maxTokens ?? 4096
+    this.retryOptions = {
+      maxRetries: config.maxRetries ?? 3,
+      baseDelay: config.retryBaseDelay ?? 1000,
+    }
   }
 
   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 response = await retryableFetch(
+      'Anthropic',
+      `${this.baseUrl}/v1/messages`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
 
     const data: any = await response.json()
     return this.parseResponse(data)
@@ -53,16 +55,12 @@ export class AnthropicProvider implements AIProvider {
   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)
-    }
+    const response = await retryableFetch(
+      'Anthropic',
+      `${this.baseUrl}/v1/messages`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
 
     if (!response.body) {
       throw new ExternalServiceError('Anthropic', undefined, 'No stream body returned')

package/src/providers/openai_provider.ts

@@ -1,4 +1,5 @@
 import { parseSSE } from '../utils/sse_parser.ts'
+import { retryableFetch, type RetryOptions } from '../utils/retry.ts'
 import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
 import type {
   AIProvider,
@@ -24,6 +25,7 @@ export class OpenAIProvider implements AIProvider {
   private baseUrl: string
   private defaultModel: string
   private defaultMaxTokens?: number
+  private retryOptions: RetryOptions
 
   constructor(config: ProviderConfig, name?: string) {
     this.name = name ?? 'openai'
@@ -31,6 +33,10 @@ export class OpenAIProvider implements AIProvider {
     this.baseUrl = (config.baseUrl ?? 'https://api.openai.com').replace(/\/$/, '')
     this.defaultModel = config.model
     this.defaultMaxTokens = config.maxTokens
+    this.retryOptions = {
+      maxRetries: config.maxRetries ?? 3,
+      baseDelay: config.retryBaseDelay ?? 1000,
+    }
   }
 
   /** Whether this provider supports OpenAI's native json_schema response format. */
@@ -41,16 +47,12 @@ export class OpenAIProvider implements AIProvider {
   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 response = await retryableFetch(
+      'OpenAI',
+      `${this.baseUrl}/v1/chat/completions`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
 
     const data: any = await response.json()
     return this.parseResponse(data)
@@ -59,16 +61,12 @@ export class OpenAIProvider implements AIProvider {
   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)
-    }
+    const response = await retryableFetch(
+      'OpenAI',
+      `${this.baseUrl}/v1/chat/completions`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
 
     if (!response.body) {
       throw new ExternalServiceError('OpenAI', undefined, 'No stream body returned')
@@ -157,16 +155,12 @@ export class OpenAIProvider implements AIProvider {
       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 response = await retryableFetch(
+      'OpenAI',
+      `${this.baseUrl}/v1/embeddings`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
 
     const data: any = await response.json()
 
@@ -179,6 +173,14 @@ export class OpenAIProvider implements AIProvider {
 
   // ── Private helpers ──────────────────────────────────────────────────────
 
+  private isReasoningModel(model: string): boolean {
+    return /^(o[1-9]|gpt-5)/.test(model)
+  }
+
+  private usesMaxCompletionTokens(model: string): boolean {
+    return this.isReasoningModel(model) || /^gpt-4\.1|gpt-4o-mini-2024/.test(model)
+  }
+
   private buildHeaders(): Record<string, string> {
     return {
       'content-type': 'application/json',
@@ -194,9 +196,18 @@ export class OpenAIProvider implements AIProvider {
 
     if (stream) body.stream = true
     if (request.maxTokens ?? this.defaultMaxTokens) {
-      body.max_tokens = request.maxTokens ?? this.defaultMaxTokens
+      const tokens = request.maxTokens ?? this.defaultMaxTokens
+      const model = (body.model as string) ?? ''
+
+      if (this.usesMaxCompletionTokens(model)) {
+        body.max_completion_tokens = tokens
+      } else {
+        body.max_tokens = tokens
+      }
+    }
+    if (request.temperature !== undefined && !this.isReasoningModel((body.model as string) ?? '')) {
+      body.temperature = request.temperature
     }
-    if (request.temperature !== undefined) body.temperature = request.temperature
     if (request.stopSequences?.length) body.stop = request.stopSequences
 
     // Tools
@@ -225,19 +236,20 @@ export class OpenAIProvider implements AIProvider {
 
     // Structured output
     if (request.schema) {
-      if (this.supportsJsonSchema) {
+      const useStrict = this.supportsJsonSchema && this.isStrictCompatible(request.schema)
+
+      if (useStrict) {
         body.response_format = {
           type: 'json_schema',
           json_schema: {
             name: 'response',
-            schema: request.schema,
+            schema: this.normalizeSchemaForOpenAI(request.schema),
             strict: true,
           },
         }
       } else {
-        // Fallback for providers that don't support json_schema (e.g. DeepSeek)
+        // Fallback: json_object mode with schema injected into system prompt
         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') {
@@ -348,4 +360,150 @@ export class OpenAIProvider implements AIProvider {
       raw: data,
     }
   }
+
+  /**
+   * OpenAI's strict structured output requires:
+   * - All properties listed in `required`
+   * - Optional properties use nullable types instead
+   * - `additionalProperties: false` on every object
+   */
+  /**
+   * Check if a schema is compatible with OpenAI's strict structured output.
+   * Record types (object with additionalProperties != false) are not supported.
+   */
+  private isStrictCompatible(schema: Record<string, unknown>): boolean {
+    if (schema == null || typeof schema !== 'object') return true
+
+    // Record type: object with additionalProperties that isn't false
+    if (
+      schema.type === 'object' &&
+      schema.additionalProperties !== undefined &&
+      schema.additionalProperties !== false
+    ) {
+      return false
+    }
+
+    // Check nested properties
+    if (schema.properties) {
+      for (const prop of Object.values(schema.properties as Record<string, any>)) {
+        if (!this.isStrictCompatible(prop)) return false
+      }
+    }
+
+    // Check array items
+    if (schema.items && !this.isStrictCompatible(schema.items as Record<string, unknown>))
+      return false
+
+    // Check anyOf / oneOf
+    for (const key of ['anyOf', 'oneOf'] as const) {
+      if (Array.isArray(schema[key])) {
+        for (const s of schema[key] as any[]) {
+          if (!this.isStrictCompatible(s)) return false
+        }
+      }
+    }
+
+    return true
+  }
+
+  /** Keywords OpenAI strict mode does NOT support. */
+  private static UNSUPPORTED_KEYWORDS = new Set([
+    'propertyNames',
+    'patternProperties',
+    'if',
+    'then',
+    'else',
+    'not',
+    'contains',
+    'minItems',
+    'maxItems',
+    'minProperties',
+    'maxProperties',
+    'minLength',
+    'maxLength',
+    'minimum',
+    'maximum',
+    'exclusiveMinimum',
+    'exclusiveMaximum',
+    'multipleOf',
+    'pattern',
+    'format',
+    'contentEncoding',
+    'contentMediaType',
+    'unevaluatedProperties',
+    '$schema',
+  ])
+
+  private normalizeSchemaForOpenAI(schema: Record<string, unknown>): Record<string, unknown> {
+    if (schema == null || typeof schema !== 'object') return schema
+
+    // Strip unsupported keywords
+    const result: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(schema)) {
+      if (!OpenAIProvider.UNSUPPORTED_KEYWORDS.has(k)) {
+        result[k] = v
+      }
+    }
+
+    // Handle object types with explicit properties
+    if (result.type === 'object' && result.properties) {
+      const props = result.properties as Record<string, any>
+      const currentRequired = new Set(
+        Array.isArray(result.required) ? (result.required as string[]) : []
+      )
+
+      const normalizedProps: Record<string, any> = {}
+
+      for (const [key, prop] of Object.entries(props)) {
+        let normalizedProp = this.normalizeSchemaForOpenAI(prop)
+
+        // If property is not required, make it nullable and add to required
+        if (!currentRequired.has(key)) {
+          normalizedProp = this.makeNullable(normalizedProp)
+        }
+
+        normalizedProps[key] = normalizedProp
+      }
+
+      result.properties = normalizedProps
+      result.required = Object.keys(normalizedProps)
+      result.additionalProperties = false
+    }
+
+    // Handle arrays
+    if (result.type === 'array' && result.items) {
+      result.items = this.normalizeSchemaForOpenAI(result.items as Record<string, unknown>)
+    }
+
+    // Handle anyOf / oneOf
+    for (const key of ['anyOf', 'oneOf'] as const) {
+      if (Array.isArray(result[key])) {
+        result[key] = (result[key] as any[]).map((s: any) => this.normalizeSchemaForOpenAI(s))
+      }
+    }
+
+    return result
+  }
+
+  private makeNullable(schema: Record<string, unknown>): Record<string, unknown> {
+    // Already nullable
+    if (Array.isArray(schema.type) && schema.type.includes('null')) return schema
+
+    // Has anyOf — add null variant
+    if (Array.isArray(schema.anyOf)) {
+      const hasNull = schema.anyOf.some((s: any) => s.type === 'null')
+      if (!hasNull) {
+        return { ...schema, anyOf: [...schema.anyOf, { type: 'null' }] }
+      }
+      return schema
+    }
+
+    // Simple type — wrap in anyOf with null
+    if (schema.type) {
+      const { type, ...rest } = schema
+      return { anyOf: [{ type, ...rest }, { type: 'null' }] }
+    }
+
+    return schema
+  }
 }

package/src/types.ts

@@ -161,6 +161,8 @@ export interface ProviderConfig {
   baseUrl?: string
   maxTokens?: number
   temperature?: number
+  maxRetries?: number
+  retryBaseDelay?: number
 }
 
 export interface SainaConfig {

package/src/utils/retry.ts

@@ -0,0 +1,100 @@
+import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
+
+export interface RetryOptions {
+  maxRetries?: number
+  baseDelay?: number
+  maxDelay?: number
+  retryableStatuses?: number[]
+}
+
+const DEFAULT_RETRYABLE = [429, 500, 502, 503, 529]
+
+/**
+ * Fetch with automatic retry and exponential backoff for transient errors.
+ *
+ * Retries on 429 (rate limit), 5xx, and network failures.
+ * Parses the `retry-after` header when available; otherwise uses
+ * exponential backoff with jitter.
+ *
+ * Returns the successful `Response`. On final failure, throws
+ * `ExternalServiceError` with the last status and body.
+ */
+export async function retryableFetch(
+  service: string,
+  url: string,
+  init: RequestInit,
+  options?: RetryOptions
+): Promise<Response> {
+  const maxRetries = options?.maxRetries ?? 3
+  const baseDelay = options?.baseDelay ?? 1000
+  const maxDelay = options?.maxDelay ?? 60_000
+  const retryable = options?.retryableStatuses ?? DEFAULT_RETRYABLE
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    let response: Response
+
+    try {
+      response = await fetch(url, init)
+    } catch (err) {
+      // Network error (DNS, connection refused, etc.)
+      if (attempt === maxRetries) {
+        throw new ExternalServiceError(
+          service,
+          undefined,
+          err instanceof Error ? err.message : String(err)
+        )
+      }
+      await sleep(backoffDelay(attempt, baseDelay, maxDelay))
+      continue
+    }
+
+    if (response.ok) return response
+
+    // Non-retryable status — fail immediately
+    if (!retryable.includes(response.status)) {
+      const text = await response.text()
+      throw new ExternalServiceError(service, response.status, text)
+    }
+
+    // Retryable status — wait and retry (unless last attempt)
+    if (attempt === maxRetries) {
+      const text = await response.text()
+      throw new ExternalServiceError(service, response.status, text)
+    }
+
+    const delay = parseRetryAfter(response) ?? backoffDelay(attempt, baseDelay, maxDelay)
+    await sleep(delay)
+  }
+
+  // Unreachable, but satisfies TypeScript
+  throw new ExternalServiceError(service, undefined, 'Retry loop exited unexpectedly')
+}
+
+/**
+ * Parse the `retry-after` header into milliseconds.
+ * Supports both delta-seconds ("2") and HTTP-date formats.
+ */
+function parseRetryAfter(response: Response): number | null {
+  const header = response.headers.get('retry-after')
+  if (!header) return null
+
+  const seconds = Number(header)
+  if (!Number.isNaN(seconds)) return seconds * 1000
+
+  // HTTP-date format
+  const date = Date.parse(header)
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now())
+
+  return null
+}
+
+/** Exponential backoff with jitter: base * 2^attempt + random jitter, capped at maxDelay. */
+function backoffDelay(attempt: number, baseDelay: number, maxDelay: number): number {
+  const exp = baseDelay * 2 ** attempt
+  const jitter = Math.random() * baseDelay
+  return Math.min(exp + jitter, maxDelay)
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}