ConnectRPC Services

Candela components use ConnectRPC (over HTTP/2 or HTTP/1.1 via the Connect protocol) for high-performance dashboard population, user governance, post-hoc annotations, and local runtime orchestration.

Port mappings for ConnectRPC services:

• candela-server / candela CLI: Listen on :8181 by default.

---

1. DashboardService

Provides aggregated metrics and usage data for visualization, chart rendering, and status displays.

GetDashboardData

Consolidates usage summaries, model breakdowns, and user budget status in a single round-trip.

• Request: GetDashboardDataRequest

  message GetDashboardDataRequest {
    string project_id = 1;
    candela.types.TimeRange time_range = 2;
    string environment = 3;
    bool include_budget = 4; // Set true to request user budget context
  }

• Response: GetDashboardDataResponse

  message GetDashboardDataResponse {
    GetUsageSummaryResponse summary = 1;
    repeated ModelUsage models = 2;
    BudgetContext budget_context = 3; // Populated only if include_budget=true + auth
  }

GetLatencyPercentiles

Retrieves latency distributions (p50, p90, p95, p99) and a time-series history for charts.

• Request: GetLatencyPercentilesRequest

  message GetLatencyPercentilesRequest {
    string project_id = 1;
    candela.types.TimeRange time_range = 2;
    string model = 3; // optional: filter by model
  }

• Response: GetLatencyPercentilesResponse

  message GetLatencyPercentilesResponse {
    double p50_ms = 1;
    double p90_ms = 2;
    double p95_ms = 3;
    double p99_ms = 4;
    repeated TimeSeriesPoint latency_over_time = 10;
  }

Deprecated Endpoints

The following endpoints are deprecated and should not be used in new integrations:

• GetUsageSummary (use GetDashboardData instead)
• GetModelBreakdown (use GetDashboardData instead)
• GetMyUsage (use GetDashboardData with include_budget=true or UserService.GetMyBudget instead)

---

2. UserService

Manages user accounts, active grants, and daily budget limits. It supports both admin commands and developer self-service.

Self-Service Endpoints (Current User)

GetCurrentUser

Returns the profile, role, status, and active budget details for the authenticated session.

• Request: GetCurrentUserRequest

  message GetCurrentUserRequest {}

• Response: GetCurrentUserResponse

  message GetCurrentUserResponse {
    candela.types.User user = 1;
    candela.types.UserBudget budget = 2;
    repeated candela.types.BudgetGrant active_grants = 3;
    double total_remaining_usd = 4; // Combined: grants + budget remaining
  }

GetMyBudget

Retrieves a lightweight, high-performance budget summary. This is the endpoint polled by IDE plugins to display status bar spend and remaining credits.

• Request: GetMyBudgetRequest

  message GetMyBudgetRequest {}

• Response: GetMyBudgetResponse

  message GetMyBudgetResponse {
    candela.types.UserBudget budget = 1;
    repeated candela.types.BudgetGrant active_grants = 2;
    double total_remaining_usd = 3;
    double budget_remaining_usd = 4;
    double grants_remaining_usd = 5;
    int64 tokens_used_today = 10;
    string period_key = 20;
    string period_resets_at = 21;
  }

Admin Endpoints

Requires admin credentials (OAuth2/ID token with appropriate roles).

• User Lifecycle:
  • CreateUser: Provision a new user with email and default daily budget.
    • Request: CreateUserRequest

      message CreateUserRequest {
        string email = 1;
        string display_name = 2;
        candela.types.UserRole role = 3;
        double daily_budget_usd = 5;
      }

    • Response: CreateUserResponse

      message CreateUserResponse {
        candela.types.User user = 1;
        candela.types.UserBudget budget = 2;
      }

  • ListUsers: Paginated list of users, with optional status filters (ACTIVE, INACTIVE).
  • GetUser: Get detailed user status, including active/expired grants.
    • Request: GetUserRequest

      message GetUserRequest {
        string id = 1;
      }

    • Response: GetUserResponse

      message GetUserResponse {
        candela.types.User user = 1;
        candela.types.UserBudget budget = 2;
        repeated candela.types.BudgetGrant active_grants = 3;
      }

  • UpdateUser: Update display names or roles using a FieldMask.
  • DeactivateUser / ReactivateUser: Enable or disable proxy traffic permissions.
  • DeleteUser: Permanently purge a deactivated user account.
