DEV Community: Yatin Davra

Past the README Demo: Conversations, Healthcare Data, Agents, and CI Checks

Yatin Davra — Thu, 27 Aug 2026 06:17:13 +0000

"Extract a name and email from this sentence" is the easy 10% of structured output. The other 90% is everything that doesn't fit in one prompt, one turn, or one model call. Here are five things shapecraft handles once you're past the basics.

1. Collecting data across a whole conversation

A single message rarely has everything you need. Someone books an appointment over three or four back-and-forth messages, not one. turnaround mode lets the conversation run naturally and validates the whole transcript once, at the end, against one schema:

import { generate, openai } from "@aviasole/shapecraft";

const result = await generate(model, BookingSchema, conversationHistory, {
  turnaround: true,
});

No manual "do I have everything yet?" tracking, no partial-state bugs, just one validated object once the conversation is actually complete.

2. Extracting from clinical notes into real FHIR shapes

Healthcare data has a standard (FHIR R4) and it's not optional if you're integrating with anything real. Built-in presets mean you're not hand-writing a Patient or Observation schema from scratch:

import { generate, openai } from "@aviasole/shapecraft/fhir";
import { PatientSchema } from "@aviasole/shapecraft/fhir";

const patient = await generate(openai({ model: "gpt-4o-mini" }), PatientSchema, clinicalNote);

Same retry/validation guarantees as any other schema, just pre-built to match a spec you'd otherwise have to implement yourself.

3. An agent that checks real data before answering

"Is this order still on hold?" isn't answerable from the prompt alone, it needs an actual lookup. generateWithTools() lets the model call your functions, see the results, and then produce a validated final answer:

import { generateWithTools } from "@aviasole/shapecraft";

const result = await generateWithTools(model, [lookupOrder], AnswerSchema, userQuestion);

The tool call's arguments are validated before your function ever runs, and the final answer goes through the same schema check as a normal generate() call.

4. Chaining validated steps into a pipeline

Triage, then diagnose, then draft a response, each step needs the previous step's validated output, not its raw text. runAgents() chains a sequence of generate() calls, each with its own model and schema, threading validated data forward:

import { defineAgent, runAgents } from "@aviasole/shapecraft/agentic";

const triage = defineAgent({ model, schema: TriageSchema, role: "triage" });
const diagnose = defineAgent({ model, schema: DiagnosisSchema, role: "diagnose" });

const result = await runAgents([triage, diagnose], input);

Each step keeps its own retry behavior, there's no shared fragile state between them.

5. Checking a JSON file against a schema, no code required

Sometimes the thing you need to validate isn't fresh model output, it's a file that already exists, maybe from a batch job, a CI pipeline, or someone else's export. The CLI does the same structural check generate() uses internally, from the terminal:

npx shapecraft validate --schema schema.json --output output.json

Exits 0 and prints a check mark on success, exits 1 with the specific violation on failure. Handy for a CI step that shouldn't need its own validation script.

The pattern underneath all of it

Multi-turn, healthcare presets, tool calling, agent pipelines, file validation, none of these are separate systems bolted on. They're all the same generate() retry-and-validate core, pointed at a different shape of input or output.

We've published full documentation covering all of this (and everything from the last post too) at aviasoletechnologies.github.io/shapecraft - worth a look if any of these five sound like your actual problem.

5 Things I've Actually Used shapecraft For

Yatin Davra — Wed, 19 Aug 2026 04:55:38 +0000

Every structured-output library's README shows you the same demo: extract a name and age from a sentence, get back clean JSON. Cool, but that's not really a use case, that's a unit test.

Here's what I've actually reached for shapecraft for, across a handful of real projects. Five short examples, no fluff, so you can see where this fits before you commit to reading the full docs.

1. Turning support tickets into triageable data

A raw customer message ("hey my invoice from last month looks wrong and also the app crashed twice") isn't something you can route or prioritize as-is. Give it a schema instead:

import { generate, openai } from "@aviasole/shapecraft";
import { z } from "zod";

const TicketSchema = z.object({
  category: z.enum(["billing", "bug", "how-to", "account"]),
  priority: z.enum(["low", "normal", "urgent"]),
  summary: z.string(),
});

const result = await generate(openai({ model: "gpt-4o-mini" }), TicketSchema, rawMessage);

One call, one typed object, ready to drop into a queue.

2. Parsing receipts, invoices, and other "almost structured" documents

OCR'd text from a receipt is a mess of line items, totals, and stray whitespace. Instead of writing regex to hunt for the total, describe the shape you want and let the model do the extraction:

const ReceiptSchema = z.object({
  vendor: z.string(),
  total: z.number(),
  lineItems: z.array(z.object({ name: z.string(), price: z.number() })),
});

Same generate() call, same guarantees, just a different schema.

3. Slot-filling for a form-driven chatbot

Onboarding flows ("what's your name, email, and company size?") don't need a whole conversation engine, they need a bot that keeps asking until it has every required field, validated. shapecraft's generate() retry loop already does the "keep trying until it's valid" part, so the bot logic is just: ask, extract, check what's missing, repeat.

4. Running a local model with a real guarantee

