Design notes

A structured-output guarantee library for TypeScript/JS. Define the output shape with Zod; the LLM always returns schema-conformant data.

1. Background and problem

LLM output is free-form text, and developers face one core pain: after every call they write a pile of parsing, validation, and fallback code.

// Typical post-processing today
const raw = await llm.chat(...)
const json = JSON.parse(raw)          // may throw
if (!json.name) throw ...              // manual per-field checks
if (typeof json.age !== 'number') ... // defensive code everywhere

The Python ecosystem's answer: Instructor (10k+ stars), built on Pydantic — one line guarantees schema-conformant output.

The TypeScript ecosystem: had no equivalent. zodstructor fills that gap.

2. Target users

TypeScript developers using LLMs in Node.js, Bun, or Edge runtimes.

3. Core design principles

Principle	Meaning
Zero required deps (except zod)	LLM SDKs install on demand — no forced 300MB dependency tree
Provider-agnostic	One API adapts OpenAI / Anthropic / Google / any OpenAI-compatible endpoint
Schema-first	Define the shape with Zod; the library handles conversion, injection, validation, retry
Automatic retry	On validation failure, feed the errors back to the LLM so it repairs itself
Streaming compatible	Collect the full JSON, validate once; optional `partialSchema` for best-effort prefix checks

4. API design

4.1 Basic usage

import { z } from 'zod'
import { createZodstructor, OpenAIProvider } from 'zodstructor'

// 1. Define the schema
const UserSchema = z.object({
  name: z.string(),
  age: z.number().int().min(0),
  email: z.string().email(),
  tags: z.array(z.string()),
})

// 2. Create the client
const client = createZodstructor(new OpenAIProvider({ apiKey: '...' }))

// 3. Call — output is guaranteed to match UserSchema
const user = await client.completion({
  schema: UserSchema,
  messages: [
    { role: 'user', content: 'Extract: Ada, 36, ada@example.com, tags: admin, security' }
  ],
  model: 'gpt-4o-mini',
})
// user's type is inferred as { name: string; age: number; email: string; tags: string[] }

4.2 Streaming usage

import { streamStructured } from 'zodstructor'

const stream = streamStructured({
  provider: new OpenAIProvider({ apiKey: '...' }),
  schema: UserSchema,
  messages: [{ role: 'user', content: '...' }],
})

for await (const chunk of stream) {
  process.stdout.write(chunk)  // raw JSON text, chunk by chunk
}
const result = await stream.return()
console.log(result.value)  // validated complete object

4.3 Switching providers

// Only the provider changes; everything else stays
const client = createZodstructor(new AnthropicProvider({ apiKey: '...' }))
// or
const client = createZodstructor(new GoogleProvider({ apiKey: '...' }))
// or any OpenAI-compatible endpoint
const client = createZodstructor(new OpenAIProvider({
  apiKey: '...', baseURL: 'https://api.deepseek.com/v1'
}))

4.4 Automatic retry & error feedback

const result = await client.completion({
  schema: z.object({ score: z.number().min(0).max(100) }),
  messages: [{ role: 'user', content: '...' }],
  maxRetries: 3,                    // up to 3 retries (default)
  onRetry: (attempt, error) => {    // called on every retry
    console.log(`retry ${attempt}: ${error.message}`)
  },
})

5. Architecture

src/
├── index.ts                    # unified exports
├── core/
│   ├── types.ts                # all type definitions
│   ├── completion.ts           # Zodstructor main class + createZodstructor
│   └── retry.ts                # retry engine (core logic)
├── providers/
│   ├── base.ts                 # abstract BaseProvider
│   ├── openai.ts               # OpenAI / OpenAI-compatible
│   ├── anthropic.ts            # Anthropic (Claude)
│   ├── google.ts               # Google Gemini
│   └── index.ts
├── streaming/
│   └── index.ts                # stream collection + deferred validation
└── utils/
    └── schema.ts               # Zod → JSON Schema + JSON extraction

6. Core flow

6.1 Retry engine flow

