Hey,

I wanted to share a library I’ve been working on: gemini-structured-output.

The Context Over the last year, I’ve built quite a few projects utilizing LLMs. In almost every single one of them, I found myself writing the same boilerplate over and over: custom adapters to coerce model output into Rust types, regex hacks to clean up JSON markdown blocks, and fragile retry loops to handle when the model hallucinates a field or gets a type wrong.

Maintaining these custom parsers across multiple projects became a nightmare. I realized I needed to encapsulate everything I’ve learned about reliable structured generation into a single, easy-to-use library.

This library solves the "last mile" problem of reliability. It doesn't just check if the JSON is valid; it actively fights to make it valid.

A few cool features

1. JSON Patch Refinement Loop: This is the core of the library. If the model outputs data that fails your schema validation or custom logic checks, the library doesn't just retry the whole request (which is slow and expensive). Instead, it feeds the specific error back to Gemini and asks for a JSON Patch (RFC 6902) to fix the struct. It applies these patches transactionally.
2. Type-Safe Agentic Workflows: It includes a composable workflow engine. You can chain steps, run parallel maps, and perform reductions (Map-Reduce) while keeping everything strictly typed.
3. Macros for DX: I built a few procedural macros to reduce boilerplate. You can define an agent or a tool almost entirely via attributes.

Code Example

Here is how you define an agent and run a structured request with automatic validation:

 use gemini_structured_output::prelude::*; // 1. Define your output with Serde + Schemars #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] struct SentimentReport { sentiment: String, score: f64, // You can enforce validation rules via attributes #[validate(length(min = 1))] key_topics: Vec<String>, } // 2. Define an Agent using the macro #[gemini_agent( input = "String", output = "SentimentReport", system = "You are a sentiment analysis engine." )] struct SentimentAgent; #[tokio::main] async fn main() -> Result<()> { let client = StructuredClientBuilder::new(env::var("GEMINI_API_KEY")?) .with_model(Model::Gemini25Flash) // Supports the new 2.0/3.0 models .build()?; let agent = SentimentAgent::new(client); // 3. Run it. If Gemini messes up the JSON, the library // automatically loops, critiques the error, and patches the result. let report = agent.run("I loved the UI, but the API was slow.".to_string(), &ExecutionContext::new()).await?; println!("{:#?}", report); Ok(()) } 

Other cool stuff:

• Adapters: Serialization helpers for types LLMs struggle with (like HashMap or Duration).
• Observability: Built-in tracing and metrics (token counts, latency) for every step in a workflow.
• Context Caching: wrappers for Gemini's context caching to save money on large system prompts.

Looking for Feedback

I'm polishing things up for a 0.1 release on crates.io. I’d love for anyone interested in Gemini or AI engineering in Rust to take a look at the code and offer suggestions.

Are the workflow abstractions (Step, Chain, ParallelMap) intuitive? Is the macro syntax ergonomic enough? Are there any features you would need if you were going to use this yourself?

Repo: https://github.com/noahbclarkson/gemini-structured-output

Thanks for any advice!