Not everything can leave the device. For document classification that has to run fully offline, llamaCpp() applies a GBNF grammar at the token level, so the model cannot produce anything outside your five category labels, not "usually doesn't," actually can't:

import { llamaCpp } from "@aviasole/shapecraft";

const model = llamaCpp({ modelPath: "./models/llama-3.2-3b.gguf" });
const result = await generate(model, { gbnf: categoryGrammar }, chunk);

That's the difference between constrained and best-effort guarantee levels, and it matters a lot more once you're running unattended over a few thousand files overnight.

5. Batch-processing a folder of anything

Classify, summarize, or extract from a directory of files without hand-rolling concurrency control:

import { generateBatch } from "@aviasole/shapecraft";

const results = await generateBatch(
  model,
  schema,
  files.map((f) => f.text),
  { concurrency: 5 }
);

Each item validates and retries independently, so one bad file doesn't take down the batch.

That's the range

Ticket triage, document extraction, chatbot slot-filling, offline classification, batch jobs, all the same core idea: describe the shape you want, get back something you can actually trust. Check result.guaranteeLevel any time you want to know exactly how much.

One more thing: we've now published full documentation, with a guide for every feature mentioned here (and a bunch not covered in this post, like streaming, tool calling, and multi-agent orchestration). Go explore it at aviasoletechnologies.github.io/shapecraft.

I Streamed Structured Output Into a Live Panel. A Field Rendered Before I Knew It Was Wrong

Yatin Davra — Thu, 13 Aug 2026 13:19:40 +0000

The panel was for our support team. An agent pastes a customer's message in, and four fields fill in next to it: category, priority, a one-line summary, and which team it should go to. All four come from one model call against one schema. Nothing exotic - a single generate() call would have done it in about three lines.

The problem was the three seconds that call took. Agents kept re-clicking the button mid-request, assuming it had hung, because the panel just sat there blank until the whole object came back at once. So the ask became: show each field the moment it's ready, not all four at once at the end.

First pass: parse whatever text has arrived so far

The obvious move was to switch to the streaming call, take the raw text deltas as they arrived, and after every delta try JSON.parse() on whatever had accumulated so far, wrapped in a try/catch. If it parsed, grab whatever fields existed and render them.

It almost never parsed. An object with unclosed braces throws every time, right up until the very last delta closes the outer }. So in practice this did nothing for the entire three seconds and then dumped all four fields on screen at once anyway - the same experience as not streaming, with extra code.

Second pass: track bracket depth by hand

Next I tried tracking whether a field's value had structurally closed by counting {/} and quote state as deltas came in, and slicing out that one field's substring the moment its depth returned to zero. That got fields appearing one at a time, which was the actual goal.

It also broke in two ways I didn't expect. The assignee field wasn't a plain string, it was { team, reason }, and nested braces threw my depth counter off by exactly the amount you'd guess. And separately - this is the one that actually worried me - "structurally closed" isn't the same as "correct." The model once returned "priority": "urgent-ish" instead of one of the four enum values. My counter saw the closing quote, decided the field was done, and rendered an orange "urgent-ish" badge on screen. A second later, when the full object finally failed validation and the whole thing retried, the badge silently flipped to something else. From the agent's side, a wrong priority had flashed on their ticket for a second before quietly changing. That's a bad thing to ship to people making triage calls under time pressure.

What was already there

I went looking for how generateStream() itself decides when a field is "done," assuming I'd have to patch around it, and found it already draws the line where I actually needed it drawn: a field only becomes visible once it's both structurally closed and has passed its own piece of the schema.

import { generateStream, openai } from "@aviasole/shapecraft";
import { z } from "zod";

const TicketSchema = z.object({
  category: z.enum(["billing", "bug", "how-to", "account"]),
  priority: z.enum(["low", "normal", "urgent"]),
  summary: z.string(),
  assignee: z.object({ team: z.string(), reason: z.string() }),
});

const stream = generateStream(openai({ model: "gpt-4o-mini" }), TicketSchema, rawMessage);

for await (const event of stream.events) {
  if (event.type === "partial") {
    renderFields(event.value); // only ever the fields that have already passed validation
  }
  if (event.type === "attempt-failed") {
    resetPanel(); // a field failed its own check mid-stream; the next attempt starts clean
  }
}

const { data } = await stream.result;

The partial event only fires after a field is checked against its own sub-schema, not just parsed. So a priority of "urgent-ish" never reaches renderFields() at all - the moment that field fails, the attempt is marked failed and abandoned mid-stream, without waiting to finish consuming the rest of that doomed response, and a fresh attempt starts. The panel never had a badge to flip back from, because it never rendered the wrong one in the first place.

The nested assignee object turned out to be handled too, just at a coarser grain than I expected: it's validated and emitted as one field once its own { team, reason } closes, not field-by-field inside it. That was finer-grained than my hand-rolled version actually needed to be.

Where it landed

Fields now start appearing within a few hundred milliseconds of the first one closing instead of all landing at once after three seconds, so the panel stopped looking hung. And the flash-then-correct badge, which agents had started asking about roughly once a shift under my bracket-counting version, hasn't come back - there's nothing left to flash, because nothing renders until it's already right.

I Wrote the Same Tool-Calling Loop Three Times, Once Per Provider, Before I Stopped