• Budget Limits:
  • SetBudget: Configure recurring daily spending limits.
  • GetBudget: Retrieve limit and spent calculations.
  • ResetSpend: Zero out today’s spending for emergency relief.
• Grants:
  • CreateGrant: Issue one-time credits with startup and expiration dates.
  • ListGrants: Show active and expired grants.
  • GetGrant: Retrieve details for a single grant by ID.
  • RevokeGrant: Cancel/expire an active grant.
• Leaderboard:
  • GetJobLeaderboard: Returns a ranked list of users by their job completion metrics, useful for gamified dashboards.
• Audit Trail:
  • ListAuditLog: Retrieve an immutable audit trail of actions taken on a user.

---

3. AnnotationService

Provides APIs for post-hoc trace enrichment. Used for business outcome logging, human review labeling, and custom metric evaluation.

Unlike traces (which flow through high-throughput OTLP ingest pipelines), annotations have CRUD semantics and arrive asynchronously after a request completes.

SetOutcome

Records whether a trace succeeded or failed along with a business-level score.

• Request: SetOutcomeRequest

  message SetOutcomeRequest {
    string trace_id = 1;
    bool success = 2;
    double score = 3; // Value from 0.0 to 1.0
    string comment = 4;
  }

• Response: SetOutcomeResponse

  message SetOutcomeResponse {
    candela.types.Annotation annotation = 1;
  }

AddLabel

Attaches a human review label to a trace.

• Request: AddLabelRequest

  message AddLabelRequest {
    string trace_id = 1;
    string label = 2;
    string reviewer = 3;
    string comment = 4;
  }

• Response: AddLabelResponse

  message AddLabelResponse {
    candela.types.Annotation annotation = 1;
  }

LogMetric

Records a custom numerical metric associated with the trace.

• Request: LogMetricRequest

  message LogMetricRequest {
    string trace_id = 1;
    string metric_name = 2;
    double metric_value = 3;
    string comment = 4;
  }

• Response: LogMetricResponse

  message LogMetricResponse {
    candela.types.Annotation annotation = 1;
  }

ListAnnotations

Returns all annotations (outcomes, labels, and metrics) associated with a trace.

• Request: ListAnnotationsRequest

  message ListAnnotationsRequest {
    string trace_id = 1;
    candela.types.AnnotationType type_filter = 2;
  }

• Response: ListAnnotationsResponse

  message ListAnnotationsResponse {
    repeated candela.types.Annotation annotations = 1;
  }

---

4. RuntimeService

Orchestrates local model servers (Ollama, vLLM, LM Studio) inside the local environment (candela).

• Process Control:

  • StartRuntime: Start the configured inference daemon (e.g., Ollama or vLLM).
    • Request: StartRuntimeRequest

      message StartRuntimeRequest {
        string backend = 1;
      }

    • Response: StartRuntimeResponse

      message StartRuntimeResponse {
        RuntimeStatus status = 1;
      }

  • StopRuntime: Terminate the active inference daemon.

• Health & Models:

  • GetHealth: Checks state (STOPPED, STARTING, RUNNING, ERROR), uptime, and currently loaded models.
    • Request: GetHealthRequest

      message GetHealthRequest {}

    • Response: GetHealthResponse

      message GetHealthResponse {
        RuntimeStatus status = 1;
        repeated RuntimeModel models = 2;
      }

  • ListModels: List all models available on the disk.
  • LoadModel / UnloadModel: Load/unload models to/from GPU memory.
    • Request: LoadModelRequest

      message LoadModelRequest {
        string model = 1;
      }

    • Response: LoadModelResponse

      message LoadModelResponse {
        ModelLoadState state = 1;
      }

  • PullModel / CancelPull: Start/cancel asynchronous model downloads from registries.
  • DeleteModel: Delete downloaded model files.

• Discovery:

  • ListBackends: Check which backend engines are installed on the local system PATH and which is active.

• State:

  • ResetState: Clear pull history and app preferences from the local SQLite database.

    • Request: ResetStateRequest

      message ResetStateRequest {}

    • Response: ResetStateResponse

      message ResetStateResponse {}

    [!WARNING] ResetState is a destructive operation that permanently clears the local SQLite database containing download history and custom preferences. This action cannot be undone.

