File size: 2,073 Bytes
6dec997 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 | # Contract Kit
Schema-first reliability helpers for structured AI outputs.
Contract Kit wraps model calls with the guardrails production teams usually end up rebuilding:
- JSON extraction from model responses
- schema validation with Zod or any compatible `.parse()` schema
- automatic repair retries
- replayable failure artifacts
- lightweight event hooks for observability
- provider adapters without forcing provider SDKs into your dependency tree
## Install
```sh
npm install @krishthesmart/contract-kit zod
```
## Usage
```ts
import { z } from "zod";
import { generateContract, openAIResponsesAdapter } from "@krishthesmart/contract-kit";
import OpenAI from "openai";
const client = new OpenAI();
const UserProfile = z.object({
name: z.string(),
role: z.string(),
risk: z.enum(["low", "medium", "high"])
});
const result = await generateContract({
model: openAIResponsesAdapter(client, {
model: "gpt-4.1-mini",
temperature: 0
}),
schema: UserProfile,
prompt: "Extract the user's profile from this support ticket: ...",
retries: 2,
onEvent(event) {
console.log(event.type);
}
});
console.log(result.data);
```
`result.data` is guaranteed to be the schema output type if the call succeeds.
If every attempt fails, Contract Kit throws a typed error containing `replay`, which can be saved as a test fixture.
## Model Interface
Any model can be used by implementing one method:
```ts
const model = {
async generate(prompt: string) {
return callYourModel(prompt);
}
};
```
## Why This Exists
Structured AI output is still brittle in production. Responses arrive with markdown fences, invalid JSON, changed enum values, missing fields, and provider-specific edge cases. Contract Kit gives application teams a small, auditable boundary where those failures are retried, logged, and turned into reproducible tests.
## Roadmap
- Anthropic adapter
- Vercel AI SDK adapter
- OpenTelemetry event exporter
- schema version diffing
- fixture runner for replay files
- CLI to turn production failures into regression tests
|