Yatin Davra — Mon, 10 Aug 2026 11:28:03 +0000

The job was an internal ops assistant. Someone asks "is order 4521 still on hold and what's the customer's plan tier?", and answering it means hitting two of our own services first - the orders API and the billing API - then coming back with a short structured summary my UI could render. Not a chatbot. The final answer had to be { status, tier, summary }, typed, every time, because a component was rendering it.

The lookups were the easy part; they're just two functions I already had. What I needed was for the model to decide which of them to call, with what arguments, see what came back, and then produce that structured answer. And I needed the arguments it invented to be trustworthy before they reached functions that hit real internal services.

The loop I wrote, then wrote again

OpenAI's tool-calling API is genuinely pleasant, so version one took an afternoon: pass tools, read message.tool_calls, JSON.parse the arguments, dispatch to the right function, push a role: "tool" message back, loop until the model stops asking. Maybe 60 lines with the turn guard.

Then I wanted Anthropic for the summarizing step, because it was better at it. Anthropic's wire format is not OpenAI's. Tool requests arrive as tool_use content blocks inside the message rather than a parallel tool_calls array, and results go back as tool_result blocks in a user message, not a dedicated tool role. So the dispatch loop got rewritten - same logic, different shape, second copy.

Then, because some of this had to run against a local model for a cost experiment, Ollama. Different again. Third copy.

Three loops, all doing the identical thing, each subtly wrong in its own way for a while. And a switch on provider name sitting in the middle of my application code, which is exactly the kind of thing I don't want to own.

The bug that actually worried me

Somewhere in copy two, a model called my order lookup with { orderId: 4521 } - a number, where every other time it had sent the string "4521". My handler did orderId.trim() and the whole request died with a TypeError from inside a function that had no business receiving a number in the first place.

That's when the real problem got clearer. It wasn't the three loops. It was that JSON.parse succeeding is not the same as the arguments being right, and I had nothing between the model's invention and a function that talks to a production service. I was one hallucinated field away from calling an internal API with garbage.

What I was already importing

I was using shapecraft for the structured-output part of this project already, so the fact that generateWithTools() was sitting in the same package was mildly embarrassing to discover this late:

import { generateWithTools, anthropic } from "@aviasole/shapecraft";
import type { ToolDefinition } from "@aviasole/shapecraft";
import { z } from "zod";

const lookupOrder: ToolDefinition = {
  name: "lookup_order",
  description: "Look up an order's current status by its ID",
  parameters: z.object({ orderId: z.string() }),
  handler: async ({ orderId }: { orderId: string }) => ordersApi.get(orderId),
};

const lookupBilling: ToolDefinition = {
  name: "lookup_billing",
  description: "Look up a customer's billing plan tier",
  parameters: z.object({ customerId: z.string() }),
  handler: async ({ customerId }: { customerId: string }) => billingApi.tier(customerId),
};

const result = await generateWithTools(
  anthropic({ model: "claude-haiku-4-5-20251001" }),
  [lookupOrder, lookupBilling],
  z.object({ status: z.string(), tier: z.string(), summary: z.string() }),
  "Is order 4521 still on hold, and what's that customer's plan tier?"
);

console.log(result.data);      // { status: "on_hold", tier: "enterprise", summary: "..." }
console.log(result.toolCalls); // every call it made, in order, with results

This uses each provider's native tool API underneath - it isn't a prompt convention pretending to be tool calling. The OpenAI-wire-format backends share one implementation, and Anthropic and Ollama get their own shapes normalized behind the same interface. Which means the three loops collapse into one call, and swapping anthropic(...) for openai(...) is a one-line edit rather than a rewrite.

The part I actually cared about: parameters is the same schema machinery as everywhere else in the library, and arguments are validated against it before the handler runs. My { orderId: 4521 } case now fails that check, gets handed back to the model as an error it can see, and the model corrects itself. It never reaches ordersApi.get().

Where my first attempt actually broke

I had lookupOrder throw on a missing order, because that's what the function already did:

handler: async ({ orderId }) => {
  const order = await ordersApi.get(orderId);
  if (!order) throw new Error(`No order ${orderId}`);  // don't
  return order;
},

First time the model guessed a wrong order number, the entire call died with ToolExecutionError. No retry, no recovery.

That's deliberate, and once I read why, I agreed with it: a handler throwing means my code failed, and re-prompting a model cannot fix a broken function. So it aborts immediately rather than looping. Bad arguments are the recoverable case, because the model can fix those - and those it does feed back.

The catch is that "order not found" isn't really my code failing. It's a legitimate result the model should get to react to. So it belongs in the return value, not in a throw:

handler: async ({ orderId }) => {
  const order = await ordersApi.get(orderId);
  return order ?? { error: `No order ${orderId}` };  // model sees this and adapts
},

Now a wrong guess comes back as data, the model tries a different ID or says it couldn't find one, and the loop carries on. Throw for "my database is down", return for "no such record." That distinction is worth getting right on day one instead of day three.

What this doesn't promise

Tool selection isn't validated, and can't be. Nothing checks the model picked the sensible tool, or that it should have called one at all - that's model behaviour, and it's the same structural-vs-semantic gap that applies to every schema-validated call. Arguments are guaranteed well-formed; the judgment to use them isn't.

