package analysis_service

Get desktop application:
View/edit binary Protocol Buffers messages

Admin-only analysis service

• rpc GetAdminStats (GetAdminStatsRequest, GetAdminStatsResponse)

  analysis_service.proto:94

  GetAdminStats returns overview statistics for the analysis system

  message GetAdminStatsRequest

  analysis_service.proto:177

  (message has no fields)

  message GetAdminStatsResponse

  analysis_service.proto:184

  • int32 total_completed = 1

  • int32 pending_count = 2

  • int32 processing_count = 3

  • repeated LeaderboardEntry leaderboard = 4

  • repeated LeaderboardEntry contributors = 5

• rpc ListAnalyzedGames (ListAnalyzedGamesRequest, ListAnalyzedGamesResponse)

  analysis_service.proto:97

  ListAnalyzedGames returns a paginated list of completed analysis jobs

  message ListAnalyzedGamesRequest

  analysis_service.proto:192

  • int32 page = 1

  • int32 page_size = 2

  message ListAnalyzedGamesResponse

  analysis_service.proto:207

  • repeated AnalyzedGameSummary games = 1

  • int32 total = 2

• rpc RequeueAnalysis (RequeueAnalysisRequest, RequeueAnalysisResponse)

  analysis_service.proto:100

  RequeueAnalysis resets an analysis job back to pending for re-processing

  message RequeueAnalysisRequest

  analysis_service.proto:212

  • string game_id = 1

  message RequeueAnalysisResponse

  analysis_service.proto:216

  • string job_id = 1

  • int32 queue_position = 2

• rpc ClaimJob (ClaimJobRequest, ClaimJobResponse)

  analysis_service.proto:79

  ClaimJob atomically claims next available job

  message ClaimJobRequest

  analysis_service.proto:7

  Request to claim next available job

  • string macondo_version = 1

    Worker authenticates via X-Api-Key header (existing middleware)

    Worker reports its version; rejected if too old

  message ClaimJobResponse

  analysis_service.proto:13

  Response with job details or no_jobs flag

  • bool no_jobs = 1

  • string job_id = 2

    Job details (populated if no_jobs = false)

  • string game_id = 3

  • optional AnalysisConfig config = 4

• rpc FailJob (FailJobRequest, FailJobResponse)

  analysis_service.proto:88

  FailJob reports a job as permanently failed due to unrecoverable data corruption

  message FailJobRequest

  analysis_service.proto:67

  Request to report a job as permanently failed (e.g. corrupted game data)

  • string job_id = 1

  • string error_message = 2

  • string macondo_version = 3

  message FailJobResponse

  analysis_service.proto:73

  • bool accepted = 1

• rpc Heartbeat (HeartbeatRequest, HeartbeatResponse)

  analysis_service.proto:82

  Heartbeat keeps job from being reclaimed due to timeout

  message HeartbeatRequest

  analysis_service.proto:37

  Heartbeat to keep job alive

  • string job_id = 1

  • int32 current_turn = 2

    Optional progress info

  • int32 total_turns = 3

  message HeartbeatResponse

  analysis_service.proto:45

  • bool continue = 1

    false if job was reclaimed

• rpc SubmitResult (SubmitResultRequest, SubmitResultResponse)

  analysis_service.proto:85

  SubmitResult submits completed analysis

  message SubmitResultRequest

  analysis_service.proto:50

  Submit completed analysis

  • string job_id = 1

  • bytes result_proto = 2

    Deprecated: raw protojson bytes; use result field instead

  • string macondo_version = 3

  • optional macondo.GameAnalysisResult result = 4

    Typed result (v2+)

  message SubmitResultResponse

  analysis_service.proto:60

  • bool accepted = 1

  • string error = 2

    Populated if accepted = false

  • string expected_version = 3

    Populated if rejected due to version mismatch

User-facing analysis service

