feat(cognitive): add local provider registry and discovery

This commit is contained in:
m
2026-08-17 09:28:33 +03:00
parent 9e99a04c76
commit a25a57ab69
38 changed files with 2344 additions and 116 deletions
+5 -1
View File
@@ -97,7 +97,11 @@ func DeterministicAdvisoryUnavailable(request cognitive.AdvisoryRequest) (cognit
func validFinishReason(reason cognitive.FinishReason) bool {
switch reason {
case cognitive.FinishCompleted, cognitive.FinishLengthLimit, cognitive.FinishContentRejected, cognitive.FinishProviderUnavailable, cognitive.FinishTimeout, cognitive.FinishInvalidProviderResponse:
case cognitive.FinishCompleted, cognitive.FinishLengthLimit, cognitive.FinishContentRejected,
cognitive.FinishProviderUnavailable, cognitive.FinishModelUnavailable, cognitive.FinishRateLimited,
cognitive.FinishAuthenticationFailed, cognitive.FinishBillingOrBudgetBlocked,
cognitive.FinishContextTooLarge, cognitive.FinishUnsupportedCapability, cognitive.FinishTimeout,
cognitive.FinishInvalidProviderResponse, cognitive.FinishInvalidStructuredOutput, cognitive.FinishDegraded:
return true
default:
return false
+31
View File
@@ -0,0 +1,31 @@
package models
import (
"context"
"git.cin.su/m/Assistant/contracts/capability"
"git.cin.su/m/Assistant/contracts/cognitive"
)
type ProviderProbe struct {
Health capability.HealthState
Version string
Failure cognitive.FinishReason
}
type DiscoveredModel struct {
ProviderModelID capability.ProviderModelID
Fingerprint capability.ModelFingerprint
MaxContextBytes int64
Modalities []capability.ModelModality
Capabilities []capability.ModelCapability
SizeBytes int64
Runtime string
Quantization string
}
type LocalProvider interface {
Probe(context.Context) ProviderProbe
Discover(context.Context) ([]DiscoveredModel, ProviderProbe)
Advise(context.Context, cognitive.AdvisoryRequest) (cognitive.AdvisoryResponse, error)
}
+169
View File
@@ -0,0 +1,169 @@
package models
import (
"bytes"
"context"
"encoding/json"
"errors"
"io"
"net/http"
"net/url"
"time"
"git.cin.su/m/Assistant/contracts/capability"
"git.cin.su/m/Assistant/contracts/cognitive"
)
type OllamaAdapter struct {
base *url.URL
client *http.Client
}
func NewOllamaAdapter(raw string, transport http.RoundTripper) (*OllamaAdapter, error) {
base, err := url.Parse(raw)
if err != nil || base.Scheme != "http" || base.Host == "" || base.Path != "" || base.User != nil || base.RawQuery != "" || base.Fragment != "" {
return nil, errors.New("invalid Ollama endpoint")
}
if transport == nil {
transport = http.DefaultTransport
}
return &OllamaAdapter{base: base, client: &http.Client{Transport: transport, Timeout: 10 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}}, nil
}
type ollamaTags struct {
Models []struct {
Name string `json:"name"`
Model string `json:"model"`
Size int64 `json:"size"`
Digest string `json:"digest"`
Details struct {
Format string `json:"format"`
Family string `json:"family"`
ParameterSize string `json:"parameter_size"`
Quantization string `json:"quantization_level"`
ContextLength int64 `json:"context_length"`
} `json:"details"`
Capabilities []string `json:"capabilities"`
} `json:"models"`
}
type ollamaVersion struct {
Version string `json:"version"`
}
func (a *OllamaAdapter) Probe(ctx context.Context) ProviderProbe {
var version ollamaVersion
status, err := a.request(ctx, http.MethodGet, "/api/version", nil, &version)
if err != nil {
return probeFailure(err)
}
if status != http.StatusOK || version.Version == "" {
return ProviderProbe{Health: capability.HealthUnavailable, Failure: mapCompatibleStatus(status)}
}
return ProviderProbe{Health: capability.HealthAvailable, Version: version.Version}
}
func (a *OllamaAdapter) Discover(ctx context.Context) ([]DiscoveredModel, ProviderProbe) {
probe := a.Probe(ctx)
if probe.Health != capability.HealthAvailable {
return nil, probe
}
var tags ollamaTags
status, err := a.request(ctx, http.MethodGet, "/api/tags", nil, &tags)
if err != nil {
return nil, probeFailure(err)
}
if status != http.StatusOK {
return nil, ProviderProbe{Health: capability.HealthUnavailable, Failure: mapCompatibleStatus(status)}
}
result := make([]DiscoveredModel, 0, len(tags.Models))
for _, item := range tags.Models {
if item.Name == "" || item.Digest == "" {
continue
}
capabilities := []capability.ModelCapability{capability.CapabilityUnknown}
for _, declared := range item.Capabilities {
if declared == "completion" {
capabilities = []capability.ModelCapability{capability.CapabilityAdvisory}
break
}
}
result = append(result, DiscoveredModel{ProviderModelID: capability.ProviderModelID(item.Name), Fingerprint: capability.ModelFingerprint(item.Digest), MaxContextBytes: item.Details.ContextLength * 4, Modalities: []capability.ModelModality{capability.ModalityText}, Capabilities: capabilities, SizeBytes: item.Size, Runtime: "ollama/" + probe.Version, Quantization: item.Details.Quantization})
}
return result, probe
}
type ollamaChatRequest struct {
Model string `json:"model"`
Messages []compatibleMessage `json:"messages"`
Stream bool `json:"stream"`
Think bool `json:"think"`
Options struct {
Temperature int `json:"temperature"`
NumCtx int64 `json:"num_ctx,omitempty"`
} `json:"options"`
}
type ollamaChatResponse struct {
Message compatibleMessage `json:"message"`
Done bool `json:"done"`
DoneReason string `json:"done_reason"`
PromptEvalCount int64 `json:"prompt_eval_count"`
EvalCount int64 `json:"eval_count"`
}
func (a *OllamaAdapter) Advise(ctx context.Context, request cognitive.AdvisoryRequest) (cognitive.AdvisoryResponse, error) {
if err := ValidateAdvisoryRequest(request); err != nil || request.ProviderModelID == "" || len(request.Context) != 0 {
return cognitive.AdvisoryResponse{}, ErrInvalidAdvisory
}
payload := ollamaChatRequest{Model: string(request.ProviderModelID), Messages: []compatibleMessage{{Role: "system", Content: "Provide non-canonical advisory text only. Never claim that an action occurred."}, {Role: "user", Content: request.Message}}, Stream: false, Think: false}
var result ollamaChatResponse
status, err := a.request(ctx, http.MethodPost, "/api/chat", payload, &result)
if err != nil {
return advisoryFailure(request, probeFailure(err).Failure), nil
}
if status != http.StatusOK {
return advisoryFailure(request, mapCompatibleStatus(status)), nil
}
if !result.Done || result.Message.Content == "" {
return advisoryFailure(request, cognitive.FinishInvalidProviderResponse), nil
}
response := cognitive.AdvisoryResponse{Version: request.Version, RequestID: request.RequestID, ProviderBindingID: request.ProviderBindingID, ProviderBindingRevision: request.ProviderBindingRevision, AdvisoryText: result.Message.Content, FinishReason: cognitive.FinishCompleted, Usage: &cognitive.ProviderUsage{InputUnits: result.PromptEvalCount, OutputUnits: result.EvalCount}}
if ValidateAdvisoryResponse(request, response) != nil {
return advisoryFailure(request, cognitive.FinishInvalidProviderResponse), nil
}
return response, nil
}
func (a *OllamaAdapter) request(ctx context.Context, method, path string, input, output any) (int, error) {
var body io.Reader
if input != nil {
encoded, err := json.Marshal(input)
if err != nil {
return 0, err
}
body = bytes.NewReader(encoded)
}
target := *a.base
target.Path = path
request, err := http.NewRequestWithContext(ctx, method, target.String(), body)
if err != nil {
return 0, err
}
request.Header.Set("Accept", "application/json")
if input != nil {
request.Header.Set("Content-Type", "application/json")
}
response, err := a.client.Do(request)
if err != nil {
return 0, err
}
defer response.Body.Close()
if response.StatusCode != http.StatusOK {
_, _ = io.Copy(io.Discard, io.LimitReader(response.Body, 4096))
return response.StatusCode, nil
}
decoder := json.NewDecoder(io.LimitReader(response.Body, 2<<20))
if err := decoder.Decode(output); err != nil {
return response.StatusCode, err
}
return response.StatusCode, nil
}
+28 -12
View File
@@ -13,19 +13,16 @@ import (
"time"
"unicode/utf8"
"git.cin.su/m/Assistant/contracts/capability"
"git.cin.su/m/Assistant/contracts/cognitive"
)
const (
OpenAIAdvisoryBindingID capability.CapabilityBindingID = "openai-responses-gpt-5.4-mini-2026-03-17"
OpenAIAdvisoryBindingRevision int64 = 1
openAIResponsesURL = "https://api.openai.com/v1/responses"
openAIModel = "gpt-5.4-mini-2026-03-17"
openAIMaxOutputTokens = 4096
openAIResponseLimitBytes = 1 << 20
openAITimeout = 30 * time.Second
openAIInstructions = "Provide non-canonical advisory text only. State uncertainty when appropriate. Never claim that an action occurred, never request or expose secrets, and never emit tool or executable instructions."
openAIResponsesURL = "https://api.openai.com/v1/responses"
openAIModel = "gpt-5.4-mini-2026-03-17"
openAIMaxOutputTokens = 4096
openAIResponseLimitBytes = 1 << 20
openAITimeout = 30 * time.Second
openAIInstructions = "Provide non-canonical advisory text only. State uncertainty when appropriate. Never claim that an action occurred, never request or expose secrets, and never emit tool or executable instructions."
)
type OpenAIAdvisoryAdapter struct {
@@ -124,8 +121,8 @@ func (a *OpenAIAdvisoryAdapter) Advise(ctx context.Context, request cognitive.Ad
if err := ValidateAdvisoryRequest(request); err != nil {
return cognitive.AdvisoryResponse{}, err
}
if request.ProviderBindingID != OpenAIAdvisoryBindingID || request.ProviderBindingRevision != OpenAIAdvisoryBindingRevision || len(request.Context) != 0 {
return cognitive.AdvisoryResponse{}, fmt.Errorf("%w: OpenAI Mode A binding", ErrInvalidAdvisory)
if request.ProviderInstanceID == "" || request.ModelDescriptorID == "" || string(request.ProviderModelID) != openAIModel || len(request.Context) != 0 {
return cognitive.AdvisoryResponse{}, fmt.Errorf("%w: incompatible registry binding", ErrInvalidAdvisory)
}
payload, err := json.Marshal(openAIRequest{
Model: openAIModel,
@@ -159,7 +156,7 @@ func (a *OpenAIAdvisoryAdapter) Advise(ctx context.Context, request cognitive.Ad
}
defer httpResponse.Body.Close()
if httpResponse.StatusCode != http.StatusOK {
return advisoryFailure(request, cognitive.FinishProviderUnavailable), nil
return advisoryFailure(request, mapOpenAIStatus(httpResponse.StatusCode)), nil
}
if contentType := httpResponse.Header.Get("Content-Type"); contentType != "" && !strings.HasPrefix(strings.ToLower(contentType), "application/json") {
return advisoryFailure(request, cognitive.FinishInvalidProviderResponse), nil
@@ -204,6 +201,25 @@ func (a *OpenAIAdvisoryAdapter) Advise(ctx context.Context, request cognitive.Ad
return response, nil
}
func mapOpenAIStatus(status int) cognitive.FinishReason {
switch status {
case http.StatusUnauthorized, http.StatusForbidden:
return cognitive.FinishAuthenticationFailed
case http.StatusPaymentRequired:
return cognitive.FinishBillingOrBudgetBlocked
case http.StatusNotFound:
return cognitive.FinishModelUnavailable
case http.StatusRequestEntityTooLarge:
return cognitive.FinishContextTooLarge
case http.StatusTooManyRequests:
return cognitive.FinishRateLimited
case http.StatusRequestTimeout, http.StatusGatewayTimeout:
return cognitive.FinishTimeout
default:
return cognitive.FinishProviderUnavailable
}
}
func extractOpenAIText(output []json.RawMessage) (string, bool, bool) {
var text string
refused := false
+12 -2
View File
@@ -10,6 +10,7 @@ import (
"testing"
"git.cin.su/m/Assistant/contracts/authority"
"git.cin.su/m/Assistant/contracts/capability"
"git.cin.su/m/Assistant/contracts/cognitive"
"git.cin.su/m/Assistant/contracts/identity"
)
@@ -28,8 +29,11 @@ func validOpenAIAdvisoryRequest() cognitive.AdvisoryRequest {
Message: "What should I verify?",
Locale: "en",
MaxOutputBytes: MaxAdvisoryResponseBytes,
ProviderBindingID: OpenAIAdvisoryBindingID,
ProviderBindingRevision: OpenAIAdvisoryBindingRevision,
ProviderBindingID: "binding-under-test",
ProviderBindingRevision: 7,
ProviderInstanceID: capability.ProviderInstanceID("provider-under-test"),
ModelDescriptorID: capability.ModelDescriptorID("model-under-test"),
ProviderModelID: capability.ProviderModelID(openAIModel),
}
}
@@ -41,6 +45,12 @@ func providerHTTPResponse(status int, body string) *http.Response {
}
}
func TestOpenAIStatusTaxonomyPreservesRateLimit(t *testing.T) {
if got := mapOpenAIStatus(http.StatusTooManyRequests); got != cognitive.FinishRateLimited {
t.Fatalf("status 429 mapped to %s", got)
}
}
func validOpenAIResponse(text string) string {
body, _ := json.Marshal(map[string]any{
"status": "completed",
+194
View File
@@ -0,0 +1,194 @@
package models
import (
"bytes"
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"net"
"net/http"
"net/url"
"strings"
"time"
"git.cin.su/m/Assistant/contracts/capability"
"git.cin.su/m/Assistant/contracts/cognitive"
)
type OpenAICompatibleLocalAdapter struct {
base *url.URL
client *http.Client
}
func NewOpenAICompatibleLocalAdapter(raw string, transport http.RoundTripper) (*OpenAICompatibleLocalAdapter, error) {
base, err := url.Parse(raw)
if err != nil || base.Scheme != "http" || base.Host == "" || strings.TrimSuffix(base.Path, "/") != "/v1" || base.RawQuery != "" || base.Fragment != "" || base.User != nil {
return nil, errors.New("invalid local compatible endpoint")
}
if transport == nil {
transport = http.DefaultTransport
}
return &OpenAICompatibleLocalAdapter{base: base, client: &http.Client{Transport: transport, Timeout: 10 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}}, nil
}
type compatibleModelsResponse struct {
Data []struct {
ID string `json:"id"`
Created int64 `json:"created"`
OwnedBy string `json:"owned_by"`
Meta struct {
Context int64 `json:"n_ctx"`
TrainingContext int64 `json:"n_ctx_train"`
Parameters int64 `json:"n_params"`
Size int64 `json:"size"`
FileType string `json:"ftype"`
} `json:"meta"`
} `json:"data"`
}
func (a *OpenAICompatibleLocalAdapter) Probe(ctx context.Context) ProviderProbe {
_, probe := a.Discover(ctx)
return probe
}
func (a *OpenAICompatibleLocalAdapter) Discover(ctx context.Context) ([]DiscoveredModel, ProviderProbe) {
var response compatibleModelsResponse
status, err := a.requestJSON(ctx, http.MethodGet, "/models", nil, &response)
if err != nil {
return nil, probeFailure(err)
}
if status != http.StatusOK {
return nil, ProviderProbe{Health: capability.HealthUnavailable, Failure: mapCompatibleStatus(status)}
}
models := make([]DiscoveredModel, 0, len(response.Data))
for _, item := range response.Data {
if item.ID == "" {
continue
}
canonical, _ := json.Marshal(item)
digest := sha256.Sum256(canonical)
contextBytes := item.Meta.Context * 4
models = append(models, DiscoveredModel{ProviderModelID: capability.ProviderModelID(item.ID), Fingerprint: capability.ModelFingerprint(hex.EncodeToString(digest[:])), MaxContextBytes: contextBytes, Modalities: []capability.ModelModality{capability.ModalityText}, Capabilities: []capability.ModelCapability{capability.CapabilityUnknown}, SizeBytes: item.Meta.Size, Runtime: item.OwnedBy, Quantization: item.Meta.FileType})
}
return models, ProviderProbe{Health: capability.HealthAvailable}
}
type compatibleChatRequest struct {
Model string `json:"model"`
Messages []compatibleMessage `json:"messages"`
Temperature int `json:"temperature"`
Stream bool `json:"stream"`
MaxTokens int `json:"max_tokens"`
}
type compatibleMessage struct {
Role string `json:"role"`
Content string `json:"content"`
}
type compatibleChatResponse struct {
Choices []struct {
FinishReason string `json:"finish_reason"`
Message compatibleMessage `json:"message"`
} `json:"choices"`
Usage struct {
Prompt int64 `json:"prompt_tokens"`
Completion int64 `json:"completion_tokens"`
} `json:"usage"`
}
func (a *OpenAICompatibleLocalAdapter) Advise(ctx context.Context, request cognitive.AdvisoryRequest) (cognitive.AdvisoryResponse, error) {
if err := ValidateAdvisoryRequest(request); err != nil || request.ProviderModelID == "" || len(request.Context) != 0 {
return cognitive.AdvisoryResponse{}, ErrInvalidAdvisory
}
payload := compatibleChatRequest{Model: string(request.ProviderModelID), Messages: []compatibleMessage{{Role: "system", Content: "Provide non-canonical advisory text only. Never claim that an action occurred."}, {Role: "user", Content: request.Message}}, Temperature: 0, Stream: false, MaxTokens: request.MaxOutputBytes / 4}
var result compatibleChatResponse
status, err := a.requestJSON(ctx, http.MethodPost, "/chat/completions", payload, &result)
if err != nil {
return advisoryFailure(request, probeFailure(err).Failure), nil
}
if status != http.StatusOK {
return advisoryFailure(request, mapCompatibleStatus(status)), nil
}
if len(result.Choices) != 1 || result.Choices[0].Message.Content == "" {
return advisoryFailure(request, cognitive.FinishInvalidProviderResponse), nil
}
finish := cognitive.FinishCompleted
if result.Choices[0].FinishReason == "length" {
finish = cognitive.FinishLengthLimit
}
if finish != cognitive.FinishCompleted {
return advisoryFailure(request, finish), nil
}
response := cognitive.AdvisoryResponse{Version: request.Version, RequestID: request.RequestID, ProviderBindingID: request.ProviderBindingID, ProviderBindingRevision: request.ProviderBindingRevision, AdvisoryText: result.Choices[0].Message.Content, FinishReason: finish, Usage: &cognitive.ProviderUsage{InputUnits: result.Usage.Prompt, OutputUnits: result.Usage.Completion}}
if ValidateAdvisoryResponse(request, response) != nil {
return advisoryFailure(request, cognitive.FinishInvalidProviderResponse), nil
}
return response, nil
}
func (a *OpenAICompatibleLocalAdapter) requestJSON(ctx context.Context, method, path string, input, output any) (int, error) {
var body io.Reader
if input != nil {
encoded, err := json.Marshal(input)
if err != nil {
return 0, err
}
body = bytes.NewReader(encoded)
}
target := *a.base
target.Path = strings.TrimSuffix(a.base.Path, "/") + path
request, err := http.NewRequestWithContext(ctx, method, target.String(), body)
if err != nil {
return 0, err
}
request.Header.Set("Accept", "application/json")
if input != nil {
request.Header.Set("Content-Type", "application/json")
}
response, err := a.client.Do(request)
if err != nil {
return 0, err
}
defer response.Body.Close()
if response.StatusCode != http.StatusOK {
_, _ = io.Copy(io.Discard, io.LimitReader(response.Body, 4096))
return response.StatusCode, nil
}
decoder := json.NewDecoder(io.LimitReader(response.Body, 2<<20))
if err := decoder.Decode(output); err != nil {
return response.StatusCode, fmt.Errorf("decode provider response: %w", err)
}
return response.StatusCode, nil
}
func probeFailure(err error) ProviderProbe {
finish := cognitive.FinishProviderUnavailable
if errors.Is(err, context.DeadlineExceeded) {
finish = cognitive.FinishTimeout
}
var network net.Error
if errors.As(err, &network) && network.Timeout() {
finish = cognitive.FinishTimeout
}
return ProviderProbe{Health: capability.HealthUnavailable, Failure: finish}
}
func mapCompatibleStatus(status int) cognitive.FinishReason {
switch status {
case 401, 403:
return cognitive.FinishAuthenticationFailed
case 404:
return cognitive.FinishModelUnavailable
case 408, 504:
return cognitive.FinishTimeout
case 413:
return cognitive.FinishContextTooLarge
case 429:
return cognitive.FinishRateLimited
default:
return cognitive.FinishProviderUnavailable
}
}