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.

11.0 KB
Raw Blame
use crate::cognition::api::context::{ApiContext, DcsAuthorizationService, DcsChatModelAccess};
use crate::cognition::api::tool_selection::{service_tools, structured_completion_prompt};
use crate::cognition::model::stream::ToolSet;
use crate::cognition::service::structured_completion::{ToolFreeCompletionError, ToolFreeRequest};
use agent::structured_output::{CompletionThinking, DynamicSchema};
use agent::types::{ChatMessage, ChatMessageContent, Role};
use agent::{AgentLoop, StreamAccumulator};
use ai_billing::inbound::admission::admission_status;
use axum::Json;
use axum::extract::State;
use axum::http::StatusCode;
use axum::response::IntoResponse;
use futures::StreamExt;
use macro_authorization::{MacroAuthorizationExtractor, UserOrInternal};
use serde::{Deserialize, Serialize};
use std::fmt;
use std::sync::Arc;
use utoipa::ToSchema;

mod activity;
#[cfg(test)]
mod test;
pub use activity::StructuredToolActivity;
use activity::{has_database_changes, tool_activity};

#[derive(Debug, Serialize, Deserialize, ToSchema)]
pub struct StructuredCompletionRequest {
    pub prompt: String,
    pub model: String,
    pub output_schema: DynamicSchema,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub additional_instructions: Option<String>,
    #[serde(default)]
    pub toolset: ToolSet,
    /// How much the model may think first; `low` answers faster. Applies to
    /// completions without tools.
    #[serde(default)]
    pub thinking: CompletionThinking,
}

#[derive(Debug, Serialize, Deserialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct StructuredCompletionResponse {
    pub outcome: StructuredCompletionOutcome,
    /// Actual completed tools, independent of the model's claims.
    pub tool_activity: Vec<StructuredToolActivity>,
}

#[derive(Debug, Serialize, Deserialize, ToSchema)]
#[serde(tag = "status", rename_all = "camelCase")]
pub enum StructuredCompletionOutcome {
    /// The answer, shaped by the request's `output_schema`.
    Completed { result: serde_json::Value },
    /// The model failed after committing database changes, so there is no
    /// answer but `tool_activity` says what was saved.
    Interrupted { reason: String },
}

#[derive(Debug, Serialize, Deserialize, ToSchema)]
pub struct StructuredCompletionError {
    pub error: String,
    #[serde(skip)]
    pub status: StatusCode,
    /// Stable machine-readable code for admission errors (402 or 503).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub code: Option<String>,
}

impl fmt::Display for StructuredCompletionError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.error)
    }
}

impl IntoResponse for StructuredCompletionError {
    fn into_response(self) -> axum::response::Response {
        (self.status, Json(self)).into_response()
    }
}

