feat: align gkg.proto for API design

Michael Angelo Riverarequested to merge
arivera/orbit-rest-api-proto into main

Builds on ADR 003 — Orbit API Design and implements the proto changes needed for the REST API surface.

Related to gitlab-org#20566 Related to gitlab-org/gitlab#591396

What changed

Proto (4 RPCs, down from 5)

  • Dropped ExecuteTool — queries go through ExecuteQuery, schema through GetGraphSchema
  • Replaced GetOntology with GetGraphSchema — adds expand_nodes for selective property loading and ResponseFormat for RAW vs LLM output
  • Added ResponseFormat to ExecuteQuery and GetClusterHealth
  • Restructured ExecuteQueryResult — uses oneof content { result_json, formatted_text } with a separate QueryMetadata message (query_type, raw_query_strings, row_count)
  • Removed generated_sql, redacted_count, execution_time_ms from ExecuteQueryResult (per sync decisions)
  • Removed accidental JSON blob from proto file

Rust service

  • execute_query picks raw or context-engine pipeline based on ResponseFormat, populates QueryMetadata from pipeline output
  • get_graph_schema returns StructuredSchema (RAW) or TOON text (LLM), with expand_nodes controlling expansion
  • get_cluster_health wraps response in a oneof for format switching
  • Removed all ExecuteTool handler code

How to review

  1. gkg.proto — message/RPC changes drive everything else
  2. grpc/service.rs — handler implementations for the 4 RPCs
  3. query_pipeline/types.rs + stages/formatting.rs — PipelineOutput fields and formatting stage
  4. docs/design-documents/decisions/003_api_design.md — updated response examples and proto definition

Test plan

  • cargo check compiles cleanly
  • cargo test -p gkg-server — 147 unit tests pass
  • Integration test with updated Rails gRPC client (separate MR)
Edited by Michael Angelo Rivera

Merge request reports