Handler correctness is entirely mine. The library guarantees my return value gets fed back to the model as-is, and nothing about whether it's the right value.

There's a turn cap, defaulting to 10, and a model that keeps requesting tools forever hits MaxToolTurnsExceededError rather than spinning. Blunt, but I'd rather have a blunt guard than a runaway bill.

And it's non-streaming in v1, which for my use case is fine - I'm rendering a structured object into a component, not streaming prose at anyone. It's also on every cloud backend but not local GGUF models via llamaCpp(), which simply have no tools API to call. There's a model.capabilities.toolCalling flag to check rather than memorizing that.

Where that leaves it

Three provider-specific loops and a switch statement became one function call and two plain { name, parameters, handler } objects. Roughly 180 lines of dispatch plumbing deleted, and the thing I was actually nervous about - a hallucinated argument reaching a service that mutates real orders - is now a validation failure the model gets to correct instead of a TypeError in production.

import { generateWithTools } from "@aviasole/shapecraft";

Repo's at github.com/aviasoletechnologies/shapecraft, package is @aviasole/shapecraft on npm.

[Boost]

Yatin Davra — Fri, 07 Aug 2026 12:32:59 +0000

Naitik Kapatel

Aug 7

I Kept Retrying a Local Model Into the Right Shape. Turns Out I Didn't Have To Retry At All.

#llm #node #typescript #gbnf

4 min read

My Pipeline Needed Three Different Models to Hand Off to Each Other Without Losing Validation Along the Way

Yatin Davra — Mon, 03 Aug 2026 10:36:23 +0000

The task was a moderation pipeline: classify an incoming report, draft a response if it needed one, then have a second pass review that draft before anything went out. Three distinct jobs, and I didn't want one model doing all three badly - a cheap model for triage, a stronger one for the actual drafting, and a strict re-check before anything shipped. Each step had its own schema too: triage returns a category, the drafter returns a response plus a tone flag, the reviewer returns an approval and notes. Every one of those I could already get validated individually with a plain generate() call. What I didn't have was a way to chain three of them together where step two's prompt is built from step one's already-validated output, not step one's raw text.

What I almost built myself

The obvious first move: call generate() three times, JSON.stringify() each result into the next prompt by hand, write my own for loop with a turn cap so a bad router decision couldn't spin forever. Maybe 40 lines. Not hard, but the kind of thing I'd be rewriting slightly differently in every project that needed more than one step.

The other direction I looked at was going the other way entirely - a real agent framework, something like LangGraph or Google's ADK. Both do this properly: arbitrary agent graphs, shared mutable state, tool-calling loops, the works. I backed off almost as fast as I'd looked. My pipeline is three fixed steps in a known order, not an open-ended graph, and pulling in a framework built for arbitrary orchestration to run a sequence I could describe in one sentence felt like the wrong size tool - all the surface area of "build any agent topology" for a job that's "run these three, in order, stop when the last one says done."

What was already sitting there

shapecraft - the same library I was using for each individual step - turned out to have exactly the middle ground: defineAgent() + runAgents(), from a separate /agentic entrypoint so it doesn't cost anything if you never use it.

import { defineAgent, runAgents } from "@aviasole/shapecraft/agentic";
import { openai, anthropic } from "@aviasole/shapecraft";
import { z } from "zod";

const triage = defineAgent({
  model: openai({ model: "gpt-4o-mini" }),
  schema: z.object({ category: z.enum(["spam", "abuse", "false_positive"]) }),
  role: "triage",
});

const draft = defineAgent({
  model: anthropic({ model: "claude-haiku-4-5-20251001" }),
  schema: z.object({ response: z.string(), tone: z.enum(["firm", "neutral"]) }),
  role: "draft",
});

const review = defineAgent({
  model: anthropic({ model: "claude-opus-5" }),
  schema: z.object({ approved: z.boolean(), notes: z.string() }),
  role: "review",
});

const result = await runAgents(
  { triage, draft, review },
  reportText,
  {
    router: (last) => {
      if (!last) return "triage";
      if (last.role === "triage") return "draft";
      if (last.role === "draft") return "review";
      return "done";
    },
    maxTurns: 5,
  }
);

console.log(result.final); // review's validated { approved, notes }

Each step is an ordinary generate() call underneath - same retry loop, same guarantee level per backend, nothing new invented for validation. runAgents() is just the loop I was about to write myself, plus the part I hadn't gotten to yet: threading the validated data forward, never the model's raw response text. The router is a plain function I write and fully control - no DSL, no hidden state machine, no framework deciding what "agent" means.

Where my first attempt actually broke

I let the default handoff do its thing at first - each step's prompt is just the previous step's validated data, JSON-stringified. That's fine between triage and draft. It broke between draft and review: all the reviewer got was {"response": "...", "tone": "neutral"}. No idea what the original report even said. It approved things it had no basis to approve, because it genuinely didn't have the basis.

The fix was buildPrompt, an optional override per agent:

const review = defineAgent({
  model: anthropic({ model: "claude-opus-5" }),
  schema: z.object({ approved: z.boolean(), notes: z.string() }),
  role: "review",
  buildPrompt: (last, _history, input) =>
    `Original report: ${input}\nProposed response: ${JSON.stringify(last?.data)}`,
});