#[utoipa::path(
    post,
    path = "/structured-completion",
    request_body = StructuredCompletionRequest,
    responses(
        (status = 200, description = "Structured completion result", body = StructuredCompletionResponse),
        (status = 400, description = "Bad request", body = StructuredCompletionError),
        (status = 401, description = "Unauthorized"),
        (status = 402, description = "Payment required", body = StructuredCompletionError),
        (status = 403, description = "No access to the requested model", body = StructuredCompletionError),
        (status = 500, description = "Internal error", body = StructuredCompletionError),
        (status = 503, description = "AI usage validation unavailable — retry later", body = StructuredCompletionError),
        (status = 504, description = "Tool-free completion deadline exceeded", body = StructuredCompletionError),
    )
)]
#[tracing::instrument(skip(state, model_access, user, request), fields(user_id = %user.authorization.user.macro_user_id), err)]
pub async fn structured_completion(
    State(state): State<ApiContext>,
    model_access: DcsChatModelAccess,
    user: MacroAuthorizationExtractor<DcsAuthorizationService, UserOrInternal>,
    Json(request): Json<StructuredCompletionRequest>,
) -> Result<Json<StructuredCompletionResponse>, StructuredCompletionError> {
    let ctx = Arc::new(state);
    if !model_access.has_access(&request.model) {
        return Err(StructuredCompletionError {
            error: format!("No access to model {}", request.model),
            status: StatusCode::FORBIDDEN,
            code: None,
        });
    }
    agent::structured_output::validate_schema(&request.output_schema).map_err(|error| {
        StructuredCompletionError {
            error: error.to_string(),
            status: StatusCode::BAD_REQUEST,
            code: Some("invalid_output_schema".into()),
        }
    })?;
    let model = request.model.clone();

    let user_id = user.authorization.user.macro_user_id.clone();

    // One admission covers both the agent and final formatting phases.
    ctx.ai_admission
        .admit(&user_id, ai_usage::AiFeature::DynamicCompletionsApi)
        .await
        .map_err(|error| StructuredCompletionError {
            error: error.to_string(),
            status: admission_status(error),
            code: Some(error.code().to_string()),
        })?;

    if matches!(request.toolset, ToolSet::None) {
        let system_prompt = structured_completion_prompt(
            &request.toolset,
            &*ctx.all_tools_prompt,
            request.additional_instructions.as_deref(),
            &[],
        );
        let result = ctx
            .tool_free_completions
            .complete(
                user_id,
                ToolFreeRequest {
                    model,
                    system_prompt,
                    prompt: request.prompt,
                    schema: request.output_schema,
                    thinking: request.thinking,
                },
            )
            .await
            .map_err(|error| StructuredCompletionError {
                status: match &error {
                    ToolFreeCompletionError::Busy => StatusCode::SERVICE_UNAVAILABLE,
                    ToolFreeCompletionError::Timeout => StatusCode::GATEWAY_TIMEOUT,
                    ToolFreeCompletionError::Failed(_) => StatusCode::INTERNAL_SERVER_ERROR,
                },
                code: None,
                error: error.to_string(),
            })?;
        return Ok(Json(StructuredCompletionResponse {
            outcome: StructuredCompletionOutcome::Completed { result },
            tool_activity: Vec::new(),
        }));
    }

    // Tool-enabled requests retain their discovery and final formatting phases.
    let toolset = service_tools(
        &request.toolset,
        ctx.all_tools.clone(),
        &ctx.mcp_selector,
        &user_id,
    )
    .await;

    // Both phases need the registered tools' reference, including SQL syntax.
    // The formatter has no executable tools of its own.
    let system_prompt = structured_completion_prompt(
        &request.toolset,
        &*ctx.all_tools_prompt,
        request.additional_instructions.as_deref(),
        &toolset.request_schemas().unwrap_or_default(),
    );

    let user_message = ChatMessage {
        role: Role::User,
        content: ChatMessageContent::Text(request.prompt.clone()),
        attachments: None,
    };
    let rig_messages = agent::to_rig_messages(&[user_message]);

    let agent_loop = AgentLoop::new(ctx.tool_service_context.recorder.clone()).with_model(&model);
    let usage_ctx =
        ai_usage::UsageContext::new(ai_usage::AiFeature::DynamicCompletionsApi, user_id.clone());
    // Carry the feature on the context so tool-spawned subagents attribute to it.
    let mut tool_context = ctx.tool_service_context.clone();
    tool_context.usage_context = usage_ctx.clone();
    let mut session = agent_loop
        .session(toolset, Arc::new(tool_context), &system_prompt, usage_ctx)
        .await;

    let mut ai_stream =
        session
            .send_message(rig_messages)
            .await
            .map_err(|e| StructuredCompletionError {
                error: format!("Agent loop failed: {e}"),
                status: StatusCode::INTERNAL_SERVER_ERROR,
                code: None,
            })?;

    let mut accumulator = StreamAccumulator::new();
    let mut stream_error = None;
    while let Some(item) = ai_stream.next().await {
        match item {
            Ok(part) => {
                accumulator.push(part);
            }
            Err(e) => {
                stream_error = Some(StructuredCompletionError {
                    error: format!("Agent loop error: {e}"),
                    status: StatusCode::INTERNAL_SERVER_ERROR,
                    code: None,
                });
                break;
            }
        }
    }
    drop(ai_stream);
    let yielded_parts = accumulator.into_parts();
    let activity = tool_activity(&yielded_parts);
    if let Some(error) = stream_error {
        return partial_completion_or_error(activity, error);
    }

    // Phase 2: Structured completion with the gathered context
    let conversation: Vec<ChatMessage> = vec![
        ChatMessage {
            role: Role::User,
            content: ChatMessageContent::Text(request.prompt),
            attachments: None,
        },
        ChatMessage {
            role: Role::Assistant,
            content: ChatMessageContent::AssistantMessageParts(yielded_parts),
            attachments: None,
        },
        ChatMessage {
            role: Role::User,
            content: ChatMessageContent::Text(
                "Based on the information gathered above, produce a structured response matching the required schema.".to_string(),
            ),
            attachments: None,
        },
    ];
    let rig_messages = agent::to_rig_messages(&conversation);

    let result = agent::structured_output::dynamic_structured_completion(
        model,
        &system_prompt,
        rig_messages,
        request.output_schema,
        ctx.tool_service_context.recorder.as_ref(),
        ai_usage::UsageContext::new(ai_usage::AiFeature::DynamicCompletionsApi, user_id),
    )
    .await;
    match result {
        Ok(result) => Ok(Json(StructuredCompletionResponse {
            outcome: StructuredCompletionOutcome::Completed { result },
            tool_activity: activity,
        })),
        Err(error) => partial_completion_or_error(
            activity,
            StructuredCompletionError {
                error: format!("Structured completion failed: {error}"),
                status: StatusCode::INTERNAL_SERVER_ERROR,
                code: None,
            },
        ),
    }
}

/// Do not conceal committed edits behind a failed follow-up model request.
fn partial_completion_or_error(
    tool_activity: Vec<StructuredToolActivity>,
    error: StructuredCompletionError,
) -> Result<Json<StructuredCompletionResponse>, StructuredCompletionError> {
    if !has_database_changes(&tool_activity) {
        return Err(error);
    }
    tracing::warn!(error = %error, "Completion interrupted after database changes");
    Ok(Json(StructuredCompletionResponse {
        outcome: StructuredCompletionOutcome::Interrupted {
            reason: error.error,
        },
        tool_activity,
    }))
}