gitcaddy-ai/protos/gitcaddy_ai.proto

syntax = "proto3";

option csharp_namespace = "GitCaddy.AI.Proto";

package gitcaddy.ai.v1;

// GitCaddyAI is the main service for AI-powered code intelligence
service GitCaddyAI {
  // Code Review
  rpc ReviewPullRequest(ReviewPullRequestRequest) returns (ReviewPullRequestResponse);
  rpc ReviewCommit(ReviewCommitRequest) returns (ReviewCommitResponse);

  // Code Intelligence
  rpc SummarizeChanges(SummarizeChangesRequest) returns (SummarizeChangesResponse);
  rpc ExplainCode(ExplainCodeRequest) returns (ExplainCodeResponse);
  rpc SuggestFix(SuggestFixRequest) returns (SuggestFixResponse);

  // Issue Management
  rpc TriageIssue(TriageIssueRequest) returns (TriageIssueResponse);
  rpc SuggestLabels(SuggestLabelsRequest) returns (SuggestLabelsResponse);
  rpc GenerateIssueResponse(GenerateIssueResponseRequest) returns (GenerateIssueResponseResponse);

  // Documentation
  rpc GenerateDocumentation(GenerateDocumentationRequest) returns (GenerateDocumentationResponse);
  rpc GenerateCommitMessage(GenerateCommitMessageRequest) returns (GenerateCommitMessageResponse);

  // Agentic Workflows
  rpc StartWorkflow(StartWorkflowRequest) returns (stream WorkflowEvent);
  rpc ExecuteTask(ExecuteTaskRequest) returns (ExecuteTaskResponse);

  // Chat Interface
  rpc Chat(stream ChatRequest) returns (stream ChatResponse);

  // Health & License
  rpc CheckHealth(HealthCheckRequest) returns (HealthCheckResponse);
  rpc ValidateLicense(ValidateLicenseRequest) returns (ValidateLicenseResponse);
}

// ============================================================================
// Code Review Messages
// ============================================================================

message ReviewPullRequestRequest {
  int64 repo_id = 1;
  int64 pull_request_id = 2;
  string base_branch = 3;
  string head_branch = 4;
  repeated FileDiff files = 5;
  string pr_title = 6;
  string pr_description = 7;
  ReviewOptions options = 8;
}

message ReviewPullRequestResponse {
  string summary = 1;
  repeated ReviewComment comments = 2;
  ReviewVerdict verdict = 3;
  repeated string suggestions = 4;
  SecurityAnalysis security = 5;
  int32 estimated_review_minutes = 6;
}

message ReviewCommitRequest {
  int64 repo_id = 1;
  string commit_sha = 2;
  string commit_message = 3;
  repeated FileDiff files = 4;
  ReviewOptions options = 5;
}

message ReviewCommitResponse {
  string summary = 1;
  repeated ReviewComment comments = 2;
  repeated string suggestions = 3;
}

message FileDiff {
  string path = 1;
  string old_path = 2;  // for renames
  string status = 3;    // added, modified, deleted, renamed
  string patch = 4;     // unified diff
  string content = 5;   // full file content (optional)
  string language = 6;
}

message ReviewComment {
  string path = 1;
  int32 line = 2;
  int32 end_line = 3;
  string body = 4;
  CommentSeverity severity = 5;
  string category = 6;  // security, performance, style, bug, etc.
  string suggested_fix = 7;
}

enum CommentSeverity {
  COMMENT_SEVERITY_UNSPECIFIED = 0;
  COMMENT_SEVERITY_INFO = 1;
  COMMENT_SEVERITY_WARNING = 2;
  COMMENT_SEVERITY_ERROR = 3;
  COMMENT_SEVERITY_CRITICAL = 4;
}

enum ReviewVerdict {
  REVIEW_VERDICT_UNSPECIFIED = 0;
  REVIEW_VERDICT_APPROVE = 1;
  REVIEW_VERDICT_REQUEST_CHANGES = 2;
  REVIEW_VERDICT_COMMENT = 3;
}

message ReviewOptions {
  bool check_security = 1;
  bool check_performance = 2;
  bool check_style = 3;
  bool check_tests = 4;
  bool suggest_improvements = 5;
  string focus_areas = 6;  // comma-separated areas to focus on
  string language_hints = 7;  // help with language detection
}

message SecurityAnalysis {
  repeated SecurityIssue issues = 1;
  int32 risk_score = 2;  // 0-100
  string summary = 3;
}

message SecurityIssue {
  string path = 1;
  int32 line = 2;
  string issue_type = 3;  // sql_injection, xss, hardcoded_secret, etc.
  string description = 4;
  string severity = 5;
  string remediation = 6;
}

// ============================================================================
// Code Intelligence Messages
// ============================================================================

message SummarizeChangesRequest {
  int64 repo_id = 1;
  repeated FileDiff files = 2;
  string context = 3;  // PR title, commit message, etc.
}

message SummarizeChangesResponse {
  string summary = 1;
  repeated string bullet_points = 2;
  string impact_assessment = 3;
}

message ExplainCodeRequest {
  int64 repo_id = 1;
  string file_path = 2;
  string code = 3;
  int32 start_line = 4;
  int32 end_line = 5;
  string question = 6;  // optional specific question
}

message ExplainCodeResponse {
  string explanation = 1;
  repeated string key_concepts = 2;
  repeated CodeReference references = 3;
}

message CodeReference {
  string description = 1;
  string url = 2;
}

message SuggestFixRequest {
  int64 repo_id = 1;
  string file_path = 2;
  string code = 3;
  string error_message = 4;
  string language = 5;
}

message SuggestFixResponse {
  string explanation = 1;
  string suggested_code = 2;
  repeated string alternative_fixes = 3;
}

