@stravigor/saina 0.4.7 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravigor/saina",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "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/openai_provider.ts

@@ -179,6 +179,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 +202,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 +242,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 +366,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
+  }
 }