Chapter 3: The AI Reasoning Engine

Strict Structured Outputs

Target Audience: Users refining their LLM prompts and JSON schemas.

When bridging the gap between generative AI and deterministic code, formatting is everything. If an LLM hallucinates a new JSON key, forgets a nested array, or changes a string to a number, your downstream PDF template will fail to render correctly.

In Strucsta, the Reason step is engineered to solve this completely. By leveraging OpenAI's strict: true schema enforcement and our visual editor, we ensure that the AI's reasoning is returned in a 100% predictable format.

Why We Enforce Strict Outputs

Standard JSON mode in LLMs guarantees that the output will be valid JSON, but it does not guarantee the JSON will match your specific application's required structure.

Strucsta utilizes strict JSON Schema enforcement mapped directly to OpenAI's zodResponseFormat. This transforms the LLM from a loose text generator into a strictly typed data transformation engine.

Standard JSON vs. Strict Outputs

The Output Schema Visual Editor

To make defining these strict structures effortless, the Reason step includes a visual Output Format editor. You do not need to write complex JSON schemas or Zod validation code by hand; the visual editor builds the strict, highly-nested schema required by the engine behind the scenes.

1. Root Response Schema

This is the top-level structure of the data the AI will produce. You can define fields using a hierarchical grid, supporting a variety of data types:

Primitives: String, Number, Boolean.
Constants: Constant (Locks a specific value, e.g., forcing a type field to always equal "invoice").
Complex Types: Object (for nested groupings) and Array (for dynamic lists, like line items or daily itineraries).

Every field allows you to provide LLM Instructions (descriptions). This is where you tell the AI exactly what that specific field should contain (e.g., "A 2-sentence executive summary with a professional tone").

2. Custom Schema Library

For advanced use cases, the visual editor includes a Custom Schema Library where you can define reusable structures to keep your root schema clean.

Enums: Restrict a string to a specific set of allowed values (e.g., outputting only Monday, Tuesday, etc.). The AI physically cannot output a value outside of this list.
Objects: Define a complex nested object once (like an Address block with street, city, zip) and reuse it across multiple fields or arrays.
Discriminated Unions (Variants): Define multiple acceptable shapes for an object based on dynamic conditions (mapped to anyOf / oneOf).

How the Engine Enforces the Rules

Under the hood, Strucsta's runtime automatically aggressively formats the schema you design in the UI to comply with OpenAI's strict structured output requirements.

When your workflow executes:

No Additional Properties: The engine automatically applies additionalProperties: false to every object and nested object in your schema.
Required Field Enforcement: OpenAI requires all properties to be strictly marked as required. The engine handles this automatically.
Safe Optionals (Nullable): If you mark a field as "Optional" in the UI, the engine automatically converts its type to a nullable union (e.g., ["string", "null"]). This ensures that if the AI doesn't have the data, it explicitly returns null rather than hallucinating fallback data or breaking the rigid schema rules.

The Payoff: Bulletproof Templates

Because the Reason step outputs strictly validated data, designing the final visual document in the Render (pdfmaker) step becomes entirely deterministic.

You can confidently write your JSONC templates—looping over arrays or referencing nested objects—knowing that if the AI step completed successfully, the data structure matches your exact specifications. If the data doesn't match, the engine catches it before a broken PDF is ever generated.