@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/libraries/ai/types.ts

@@ -0,0 +1,260 @@
+/**
+ * Shared types for the LLM helper library — the lingua franca every
+ * `LLMProvider` adapter (Anthropic, OpenAI, future Bedrock / Vertex /
+ * local-Ollama) translates to and from. Adapters own provider-specific
+ * SDK shapes; the framework never sees them.
+ *
+ * Designed for the v4 plan §G surface: `complete`, `streamComplete`,
+ * structured outputs (Zod schema → typed `T`), tool calling, agent
+ * loop, embeddings, token counting, streaming through Hono `streamSSE`.
+ *
+ * Type-only — no runtime imports.
+ */
+
+/**
+ * One conversational turn. The role identifies the speaker; content is
+ * either a single text string (the common case) or an ordered array of
+ * `MessageContentPart`s (mixed text + tool-use + tool-result + image
+ * parts, used for tool-calling and multi-modal flows).
+ *
+ * `system` messages are *not* in the array — providers handle them as a
+ * top-level option (`opts.system`) per their respective API conventions.
+ * Mixing them in here would force every adapter to scan the array and
+ * extract them, which is ceremony.
+ */
+export interface Message {
+  role: "user" | "assistant" | "tool";
+  content: string | MessageContentPart[];
+  /** Optional name for tool-result messages (echoes the tool name). */
+  name?: string;
+}
+
+export type MessageContentPart = TextPart | ToolUsePart | ToolResultPart | ImagePart;
+
+export interface TextPart {
+  type: "text";
+  text: string;
+}
+
+export interface ToolUsePart {
+  type: "tool_use";
+  /** Adapter-issued tool-call ID; passed back in the matching `ToolResultPart`. */
+  id: string;
+  name: string;
+  /** Parsed JSON object. Adapters parse the provider's raw string for us. */
+  input: Record<string, unknown>;
+}
+
+export interface ToolResultPart {
+  type: "tool_result";
+  /** ID of the originating `ToolUsePart`. */
+  toolUseId: string;
+  /** Stringified result; adapters serialize objects via JSON.stringify. */
+  content: string;
+  /** True if the tool handler threw — providers handle errors differently. */
+  isError?: boolean;
+}
+
+export interface ImagePart {
+  type: "image";
+  /** Base64-encoded bytes (no data: prefix). */
+  data: string;
+  mediaType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+}
+
+/**
+ * Top-level options to a single non-streaming completion request.
+ * Provider-specific tunables (e.g., Anthropic `top_k`, OpenAI
+ * `frequency_penalty`) ride along in `providerOptions` so they don't
+ * pollute the cross-provider surface.
+ */
+export interface CompleteOptions {
+  model: string;
+  messages: Message[];
+  /** Top-level system prompt. Providers pass it as their dedicated field. */
+  system?: string;
+  /** Caller-defined ceiling. Adapters apply provider-specific defaults if omitted. */
+  maxTokens?: number;
+  /** 0–1; adapters clamp / translate to provider scales. */
+  temperature?: number;
+  /** Tool definitions the model may invoke. */
+  tools?: ToolDefinition[];
+  /**
+   * Force a specific tool, allow any tool, or disable tool use entirely.
+   * Mirrors Anthropic / OpenAI "tool_choice" semantics.
+   */
+  toolChoice?: ToolChoice;
+  /** Stop sequences. */
+  stopSequences?: string[];
+  /** AbortSignal — adapters wire to the SDK's abort path. */
+  signal?: AbortSignal;
+  /**
+   * Pass-through for provider-specific options the unified surface
+   * doesn't yet model. Adapters merge into the provider request.
+   */
+  providerOptions?: Record<string, unknown>;
+  /** Request-tagging for observability / cost-tracking integrations. */
+  metadata?: Record<string, string>;
+}
+
+export type ToolChoice =
+  | { type: "auto" }
+  | { type: "any" }
+  | { type: "none" }
+  | { type: "tool"; name: string };
+
+/**
+ * Structural tool definition. The library's `defineTool({...})` factory
+ * (later commit) produces these from a Zod schema + handler; adapters
+ * forward the JSON Schema as-is.
+ */
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  /** JSON Schema (Draft 7+) describing the tool's input. */
+  inputSchema: Record<string, unknown>;
+}
+
+/**
+ * Result of a non-streaming completion. The `content` array preserves
+ * every part the model emitted (text + tool-use + …) in order; callers
+ * filter for what they need. `text` is a convenience join of all text
+ * parts.
+ */
+export interface CompleteResult {
+  /** Provider's stable identifier for this response (e.g. for retries). */
+  id: string;
+  model: string;
+  content: MessageContentPart[];
+  /** Convenience: concatenated text parts. */
+  text: string;
+  /** Why the model stopped — normalized across providers. */
+  stopReason: StopReason;
+  /** Stop sequence that triggered, when stopReason === "stop_sequence". */
+  stopSequence?: string;
+  usage: TokenUsage;
+  /** Pass-through for provider-specific extras (e.g. caching metadata). */
+  providerExtras?: Record<string, unknown>;
+  /**
+   * The untranslated provider SDK response — escape hatch for native
+   * fields the unified surface drops (thinking blocks, citations,
+   * server-tool use, …). Shape is provider-specific; cast at the use site.
+   */
+  raw?: unknown;
+}
+
+export type StopReason =
+  | "end_turn"
+  | "max_tokens"
+  | "stop_sequence"
+  | "tool_use"
+  | "content_filter"
+  | "unknown";
+
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  /** Provider-supported cache reads (Anthropic prompt caching). */
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+  /**
+   * Reasoning/thinking tokens billed as output (OpenAI o-series
+   * `completion_tokens_details.reasoning_tokens`; Anthropic extended
+   * thinking). Present only when the provider reports it.
+   */
+  reasoningTokens?: number;
+  /** The untranslated provider usage object — escape hatch for fields not modeled here. */
+  raw?: unknown;
+}
+
+/**
+ * Streaming events. Adapters translate each provider's stream protocol
+ * (Anthropic SSE event-types, OpenAI delta chunks) into this set.
+ *
+ * Event order on a successful turn:
+ *   1. one `start` (model id + initial usage if available)
+ *   2. zero-or-more `text_delta` (incremental content tokens)
+ *   3. zero-or-more `tool_use_start` + `tool_input_delta` + `tool_use_end`
+ *      groups (one per tool call the model emits)
+ *   4. one `stop` (stopReason + final usage)
+ *
+ * Errors throw out of the iterator — no `error` event variant; callers
+ * use try/catch or `for await` rejection.
+ */
+export type StreamEvent =
+  | StreamStartEvent
+  | StreamTextDeltaEvent
+  | StreamToolUseStartEvent
+  | StreamToolInputDeltaEvent
+  | StreamToolUseEndEvent
+  | StreamStopEvent;
+
+export interface StreamStartEvent {
+  type: "start";
+  id: string;
+  model: string;
+}
+
+export interface StreamTextDeltaEvent {
+  type: "text_delta";
+  /** The new token(s) to append. */
+  delta: string;
+}
+
+export interface StreamToolUseStartEvent {
+  type: "tool_use_start";
+  /** Adapter-issued ID for matching `tool_input_delta` / `tool_use_end`. */
+  id: string;
+  name: string;
+}
+
+export interface StreamToolInputDeltaEvent {
+  type: "tool_input_delta";
+  id: string;
+  /** Partial JSON string; concatenate to reconstruct the full input. */
+  partialJson: string;
+}
+
+export interface StreamToolUseEndEvent {
+  type: "tool_use_end";
+  id: string;
+  /** Parsed input — adapter does the JSON.parse once the tool_use closes. */
+  input: Record<string, unknown>;
+}
+
+export interface StreamStopEvent {
+  type: "stop";
+  stopReason: StopReason;
+  stopSequence?: string;
+  usage: TokenUsage;
+  /** Pass-through for provider-specific extras on the final event (parity with `CompleteResult`). */
+  providerExtras?: Record<string, unknown>;
+  /** The untranslated final provider event/message — streaming escape hatch (parity with `CompleteResult.raw`). */
+  raw?: unknown;
+}
+
+/**
+ * Streaming-request options. Same shape as `CompleteOptions` minus the
+ * `signal` (kept) — kept identical to make swapping `complete` /
+ * `streamComplete` mechanical.
+ */
+export type StreamCompleteOptions = CompleteOptions;
+
+/**
+ * Embeddings — vector representation of input text(s). One adapter call
+ * may embed multiple inputs in a single batch.
+ */
+export interface EmbedOptions {
+  model: string;
+  /** One or more strings to embed. Adapters may chunk into provider-permitted batch sizes. */
+  inputs: string[];
+  signal?: AbortSignal;
+  providerOptions?: Record<string, unknown>;
+}
+
+export interface EmbedResult {
+  model: string;
+  /** One vector per input, in the same order. */
+  embeddings: number[][];
+  usage: { inputTokens: number };
+}

