OpenShell/proto/inference.proto

// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";

package openshell.inference.v1;

import "datamodel.proto";
import "options.proto";

// Inference service provides workspace-scoped inference route configuration and bundle delivery.
service Inference {
  // Return the resolved inference route bundle for sandbox-local execution.
  rpc GetInferenceBundle(GetInferenceBundleRequest)
      returns (GetInferenceBundleResponse) {
    option (openshell.options.v1.authorization) = {
      auth_mode: "sandbox"
    };
  }

  // Set the inference route for a workspace.
  //
  // This controls how requests sent to `inference.local` are routed
  // for sandboxes in the specified workspace.
  rpc SetInferenceRoute(SetInferenceRouteRequest)
      returns (SetInferenceRouteResponse) {
    option (openshell.options.v1.authorization) = {
      auth_mode: "bearer"
      scope: "inference:write"
      workspace_role: "admin"
    };
  }

  // Get the inference route for a workspace.
  rpc GetInferenceRoute(GetInferenceRouteRequest)
      returns (GetInferenceRouteResponse) {
    option (openshell.options.v1.authorization) = {
      auth_mode: "bearer"
      scope: "inference:read"
      workspace_role: "user"
    };
  }

  // Delete an inference route from a workspace.
  rpc DeleteInferenceRoute(DeleteInferenceRouteRequest)
      returns (DeleteInferenceRouteResponse) {
    option (openshell.options.v1.authorization) = {
      auth_mode: "bearer"
      scope: "inference:write"
      workspace_role: "admin"
    };
  }
}

// Persisted inference route configuration.
//
// Only `provider_name` and `model_id` are stored; endpoint, protocols,
// credentials, and auth style are resolved from the provider at bundle time.
message InferenceRouteConfig {
  // Provider record name backing this route.
  string provider_name = 1;
  // Model identifier to force on generation calls.
  string model_id = 2;
  // Per-route request timeout in seconds. 0 means use default (60s).
  uint64 timeout_secs = 3;
}

// Storage envelope for a workspace-scoped inference route.
message InferenceRoute {
  openshell.datamodel.v1.ObjectMeta metadata = 1;
  InferenceRouteConfig config = 2;
  // Monotonic version incremented on every update.
  uint64 version = 3;
}

message SetInferenceRouteRequest {
  // Provider record name to use for credentials + endpoint mapping.
  string provider_name = 1;
  // Model identifier to force on generation calls.
  string model_id = 2;
  // Route name to target. Empty string defaults to "inference.local" (user-facing).
  // Use "sandbox-system" for the sandbox system-level inference route.
  string route_name = 3;
  // Verify the resolved upstream endpoint synchronously before persistence.
  bool verify = 4;
  // Skip synchronous endpoint validation before persistence.
  bool no_verify = 5;
  // Per-route request timeout in seconds. 0 means use default (60s).
  uint64 timeout_secs = 6;
  // Target workspace. Empty string defaults to "default".
  string workspace = 7;
}

message ValidatedEndpoint {
  string url = 1;
  string protocol = 2;
}

message SetInferenceRouteResponse {
  string provider_name = 1;
  string model_id = 2;
  uint64 version = 3;
  // Route name that was configured.
  string route_name = 4;
  // Whether endpoint verification ran as part of this request.
  bool validation_performed = 5;
  // The concrete endpoints that were probed during validation, when available.
  repeated ValidatedEndpoint validated_endpoints = 6;
  // Per-route request timeout in seconds that was persisted.
  uint64 timeout_secs = 7;
  // Workspace the route was configured in.
  string workspace = 8;
}

message GetInferenceRouteRequest {
  // Route name to query. Empty string defaults to "inference.local" (user-facing).
  // Use "sandbox-system" for the sandbox system-level inference route.
  string route_name = 1;
  // Target workspace. Empty string defaults to "default".
  string workspace = 2;
}

message GetInferenceRouteResponse {
  string provider_name = 1;
  string model_id = 2;
  uint64 version = 3;
  // Route name that was queried.
  string route_name = 4;
  // Per-route request timeout in seconds. 0 means default (60s).
  uint64 timeout_secs = 5;
  // Workspace the route belongs to.
  string workspace = 6;
}

message DeleteInferenceRouteRequest {
  // Route name to delete. Empty string defaults to "inference.local" (user-facing).
  // Use "sandbox-system" for the sandbox system-level inference route.
  string route_name = 1;
  // Target workspace. Empty string defaults to "default".
  string workspace = 2;
}

message DeleteInferenceRouteResponse {
  // Whether a route was actually deleted.
  bool deleted = 1;
}

message GetInferenceBundleRequest {}

// A single resolved route ready for sandbox-local execution.
message ResolvedRoute {
  string name = 1;
  string base_url = 2;
  repeated string protocols = 3;
  string api_key = 4 [(openshell.options.v1.secret) = true];
  string model_id = 5;
  string provider_type = 6;
  // Per-route request timeout in seconds. 0 means use default (60s).
  uint64 timeout_secs = 7;
  // When true, the model identifier is embedded in the URL path (e.g. Vertex AI).
  bool model_in_path = 8;
  // Optional override for the request path. When set, replaces the protocol-derived path.
  // An empty string means POST directly to base_url/model_id with no additional path.
  optional string request_path_override = 9;
}

message GetInferenceBundleResponse {
  repeated ResolvedRoute routes = 1;
  // Opaque revision tag for cache freshness checks.
  string revision = 2;
  // Timestamp (epoch ms) when this bundle was generated.
  int64 generated_at_ms = 3;
}