input: schema + messages + provider
  │
  ├─ 1. Zod → JSON Schema conversion
  ├─ 2. inject schema into system prompt
  │
  ├─ 3. call LLM → raw text
  ├─ 4. extractJson() → pure JSON
  ├─ 5. JSON.parse()
  ├─ 6. schema.safeParse()
  │
  ├─ pass → return typed data
  │
  └─ fail
       ├─ attempts left
       │   ├─ append assistant message (the invalid output)
       │   ├─ append user message (error description + required schema)
       │   └─ back to step 3
       │
       └─ attempts exhausted → throw ValidationError

6.2 Schema conversion coverage

Zod type	JSON Schema
`z.string()`	`{ type: "string" }`
`z.number()` / `.int()`	`{ type: "number" }` / `{ type: "integer" }`
`z.boolean()`	`{ type: "boolean" }`
`z.array(T)`	`{ type: "array", items: T }`
`z.object({...})`	`{ type: "object", properties, required }`
`z.enum([...])` / `z.literal(V)`	`{ enum: [...] }` / `{ enum: [V] }`
`z.union([...])`	`{ anyOf: [...] }`
`optional/default/catch`	generic: not in required; strict: in required as `anyOf [T, null]`
`z.nullable(T)`	generic: `nullable: true`; strict: `anyOf [T, null]`
`z.tuple([...])`	`prefixItems` + `minItems/maxItems`
`z.record(V)`	`{ type: "object", additionalProperties: V }`
`z.intersection(A, B)`	`{ allOf: [A, B] }`
`z.discriminatedUnion(...)`	`{ oneOf: [...] }`
`z.date()`	`{ type: "string", format: "date-time" }`
`.describe('...')`	`description: "..."`
`.min(N)` / `.max(N)`	`minimum` / `maxLength` etc.

7. Provider interface

interface LLMProvider {
  name: string
  complete(params: CompletionParams): Promise<string>
  stream?(params: CompletionParams): AsyncIterable<string>
}

interface CompletionParams {
  messages: ChatMessage[]
  model?: string
  schema: JsonSchema         // JSON Schema for injection
  schemaName?: string
  maxTokens?: number
  temperature?: number
  mode?: OutputMode          // auto | json_schema | json_object | tool_call | prompt
  structured?: boolean       // legacy API; true ≡ json_schema
}

Provider strategies

Provider	Structured-output strategy
OpenAI chat.completions	`response_format: json_schema`, or `tools + tool_choice` for tool_call
OpenAI Responses	`text.format: json_schema/json_object`, or read `output[*].function_call.arguments` for tool_call
Anthropic	`tools + tool_choice` reading `tool_use.input`; otherwise system-prompt injection + raw-JSON instruction
Google	`responseMimeType: "application/json"` + `responseSchema`
OpenAI-compatible	`response_format: { type: "json_object" }` + prompt injection

8. Dependency design

dependencies:      zod (only)
peerDependencies:  openai (optional) | @anthropic-ai/sdk (optional) | @google/generative-ai (optional)
devDependencies:   tsup, typescript, vitest

Users install only the provider SDKs they actually use.

9. Comparison with Instructor (Python)

Feature	Instructor (Python)	zodstructor
Schema definition	Pydantic	Zod
Language	Python	TypeScript
Retry mechanism	Yes	Yes
Streaming	Yes	Yes
Multi-provider	Yes	Yes
Native JSON Schema	OpenAI only	OpenAI + Google
Peer deps strategy	On demand	On demand
Bundle size	~50KB	target <30KB

10. Release plan

v0.1.0 — core: Zod→JSON Schema, OpenAI provider, auto retry, unit tests
v0.2.0 — Anthropic + Google providers, streaming
v0.3.0 — OpenAI-compatible auto-discovery, more schema types
v1.0.0 — stable API, complete docs, production ready

设计说明

TypeScript/JS 结构化输出保证库。用 Zod 定义输出格式，LLM 一定返回符合 schema 的数据。

1. 背景与问题

LLM 输出是自由文本，开发者面临一个核心痛点：每次调用后都要写一大段解析 + 校验 + 容错代码。

