The core Island AI packages provides more low-level utilities for building custom LLM clients and data handling pipelines (schema-stream, zod-stream, stream-hooks). For a complete, ready-to-use solution, check out Instructor, which composes some of these tools into a full-featured client.
When to use core packages:
You need direct access to the HTTP stream for custom transport (e.g., not using SSE/WebSockets)
You want to build a custom LLM client
You need fine-grained control over streaming and parsing
You're implementing server-side streaming with client-side parsing
You need a structured evaluation tool
You want to use different LLM providers that don't support the OpenAI SDK format
When to use Instructor:
You want a complete solution for structured extraction
You're using WebSocket-based streaming from server to client
Your requests are only on the server
You need the full async generator pattern for progressive object updates
Instructor provides a high-level client that composes Island AI's core packages into a complete solution for structured extraction. It extends the OpenAI client with streaming and schema validation capabilities.
import Instructor from "@instructor-ai/instructor";import OpenAI from "openai";import { z } from "zod";// Define your extraction schemaconst ExtractionSchema = z.object({ users: z.array( z.object({ name: z.string(), handle: z.string(), twitter: z.string() }) ).min(3), location: z.string(), budget: z.number()});type Extraction = Partial<z.infer<typeof ExtractionSchema>>;// Initialize OpenAI client with Instructorconst oai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, organization: process.env.OPENAI_ORG_ID});const client = Instructor({ client: oai, mode: "TOOLS"});// Stream completions with structured outputconst extractionStream = await client.chat.completions.create({ messages: [{ role: "user", content: "Your text content here..." }], model: "gpt-4", response_model: { schema: ExtractionSchema, name: "Extract" }, max_retries: 3, stream: true, stream_options: { include_usage: true }});// Process streaming resultslet extraction: Extraction = {};for await (const result of extractionStream) { extraction = result; console.log('Progressive update:', result);}console.log('Final extraction:', extraction);