@stravigor/saina 0.4.7

package/src/saina_manager.ts

@@ -0,0 +1,116 @@
+import { inject } from '@stravigor/core/core/inject'
+import { ConfigurationError } from '@stravigor/core/exceptions/errors'
+import Configuration from '@stravigor/core/config/configuration'
+import { AnthropicProvider } from './providers/anthropic_provider.ts'
+import { OpenAIProvider } from './providers/openai_provider.ts'
+import type {
+  AIProvider,
+  SainaConfig,
+  ProviderConfig,
+  CompletionRequest,
+  CompletionResponse,
+  BeforeHook,
+  AfterHook,
+} from './types.ts'
+
+/**
+ * Central AI configuration hub.
+ *
+ * Resolved once via the DI container — reads the AI config
+ * and initializes the appropriate provider drivers.
+ *
+ * @example
+ * app.singleton(SainaManager)
+ * app.resolve(SainaManager)
+ *
+ * // Plug in a custom provider
+ * SainaManager.useProvider(new OllamaProvider())
+ */
+@inject
+export default class SainaManager {
+  private static _config: SainaConfig
+  private static _providers = new Map<string, AIProvider>()
+  private static _beforeHooks: BeforeHook[] = []
+  private static _afterHooks: AfterHook[] = []
+
+  constructor(config: Configuration) {
+    SainaManager._config = {
+      default: config.get('ai.default', 'anthropic') as string,
+      providers: config.get('ai.providers', {}) as Record<string, ProviderConfig>,
+      maxTokens: config.get('ai.maxTokens', 4096) as number,
+      temperature: config.get('ai.temperature', 0.7) as number,
+      maxIterations: config.get('ai.maxIterations', 10) as number,
+    }
+
+    for (const [name, providerConfig] of Object.entries(SainaManager._config.providers)) {
+      SainaManager._providers.set(name, SainaManager.createProvider(name, providerConfig))
+    }
+  }
+
+  private static createProvider(name: string, config: ProviderConfig): AIProvider {
+    const driver = config.driver ?? name
+    switch (driver) {
+      case 'anthropic':
+        return new AnthropicProvider(config)
+      case 'openai':
+        return new OpenAIProvider(config, name)
+      default:
+        throw new ConfigurationError(
+          `Unknown AI provider driver: ${driver}. Use SainaManager.useProvider() for custom providers.`
+        )
+    }
+  }
+
+  static get config(): SainaConfig {
+    if (!SainaManager._config) {
+      throw new ConfigurationError(
+        'SainaManager not configured. Resolve it through the container first.'
+      )
+    }
+    return SainaManager._config
+  }
+
+  /** Get a provider by name, or the default provider. */
+  static provider(name?: string): AIProvider {
+    const key = name ?? SainaManager._config.default
+    const p = SainaManager._providers.get(key)
+    if (!p) throw new ConfigurationError(`AI provider "${key}" not configured.`)
+    return p
+  }
+
+  /** Swap or add a provider at runtime (e.g., for testing or a custom provider). */
+  static useProvider(provider: AIProvider): void {
+    SainaManager._providers.set(provider.name, provider)
+  }
+
+  /** Register a hook that runs before every completion. */
+  static before(hook: BeforeHook): void {
+    SainaManager._beforeHooks.push(hook)
+  }
+
+  /** Register a hook that runs after every completion. */
+  static after(hook: AfterHook): void {
+    SainaManager._afterHooks.push(hook)
+  }
+
+  /**
+   * Run a completion through the named provider, with before/after hooks.
+   * Used internally by AgentRunner and the `saina` helper.
+   */
+  static async complete(
+    providerName: string | undefined,
+    request: CompletionRequest
+  ): Promise<CompletionResponse> {
+    for (const hook of SainaManager._beforeHooks) await hook(request)
+    const response = await SainaManager.provider(providerName).complete(request)
+    for (const hook of SainaManager._afterHooks) await hook(request, response)
+    return response
+  }
+
+  /** Clear all providers and hooks (for testing). */
+  static reset(): void {
+    SainaManager._providers.clear()
+    SainaManager._beforeHooks = []
+    SainaManager._afterHooks = []
+  }
+}

