@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/libraries/ai/library.json

@@ -0,0 +1,19 @@
+{
+  "name": "ai",
+  "description": "LLM helper library — provider adapters (Anthropic, OpenAI), prompt registry, structured outputs, tool-calling, RAG, and an experimental agent loop. Pluggable LLMProvider interface; concrete adapters are opt-in (install only the SDK you use).",
+  "version": "0.2.0",
+  "dependencies": [],
+  "npmDependencies": {},
+  "optionalNpmDependencies": {
+    "@anthropic-ai/sdk": "^0.91.0",
+    "openai": "^6.0.0"
+  },
+  "requiredEnvVars": [],
+  "optionalEnvVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+  "postInstall": [
+    "Install the SDK for the providers you need: `npm i @anthropic-ai/sdk` and/or `npm i openai`",
+    "Import { type LLMProvider } from '@sixthsummit/ship-api/libraries/ai' and the adapter you want (e.g. AnthropicAdapter)",
+    "Construct the adapter with your API key: `const llm = new AnthropicAdapter({ apiKey: env.ANTHROPIC_API_KEY })`",
+    "All adapters share the same `LLMProvider` interface — swap providers without changing call sites"
+  ]
+}

package/lib/libraries/ai/loop/agentLoop.ts

@@ -0,0 +1,377 @@
+import type { LLMProvider } from "../adapters/LLMProvider.js";
+import type { ToolContext, ToolRegistry } from "../tools/defineTool.js";
+import type {
+  CompleteResult,
+  Message,
+  MessageContentPart,
+  StopReason,
+  TokenUsage,
+  ToolChoice,
+  ToolResultPart,
+  ToolUsePart,
+} from "../types.js";
+
+/**
+ * `agentLoop({ llm, tools, messages, ... })` — runs the model →
+ * tool-call → execute → continue cycle until the model returns
+ * `end_turn` (or `max_tokens` / `content_filter`), or until
+ * `maxIterations` is exceeded.
+ *
+ * Each iteration:
+ *   1. Call `llm.complete` with the running history + tool definitions.
+ *   2. If the response has `tool_use` content parts, execute each via
+ *      the registry and append a `user` message containing the
+ *      `tool_result` parts. Loop.
+ *   3. Otherwise, return — the model is done.
+ *
+ * The `assistant` message we append to history preserves *every*
+ * content part the model emitted (text + tool_use), in order, so the
+ * provider sees a faithful turn record on the next request — Anthropic
+ * (and OpenAI) require the assistant message to round-trip exactly so
+ * the tool_use IDs align with the matching tool_result.
+ *
+ * Errors:
+ *   - Tool handlers that throw → captured as `isError: true`
+ *     `tool_result` so the model can recover. The loop survives.
+ *   - Tool not found in the registry → also captured as
+ *     `isError: true` with a clear message; the model adapts.
+ *   - `maxIterations` exceeded → throws `AgentLoopMaxIterationsError`
+ *     with the partial history attached for debugging.
+ *   - `signal` aborts → SDK rejects, the throw propagates out of the
+ *     loop without further iteration.
+ *
+ * Observability hook: `onEvent(event)` fires synchronously for each
+ * lifecycle event. Consumers wire it to `streamSSE`, OTel spans,
+ * prompt-eval logs — anything that wants per-step visibility. Awaited
+ * if it returns a promise so callers can backpressure (e.g. SSE
+ * write).
+ *
+ * @experimental — AI-R2. NOT on the stable API surface; carries no semver
+ * stability promise and is expected to be superseded by MCP / provider-native
+ * agent runtimes. Import from `@sixthsummit/ship-api/libraries/ai/experimental`.
+ * Durable code should prefer `completeStructured` (single-shot) or call
+ * `llm.complete` directly.
+ */
+
+export interface AgentLoopOptions {
+  /** Provider that drives each iteration. */
+  llm: LLMProvider;
+  /** Tools the model can invoke. May be empty (degrades to plain `complete`). */
+  tools?: ToolRegistry;
+  /** Initial conversation history. The loop appends to a copy; the input is not mutated. */
+  messages: Message[];
+  /** Model identifier. Forwarded to `llm.complete` on every iteration. */
+  model: string;
+  /** Top-level system prompt. */
+  system?: string;
+  /**
+   * Per-iteration `max_tokens` cap forwarded to `llm.complete`. Adapter
+   * defaults apply when omitted.
+   */
+  maxTokens?: number;
+  /** Sampling temperature forwarded to `llm.complete`. */
+  temperature?: number;
+  /** Tool-choice override. Defaults to `{ type: "auto" }` when tools are present. */
+  toolChoice?: ToolChoice;
+  /**
+   * Provider-native passthrough forwarded to `llm.complete` on every
+   * iteration (e.g. prompt caching, extended thinking). Without it the
+   * seam's pass-through never reaches the adapter through the loop (AI-R1).
+   */
+  providerOptions?: Record<string, unknown>;
+  /** Request-tagging forwarded to `llm.complete` for observability / cost tracking. */
+  metadata?: Record<string, string>;
+  /**
+   * Maximum number of model→tool→model round-trips. The loop throws
+   * `AgentLoopMaxIterationsError` if the model never returns
+   * `end_turn` within this budget. Default 10.
+   */
+  maxIterations?: number;
+  /** Cancels in-flight provider requests + tool handlers. */
+  signal?: AbortSignal;
+  /**
+   * Forwarded to each tool handler's `ToolContext.metadata`. Typical
+   * contents: `{ requestId, userId, tenantId }`. Caller-defined.
+   */
+  toolMetadata?: Record<string, unknown>;
+  /** Lifecycle hook — see `AgentEvent` for event shapes. */
+  onEvent?: (event: AgentEvent) => void | Promise<void>;
+}
+
+export type AgentEvent =
+  | { type: "iteration_start"; iteration: number; messages: Message[] }
+  | { type: "model_response"; iteration: number; result: CompleteResult }
+  | {
+      type: "tool_call";
+      iteration: number;
+      toolUseId: string;
+      name: string;
+      input: Record<string, unknown>;
+    }
+  | {
+      type: "tool_result";
+      iteration: number;
+      toolUseId: string;
+      name: string;
+      ok: boolean;
+      output?: unknown;
+      error?: string;
+    }
+  | {
+      type: "iteration_end";
+      iteration: number;
+      stopReason: StopReason;
+    }
+  | {
+      type: "complete";
+      finalText: string;
+      iterations: number;
+      totalUsage: TokenUsage;
+    };
+
+export interface AgentLoopResult {
+  /** The terminal `complete()` response — i.e. the one with `stopReason !== "tool_use"`. */
+  finalMessage: CompleteResult;
+  /** Convenience: the final assistant text (already on `finalMessage.text`). */
+  finalText: string;
+  /** Number of model calls made (≥ 1). */
+  iterations: number;
+  /** Sum of input + output tokens across every iteration. */
+  totalUsage: TokenUsage;
+  /**
+   * Full conversation history as the loop saw it after termination,
+   * including all tool_use + tool_result content parts. Useful for
+   * audit trails / tests.
+   */
+  history: Message[];
+}
+
+export class AgentLoopError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AgentLoopError";
+  }
+}
+
+export class AgentLoopMaxIterationsError extends AgentLoopError {
+  constructor(
+    public readonly iterations: number,
+    public readonly history: Message[],
+  ) {
+    super(`Agent loop exceeded maxIterations=${iterations} without reaching end_turn`);
+    this.name = "AgentLoopMaxIterationsError";
+  }
+}
+
+const DEFAULT_MAX_ITERATIONS = 10;
+
+export async function agentLoop(opts: AgentLoopOptions): Promise<AgentLoopResult> {
+  const maxIterations = opts.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+  const tools = opts.tools;
+  const toolDefs = tools?.getDefinitions();
+  const toolChoice =
+    opts.toolChoice ?? (toolDefs && toolDefs.length > 0 ? { type: "auto" } : undefined);
+  const onEvent = opts.onEvent ?? (() => undefined);
+
+  const history: Message[] = [...opts.messages];
+  let totalUsage: TokenUsage = { inputTokens: 0, outputTokens: 0 };
+
+  for (let iteration = 1; iteration <= maxIterations; iteration++) {
+    if (opts.signal?.aborted) {
+      throw new AgentLoopError("Aborted before iteration " + iteration);
+    }
+    await onEvent({ type: "iteration_start", iteration, messages: history });
+
+    const result = await opts.llm.complete({
+      model: opts.model,
+      // Defensive copy: the loop mutates `history` post-call by
+      // appending the assistant turn + tool_results. Passing the live
+      // reference would leak that mutation back into adapter retry
+      // logic / test assertions on `mock.calls[].messages`.
+      messages: [...history],
+      system: opts.system,
+      maxTokens: opts.maxTokens,
+      temperature: opts.temperature,
+      tools: toolDefs && toolDefs.length > 0 ? toolDefs : undefined,
+      toolChoice,
+      signal: opts.signal,
+      providerOptions: opts.providerOptions,
+      metadata: opts.metadata,
+    });
+    totalUsage = accumulateUsage(totalUsage, result.usage);
+    await onEvent({ type: "model_response", iteration, result });
+
+    if (result.stopReason !== "tool_use") {
+      await onEvent({
+        type: "iteration_end",
+        iteration,
+        stopReason: result.stopReason,
+      });
+      // Persist the final assistant turn so the returned history is
+      // self-consistent (consumer can replay).
+      history.push({ role: "assistant", content: result.content });
+      await onEvent({
+        type: "complete",
+        finalText: result.text,
+        iterations: iteration,
+        totalUsage,
+      });
+      return {
+        finalMessage: result,
+        finalText: result.text,
+        iterations: iteration,
+        totalUsage,
+        history,
+      };
+    }
+
+    // Round-trip the assistant turn verbatim so tool_use IDs align with
+    // the tool_result IDs the next user message carries.
+    history.push({ role: "assistant", content: result.content });
+
+    const toolUseParts = result.content.filter((p): p is ToolUsePart => p.type === "tool_use");
+    if (toolUseParts.length === 0) {
+      // Provider claimed `tool_use` but emitted no tool_use blocks —
+      // treat as terminal to avoid infinite loop.
+      await onEvent({
+        type: "iteration_end",
+        iteration,
+        stopReason: "unknown",
+      });
+      await onEvent({
+        type: "complete",
+        finalText: result.text,
+        iterations: iteration,
+        totalUsage,
+      });
+      return {
+        finalMessage: result,
+        finalText: result.text,
+        iterations: iteration,
+        totalUsage,
+        history,
+      };
+    }
+
+    const toolResults: ToolResultPart[] = [];
+    for (const tu of toolUseParts) {
+      await onEvent({
+        type: "tool_call",
+        iteration,
+        toolUseId: tu.id,
+        name: tu.name,
+        input: tu.input,
+      });
+      const tool = tools?.lookup(tu.name);
+      if (!tool) {
+        const error = `tool "${tu.name}" not registered`;
+        toolResults.push({
+          type: "tool_result",
+          toolUseId: tu.id,
+          content: error,
+          isError: true,
+        });
+        await onEvent({
+          type: "tool_result",
+          iteration,
+          toolUseId: tu.id,
+          name: tu.name,
+          ok: false,
+          error,
+        });
+        continue;
+      }
+      const ctx: ToolContext = {
+        signal: opts.signal,
+        metadata: opts.toolMetadata,
+      };
+      const exec = await tool.execute(tu.input, ctx);
+      if (exec.ok) {
+        toolResults.push({
+          type: "tool_result",
+          toolUseId: tu.id,
+          content: serializeToolOutput(exec.output),
+        });
+        await onEvent({
+          type: "tool_result",
+          iteration,
+          toolUseId: tu.id,
+          name: tu.name,
+          ok: true,
+          output: exec.output,
+        });
+      } else {
+        toolResults.push({
+          type: "tool_result",
+          toolUseId: tu.id,
+          content: exec.content,
+          isError: true,
+        });
+        await onEvent({
+          type: "tool_result",
+          iteration,
+          toolUseId: tu.id,
+          name: tu.name,
+          ok: false,
+          error: exec.content,
+        });
+      }
+    }
+
+    history.push({ role: "user", content: toolResults });
+    await onEvent({
+      type: "iteration_end",
+      iteration,
+      stopReason: "tool_use",
+    });
+  }
+
+  throw new AgentLoopMaxIterationsError(maxIterations, history);
+}
+
+function accumulateUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    cacheReadInputTokens: sumOpt(a.cacheReadInputTokens, b.cacheReadInputTokens) ?? undefined,
+    cacheCreationInputTokens:
+      sumOpt(a.cacheCreationInputTokens, b.cacheCreationInputTokens) ?? undefined,
+  };
+}
+
+function sumOpt(a?: number, b?: number): number | undefined {
+  if (a === undefined && b === undefined) return undefined;
+  return (a ?? 0) + (b ?? 0);
+}
+
+function serializeToolOutput(output: unknown): string {
+  if (typeof output === "string") return output;
+  if (output === undefined || output === null) return "";
+  try {
+    return JSON.stringify(output);
+  } catch {
+    return String(output);
+  }
+}
+
+/**
+ * Helper for assertions / observability — flatten the assistant text
+ * across every iteration in the history. Useful when you want the
+ * model's full reasoning trace, not just the terminal response.
+ */
+export function collectAssistantText(history: Message[]): string[] {
+  const out: string[] = [];
+  for (const msg of history) {
+    if (msg.role !== "assistant") continue;
+    if (typeof msg.content === "string") {
+      out.push(msg.content);
+    } else {
+      const text = (msg.content as MessageContentPart[])
+        .filter((p): p is { type: "text"; text: string } => p.type === "text")
+        .map((p) => p.text)
+        .join("");
+      if (text) out.push(text);
+    }
+  }
+  return out;
+}