• Catalog:

  • ListCatalog: Retrieve recommended models to install.

---

5. ModelCatalogService

Manages the centralized model catalog — the registry of all models known to the Candela server, including their pricing, capabilities, and availability.

ListModelCatalog

Returns all entries in the model catalog, with optional filtering.

• Request: ListModelCatalogRequest

  message ListModelCatalogRequest {
    string provider = 1;       // optional: filter by provider
    string capability = 2;     // optional: filter by capability (e.g., "vision", "code")
    int32 page_size = 10;
    string page_token = 11;
  }

• Response: ListModelCatalogResponse

  message ListModelCatalogResponse {
    repeated candela.types.ModelCatalogEntry entries = 1;
    string next_page_token = 2;
  }

UpdateModelCatalogEntry

Updates an existing model catalog entry (e.g., pricing, display name, or capability tags).

• Request: UpdateModelCatalogEntryRequest

  message UpdateModelCatalogEntryRequest {
    candela.types.ModelCatalogEntry entry = 1;
    google.protobuf.FieldMask update_mask = 2;
  }

• Response: UpdateModelCatalogEntryResponse

  message UpdateModelCatalogEntryResponse {
    candela.types.ModelCatalogEntry entry = 1;
  }

DeleteModelCatalogEntry

Removes a model from the catalog. Existing traces referencing this model are unaffected.

• Request: DeleteModelCatalogEntryRequest

  message DeleteModelCatalogEntryRequest {
    string model_id = 1;
  }

• Response: DeleteModelCatalogEntryResponse

  message DeleteModelCatalogEntryResponse {}

---

6. ProjectService

Manages Candela projects — logical groupings for organizing models, users, and traces.

CreateProject

Creates a new project.

• Request: CreateProjectRequest

  message CreateProjectRequest {
    string display_name = 1;
    string description = 2;
  }

• Response: CreateProjectResponse

  message CreateProjectResponse {
    candela.types.Project project = 1;
  }

GetProject

Retrieves a project by ID.

• Request: GetProjectRequest

  message GetProjectRequest {
    string project_id = 1;
  }

• Response: GetProjectResponse

  message GetProjectResponse {
    candela.types.Project project = 1;
  }

ListProjects

Lists all projects visible to the authenticated user.

• Request: ListProjectsRequest

  message ListProjectsRequest {
    candela.types.PaginationRequest pagination = 1;
  }

• Response: ListProjectsResponse

  message ListProjectsResponse {
    repeated candela.types.Project projects = 1;
    candela.types.PaginationResponse pagination = 2;
  }

UpdateProject

Updates project metadata.

• Request: UpdateProjectRequest

  message UpdateProjectRequest {
    candela.types.Project project = 1;
    google.protobuf.FieldMask update_mask = 2;
  }

• Response: UpdateProjectResponse

  message UpdateProjectResponse {
    candela.types.Project project = 1;
  }

DeleteProject

Deletes a project. All associated traces and configuration are removed.

• Request: DeleteProjectRequest

  message DeleteProjectRequest {
    string project_id = 1;
  }

• Response: DeleteProjectResponse

  message DeleteProjectResponse {}

---

7. TraceService

Provides query and retrieval APIs for LLM request traces stored by Candela.

GetTrace

Retrieves a single trace by its trace ID.

• Request: GetTraceRequest

  message GetTraceRequest {
    string trace_id = 1;
  }

• Response: GetTraceResponse

  message GetTraceResponse {
    candela.types.Trace trace = 1;
  }

ListTraces

Queries traces with filtering and pagination.

• Request: ListTracesRequest

  message ListTracesRequest {
    string project_id = 1;
    candela.types.TimeRange time_range = 2;
    string model = 3;            // optional: filter by model
    string user_id = 4;          // optional: filter by user
    string status = 5;           // optional: "ok", "error"
    int32 page_size = 10;
    string page_token = 11;
  }

• Response: ListTracesResponse

  message ListTracesResponse {
    repeated candela.types.Trace traces = 1;
    string next_page_token = 2;
    int32 total_count = 3;
  }

DeleteTrace

Deletes a trace by ID. Associated annotations are also removed.

• Request: DeleteTraceRequest

  message DeleteTraceRequest {
    string trace_id = 1;
  }

• Response: DeleteTraceResponse

  message DeleteTraceResponse {}