package/src/saina_provider.ts

@@ -0,0 +1,16 @@
+import { ServiceProvider } from '@stravigor/core/core'
+import type { Application } from '@stravigor/core/core'
+import SainaManager from './saina_manager.ts'
+
+export default class SainaProvider extends ServiceProvider {
+  readonly name = 'saina'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(SainaManager)
+  }
+
+  override boot(app: Application): void {
+    app.resolve(SainaManager)
+  }
+}

package/src/tool.ts

@@ -0,0 +1,50 @@
+import { zodToJsonSchema } from './utils/schema.ts'
+import type { ToolDefinition, JsonSchema } from './types.ts'
+
+/**
+ * Define a tool that an agent can invoke.
+ *
+ * Accepts either a Zod schema or a raw JSON Schema object
+ * for `parameters`. Zod schemas are automatically converted.
+ *
+ * @example
+ * const searchTool = defineTool({
+ *   name: 'search',
+ *   description: 'Search the database',
+ *   parameters: z.object({ query: z.string() }),
+ *   execute: async ({ query }) => {
+ *     return await db.search(query)
+ *   },
+ * })
+ */
+export function defineTool(config: {
+  name: string
+  description: string
+  parameters: any
+  execute: (args: any) => unknown | Promise<unknown>
+}): ToolDefinition {
+  return {
+    name: config.name,
+    description: config.description,
+    parameters: zodToJsonSchema(config.parameters) as JsonSchema,
+    execute: config.execute,
+  }
+}
+
+/**
+ * Group related tools into a named collection.
+ *
+ * A toolbox is simply a labeled array — useful for organizing
+ * tools by domain (e.g., database tools, API tools) and
+ * spreading them into an agent's `tools` array.
+ *
+ * @example
+ * const dbTools = defineToolbox('database', [searchTool, insertTool])
+ *
+ * class MyAgent extends Agent {
+ *   tools = [...dbTools, weatherTool]
+ * }
+ */
+export function defineToolbox(_name: string, tools: ToolDefinition[]): ToolDefinition[] {
+  return tools
+}

package/src/types.ts