package/lib/libraries/ai/rag/retrieveAndAnswer.ts

@@ -0,0 +1,177 @@
+import type { LLMProvider } from "../adapters/LLMProvider.js";
+import { definePrompt, type Prompt } from "../prompts/definePrompt.js";
+import type { CompleteResult, Message } from "../types.js";
+
+/**
+ * `retrieveAndAnswer({ llm, vectorStore, query, ... })` — RAG pipeline
+ * primitive per plan §G. Retrieves the top-k relevant documents from a
+ * `VectorStore`, formats them into a context block, and asks the
+ * `LLMProvider` to answer the query grounded in those documents.
+ *
+ * Pluggable on both axes:
+ *   - `LLMProvider` is the cross-provider interface from
+ *     `adapters/LLMProvider.ts` — Anthropic / OpenAI / future
+ *     adapters all work identically.
+ *   - `VectorStore` is a structural interface defined here. The
+ *     library deliberately takes no dep on `libraries/weaviate` or
+ *     any specific store — consumers pass their own implementation
+ *     (Weaviate, Pinecone, in-memory, Postgres pgvector, …). Keeping
+ *     the dep narrow means the RAG helper is usable with any
+ *     retrieval backend the consumer happens to have.
+ *
+ * The prompt is overridable: callers can pass their own
+ * `Prompt<{ query, documents }>` to swap the template (e.g., domain-
+ * specific framing, multi-language). The default produces the
+ * standard "answer the question using only the documents below"
+ * template most RAG flows want.
+ *
+ * Output shape: `{ answer, sources, raw }`. `sources` is the original
+ * `RetrievedDocument[]` (id + score + metadata), so callers can
+ * surface citations in their UI without re-querying.
+ */
+
+export interface RetrievedDocument {
+  /** Stable identifier — surfaced as a citation marker in the prompt. */
+  id: string;
+  /** The text the model sees. */
+  text: string;
+  /** Similarity / relevance score from the store. Higher is better. */
+  score: number;
+  /** Free-form metadata (source URL, author, timestamp, …). */
+  metadata?: Record<string, unknown>;
+}
+
+export interface VectorStoreSearchOptions {
+  query: string;
+  /** Caller-defined ceiling on retrieved document count. */
+  topK: number;
+  /**
+   * Optional store-specific filter (e.g. tenant scoping). Pass
+   * unchanged to the underlying store.
+   */
+  filter?: Record<string, unknown>;
+  signal?: AbortSignal;
+}
+
+export interface VectorStore {
+  /** Stable identifier ("weaviate", "pinecone", "pgvector", …). */
+  readonly name: string;
+  /** Retrieve the top-k most relevant documents for the given query. */
+  search(opts: VectorStoreSearchOptions): Promise<RetrievedDocument[]>;
+}
+
+export interface RetrieveAndAnswerOptions {
+  /** Provider that produces the final answer. */
+  llm: LLMProvider;
+  /** Vector store to query. */
+  vectorStore: VectorStore;
+  /** The user question. */
+  query: string;
+  /** Top-k documents to retrieve. Default 5. */
+  topK?: number;
+  /** Model id forwarded to `llm.complete`. */
+  model: string;
+  /**
+   * Top-level system prompt. Defaults to a faithful-attribution
+   * instruction; override to add tone / domain framing.
+   */
+  systemPrompt?: string;
+  /**
+   * Override the prompt template. Receives `{ query, documents }`
+   * (`documents` is the formatted context block). Defaults to the
+   * built-in `RAG_DEFAULT_PROMPT`.
+   */
+  promptTemplate?: Prompt<{ query: string; documents: string }>;
+  /**
+   * Filter forwarded to `vectorStore.search` — store-specific
+   * (tenant scoping, time range, …).
+   */
+  filter?: Record<string, unknown>;
+  /**
+   * Per-document context formatter. Defaults to numbered citation
+   * markers (`[1]`, `[2]`, …) that the model can cite back. Pass a
+   * custom formatter for richer formatting (markdown headers,
+   * metadata interpolation, …).
+   */
+  formatDocument?: (doc: RetrievedDocument, index: number) => string;
+  maxTokens?: number;
+  temperature?: number;
+  signal?: AbortSignal;
+  /**
+   * Provider-native passthrough forwarded to `llm.complete` (e.g. prompt
+   * caching for the system prompt / documents). Without it the seam's
+   * pass-through never reaches the adapter through RAG (AI-R1).
+   */
+  providerOptions?: Record<string, unknown>;
+  /** Request-tagging forwarded to `llm.complete` for observability / cost tracking. */
+  metadata?: Record<string, string>;
+}
+
+export interface RetrieveAndAnswerResult {
+  /** The model's answer text (joined `text` content parts). */
+  answer: string;
+  /** Documents the answer was grounded in, in retrieval order. */
+  sources: RetrievedDocument[];
+  /** The raw provider response (id / model / usage / etc.). */
+  raw: CompleteResult;
+}
+
+const DEFAULT_TOP_K = 5;
+const DEFAULT_SYSTEM_PROMPT =
+  "You are a careful assistant. Answer the user's question using only the documents provided. If the documents don't contain the answer, say so explicitly. Cite document numbers (e.g. [1], [2]) for any claim sourced from a document.";
+
+export const RAG_DEFAULT_PROMPT = definePrompt({
+  id: "ship-api.rag.retrieve_and_answer",
+  version: 1,
+  template:
+    "Question:\n{{query}}\n\nDocuments:\n{{documents}}\n\nAnswer the question using only the documents above. Cite document numbers in square brackets for each claim sourced from a document.",
+  description: "Default RAG prompt — grounded answer with citations.",
+});
+
+export async function retrieveAndAnswer(
+  opts: RetrieveAndAnswerOptions,
+): Promise<RetrieveAndAnswerResult> {
+  const topK = opts.topK ?? DEFAULT_TOP_K;
+  const formatDocument = opts.formatDocument ?? defaultDocumentFormatter;
+  const promptTemplate = opts.promptTemplate ?? RAG_DEFAULT_PROMPT;
+
+  const sources = await opts.vectorStore.search({
+    query: opts.query,
+    topK,
+    filter: opts.filter,
+    signal: opts.signal,
+  });
+
+  const documentsBlock = sources.map((doc, i) => formatDocument(doc, i)).join("\n\n");
+
+  const userPrompt = promptTemplate.render({
+    query: opts.query,
+    documents:
+      sources.length === 0
+        ? "(no documents retrieved — answer should explicitly say no source material was available)"
+        : documentsBlock,
+  });
+
+  const messages: Message[] = [{ role: "user", content: userPrompt }];
+
+  const raw = await opts.llm.complete({
+    model: opts.model,
+    messages,
+    system: opts.systemPrompt ?? DEFAULT_SYSTEM_PROMPT,
+    maxTokens: opts.maxTokens,
+    temperature: opts.temperature,
+    signal: opts.signal,
+    providerOptions: opts.providerOptions,
+    metadata: opts.metadata,
+  });
+
+  return {
+    answer: raw.text,
+    sources,
+    raw,
+  };
+}
+
+function defaultDocumentFormatter(doc: RetrievedDocument, index: number): string {
+  return `[${index + 1}] (${doc.id}) ${doc.text}`;
+}

