Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

5.6 KB
Raw Blame
//! Structured output via prompted JSON generation and offline schema validation.
use anyhow::Context;
use rig_core::message::Message;
use serde::{Deserialize, Serialize};
use utoipa::ToSchema;

use crate::model::router::{ModelRouter, RoutedModel};

#[cfg(test)]
mod test;

const MAX_SCHEMA_BYTES: usize = 64 * 1024;

/// Schema definition for dynamic structured completions.
#[derive(Debug, Serialize, Deserialize, ToSchema)]
pub struct DynamicSchema {
    /// The JSON schema to validate against.
    pub schema: serde_json::Value,
    /// Name of the schema.
    pub name: String,
    /// Optional description of what the schema represents.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
}

/// Preflight a dynamic schema without network or filesystem reference retrieval.
/// Local `$defs`/`$ref` references are supported. Call before beginning paid work
/// when an API needs to reject an invalid schema as a client error.
pub fn validate_schema(schema: &DynamicSchema) -> anyhow::Result<jsonschema::Validator> {
    anyhow::ensure!(
        serde_json::to_vec(&schema.schema)?.len() <= MAX_SCHEMA_BYTES,
        "output schema must fit in 64 KiB"
    );
    jsonschema::options()
        .offline()
        .should_validate_formats(true)
        .build(&schema.schema)
        .map_err(|_| {
            anyhow::anyhow!(
                "output schema is invalid or requires an unavailable external reference"
            )
        })
}

/// How much a model may think before it gives a structured answer.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, ToSchema)]
#[serde(rename_all = "snake_case")]
pub enum CompletionThinking {
    /// The model's own default.
    #[default]
    Default,
    /// Briefly, for a faster answer: Gemini 3 models think at their low
    /// level, which can take a structured answer from minutes to seconds.
    /// Other providers keep their defaults.
    Low,
}

impl CompletionThinking {
    /// The provider parameters that ask `model` to think this way, if any.
    fn params(self, model: &str) -> Option<serde_json::Value> {
        match self {
            Self::Default => None,
            Self::Low => self.params_for(&ModelRouter::shared().ok()?.route_or_default(model)),
        }
    }

    pub(crate) fn params_for<H>(self, routed: &RoutedModel<'_, H>) -> Option<serde_json::Value> {
        match (self, routed) {
            (Self::Low, RoutedModel::Gemini(_)) => Some(serde_json::json!({
                "generationConfig": { "thinkingConfig": { "thinkingLevel": "low" } }
            })),
            (Self::Default, _)
            | (
                Self::Low,
                RoutedModel::Anthropic(_)
                | RoutedModel::OpenAiChatCompletions(_)
                | RoutedModel::OpenAiResponses(_),
            ) => None,
        }
    }
}

/// Run a completion with conversation history and return a JSON value
/// conforming to `schema`.
#[tracing::instrument(skip(model, system_prompt, messages, schema, recorder, ctx), err)]
pub async fn dynamic_structured_completion<M: ToString>(
    model: M,
    system_prompt: &str,
    messages: Vec<Message>,
    schema: DynamicSchema,
    recorder: &dyn ai_usage::UsageRecorder,
    ctx: ai_usage::UsageContext,
) -> anyhow::Result<serde_json::Value> {
    dynamic_structured_completion_thinking(
        model,
        system_prompt,
        messages,
        schema,
        CompletionThinking::Default,
        recorder,
        ctx,
    )
    .await
}

/// [`dynamic_structured_completion`], letting the model think as `thinking` says.
#[tracing::instrument(
    skip(model, system_prompt, messages, schema, recorder, ctx),
    fields(gen_ai.request.thinking = ?thinking),
    err
)]
pub async fn dynamic_structured_completion_thinking<M: ToString>(
    model: M,
    system_prompt: &str,
    messages: Vec<Message>,
    schema: DynamicSchema,
    thinking: CompletionThinking,
    recorder: &dyn ai_usage::UsageRecorder,
    ctx: ai_usage::UsageContext,
) -> anyhow::Result<serde_json::Value> {
    let model = model.to_string();
    let validator = validate_schema(&schema)?;
    let structured_prompt = format!(
        "{system_prompt}\n\n\
         You MUST respond with ONLY a valid JSON value matching this schema.\n\
         Schema name: {name}\n\
         {desc}\
         Schema:\n```json\n{schema_json}\n```\n\
         Respond with ONLY the raw JSON value. No markdown fences, no explanation.",
        name = schema.name,
        desc = schema
            .description
            .as_deref()
            .map(|d| format!("{d}\n"))
            .unwrap_or_default(),
        schema_json = serde_json::to_string_pretty(&schema.schema)?,
    );

    let params = thinking.params(&model);
    let response = crate::completion::complete_with_history_and_params(
        model,
        &structured_prompt,
        messages,
        params,
        recorder,
        ctx,
    )
    .await?;

    parse_and_validate(&response, &validator)
}

fn parse_and_validate(
    response: &str,
    validator: &jsonschema::Validator,
) -> anyhow::Result<serde_json::Value> {
    let trimmed = response.trim();
    let json_str = if let Some(rest) = trimmed.strip_prefix("```") {
        let inner = rest.strip_prefix("json").unwrap_or(rest);
        inner.strip_suffix("```").unwrap_or(inner).trim()
    } else {
        trimmed
    };

    let value =
        serde_json::from_str(json_str).context("Failed to parse structured output as JSON")?;
    validator.validate(&value).map_err(|error| {
        anyhow::anyhow!(
            "structured output does not match the output schema at {}",
            error.instance_path()
        )
    })?;
    Ok(value)
}