package/lib/libraries/chunking/ChunkingService.ts

@@ -0,0 +1,103 @@
+import type { ChunkingStrategy } from "./strategies/ChunkingStrategy.js";
+import { FixedLengthChunkingStrategy } from "./strategies/FixedLengthChunkingStrategy.js";
+import { SemanticChunkingStrategy } from "./strategies/SemanticChunkingStrategy.js";
+import { SlidingWindowChunkingStrategy } from "./strategies/SlidingWindowChunkingStrategy.js";
+import type {
+  ChunkingOptions,
+  FixedLengthChunkingOptions,
+  SemanticChunkingOptions,
+  SlidingWindowChunkingOptions,
+  TextChunk,
+} from "./types/index.js";
+
+/**
+ * Service for chunking documents for embedding using various strategies
+ */
+export class ChunkingService {
+  private strategy: ChunkingStrategy;
+
+  /**
+   * Creates a new ChunkingService with the specified strategy
+   * @param strategy - The chunking strategy to use
+   */
+  constructor(strategy: ChunkingStrategy) {
+    this.strategy = strategy;
+  }
+
+  /**
+   * Chunks the given text using the configured strategy
+   * @param text - The text to chunk
+   * @returns An array of text chunks
+   */
+  async chunk(text: string): Promise<TextChunk[]> {
+    if (!text || text.trim().length === 0) {
+      return [];
+    }
+
+    return await this.strategy.chunk(text);
+  }
+
+  /**
+   * Sets a new chunking strategy
+   * @param strategy - The new strategy to use
+   */
+  setStrategy(strategy: ChunkingStrategy): void {
+    this.strategy = strategy;
+  }
+
+  /**
+   * Factory method to create a ChunkingService with fixed length strategy
+   * @param options - Configuration options for fixed length chunking
+   * @returns A new ChunkingService instance
+   */
+  static createWithFixedLength(options: FixedLengthChunkingOptions): ChunkingService {
+    const strategy = new FixedLengthChunkingStrategy(options);
+    return new ChunkingService(strategy);
+  }
+
+  /**
+   * Factory method to create a ChunkingService with sliding window strategy
+   * @param options - Configuration options for sliding window chunking
+   * @returns A new ChunkingService instance
+   */
+  static createWithSlidingWindow(options: SlidingWindowChunkingOptions): ChunkingService {
+    const strategy = new SlidingWindowChunkingStrategy(options);
+    return new ChunkingService(strategy);
+  }
+
+  /**
+   * Factory method to create a ChunkingService with semantic strategy
+   * Industry Best Practice: Use for RAG and embedding applications requiring semantic coherence
+   *
+   * @param options - Configuration options for semantic chunking
+   * @returns A new ChunkingService instance
+   */
+  static createWithSemantic(options: SemanticChunkingOptions): ChunkingService {
+    const strategy = new SemanticChunkingStrategy(options);
+    return new ChunkingService(strategy);
+  }
+
+  /**
+   * Factory method to create a ChunkingService with the appropriate strategy based on options
+   * @param options - Configuration options for chunking
+   * @returns A new ChunkingService instance
+   */
+  static create(options: ChunkingOptions): ChunkingService {
+    if ("overlapTokens" in options) {
+      return ChunkingService.createWithSlidingWindow(options);
+    } else if ("minTokens" in options || "mergeSmallChunks" in options) {
+      return ChunkingService.createWithSemantic(options as SemanticChunkingOptions);
+    } else {
+      return ChunkingService.createWithFixedLength(options);
+    }
+  }
+
+  /**
+   * Cleanup method to dispose of the strategy if needed
+   */
+  dispose(): void {
+    if ("dispose" in this.strategy && typeof this.strategy.dispose === "function") {
+      (this.strategy as any).dispose();
+    }
+  }
+}