Worth calling out because it's not a bug - the default of "just forward the last validated result" is the right default for a two-step chain. It stops being right the moment a downstream step needs context from more than one hop back, and nothing tells you that until the reviewer starts approving things blind. Once I knew to look for it, the fix was one field.

What this doesn't promise

Each step is validated exactly as strongly as calling generate() on it directly - no weaker, but also no stronger as a chain. Nothing checks that triage → draft → review was the right sequence of steps for this particular report, or that the reviewer's notes are actually about the draft it was shown. That's the router's job and mine, same as it would be if I'd hand-written the loop myself.

Routing is caller-owned, not model-inferred - runAgents() doesn't ship a meta-agent that decides what runs next on its own. If I want the model to influence routing, I put that decision inside an agent's own schema (triage's category field, here) and branch on it in my router function. And it's sequential only - one agent at a time, each seeing only what the router explicitly hands it. If I need several independent things running in parallel, that's generateBatch(), a different axis entirely, not this.

Where that leaves it

Three defineAgent() calls, one router function, one buildPrompt override once I found the gap in the default. No hand-rolled loop, no state machine, no framework I'd have had to learn to run a three-step pipeline I could already describe in a sentence:

import { defineAgent, runAgents } from "@aviasole/shapecraft/agentic";

Repo's at github.com/aviasoletechnologies/shapecraft, package is @aviasole/shapecraft on npm.

I Built a Slot-Filling Onboarding Bot. It Leaked a Validation Error Into the Chat

Yatin Davra — Tue, 21 Jul 2026 05:40:28 +0000

I was building an onboarding flow: a new user lands, a chat window asks them three things - what problem they're solving, what their idea is, who the user is - and once all three are answered, the app needs { problem, idea, user } as a clean, validated object. Not a transcript. Not "probably in there somewhere." An actual object my code could pass to the next step without re-reading prose.

My first pass was the obvious one: after every user reply, try to extract the object, check if it validated, and if it didn't, ask the model for a follow-up question. It worked right up until the extraction step threw partway through a conversation - a SchemaViolationError with actual validation details in it - and I hadn't wrapped that path carefully enough. The raw error text got forwarded straight into the chat window as if it were the bot's next question. A user saw "idea": expected string, received undefined where a friendly follow-up question should have been.

I fixed that specific leak with a try/catch. Then found a second one a day later in a different code path. That's when I stopped patching leaks one at a time and looked at whether the tool I was already using (shapecraft) had a mode built for exactly this shape of problem, instead of me re-deriving "never let internal errors reach the user" by hand, one bug at a time.

The actual design problem

It's not really "extract after every message and retry." It's two completely different concerns that I'd tangled into one loop:

Having a conversation - a model asking natural questions, probing vague answers, deciding when it has enough. That's chat. It should never be schema-constrained, because forcing JSON-shaped output mid-conversation is exactly how you get a bot that "helpfully" outputs a stray {...} into the chat.
Producing a validated object, once, at the end - a completely separate concern from the conversation itself.

Conflating them means every turn is a place validation could fail and leak. Separating them means there's exactly one place validation happens - after the conversation is over - and exactly one rule to enforce: nothing generated internally at that step is ever routed back into the chat.

`turnaround` mode

generate(..., { turnaround: true }) is built around that split. The model drives the conversation entirely through systemPrompt - what to ask, when to probe a vague answer, when it's satisfied. Shapecraft's only job during collection is to relay the model's reply and carry the transcript forward:

import { generate, anthropic } from "@aviasole/shapecraft";

const model = anthropic({ model: "claude-haiku-4-5-20251001" });

const FACILITATOR =
  "You are the onboarding facilitator. Ask exactly one focused question at a time to learn: " +
  "(1) what problem we're solving, (2) what the idea is, (3) who the user is. " +
  "Probe vague answers for specifics. Do not invent details on the user's behalf.";

let r = await generate(model, OnboardingSchema, "Hi", { systemPrompt: FACILITATOR }, { turnaround: true });
console.log(r.status === "collecting" ? r.message : r); // "What problem are you trying to solve?"

r = await generate(model, OnboardingSchema, "Onboarding takes too long", { systemPrompt: FACILITATOR }, {
  turnaround: true,
  memory: r.memory, // thread the running transcript back in
});
console.log(r.status === "collecting" ? r.message : r); // "What's your idea to fix that?"

// ...more turns, same pattern...

if (r.status === "complete") {
  console.log(r.data); // { problem, idea, user } - validated once, here, never mid-conversation
}

Notice FACILITATOR never mentions how to signal "done" - I don't have to write that part. Shapecraft appends its own completion instruction (plus a checklist built from the schema's required fields) to whatever system prompt I pass in, so the sentinel handshake isn't something I own or could get subtly wrong.

memory is a plain JSON-serializable object - just the transcript plus a turn count - so a stateless HTTP handler can persist it between requests and rehydrate it on the next one, which is the actual shape a real chat backend needs anyway.

The completion sentinel