// ============================================================================
// Issue Management Messages
// ============================================================================

message TriageIssueRequest {
  int64 repo_id = 1;
  int64 issue_id = 2;
  string title = 3;
  string body = 4;
  repeated string existing_labels = 5;
  repeated string available_labels = 6;
}

message TriageIssueResponse {
  string priority = 1;  // critical, high, medium, low
  string category = 2;  // bug, feature, question, docs, etc.
  repeated string suggested_labels = 3;
  repeated string suggested_assignees = 4;
  string summary = 5;
  bool is_duplicate = 6;
  int64 duplicate_of = 7;
}

message SuggestLabelsRequest {
  int64 repo_id = 1;
  string title = 2;
  string body = 3;
  repeated string available_labels = 4;
}

message SuggestLabelsResponse {
  repeated LabelSuggestion suggestions = 1;
}

message LabelSuggestion {
  string label = 1;
  float confidence = 2;
  string reason = 3;
}

message GenerateIssueResponseRequest {
  int64 repo_id = 1;
  int64 issue_id = 2;
  string title = 3;
  string body = 4;
  repeated IssueComment comments = 5;
  string response_type = 6;  // clarification, solution, acknowledgment
}

message GenerateIssueResponseResponse {
  string response = 1;
  repeated string follow_up_questions = 2;
}

message IssueComment {
  string author = 1;
  string body = 2;
  string created_at = 3;
}

// ============================================================================
// Documentation Messages
// ============================================================================

message GenerateDocumentationRequest {
  int64 repo_id = 1;
  string file_path = 2;
  string code = 3;
  string doc_type = 4;  // function, class, module, api
  string language = 5;
  string style = 6;  // jsdoc, docstring, xml, markdown
}

message GenerateDocumentationResponse {
  string documentation = 1;
  repeated DocumentationSection sections = 2;
}

message DocumentationSection {
  string title = 1;
  string content = 2;
}

message GenerateCommitMessageRequest {
  int64 repo_id = 1;
  repeated FileDiff files = 2;
  string style = 3;  // conventional, descriptive, brief
}

message GenerateCommitMessageResponse {
  string message = 1;
  repeated string alternatives = 2;
}

// ============================================================================
// Agentic Workflow Messages
// ============================================================================

message StartWorkflowRequest {
  int64 repo_id = 1;
  string workflow_type = 2;  // code_review, refactor, test_generation, etc.
  string goal = 3;
  map<string, string> parameters = 4;
  WorkflowOptions options = 5;
}

message WorkflowOptions {
  int32 max_steps = 1;
  int32 timeout_seconds = 2;
  float budget_limit = 3;
  bool allow_file_changes = 4;
  bool require_approval = 5;
}

message WorkflowEvent {
  string event_id = 1;
  string workflow_id = 2;
  WorkflowEventType type = 3;
  string agent_id = 4;
  string message = 5;
  map<string, string> data = 6;
  string timestamp = 7;
}

enum WorkflowEventType {
  WORKFLOW_EVENT_TYPE_UNSPECIFIED = 0;
  WORKFLOW_EVENT_TYPE_STARTED = 1;
  WORKFLOW_EVENT_TYPE_STEP_STARTED = 2;
  WORKFLOW_EVENT_TYPE_STEP_COMPLETED = 3;
  WORKFLOW_EVENT_TYPE_STEP_FAILED = 4;
  WORKFLOW_EVENT_TYPE_AGENT_THINKING = 5;
  WORKFLOW_EVENT_TYPE_TOOL_CALLED = 6;
  WORKFLOW_EVENT_TYPE_APPROVAL_NEEDED = 7;
  WORKFLOW_EVENT_TYPE_COMPLETED = 8;
  WORKFLOW_EVENT_TYPE_FAILED = 9;
  WORKFLOW_EVENT_TYPE_CANCELLED = 10;
}

message ExecuteTaskRequest {
  int64 repo_id = 1;
  string task = 2;
  map<string, string> context = 3;
  repeated string allowed_tools = 4;
}

message ExecuteTaskResponse {
  bool success = 1;
  string result = 2;
  repeated ToolExecution tool_calls = 3;
  string error = 4;
}

message ToolExecution {
  string tool_name = 1;
  string input = 2;
  string output = 3;
  bool success = 4;
}

// ============================================================================
// Chat Messages
// ============================================================================

message ChatRequest {
  string conversation_id = 1;
  int64 repo_id = 2;
  string message = 3;
  repeated ChatAttachment attachments = 4;
  ChatContext context = 5;
}

message ChatAttachment {
  string type = 1;  // file, diff, issue, pr
  string name = 2;
  string content = 3;
}

message ChatContext {
  string current_file = 1;
  int32 current_line = 2;
  string selected_code = 3;
  string branch = 4;
}

message ChatResponse {
  string conversation_id = 1;
  string message = 2;
  bool is_complete = 3;
  repeated ChatAction suggested_actions = 4;
}

message ChatAction {
  string type = 1;  // apply_fix, create_pr, create_issue, run_command
  string label = 2;
  map<string, string> parameters = 3;
}

// ============================================================================
// Health & License Messages
// ============================================================================

message HealthCheckRequest {}

message HealthCheckResponse {
  bool healthy = 1;
  string version = 2;
  map<string, string> provider_status = 3;  // provider -> status
  LicenseInfo license = 4;
}

message ValidateLicenseRequest {
  string license_key = 1;
}

message ValidateLicenseResponse {
  bool valid = 1;
  LicenseInfo license = 2;
  string error = 3;
}

message LicenseInfo {
  string tier = 1;  // standard, professional, enterprise
  string customer = 2;
  string expires_at = 3;
  repeated string features = 4;
  int32 seat_count = 5;
  bool is_trial = 6;
}