package/lib/libraries/ai/streaming/streamLLM.ts

@@ -0,0 +1,94 @@
+import type { StreamEvent } from "../types.js";
+
+/**
+ * Structural view of the kernel stream seam handed to streaming operation
+ * handlers (`OperationStream` from `@sixthsummit/ship-core`). Declared here so
+ * the library keeps zero runtime or type dependencies on the kernel package.
+ */
+export interface LLMFrameStream<TFrame> {
+  readonly emit: (frame: TFrame) => Promise<void>;
+  readonly signal: AbortSignal;
+}
+
+/**
+ * Minimum shape `streamLLM` requires: a string `type` plus JSON-serializable
+ * fields. The full `StreamEvent` union from this library fits.
+ */
+export interface LLMStreamFrame {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+export interface StreamLLMOptions<TFrame extends LLMStreamFrame> {
+  /**
+   * Called once if the provider iterator throws, before the error propagates
+   * to the kernel (which delivers it as a terminal `error` frame). Throwing
+   * here is swallowed so the propagation still completes.
+   */
+  readonly onError?: (error: Error) => Promise<void> | void;
+  /**
+   * Maps a provider event onto the operation's declared frame. Defaults to
+   * passing the event through unchanged.
+   */
+  readonly toFrame?: (event: StreamEvent | LLMStreamFrame, index: number) => TFrame;
+}
+
+export interface StreamLLMResult {
+  /** Number of frames handed to `emit`. */
+  readonly frames: number;
+  /** True when the run stopped early because the operation signal aborted. */
+  readonly aborted: boolean;
+}
+
+/**
+ * `streamLLM(stream, events, options?)` — pipes an LLM provider stream
+ * (typically `LLMProvider.streamComplete()`) through the kernel stream seam.
+ * Each provider event becomes one validated frame; cancellation flows from the
+ * operation's `AbortSignal` back into the provider iterator via `return()`.
+ *
+ * This is the operation-kernel counterpart of the compatibility
+ * `streamLLM(c, events)` Hono helper in `@sixthsummit/ship-api`, whose SSE
+ * layout (`event: <type>`) is unchanged. Under the kernel the frame is the
+ * whole event object and the SSE event name is always `frame`.
+ *
+ * Usage:
+ * ```ts
+ * handler: async ({ input, services, stream }) => {
+ *   const events = services.llm.streamComplete({ model, messages, signal: stream.signal });
+ *   const { frames } = await streamLLM(stream, events);
+ *   return { frames };
+ * }
+ * ```
+ */
+export async function streamLLM<TFrame extends LLMStreamFrame = StreamEvent>(
+  stream: LLMFrameStream<TFrame>,
+  events: AsyncIterable<StreamEvent | LLMStreamFrame>,
+  options: StreamLLMOptions<TFrame> = {},
+): Promise<StreamLLMResult> {
+  const toFrame = options.toFrame ?? ((event) => event as TFrame);
+  const iterator = events[Symbol.asyncIterator]();
+  let frames = 0;
+  try {
+    while (true) {
+      if (stream.signal.aborted) {
+        await iterator.return?.();
+        return { frames, aborted: true };
+      }
+      const next = await iterator.next();
+      if (next.done) return { frames, aborted: false };
+      await stream.emit(toFrame(next.value, frames));
+      frames += 1;
+    }
+  } catch (caught) {
+    const error = caught instanceof Error ? caught : new Error(String(caught));
+    if (options.onError) {
+      try {
+        await options.onError(error);
+      } catch {
+        // The hook must not mask the original failure.
+      }
+    }
+    await iterator.return?.().catch(() => undefined);
+    throw error;
+  }
+}