@@ -0,0 +1,179 @@
+// ── JSON Schema ──────────────────────────────────────────────────────────────
+
+/** Minimal recursive JSON Schema type. */
+export type JsonSchema = Record<string, unknown>
+
+// ── SSE ──────────────────────────────────────────────────────────────────────
+
+export interface SSEEvent {
+  event?: string
+  data: string
+}
+
+// ── Usage ────────────────────────────────────────────────────────────────────
+
+export interface Usage {
+  inputTokens: number
+  outputTokens: number
+  totalTokens: number
+}
+
+// ── Messages ─────────────────────────────────────────────────────────────────
+
+export interface ToolCall {
+  id: string
+  name: string
+  arguments: Record<string, unknown>
+}
+
+export interface ContentBlock {
+  type: 'text' | 'tool_use' | 'tool_result'
+  text?: string
+  id?: string
+  name?: string
+  input?: Record<string, unknown>
+  toolUseId?: string
+  content?: string
+}
+
+export interface Message {
+  role: 'user' | 'assistant' | 'tool'
+  content: string | ContentBlock[]
+  toolCalls?: ToolCall[]
+  toolCallId?: string
+}
+
+// ── Tool Definition ──────────────────────────────────────────────────────────
+
+export interface ToolDefinition {
+  name: string
+  description: string
+  parameters: JsonSchema
+  execute: (args: Record<string, unknown>) => unknown | Promise<unknown>
+}
+
+// ── Completion Request / Response ────────────────────────────────────────────
+
+export interface CompletionRequest {
+  model: string
+  messages: Message[]
+  system?: string
+  tools?: ToolDefinition[]
+  toolChoice?: 'auto' | 'required' | { name: string }
+  maxTokens?: number
+  temperature?: number
+  schema?: JsonSchema
+  stopSequences?: string[]
+}
+
+export interface CompletionResponse {
+  id: string
+  content: string
+  toolCalls: ToolCall[]
+  stopReason: 'end' | 'tool_use' | 'max_tokens' | 'stop_sequence'
+  usage: Usage
+  raw: unknown
+}
+
+// ── Streaming ────────────────────────────────────────────────────────────────
+
+export interface StreamChunk {
+  type: 'text' | 'tool_start' | 'tool_delta' | 'tool_end' | 'usage' | 'done'
+  text?: string
+  toolCall?: Partial<ToolCall>
+  toolIndex?: number
+  usage?: Usage
+}
+
+// ── Output Schema ────────────────────────────────────────────────────────────
+
+/** A schema that optionally validates data via `.parse()` (e.g., Zod schema). */
+export interface OutputSchema {
+  parse?: (data: unknown) => unknown
+  [key: string]: unknown
+}
+
+// ── Agent ────────────────────────────────────────────────────────────────────
+
+export interface ToolCallRecord {
+  name: string
+  arguments: Record<string, unknown>
+  result: unknown
+  duration: number
+}
+
+export interface AgentResult<T = any> {
+  data: T
+  text: string
+  toolCalls: ToolCallRecord[]
+  messages: Message[]
+  usage: Usage
+  iterations: number
+}
+
+export interface AgentEvent {
+  type: 'text' | 'tool_start' | 'tool_result' | 'iteration' | 'done'
+  text?: string
+  toolCall?: ToolCallRecord
+  iteration?: number
+  result?: AgentResult
+}
+
+// ── Workflow ──────────────────────────────────────────────────────────────────
+
+export interface WorkflowResult {
+  results: Record<string, AgentResult>
+  usage: Usage
+  duration: number
+}
+
+// ── Embedding ────────────────────────────────────────────────────────────────
+
+export interface EmbeddingResponse {
+  embeddings: number[][]
+  model: string
+  usage: { totalTokens: number }
+}
+
+// ── Provider ─────────────────────────────────────────────────────────────────
+
+export interface AIProvider {
+  readonly name: string
+  complete(request: CompletionRequest): Promise<CompletionResponse>
+  stream(request: CompletionRequest): AsyncIterable<StreamChunk>
+  embed?(input: string | string[], model?: string): Promise<EmbeddingResponse>
+}
+
+// ── Hooks ────────────────────────────────────────────────────────────────────
+
+export type BeforeHook = (request: CompletionRequest) => void | Promise<void>
+export type AfterHook = (
+  request: CompletionRequest,
+  response: CompletionResponse
+) => void | Promise<void>
+
+// ── Config ───────────────────────────────────────────────────────────────────
+
+export interface ProviderConfig {
+  driver: string
+  apiKey: string
+  model: string
+  baseUrl?: string
+  maxTokens?: number
+  temperature?: number
+}
+
+export interface SainaConfig {
+  default: string
+  providers: Record<string, ProviderConfig>
+  maxTokens: number
+  temperature: number
+  maxIterations: number
+}
+
+// ── Serialized Thread ────────────────────────────────────────────────────────
+
+export interface SerializedThread {
+  messages: Message[]
+  system?: string
+}

package/src/utils/schema.ts

@@ -0,0 +1,27 @@
+import type { JsonSchema } from '../types.ts'
+
+/**
+ * Convert a Zod schema to a JSON Schema object.
+ *
+ * Detection logic:
+ * - If the input has a `toJSONSchema()` method (Zod v4+), use it directly
+ * - If the input is already a plain object (raw JSON Schema), return as-is
+ * - null/undefined pass through unchanged
+ *
+ * The `$schema` meta-field is stripped from the output since
+ * AI provider APIs don't expect it.
+ */
+export function zodToJsonSchema(schema: any): JsonSchema {
+  if (schema == null) return schema
+
+  // Zod v4+: native toJSONSchema() method
+  if (typeof schema.toJSONSchema === 'function') {
+    const jsonSchema = schema.toJSONSchema()
+    // Strip the $schema meta-field — providers don't need it
+    const { $schema, ...rest } = jsonSchema
+    return rest as JsonSchema
+  }
+
+  // Already a plain JSON Schema object
+  return schema as JsonSchema
+}

