@strav/brain 0.1.0

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 brain.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,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "tests"]
+}