• rpc GetAnalysisResult (GetAnalysisResultRequest, GetAnalysisResultResponse)

  analysis_service.proto:112

  GetAnalysisResult gets the completed analysis result

  message GetAnalysisResultRequest

  analysis_service.proto:165

  Get analysis result

  • string game_id = 1

  message GetAnalysisResultResponse

  analysis_service.proto:169

  • bool found = 1

  • bytes result_proto = 2

    Deprecated: raw bytes for backward compat

  • optional macondo.GameAnalysisResult result = 3

    Typed result

• rpc GetAnalysisStatus (GetAnalysisStatusRequest, GetAnalysisStatusResponse)

  analysis_service.proto:109

  GetAnalysisStatus gets status of an analysis job

  message GetAnalysisStatusRequest

  analysis_service.proto:144

  Get status of an analysis

  • string game_id = 1

  message GetAnalysisStatusResponse

  analysis_service.proto:148

  • GetAnalysisStatusResponse.JobStatus status = 1

  • string job_id = 2

  • int32 queue_position = 3

    Position in queue (0 if not pending)

  • string error_message = 4

    If failed

  • int32 analysis_version = 5

    0 = legacy (v1), 2 = enriched; only set when COMPLETED

• rpc GetGamesAnalysisStatus (GetGamesAnalysisStatusRequest, GetGamesAnalysisStatusResponse)

  analysis_service.proto:115

  GetGamesAnalysisStatus returns which of the given game IDs have completed analysis

  message GetGamesAnalysisStatusRequest

  analysis_service.proto:221

  • repeated string game_ids = 1

  message GetGamesAnalysisStatusResponse

  analysis_service.proto:225

  • repeated string analyzed_game_ids = 1

• rpc RequestAnalysis (RequestAnalysisRequest, RequestAnalysisResponse)

  analysis_service.proto:106

  RequestAnalysis requests analysis for a completed game

  message RequestAnalysisRequest

  analysis_service.proto:119

  Request analysis for a game

  • string game_id = 1

  • bool force = 2

    Re-analyze even if completed (only allowed for legacy v0 results)

  message RequestAnalysisResponse

  analysis_service.proto:124

  • RequestAnalysisResponse.Status status = 1

  • string message = 2

    Human-readable message

  • string job_id = 3

    If successful or already requested:

    Analysis job ID

  • int32 queue_position = 4

    Position in queue (0 if processing/completed)

Analysis configuration

Used in: ClaimJobResponse

• int32 sim_plays_early_mid = 1

• int32 sim_plies_early_mid = 2

• int32 sim_stop_early_mid = 3

• int32 sim_plays_early_preendgame = 4

• int32 sim_plies_early_preendgame = 5

• int32 sim_stop_early_preendgame = 6

• bool peg_early_cutoff = 7

• int32 threads = 8

Used in: ListAnalyzedGamesResponse

• string job_id = 1

• string game_id = 2

• int64 created_at_ms = 3

  Unix milliseconds

• int64 completed_at_ms = 4

  Unix milliseconds

• string request_type = 5

• string requested_by_username = 6

• int64 claimed_at_ms = 7

  Unix milliseconds

Used in: GetAnalysisStatusResponse

• NOT_FOUND = 0

  No analysis job exists

• PENDING = 1

  Waiting in queue

• PROCESSING = 2

  Currently being analyzed

• COMPLETED = 3

  Analysis complete

• FAILED = 4

  Analysis failed

Used in: GetAdminStatsResponse

• string username = 1

• int32 analysis_count = 2

Status of the request

Used in: RequestAnalysisResponse

• SUCCESS = 0

  Analysis queued successfully

• ALREADY_REQUESTED = 1

  Analysis already requested/exists for this game

• GAME_NOT_ENDED = 2

  Game hasn't ended yet

• NOT_A_PLAYER = 3

  Requester is not a player in this game

• RATE_LIMITED = 4

  User has exceeded daily limit

• INVALID_VARIANT = 5

  Game variant not supported