AI Service: gRPC API Contract

This document defines the gRPC contract for the ai_service.

1. Overview

The ai_service exposes a gRPC service for high-performance communication with the api_gateway. It also acts as a client to other services as needed.

• gRPC Server: Exposes the AIService for the api_gateway.
• HTTP Client: Consumes the RESTful API of the mcp_service to execute tool calls.

2. Protobuf Definition (ai_service.proto)

syntax = "proto3";

package ai_service;

// The AIService is called by the API Gateway to process all user interactions.
service AIService {
  rpc ProcessQuery(ProcessQueryRequest) returns (ProcessQueryResponse);
}

// Represents a user's interaction from the gateway.
message ProcessQueryRequest {
  // Optional. If provided, continues an existing conversation.
  string session_id = 1;

  // The user's raw text input.
  string query = 2;

  // Optional. Sent when a user confirms a previously presented plan.
  Confirmation confirmation = 3;
}

message Confirmation {
  string plan_id = 1;
  bool confirmed = 2; // Should be true
}

// The service's response to the gateway.
message ProcessQueryResponse {
  // A unique identifier for the conversation session.
  string session_id = 1;

  // The response can be one of two types.
  oneof response_type {
    PlanConfirmation plan = 2;
    FinalAnswer answer = 3;
  }
}

// A plan that requires user confirmation.
message PlanConfirmation {
  string plan_id = 1;
  string description = 2; // The human-readable text to show the user.
}

// A final answer to be displayed to the user.
message FinalAnswer {
  string response = 1; // The user-facing text.
}