Structured output

​

How it works

• A struct deriving JsonSchema so the parser can describe the format to the model.
• A parser — StructuredOutputParser<T> — that injects format instructions into the prompt and parses replies back into T.
• A recovery strategy — OutputFixingParser or RetryParser — for the cases when the model wanders off-format.

use cognis::prelude::*;
use cognis_core::output_parsers::{OutputParser, StructuredOutputParser};
use cognis_core::schemars::{self, JsonSchema};
use serde::Deserialize;

#[derive(Debug, Deserialize, JsonSchema)]
struct Recipe {
    title: String,
    ingredients: Vec<String>,
    steps: Vec<String>,
}

let parser: StructuredOutputParser<Recipe> = StructuredOutputParser::new();
let format_hint = OutputParser::format_instructions(&parser).unwrap_or_default();

let prompt = format!("Give me a recipe for scrambled eggs.\n\n{format_hint}");
let reply = client.invoke(vec![Message::human(prompt)]).await?;
let recipe: Recipe = parser.parse(reply.content())?;

​

When models drift

use cognis_core::output_parsers::{OutputFixingParser, StructuredOutputParser};

let inner = StructuredOutputParser::<Recipe>::new();
let parser = OutputFixingParser::new(inner, fixer_client);
let recipe: Recipe = parser.parse(reply.content())?;

use cognis_core::output_parsers::RetryParser;

let parser = RetryParser::with_retries(inner, fixer, 5);

​

Other parsers

​

How it composes

let chain = prompt.pipe(model).pipe(parser);
let recipe: Recipe = chain.invoke(query, cfg).await?;

​

Provider tips

• Anthropic and Google generally produce excellent JSON when the schema is in the system prompt.
• OpenAI’s “JSON mode” / structured output API is a tighter contract. Cognis’ StructuredOutputParser works with any provider; if you want the provider’s strict mode, build your own Tool definition and use the provider’s structured-output route.
• Smaller Ollama models (llama3.2:1b, etc.) drift often. Always wrap with OutputFixingParser in production.

​

How it works

• Schema goes in the prompt, not in the request. The parser appends format_instructions() to the user prompt — that’s how providers without a structured-output API still emit valid JSON.
• Fixing is a sub-call. OutputFixingParser makes another LLM call for the repair. Budget for it.
• Errors are typed. Parse failures return Err(CognisError::OutputParse { … }) with the raw text and the parse error — surface those so users see a useful message, not a panic.

​

See also