The model signals "I'm done" by replying with a literal <<<COMPLETE>>> instead of another question - the instruction to do so is injected automatically, not something I write myself. That reply is the trigger for a single, separate generate() call - a normal structured extraction pass over the whole transcript, not part of the conversation the user sees. I liked this over having the model just emit JSON directly once it thinks it's done, for the same reason my original leak happened: raw or premature JSON has no business anywhere near the user-facing chat, and "is this the sentinel string" is a trivial check instead of a fragile "does this look like JSON" guess.

The rule that actually fixes my bug

Every response from a turnaround call is one of two shapes: { status: "collecting", message } where message is only ever the model's own conversational text, or { status: "complete", data } where data is only ever produced by the end-of-conversation extraction pass. There is no third path where something shapecraft generated internally ends up in message. If that end-of-conversation extraction fails validation, it throws a real, terminal error out of generate() - it does not get wrapped into a fake follow-up question, and the user is never re-interrogated for answers already sitting in the transcript.

That last part surprised me at first - I expected "validation failed, so ask again." But if the user's answers are already in the transcript, a validation failure at the end means my extraction step is broken, not that the user needs to repeat themselves. Re-asking would be asking the wrong party to fix the wrong problem.

Where that leaves it

My onboarding bot now has exactly one place structured data gets produced, and exactly zero places an internal error can masquerade as a chat message:

import { generate } from "@aviasole/shapecraft";

Repo's at github.com/aviasoletechnologies/shapecraft, package is @aviasole/shapecraft on npm. If you've ever had a slot-filling bot leak something internal into the chat window - curious how you caught it.

I Had a GBNF Grammar File and Nowhere to Point It. So I Added Support for It.

Yatin Davra — Fri, 17 Jul 2026 06:44:46 +0000

I was building a classification step that had to run entirely on a local model - no cloud calls, straight through llama.cpp. Read a chunk of text, output exactly one of a handful of fixed labels. It ran in a tight, low-latency loop with basically no retry budget, and local models - even good quantized ones - drift more on output formatting than the big hosted APIs do. Wrap the label in a sentence, add a stray quote, whatever. Small thing, but multiplied over a few thousand calls it's a real failure rate.

The fix already exists: llama.cpp grammars, better known as GBNF. Hand llama.cpp a grammar and it masks the token logits at every generation step, so the model literally cannot produce a token that would break the grammar. Not "probably won't" - cannot.

I already had a grammar file. What I didn't have was a way to hand it to the structured-output library I was using (shapecraft) - it had five schema-input types at the time (Zod, JSON Schema, regex, a validator function, XML), and none of them were built for "apply this formal grammar directly."

Why the existing schema types didn't fit

Not JSON Schema - GBNF describes a context-free grammar over an arbitrary string, not a JSON shape. My output was going to be a matched string, not an object.
Not a regex pattern - GBNF grammars are recursive (rules referencing rules, alternation, repetition). You can't flatten that into one flat regex.
Not a validator function - a validator checks output after generation. I wanted the model physically unable to produce the wrong shape, not a check that catches it afterward.

So I added a schema type that did fit.

What I built

A new schema-input type, { gbnf: grammarString }:

import { generate, llamaCpp } from "@aviasole/shapecraft";

const sentimentGrammar = `root ::= "positive" | "negative" | "neutral"`;
const local = llamaCpp({ modelPath: "./models/llama-3.2-3b-instruct.gguf" });

const result = await generate(local, { gbnf: sentimentGrammar }, "Classify: 'I love this!'");

console.log(result.data);           // "positive" - cannot be anything else
console.log(result.guaranteeLevel); // "constrained"

result.data is a raw string, not a parsed object - GBNF describes a string language, not a JSON shape.

A llamaCpp() backend (node-llama-cpp) - the thing that actually applies the grammar at the token level.

A bundled GBNF interpreter for every other backend (openai, groq, anthropic, ollama), none of which have a grammar parameter. There, the grammar gets injected into the prompt instead, and the returned string is checked against it - mismatch, retry:

import { generate, openai } from "@aviasole/shapecraft";

const date = await generate(openai({ model: "gpt-4o-mini" }), {
  gbnf: `root ::= year "-" month "-" day\nyear ::= [0-9]{4}\nmonth ::= [0-9]{2}\nday ::= [0-9]{2}`,
}, "When did WWII end in Europe?");

console.log(date.data);           // "1945-05-08"
console.log(date.guaranteeLevel); // "best-effort" - no grammar param on this API

Same grammar, same call, two very different guarantee levels depending on the backend. GBNF ended up being the one schema type where the guarantee genuinely depends on which backend is running it, not just retry count.

Then I tried to break my own validator

I don't trust a validator only tested against grammars that were supposed to pass.

Catastrophic backtracking - the classic thing that blows up naive regex engines, like ("a" "a"?)* "b" against a long run of as with no trailing b. Didn't blow up - milliseconds, every time. The matcher dedupes by position reached, not path taken, so it doesn't re-explore the same dead end repeatedly.

A genuinely adversarial grammar did slow it down - a ~26-way ambiguous alternation against a 300,000-character input with no valid terminator. That trips a step-budget guard in under a second with a clear error instead of hanging.

