feat/API: implement /models and /models/{modelId} using TypeSpec (#64421)

Fixes CODY-3085
Fixes CODY-3086

Previously, there was no way for OpenAI clients to list the available
models on Sourcegraph or query metadata about a given model ID ("model
ref" using our internal terminology). This PR fixes that problem AND
additionally adds infrastructure to auto-generate Go models from a
TypeSpec specification.

[TypeSpec](https://typespec.io/) is an IDL to document REST APIs,
created by Microsoft. Historically, the Go code in this repository has
been the single source of truth about what exact JSON structures are
expected in HTTP request/response pairs in our REST endpoints. This new
TypeSpec infrastructure allows us to document these shapes at a higher
abstraction level, which has several benefits including automatic
OpenAPI generation, which we can use to generate docs on
sourcegraph.com/docs or automatically generate client bindings in
TypeScript (among many other use-cases).

I am planning to write an RFC to propose we start using TypeSpec for new
REST endpoints going forward. If the RFC is not approved then we can
just delete the new `tools/typespec_codegen` directory and keep the
generated code in the repo. It won't be a big difference in the end
compared our current manual approach of writing Go structs for HTTP
APIs.

<!-- PR description tips:
https://www.notion.so/sourcegraph/Write-a-good-pull-request-description-610a7fd3e613496eb76f450db5a49b6e
-->

## Test plan
See test cases. I additionally wrote a basic python script with the
official OpenAI client to test that it works with this endpoint. First,
I ran `sg start minimal`. Then I wrote this script
```py
import os
from openai import OpenAI
from dotenv import load_dotenv
import httpx

load_dotenv()

openai = OpenAI(
    # base_url="https://api.openai.com/v1",
    # api_key=os.getenv("OPENAI_API_KEY"),
    base_url="https://sourcegraph.test:3443/api/v1",
    api_key=os.getenv("SRC_ACCESS_TOKEN"),
    http_client=httpx.Client(verify=False)
)

def main():
    response = openai.models.list()
    for model in response.data:
        print(model.id)
if __name__ == "__main__":
    main()

```
Finally, I ran 
```
❯ python3 models.py
anthropic::unknown::claude-3-haiku-20240307
anthropic::unknown::claude-3-sonnet-20240229
fireworks::unknown::starcoder
```
<!-- REQUIRED; info at
https://docs-legacy.sourcegraph.com/dev/background-information/testing_principles
-->

## Changelog

* New `GET /.api/llm/models` and `GET /.api/llm/models/{modelId}` REST
API endpoints to list available LLM models on the instance and to get
information about a given model. This endpoints is compatible with the
`/models` and `/models/{modelId}` endpoints from OpenAI.

<!-- OPTIONAL; info at
https://www.notion.so/sourcegraph/Writing-a-changelog-entry-dd997f411d524caabf0d8d38a24a878c
-->

Author: olafurpg

.bazelignore

@@ -26,6 +26,7 @@ client/web/node_modules
 client/web-sveltekit/node_modules
 client/wildcard/node_modules
 internal/appliance/frontend/maintenance/node_modules
+internal/openapi/node_modules
 
 cmd/symbols/internal/squirrel/test_repos/starlark
 

cmd/frontend/internal/llmapi/BUILD.bazel

@@ -4,15 +4,17 @@ load("//dev:go_defs.bzl", "go_test")
 go_library(
     name = "llmapi",
     srcs = [
-        "chat_completions_handler.go",
-        "chat_completions_models.go",
+        "handler_chat_completions.go",
+        "handler_models.go",
+        "handler_models_modelid.go",
         "httpapi.go",
     ],
     importpath = "github.com/sourcegraph/sourcegraph/cmd/frontend/internal/llmapi",
     visibility = ["//cmd/frontend:__subpackages__"],
     deps = [
         "//internal/completions/types",
         "//internal/modelconfig/types",
+        "//internal/openapi/goapi",
         "//lib/errors",
         "@com_github_google_uuid//:uuid",
         "@com_github_gorilla_mux//:mux",
@@ -23,8 +25,9 @@ go_library(
 go_test(
     name = "llmapi_test",
     srcs = [
-        "chat_completions_handler_test.go",
-        "chat_completions_models_test.go",
+        "handler_chat_completions_test.go",
+        "handler_models_modelid_test.go",
+        "handler_models_test.go",
         "utils_test.go",
     ],
     data = glob(["golly-recordings/**"]),
@@ -33,8 +36,10 @@ go_test(
         "//internal/golly",
         "//internal/httpcli",
         "//internal/modelconfig/types",
+        "//internal/openapi/goapi",
         "@com_github_gorilla_mux//:mux",
         "@com_github_hexops_autogold_v2//:autogold",
         "@com_github_stretchr_testify//assert",
+        "@com_github_stretchr_testify//require",
     ],
 )

cmd/frontend/internal/llmapi/chat_completions_handler.go renamed to cmd/frontend/internal/llmapi/handler_chat_completions.go

@@ -11,13 +11,13 @@ import (
 	"time"
 
 	"github.com/google/uuid"
-	"github.com/sourcegraph/log"
 	sglog "github.com/sourcegraph/log"
 
 	"github.com/sourcegraph/sourcegraph/lib/errors"
 
 	completions "github.com/sourcegraph/sourcegraph/internal/completions/types"
 	types "github.com/sourcegraph/sourcegraph/internal/modelconfig/types"
+	"github.com/sourcegraph/sourcegraph/internal/openapi/goapi"
 )
 
 // chatCompletionsHandler implements the REST endpoint /chat/completions
@@ -34,12 +34,10 @@ type chatCompletionsHandler struct {
 	GetModelConfig GetModelConfigurationFunc
 }
 
-type GetModelConfigurationFunc func() (*types.ModelConfiguration, error)
-
 var _ http.Handler = (*chatCompletionsHandler)(nil)
 
 func (h *chatCompletionsHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	var chatCompletionRequest CreateChatCompletionRequest
+	var chatCompletionRequest goapi.CreateChatCompletionRequest
 	body, err := io.ReadAll(r.Body)
 	if err != nil {
 		http.Error(w, fmt.Sprintf("io.ReadAll: %v", err), http.StatusInternalServerError)
@@ -78,19 +76,14 @@ func (h *chatCompletionsHandler) ServeHTTP(w http.ResponseWriter, r *http.Reques
 
 	chatCompletionResponse := transformToOpenAIResponse(sgResp, chatCompletionRequest)
 
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(http.StatusOK)
-	if err = json.NewEncoder(w).Encode(chatCompletionResponse); err != nil {
-		h.logger.Error("writing /chat/completions response body", log.Error(err))
-	}
-
+	serveJSON(w, r, h.logger, chatCompletionResponse)
 }
 
 // validateRequestedModel checks that are only use the modelref syntax
 // (${ProviderID}::${APIVersionID}::${ModelID}).  If the user passes the old
 // syntax `${ProviderID}/${ModelID}`, then we try to return a helpful error
 // message suggesting to use the new modelref syntax.
-func validateRequestedModel(chatCompletionRequest CreateChatCompletionRequest, modelConfig *types.ModelConfiguration) string {
+func validateRequestedModel(chatCompletionRequest goapi.CreateChatCompletionRequest, modelConfig *types.ModelConfiguration) string {
 	closestModelRef := ""
 	for _, model := range modelConfig.Models {
 		if string(model.ModelRef) == chatCompletionRequest.Model {
@@ -109,7 +102,7 @@ func validateRequestedModel(chatCompletionRequest CreateChatCompletionRequest, m
 	return fmt.Sprintf("model %s is not supported%s", chatCompletionRequest.Model, didYouMean)
 }
 
-func validateChatCompletionRequest(chatCompletionRequest CreateChatCompletionRequest) string {
+func validateChatCompletionRequest(chatCompletionRequest goapi.CreateChatCompletionRequest) string {
 
 	if chatCompletionRequest.N != nil && *chatCompletionRequest.N != 1 {
 		return "n must be nil or 1"
@@ -148,7 +141,7 @@ func validateChatCompletionRequest(chatCompletionRequest CreateChatCompletionReq
 	return ""
 }
 
-func transformToSGRequest(openAIReq CreateChatCompletionRequest) completions.CodyCompletionRequestParameters {
+func transformToSGRequest(openAIReq goapi.CreateChatCompletionRequest) completions.CodyCompletionRequestParameters {
 	maxTokens := 16 // Default in OpenAI openapi.yaml spec
 	if openAIReq.MaxTokens != nil {
 		maxTokens = *openAIReq.MaxTokens
@@ -178,7 +171,7 @@ func transformToSGRequest(openAIReq CreateChatCompletionRequest) completions.Cod
 	}
 }
 
-func transformMessages(messages []ChatCompletionRequestMessage) []completions.Message {
+func transformMessages(messages []goapi.ChatCompletionRequestMessage) []completions.Message {
 	// Transform OpenAI messages to Sourcegraph format
 	transformed := make([]completions.Message, len(messages))
 	for i, msg := range messages {
@@ -248,23 +241,23 @@ func (h *chatCompletionsHandler) forwardToAPIHandler(sgReq completions.CodyCompl
 	return &sgResp, nil
 }
 
-func transformToOpenAIResponse(sgResp *completions.CompletionResponse, openAIReq CreateChatCompletionRequest) CreateChatCompletionResponse {
-	return CreateChatCompletionResponse{
+func transformToOpenAIResponse(sgResp *completions.CompletionResponse, openAIReq goapi.CreateChatCompletionRequest) goapi.CreateChatCompletionResponse {
+	return goapi.CreateChatCompletionResponse{
 		ID:      "chat-" + generateUUID(),
 		Object:  "chat.completion",
 		Created: time.Now().Unix(),
 		Model:   openAIReq.Model,
-		Choices: []ChatCompletionChoice{
+		Choices: []goapi.ChatCompletionChoice{
 			{
 				Index: 0,
-				Message: ChatCompletionResponseMessage{
+				Message: goapi.ChatCompletionResponseMessage{
 					Role:    "assistant",
 					Content: sgResp.Completion,
 				},
 				FinishReason: sgResp.StopReason,
 			},
 		},
-		Usage: CompletionUsage{},
+		Usage: goapi.CompletionUsage{},
 	}
 }
 

cmd/frontend/internal/llmapi/chat_completions_handler_test.go renamed to cmd/frontend/internal/llmapi/handler_chat_completions_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/stretchr/testify/assert"
 
 	types "github.com/sourcegraph/sourcegraph/internal/modelconfig/types"
+	"github.com/sourcegraph/sourcegraph/internal/openapi/goapi"
 )
 
 func TestChatCompletionsHandler(t *testing.T) {
@@ -89,7 +90,7 @@ func TestChatCompletionsHandler(t *testing.T) {
 			t.Fatalf("Expected status code %d, got %d. Body: %s%s", http.StatusOK, rr.Code, rr.Body.String(), extraMessage)
 		}
 
-		var resp CreateChatCompletionResponse
+		var resp goapi.CreateChatCompletionResponse
 		responseBytes := rr.Body.Bytes()
 		err := json.Unmarshal(responseBytes, &resp)
 		if err != nil {

cmd/frontend/internal/llmapi/handler_models.go

@@ -0,0 +1,41 @@
+package llmapi
+
+import (
+	"fmt"
+	"net/http"
+
+	sglog "github.com/sourcegraph/log"
+
+	"github.com/sourcegraph/sourcegraph/internal/openapi/goapi"
+)
+
+type modelsHandler struct {
+	logger         sglog.Logger
+	GetModelConfig GetModelConfigurationFunc
+}
+
+var _ http.Handler = (*modelsHandler)(nil)
+
+func (m *modelsHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	currentModelConfig, err := m.GetModelConfig()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("modelConfigSvc.Get: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	var data []goapi.Model
+	for _, model := range currentModelConfig.Models {
+		data = append(data, goapi.Model{
+			Object:  "model",
+			Id:      string(model.ModelRef),
+			OwnedBy: string(model.ModelRef.ProviderID()),
+		})
+	}
+
+	response := goapi.ListModelsResponse{
+		Object: "list",
+		Data:   data,
+	}
+
+	serveJSON(w, r, m.logger, response)
+}

cmd/frontend/internal/llmapi/handler_models_modelid.go

@@ -0,0 +1,48 @@
+package llmapi
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/gorilla/mux"
+	sglog "github.com/sourcegraph/log"
+
+	"github.com/sourcegraph/sourcegraph/internal/openapi/goapi"
+)
+
+type modelsModelIDHandler struct {
+	logger         sglog.Logger
+	GetModelConfig GetModelConfigurationFunc
+}
+
+var _ http.Handler = (*modelsModelIDHandler)(nil)
+
+func (m *modelsModelIDHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	vars := mux.Vars(r)
+	modelId := vars["modelId"]
+
+	if modelId == "" {
+		http.Error(w, "modelId is required", http.StatusBadRequest)
+		return
+	}
+
+	currentModelConfig, err := m.GetModelConfig()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("modelConfigSvc.Get: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	for _, model := range currentModelConfig.Models {
+		if string(model.ModelRef) == modelId {
+			response := goapi.Model{
+				Object:  "model",
+				Id:      string(model.ModelRef),
+				OwnedBy: string(model.ModelRef.ProviderID()),
+			}
+			serveJSON(w, r, m.logger, response)
+			return
+		}
+	}
+
+	http.Error(w, "Model not found", http.StatusNotFound)
+}

cmd/frontend/internal/llmapi/handler_models_modelid_test.go

@@ -0,0 +1,78 @@
+package llmapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	types "github.com/sourcegraph/sourcegraph/internal/modelconfig/types"
+	"github.com/sourcegraph/sourcegraph/internal/openapi/goapi"
+)
+
+func TestModelsModelIDHandler(t *testing.T) {
+	mockModels := []types.Model{
+		{
+			ModelRef:    "anthropic::unknown::claude-3-sonnet-20240229",
+			DisplayName: "Claude 3 Sonnet",
+		},
+		{
+			ModelRef:    "openai::unknown::gpt-4",
+			DisplayName: "GPT-4",
+		},
+	}
+
+	c := newTest(t, func() (*types.ModelConfiguration, error) {
+		return &types.ModelConfiguration{Models: mockModels}, nil
+	})
+
+	testCases := []struct {
+		name           string
+		modelID        string
+		expectedStatus int
+		expectedModel  *goapi.Model
+	}{
+		{
+			name:           "Existing model",
+			modelID:        "anthropic::unknown::claude-3-sonnet-20240229",
+			expectedStatus: http.StatusOK,
+			expectedModel: &goapi.Model{
+				Id:      "anthropic::unknown::claude-3-sonnet-20240229",
+				Object:  "model",
+				OwnedBy: "anthropic",
+			},
+		},
+		{
+			name:           "Non-existent model",
+			modelID:        "non-existent-model",
+			expectedStatus: http.StatusNotFound,
+			expectedModel:  nil,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			req, err := http.NewRequest("GET", "/.api/llm/models/"+tc.modelID, nil)
+			require.NoError(t, err)
+
+			rr := httptest.NewRecorder()
+
+			c.Handler.ServeHTTP(rr, req)
+
+			assert.Equal(t, tc.expectedStatus, rr.Code)
+			if rr.Code == http.StatusOK {
+				assert.Equal(t, "application/json", rr.Header().Get("Content-Type"))
+			}
+
+			if tc.expectedModel != nil {
+				var response goapi.Model
+				err = json.Unmarshal(rr.Body.Bytes(), &response)
+				require.NoError(t, err)
+				assert.Equal(t, response, *tc.expectedModel)
+			}
+		})
+	}
+}