@stravigor/saina 0.4.7

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.1
+
+### Changed
+
+- Applied consistent code formatting across all source files

package/README.md

@@ -0,0 +1,82 @@
+# @stravigor/saina
+
+AI module for the [Strav](https://www.npmjs.com/package/@stravigor/core) framework. Provides a unified interface for AI providers with support for agents, threads, tool use, and multi-step workflows.
+
+## Install
+
+```bash
+bun add @stravigor/saina
+```
+
+Requires `@stravigor/core` as a peer dependency.
+
+## Providers
+
+- **Anthropic** (Claude)
+- **OpenAI** (GPT, also works with DeepSeek via custom `baseUrl`)
+
+## Usage
+
+```ts
+import { saina } from '@stravigor/saina'
+
+// One-shot chat
+const response = await saina.chat('Explain quantum computing')
+
+// Streaming
+for await (const chunk of saina.stream('Write a poem')) {
+  process.stdout.write(chunk.text)
+}
+
+// Structured output with Zod
+import { z } from 'zod'
+const result = await saina.generate('List 3 colors', {
+  schema: z.object({ colors: z.array(z.string()) }),
+})
+
+// Embeddings
+const vectors = await saina.embed('Hello world')
+```
+
+## Agents
+
+```ts
+import { Agent, defineTool } from '@stravigor/saina'
+
+class ResearchAgent extends Agent {
+  provider = 'anthropic'
+  model = 'claude-sonnet-4-20250514'
+  instructions = 'You are a research assistant.'
+  tools = [searchTool, summarizeTool]
+}
+
+const result = await saina.agent(ResearchAgent).input('Find info on Bun').run()
+```
+
+## Threads
+
+Multi-turn conversations with serialization support:
+
+```ts
+const thread = saina.thread({ provider: 'anthropic', model: 'claude-sonnet-4-20250514' })
+await thread.send('Hello')
+await thread.send('Tell me more')
+const saved = thread.serialize() // persist and restore later
+```
+
+## Workflows
+
+Orchestrate multi-agent pipelines:
+
+```ts
+const workflow = saina.workflow()
+  .step('research', ResearchAgent)
+  .step('summarize', SummaryAgent)
+  .parallel('review', [FactCheckAgent, StyleAgent])
+
+const result = await workflow.run('Analyze this topic')
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@stravigor/saina",
+  "version": "0.4.7",
+  "type": "module",
+  "description": "AI module for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@stravigor/core": "0.4.5",
+    "@stravigor/workflow": "0.4.5"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,73 @@
+import type {
+  ToolDefinition,
+  ToolCall,
+  ToolCallRecord,
+  AgentResult,
+  OutputSchema,
+} from './types.ts'
+
+/**
+ * Base class for AI agents.
+ *
+ * Extend this class to define an agent with custom instructions,
+ * tools, structured output, and lifecycle hooks.
+ *
+ * @example
+ * class SupportAgent extends Agent {
+ *   provider = 'anthropic'
+ *   model = 'claude-sonnet-4-5-20250929'
+ *   instructions = 'You are a customer support agent.'
+ *   tools = [searchTool, lookupOrderTool]
+ *
+ *   output = z.object({
+ *     reply: z.string(),
+ *     category: z.enum(['billing', 'shipping', 'product', 'other']),
+ *   })
+ *
+ *   onToolCall(call: ToolCall) {
+ *     console.log(`Calling tool: ${call.name}`)
+ *   }
+ * }
+ */
+export abstract class Agent {
+  /** Provider name (e.g., 'anthropic', 'openai'). Falls back to config default. */
+  provider?: string
+
+  /** Model identifier. Falls back to the provider's configured default model. */
+  model?: string
+
+  /** System prompt / instructions for this agent. Supports `{{key}}` context interpolation. */
+  instructions: string = ''
+
+  /** Tools available to this agent during execution. */
+  tools?: ToolDefinition[]
+
+  /** Structured output schema (Zod or JSON Schema). When set, the final response is parsed and validated. */
+  output?: OutputSchema
+
+  /** Maximum tool-use loop iterations before forcing a stop. Falls back to config default (10). */
+  maxIterations?: number
+
+  /** Maximum tokens per completion request. Falls back to config default (4096). */
+  maxTokens?: number
+
+  /** Temperature for completion requests. Falls back to config default (0.7). */
+  temperature?: number
+
+  // ── Lifecycle hooks (optional) ───────────────────────────────────────────
+
+  /** Called before the first completion request. */
+  onStart?(input: string, context: Record<string, unknown>): void | Promise<void>
+
+  /** Called when the model requests a tool call, before execution. */
+  onToolCall?(call: ToolCall): void | Promise<void>
+
+  /** Called after a tool finishes execution. */
+  onToolResult?(call: ToolCallRecord): void | Promise<void>
+
+  /** Called when the agent run completes successfully. */
+  onComplete?(result: AgentResult): void | Promise<void>
+
+  /** Called when the agent run encounters an error. */
+  onError?(error: Error): void | Promise<void>
+}