// 典型的 LLM 调用后处理（现状）
const raw = await llm.chat(...)
const json = JSON.parse(raw)          // 可能抛异常
if (!json.name) throw ...              // 手动逐字段校验
if (typeof json.age !== 'number') ... // 防御性编程到处都是

Python 生态的解答： Instructor（GitHub 10k+ stars），基于 Pydantic，一行代码保证输出 schema 合规。

TypeScript 生态的现状： 没有对等产品，zodstructor 填补这一空白。

2. 目标用户

Node.js / Bun / Edge Runtime 中使用 LLM 的 TypeScript 开发者。

3. 核心设计原则

原则	说明
零必选依赖（除 zod）	LLM SDK 按需安装，不强制拉入 300MB 依赖
Provider 无关	同一套 API 适配 OpenAI / Anthropic / Google / 任意 OpenAI-compatible
Schema-first	用 Zod 定义期望结构，库负责转换 + 注入 + 验证 + 重试
自动重试	验证失败时把错误反馈给 LLM，让它自我修正
流式兼容	支持流式输出，收集完整 JSON 后一次性校验；可选 partialSchema 做 best-effort 前缀校验

4. API 设计

4.1 基础用法

import { z } from 'zod'
import { createZodstructor, OpenAIProvider } from 'zodstructor'

// 1. 定义 schema
const UserSchema = z.object({
  name: z.string(),
  age: z.number().int().min(0),
  email: z.string().email(),
  tags: z.array(z.string()),
})

// 2. 创建客户端
const client = createZodstructor(new OpenAIProvider({ apiKey: '...' }))

// 3. 调用 — 输出保证符合 UserSchema
const user = await client.completion({
  schema: UserSchema,
  messages: [
    { role: 'user', content: '提取用户信息：张三，25岁，zhangsan@gmail.com，标签：开发者、Vue爱好者' }
  ],
  model: 'gpt-4o-mini',
})
// user 的类型自动推断为 { name: string; age: number; email: string; tags: string[] }

4.2 流式用法

import { streamStructured } from 'zodstructor'

const stream = streamStructured({
  provider: new OpenAIProvider({ apiKey: '...' }),
  schema: UserSchema,
  messages: [{ role: 'user', content: '...' }],
})

for await (const chunk of stream) {
  process.stdout.write(chunk)  // 逐块输出原始 JSON 文本
}
const result = await stream.return()
console.log(result.value)  // 校验后的完整对象

4.3 多 Provider 切换

// 只需更换 Provider，其他代码不变
const client = createZodstructor(new AnthropicProvider({ apiKey: '...' }))
// 或
const client = createZodstructor(new GoogleProvider({ apiKey: '...' }))
// 或任意 OpenAI-compatible
const client = createZodstructor(new OpenAIProvider({
  apiKey: '...', baseURL: 'https://api.deepseek.com/v1'
}))

4.4 自动重试与错误反馈

const result = await client.completion({
  schema: z.object({ score: z.number().min(0).max(100) }),
  messages: [{ role: 'user', content: '...' }],
  maxRetries: 3,                    // 最多重试 3 次（默认）
  onRetry: (attempt, error) => {    // 每次重试的回调
    console.log(`第 ${attempt} 次重试：${error.message}`)
  },
})

5. 架构设计

src/
├── index.ts                    # 统一导出
├── core/
│   ├── types.ts                # 所有类型定义
│   ├── completion.ts           # Zodstructor 主类 + createZodstructor
│   └── retry.ts                # 重试引擎（核心逻辑）
├── providers/
│   ├── base.ts                 # 抽象基类 BaseProvider
│   ├── openai.ts               # OpenAI / OpenAI-compatible
│   ├── anthropic.ts            # Anthropic (Claude)
│   ├── google.ts               # Google Gemini
│   └── index.ts
├── streaming/
│   └── index.ts                # 流式输出收集 + 延迟校验
└── utils/
    └── schema.ts               # Zod → JSON Schema 转换 + JSON 提取

6. 核心流程

6.1 重试引擎流程