package/lib/libraries/chunking/README.md

@@ -0,0 +1,104 @@
+# `libraries/chunking/` — Document chunking for RAG
+
+Document chunking primitives for preparing text for embedding and Retrieval-Augmented Generation (RAG). Strategy-pattern API with three interchangeable algorithms.
+
+> **Install via**: `ship-api add -l chunking`. Pulls in `tiktoken` for OpenAI-compatible token counts.
+
+## Features
+
+- **Three Chunking Strategies**:
+  - **Fixed Length** — Simple, fast chunking for prototyping
+  - **Sliding Window** — Overlapping chunks with intelligent boundary detection
+  - **Semantic** — Structure-aware chunking (recommended for production)
+- **Accurate Token Counting** — Uses tiktoken for OpenAI-compatible token counts
+- **Strategy Pattern** — Swap strategies at runtime without changing client code
+- **Structure-Aware** — Preserves code blocks, lists, headers, and paragraphs
+- **TypeScript** — Full type safety with exported interfaces
+
+## Quick Start
+
+```typescript
+import { ChunkingService } from "@sixthsummit/ship-api/libraries/chunking";
+
+// Semantic chunking (recommended for production RAG)
+const service = ChunkingService.createWithSemantic({
+  maxTokens: 512,
+  minTokens: 100,
+  mergeSmallChunks: true,
+});
+
+const chunks = await service.chunk(document);
+
+for (const chunk of chunks) {
+  console.log(`Chunk ${chunk.chunkIndex}: ${chunk.tokenCount} tokens`);
+  // Send to your embedding service...
+}
+
+service.dispose(); // Always clean up
+```
+
+## Strategies at a Glance
+
+| Strategy           | Speed   | Quality | Overlap | Best For                        |
+| ------------------ | ------- | ------- | ------- | ------------------------------- |
+| **Fixed Length**   | Fastest | Basic   | No      | Prototyping, uniform text       |
+| **Sliding Window** | Medium  | Good    | Yes     | Narrative content, articles     |
+| **Semantic**       | Slower  | Best    | No      | Production RAG, structured docs |
+
+```typescript
+// Sliding Window — overlapping chunks with boundary detection
+const service = ChunkingService.createWithSlidingWindow({
+  maxTokens: 512,
+  overlapTokens: 80,
+  preferParagraphBoundaries: true,
+});
+
+// Fixed Length — simple token-based splitting
+const service = ChunkingService.createWithFixedLength({
+  maxTokens: 512,
+});
+```
+
+## Output Format
+
+Every strategy returns an array of `TextChunk` objects:
+
+```typescript
+interface TextChunk {
+  content: string; // The text content
+  startIndex: number; // Character position in original document
+  endIndex: number; // End character position
+  tokenCount: number; // Token count (via tiktoken)
+  chunkIndex: number; // Sequential chunk number (0-indexed)
+}
+```
+
+## Documentation
+
+Comprehensive documentation is available in the [`docs/`](docs/) folder:
+
+| Document                                           | Description                                                 |
+| -------------------------------------------------- | ----------------------------------------------------------- |
+| **[Quick Start](docs/quick-start.md)**             | Get started in 5 minutes                                    |
+| **[Strategies Guide](docs/strategies.md)**         | Deep dive into each strategy with algorithms and comparison |
+| **[API Reference](docs/api-reference.md)**         | Complete class, method, and type documentation              |
+| **[Configuration](docs/configuration.md)**         | All options, tuning, and embedding model alignment          |
+| **[Best Practices](docs/best-practices.md)**       | Production guidance, advanced techniques, and pitfalls      |
+| **[Code Organization](docs/code-organization.md)** | Architecture, conventions, and creating custom strategies   |
+| **[Troubleshooting](docs/troubleshooting.md)**     | Common issues and solutions                                 |
+| **[Documentation Index](docs/index.md)**           | Full navigation hub                                         |
+
+## Installation
+
+Add the library to your ShipAPI project:
+
+```bash
+npx ship-api add chunking --lib
+```
+
+This installs the library files and the `tiktoken` dependency.
+
+## Requirements
+
+- Node.js >= 22
+- tiktoken (installed automatically via CLI)