Deep right-recursion through a rule reference found a real limit. */+ repetition is iterative, no limit tested up to 50,000+ repeats. But a grammar like list ::= item "," list | item recurses through the JS call stack once per repetition, and breaks around 900-1000 reps. Instead of a raw stack-overflow trace, it now throws a clear message telling you to rewrite with */+ instead.

A real bug this surfaced

Stress-testing also found something unrelated but genuinely broken: the Groq backend was forcing response_format: json_object on every call, including GBNF ones. Groq's API rejects that mode if the prompt doesn't literally contain the word "json" - which a GBNF grammar prompt has no reason to. Every GBNF call against Groq was failing before the model even ran. Two-line fix, but only found by trying to break the feature instead of just checking the happy path.

Where that leaves it

From "I have a grammar file and nowhere to point it" to a schema type that's genuinely valid by construction on a local llama.cpp model, and checked (not just trusted) everywhere else - same call shape, same retry behavior as every other schema type.

If you've got a .gbnf grammar sitting around, or want a local model physically incapable of drifting off a fixed format:

import { generate, llamaCpp } from "@aviasole/shapecraft";

Repo's at github.com/aviasoletechnologies/shapecraft, package is @aviasole/shapecraft on npm. Curious if anyone else here is running GBNF grammars against local models, and what for - I only had the one use case in mind.

How I ended up contributing five ways to shape an LLM's output

Yatin Davra — Fri, 03 Jul 2026 06:46:44 +0000

A few months back I was on a project that needed LLMs to return actual structured data, not prose I'd have to regex my way through. Simple enough in theory, except every provider wanted the shape described differently - Anthropic's SDK wanted a tool schema, OpenAI had its own response-format, Ollama was basically raw prompting and hoping. I was rewriting the same schema three times per feature and writing my own retry-on-invalid-output loop for anything that didn't guarantee output.

That's how I found ShapeCraft (@aviasole/shapecraft on npm). Define a schema once, hand it a model, get back validated data plus a guaranteeLevel telling you how much to trust it - "guaranteed" means something different on OpenAI's native schema enforcement than on Anthropic's prompt-and-validate approach than on Ollama's token-level grammar constraints.

It already supported Zod out of the box:

import { z } from "zod";
import { generate, openai } from "@aviasole/shapecraft";

const schema = z.object({ name: z.string(), score: z.number() });
const result = await generate(openai({ model: "gpt-4o-mini" }), schema, prompt);

That covered most of what I needed. But a few things in my actual project didn't fit "define a Zod schema," so instead of working around it, I opened some PRs.

Part of the data I was extracting already had a JSON Schema, generated by another tool upstream. Rewriting it as Zod types just to satisfy the library felt like busywork, so that became the first addition - pass the JSON Schema straight through:

const result = await generate(model, {
  jsonSchema: {
    type: "object",
    properties: { name: { type: "string" }, score: { type: "number" } },
    required: ["name", "score"],
  },
}, prompt);

Then I hit cases where I didn't need an object at all, just a string in a specific format. Wrapping that in an object schema felt like putting a hat on a hat, so next came a plain regex option:

const result = await generate(model, {
  pattern: /^\d{4}-\d{2}-\d{2}$/,
}, "What is today's date?");

After that, a rule that only made sense as logic, not a type - something like "required only if this other field equals X." Technically expressible as a schema, miserable to read. So I added a way to pass a validator function directly, plus a hint so the model still has something to aim for:

const result = await generate(model, {
  validate: (output) => typeof output === "object" && output !== null && "id" in output,
  hint: { type: "object", properties: { id: { type: "string" } } },
}, prompt);

The one that mattered most to me was separate from this project entirely. I also do Tally/TDL and GST integration work, and that world runs on XML - nested tags, required fields buried a few levels deep. None of the above helped there since the output isn't JSON-shaped at all. So the last addition was template-based XML: give it an example with typed placeholders, model fills them in.

const result = await generate(model, {
  xml: {
    template: `<book>
  <title>{string}</title>
  <author>{string}</author>
  <year>{number}</year>
</book>`,
    required: ["title", "author"],
  },
}, 'Extract: "Clean Code" by Robert C. Martin, 2008.');

This one took the most back-and-forth. Placeholders are deliberately limited to {string}, {number}, {boolean}, and a typo throws before the model is even called - that's a template bug, not something worth a retry.

The trickier part was literal text. Anything outside the {} is supposed to survive untouched, but it's best-effort by default - a model will occasionally "improve" fixed text that reads like an instruction, since nothing marks it as untouchable. There's an enforceLiterals: true flag that force-corrects every literal after the fact if you need that guaranteed. Or, often simpler, just leave the fixed value out of the template and splice it into result.data yourself afterward.

required also checks non-emptiness at any depth, so <items></items> still triggers a retry instead of counting as present. And arrays plus parse: true gets you back a parsed JS object instead of raw XML, with specific nodes coerced into arrays even with a single item.

One caveat worth knowing up front: XML generation is prompt-driven on every backend, no token-level grammar constraint like Ollama has for JSON. It leans on the model being capable, especially with deeply nested templates.

All five of these route through the same generate() call underneath - same retries, same guaranteeLevel, same error types (SchemaViolationError, MaxRetriesExceededError). Different doors into the same room, which is probably why it was easy to keep adding them.