输入: schema + messages + provider
  │
  ├─ 1. Zod → JSON Schema 转换
  ├─ 2. 注入 schema 到 system prompt
  │
  ├─ 3. 调用 LLM → 获取原始文本
  ├─ 4. extractJson() → 提取纯 JSON
  ├─ 5. JSON.parse() → 解析
  ├─ 6. schema.safeParse() → Zod 校验
  │
  ├─ 校验成功 → 返回 typed data
  │
  └─ 校验失败
       ├─ 尝试次数未用完
       │   ├─ 追加 assistant 消息（上次的错误输出）
       │   ├─ 追加 user 消息（错误描述 + 正确 schema）
       │   └─ 回到第 3 步
       │
       └─ 尝试次数用完 → 抛出 ValidationError

6.2 Schema 转换覆盖

Zod 类型	JSON Schema
`z.string()`	`{ type: "string" }`
`z.number()` / `.int()`	`{ type: "number" }` / `{ type: "integer" }`
`z.boolean()`	`{ type: "boolean" }`
`z.array(T)`	`{ type: "array", items: T }`
`z.object({...})`	`{ type: "object", properties, required }`
`z.enum([...])` / `z.literal(V)`	`{ enum: [...] }` / `{ enum: [V] }`
`z.union([...])`	`{ anyOf: [...] }`
`optional/default/catch`	generic 不加入 required；strict 加入且表示为 `anyOf [T, null]`
`z.nullable(T)`	generic：`nullable: true`；strict：`anyOf [T, null]`
`z.tuple([...])`	`prefixItems` + `minItems/maxItems`
`z.record(V)`	`{ type: "object", additionalProperties: V }`
`z.intersection(A, B)`	`{ allOf: [A, B] }`
`z.discriminatedUnion(...)`	`{ oneOf: [...] }`
`z.date()`	`{ type: "string", format: "date-time" }`
`.describe('...')`	`description: "..."`
`.min(N)` / `.max(N)`	`minimum` / `maxLength` 等

7. Provider 接口

interface LLMProvider {
  name: string
  complete(params: CompletionParams): Promise<string>
  stream?(params: CompletionParams): AsyncIterable<string>
}

interface CompletionParams {
  messages: ChatMessage[]
  model?: string
  schema: JsonSchema         // 注入用的 JSON Schema
  schemaName?: string
  maxTokens?: number
  temperature?: number
  mode?: OutputMode          // auto | json_schema | json_object | tool_call | prompt
  structured?: boolean       // 兼容旧 API；true 等价 json_schema
}

Provider 差异化策略

Provider	结构化策略
OpenAI chat.completions	`response_format: json_schema`，或 `tool_call` 时 `tools + tool_choice`
OpenAI Responses	`text.format: json_schema/json_object`，或 `tool_call` 时读取 `output[*].function_call.arguments`
Anthropic	`tool_call` 时 `tools + tool_choice` 并读取 `tool_use.input`；否则 system prompt 注入 + 要求只返回 JSON
Google	`responseMimeType: "application/json"` + `responseSchema`
OpenAI-compatible	`response_format: { type: "json_object" }` + prompt 注入

8. 依赖设计

dependencies:      zod (唯一)
peerDependencies:  openai (可选) | @anthropic-ai/sdk (可选) | @google/generative-ai (可选)
devDependencies:   tsup, typescript, vitest

用户只需安装自己使用的 provider SDK。

9. 与 Instructor (Python) 的对比

特性	Instructor (Python)	zodstructor
Schema 定义	Pydantic	Zod
语言	Python	TypeScript
重试机制	有	有
流式支持	有	有
多 Provider	有	有
原生 JSON Schema	仅 OpenAI	OpenAI + Google
Peer deps 策略	按需	按需
包体积	~50KB	目标 <30KB

10. 发布计划

v0.1.0 —— 核心功能：Zod→JSON Schema、OpenAI provider、自动重试、单元测试
v0.2.0 —— Anthropic + Google provider、流式支持
v0.3.0 —— OpenAI-compatible 自动发现、更多 schema 类型
v1.0.0 —— 稳定 API、完整文档、生产就绪