package/src/utils/sse_parser.ts

@@ -0,0 +1,62 @@
+import type { SSEEvent } from '../types.ts'
+
+/**
+ * Parse a Server-Sent Events stream into structured events.
+ *
+ * Handles:
+ * - Chunks split at arbitrary byte boundaries
+ * - Multi-line `data:` fields (concatenated with newlines)
+ * - Optional `event:` field
+ * - Empty lines / keepalive comments
+ */
+export async function* parseSSE(stream: ReadableStream<Uint8Array>): AsyncIterable<SSEEvent> {
+  const reader = stream.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 events = buffer.split('\n\n')
+      // Last element is either empty (if buffer ended with \n\n) or incomplete
+      buffer = events.pop()!
+
+      for (const block of events) {
+        const parsed = parseBlock(block)
+        if (parsed) yield parsed
+      }
+    }
+
+    // Flush any remaining data in buffer
+    if (buffer.trim()) {
+      const parsed = parseBlock(buffer)
+      if (parsed) yield parsed
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+function parseBlock(block: string): SSEEvent | null {
+  let event: string | undefined
+  const dataLines: string[] = []
+
+  for (const line of block.split('\n')) {
+    if (line.startsWith('event: ')) {
+      event = line.slice(7)
+    } else if (line.startsWith('data: ')) {
+      dataLines.push(line.slice(6))
+    } else if (line === 'data:') {
+      dataLines.push('')
+    }
+    // Skip comments (lines starting with ':') and other fields
+  }
+
+  if (dataLines.length === 0) return null
+
+  return { event, data: dataLines.join('\n') }
+}

package/src/workflow.ts

@@ -0,0 +1,180 @@
+import { Workflow as BaseWorkflow } from '@stravigor/workflow'
+import type { WorkflowContext as BaseContext } from '@stravigor/workflow'
+import { AgentRunner } from './helpers.ts'
+import type { Agent } from './agent.ts'
+import type { AgentResult, WorkflowResult, Usage } from './types.ts'
+
+// ── AI Workflow Context ─────────────────────────────────────────────────────
+
+export interface WorkflowContext {
+  input: Record<string, unknown>
+  results: Record<string, AgentResult>
+}
+
+type StepMapInput = (ctx: WorkflowContext) => Record<string, unknown> | string
+
+// ── Utilities ───────────────────────────────────────────────────────────────
+
+function resolveInput(mapInput: StepMapInput | undefined, ctx: BaseContext): string {
+  if (!mapInput) return JSON.stringify(ctx.input)
+  const mapped = mapInput(ctx as unknown as WorkflowContext)
+  return typeof mapped === 'string' ? mapped : JSON.stringify(mapped)
+}
+
+function addUsage(total: Usage, add: Usage): void {
+  total.inputTokens += add.inputTokens
+  total.outputTokens += add.outputTokens
+  total.totalTokens += add.totalTokens
+}
+
+// ── Workflow Builder ────────────────────────────────────────────────────────
+
+/**
+ * Multi-agent workflow orchestrator built on `@stravigor/workflow`.
+ *
+ * Supports sequential steps, parallel fan-out, routing, and loops.
+ * Each step wraps an Agent execution through the general-purpose workflow engine.
+ *
+ * @example
+ * const result = await saina.workflow('content-pipeline')
+ *   .step('research', ResearchAgent)
+ *   .step('write', WriterAgent, (ctx) => ({
+ *     topic: ctx.results.research.data.summary,
+ *   }))
+ *   .step('review', ReviewerAgent)
+ *   .run({ topic: 'AI in healthcare' })
+ */
+export class Workflow {
+  private pipeline: BaseWorkflow
+  private totalUsage: Usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+
+  constructor(name: string) {
+    this.pipeline = new BaseWorkflow(name)
+  }
+
+  /**
+   * Add a sequential step. Runs after all previous steps complete.
+   * Use `mapInput` to transform context into the agent's input.
+   */
+  step(name: string, agent: new () => Agent, mapInput?: StepMapInput): this {
+    this.pipeline.step(name, async (ctx: BaseContext) => {
+      const inputText = resolveInput(mapInput, ctx)
+      const result = await new AgentRunner(agent).input(inputText).run()
+      addUsage(this.totalUsage, result.usage)
+      return result
+    })
+    return this
+  }
+
+  /**
+   * Run multiple agents in parallel. All agents receive the same context.
+   * Each agent's result is stored under its name in the workflow results.
+   */
+  parallel(
+    name: string,
+    agents: { name: string; agent: new () => Agent; mapInput?: StepMapInput }[]
+  ): this {
+    this.pipeline.parallel(
+      name,
+      agents.map(a => ({
+        name: a.name,
+        handler: async (ctx: BaseContext) => {
+          const inputText = resolveInput(a.mapInput, ctx)
+          const result = await new AgentRunner(a.agent).input(inputText).run()
+          addUsage(this.totalUsage, result.usage)
+          return result
+        },
+      }))
+    )
+    return this
+  }
+
+  /**
+   * Route to a specialized agent based on a router agent's output.
+   * The router agent should return structured output with a `route` field
+   * that matches one of the branch keys.
+   */
+  route(
+    name: string,
+    router: new () => Agent,
+    branches: Record<string, new () => Agent>,
+    mapInput?: StepMapInput
+  ): this {
+    // Router step: run the router agent, store as `${name}:router`
+    this.pipeline.step(`${name}:router`, async (ctx: BaseContext) => {
+      const inputText = resolveInput(mapInput, ctx)
+      const result = await new AgentRunner(router).input(inputText).run()
+      addUsage(this.totalUsage, result.usage)
+      return result
+    })
+
+    // Branch step: dispatch to the matching branch agent
+    this.pipeline.route(
+      name,
+      (ctx: BaseContext) => {
+        const routerResult = ctx.results[`${name}:router`] as AgentResult
+        return routerResult.data?.route ?? routerResult.text?.trim() ?? ''
+      },
+      Object.fromEntries(
+        Object.entries(branches).map(([key, BranchAgent]) => [
+          key,
+          async (ctx: BaseContext) => {
+            const inputText = resolveInput(mapInput, ctx)
+            const result = await new AgentRunner(BranchAgent).input(inputText).run()
+            addUsage(this.totalUsage, result.usage)
+            return result
+          },
+        ])
+      )
+    )
+    return this
+  }
+
+  /**
+   * Run an agent in a loop until a condition is met or max iterations reached.
+   * Use `feedback` to transform the result into the next iteration's input.
+   */
+  loop(
+    name: string,
+    agent: new () => Agent,
+    options: {
+      maxIterations: number
+      until?: (result: AgentResult, iteration: number) => boolean
+      feedback?: (result: AgentResult) => string
+      mapInput?: StepMapInput
+    }
+  ): this {
+    this.pipeline.loop(
+      name,
+      async (input: unknown, _ctx: BaseContext) => {
+        const result = await new AgentRunner(agent).input(String(input)).run()
+        addUsage(this.totalUsage, result.usage)
+        return result
+      },
+      {
+        maxIterations: options.maxIterations,
+        until: options.until
+          ? (result: unknown, iteration: number) => options.until!(result as AgentResult, iteration)
+          : undefined,
+        feedback: options.feedback
+          ? (result: unknown) => options.feedback!(result as AgentResult)
+          : undefined,
+        mapInput: options.mapInput
+          ? (ctx: BaseContext) => resolveInput(options.mapInput, ctx)
+          : (ctx: BaseContext) => JSON.stringify(ctx.input),
+      }
+    )
+    return this
+  }
+
+  /** Execute the workflow. */
+  async run(input: Record<string, unknown>): Promise<WorkflowResult> {
+    this.totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+    const result = await this.pipeline.run(input)
+    return {
+      results: result.results as Record<string, AgentResult>,
+      usage: this.totalUsage,
+      duration: result.duration,
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"]
+}