Genuinely curious about a few things: if you've built template-based XML generation before, does enforceLiterals feel like the right approach, or is there a cleaner way without a re-serialize pass? Is there a schema style still missing that you've actually needed in production - YAML, something protobuf-shaped? And for the validator path, is a hint object enough context, or would you want more?

Repo's here: github.com/aviasoletechnologies/shapecraft. Package is @aviasole/shapecraft. I'm using it across a few different projects now, so I'll keep adding to it as I run into more edge cases.

How to Create Multi-Page TIFF Files in Node.js (Without ImageMagick)

Yatin Davra — Tue, 14 Apr 2026 13:11:31 +0000

If you've ever tried to create a multi-page TIFF in Node.js, you know the pain. Most solutions require ImageMagick as a system dependency, which is a headache in Docker, serverless environments, or CI pipelines. Others wrap native binaries with brittle child_processcalls.

I ran into this exact problem while building a document processing pipeline — I needed to merge multiple scanned images into a single multi-page TIFF programmatically, with no external system dependencies.

After digging through the options, I ended up writing a pure Node.js solution and published it as an npm package: multi-page-tiff.

The Problem

Multi-page TIFF files store multiple images as linked Image File Directories (IFDs) inside a single .tiff file. Creating one correctly means writing the TIFF binary structure yourself — most image libraries only handle reading, not writing multi-page TIFFs.

Common workarounds people try:

ImageMagick via child_process— works but requires ImageMagick installed, breaks in serverless
sharp — great library but doesn't support writing multi-page TIFFs
tiff-multipage — last published 3 years ago, minimal maintenance
tiff-to-png — converts TIFF to PNG, not the other way

The Solution

npm install multi-page-tiff

const { imagesToTiff, imagesToTiffBuffer } = require('multi-page-tiff');

const fs = require('fs');

const images = [
  fs.readFileSync('./page1.png'),
  fs.readFileSync('./page2.png'),
  fs.readFileSync('./page3.png'),
];

await imagesToTiff(images , 'output.tiff');

// Get a Buffer (useful for uploading, streaming, etc.)
const tiffBuffer = await imagesToTiffBuffer(images);
fs.writeFileSync('./output.tiff', tiffBuffer);

That's it. No native binaries, no system dependencies. Works on AWS Lambda, Vercel, Docker, Windows — anywhere Node.js runs.

Use Cases
Multi-page TIFFs are common in:

Fax systems — fax files are almost always multi-page TIFFs
Document scanning — scanners output multi-page TIFFs
Medical imaging — DICOM-adjacent workflows often use TIFF
Legal/archival — PDF alternatives for scanned documents
Insurance and banking — document submission pipelines

Why Not Just Use PDF?
TIFF is lossless, supports higher bit depths (16-bit, 32-bit), and is required in many enterprise, government, and medical workflows where PDF is not accepted. If your system specification says TIFF, there's usually no substitute.

Links

npm: npmjs.com/package/multi-page-tiff
GitHub: github.com/yatindavra/multi-page-tiff

If you've been fighting with multi-page TIFF generation in Node.js, give it a try and let me know in the comments if you run into any issues.
check my work at https://yatindavra.vercel.app

DEV Community: Yatin Davra

Past the README Demo: Conversations, Healthcare Data, Agents, and CI Checks

1. Collecting data across a whole conversation

2. Extracting from clinical notes into real FHIR shapes

3. An agent that checks real data before answering

4. Chaining validated steps into a pipeline

5. Checking a JSON file against a schema, no code required

The pattern underneath all of it

5 Things I've Actually Used shapecraft For

1. Turning support tickets into triageable data

2. Parsing receipts, invoices, and other "almost structured" documents

3. Slot-filling for a form-driven chatbot

4. Running a local model with a real guarantee

5. Batch-processing a folder of anything

That's the range

I Streamed Structured Output Into a Live Panel. A Field Rendered Before I Knew It Was Wrong

First pass: parse whatever text has arrived so far

Second pass: track bracket depth by hand

What was already there

Where it landed

I Wrote the Same Tool-Calling Loop Three Times, Once Per Provider, Before I Stopped

The loop I wrote, then wrote again

The bug that actually worried me

What I was already importing

Where my first attempt actually broke

What this doesn't promise

Where that leaves it

[Boost]

I Kept Retrying a Local Model Into the Right Shape. Turns Out I Didn't Have To Retry At All.

My Pipeline Needed Three Different Models to Hand Off to Each Other Without Losing Validation Along the Way

What I almost built myself

What was already sitting there

Where my first attempt actually broke

What this doesn't promise

Where that leaves it

I Built a Slot-Filling Onboarding Bot. It Leaked a Validation Error Into the Chat

The actual design problem

turnaround mode

The completion sentinel

The rule that actually fixes my bug

Where that leaves it

I Had a GBNF Grammar File and Nowhere to Point It. So I Added Support for It.

Why the existing schema types didn't fit

What I built

Then I tried to break my own validator

A real bug this surfaced

Where that leaves it

How I ended up contributing five ways to shape an LLM's output

How to Create Multi-Page TIFF Files in Node.js (Without ImageMagick)

`turnaround` mode