feat(sdk): typed errors, enums, and KB model config for the CLI
Adds the client-library surface the agent-first CLI builds on: - named server error-code constants + typed *APIError from non-2xx responses, - MessageSearchMode / AgentMode / KBSelectionMode and model type/source enumerators so the CLI validates flags against the server vocabulary, - SetKBModelConfig for binding embedding/chat models to a knowledge base.
This commit is contained in:
+1
-1
@@ -94,7 +94,7 @@ func (c *Client) AgentQAStreamWithRequest(ctx context.Context,
|
||||
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
body, _ := io.ReadAll(resp.Body)
|
||||
return fmt.Errorf("HTTP error %d: %s", resp.StatusCode, string(body))
|
||||
return newAPIError(resp.StatusCode, body)
|
||||
}
|
||||
|
||||
// Process SSE stream
|
||||
|
||||
@@ -28,6 +28,46 @@ type Agent struct {
|
||||
CreatorName string `json:"creator_name,omitempty"`
|
||||
}
|
||||
|
||||
// AgentMode is an agent's operating mode (AgentConfig.AgentMode). It mirrors
|
||||
// the server constants in internal/types/custom_agent.go.
|
||||
type AgentMode string
|
||||
|
||||
const (
|
||||
// AgentModeQuickAnswer is the RAG mode for quick Q&A.
|
||||
AgentModeQuickAnswer AgentMode = "quick-answer"
|
||||
// AgentModeSmartReasoning is the ReAct mode for multi-step reasoning.
|
||||
AgentModeSmartReasoning AgentMode = "smart-reasoning"
|
||||
)
|
||||
|
||||
// AllAgentModes returns every agent operating mode the server recognises, in a
|
||||
// stable order. Use this instead of re-typing the set so callers can't drift
|
||||
// from the SDK.
|
||||
func AllAgentModes() []AgentMode {
|
||||
return []AgentMode{AgentModeQuickAnswer, AgentModeSmartReasoning}
|
||||
}
|
||||
|
||||
// KBSelectionMode controls how an agent selects knowledge bases
|
||||
// (AgentConfig.KBSelectionMode). It mirrors the server's documented values
|
||||
// ("all" | "selected" | "none") in internal/types/custom_agent.go.
|
||||
type KBSelectionMode string
|
||||
|
||||
const (
|
||||
// KBSelectionModeAll retrieves across every knowledge base.
|
||||
KBSelectionModeAll KBSelectionMode = "all"
|
||||
// KBSelectionModeSelected retrieves only the agent's attached KBs
|
||||
// (AgentConfig.KnowledgeBases).
|
||||
KBSelectionModeSelected KBSelectionMode = "selected"
|
||||
// KBSelectionModeNone disables knowledge base retrieval.
|
||||
KBSelectionModeNone KBSelectionMode = "none"
|
||||
)
|
||||
|
||||
// AllKBSelectionModes returns every KB selection mode the server recognises, in
|
||||
// a stable order. Use this instead of re-typing the set so callers can't drift
|
||||
// from the SDK.
|
||||
func AllKBSelectionModes() []KBSelectionMode {
|
||||
return []KBSelectionMode{KBSelectionModeAll, KBSelectionModeSelected, KBSelectionModeNone}
|
||||
}
|
||||
|
||||
// AgentConfig represents the configuration for an agent.
|
||||
// Field names and JSON tags mirror internal/types.CustomAgentConfig.
|
||||
type AgentConfig struct {
|
||||
|
||||
+57
-1
@@ -225,13 +225,69 @@ func (c *Client) Raw(ctx context.Context, method, path string, body interface{})
|
||||
return c.doRequest(ctx, method, path, body, nil)
|
||||
}
|
||||
|
||||
// APIError is a typed non-2xx HTTP response from the WeKnora API. Recover it
|
||||
// with errors.As to branch on the HTTP status or the server's structured error
|
||||
// code without parsing the Error() string:
|
||||
//
|
||||
// var apiErr *client.APIError
|
||||
// if errors.As(err, &apiErr) && apiErr.StatusCode == 404 { ... }
|
||||
//
|
||||
// Error() intentionally preserves the legacy "HTTP error <status>: <body>"
|
||||
// format so existing string-matching consumers keep working unchanged.
|
||||
type APIError struct {
|
||||
StatusCode int // HTTP status (401, 404, 409, 429, 500, …)
|
||||
Body string // raw response body
|
||||
Code int // server's structured error code ({"code":N}); 0 when absent/non-JSON
|
||||
}
|
||||
|
||||
func (e *APIError) Error() string {
|
||||
return fmt.Sprintf("HTTP error %d: %s", e.StatusCode, e.Body)
|
||||
}
|
||||
|
||||
// Server error codes are the values of the {"code":N} field in an error
|
||||
// response body, surfaced as APIError.Code. These mirror the generic codes in
|
||||
// the server's internal/errors/errors.go so consumers branch on a named
|
||||
// constant instead of a magic number. Domain-specific codes (2xxx+) are
|
||||
// omitted until a consumer needs to branch on one.
|
||||
const (
|
||||
ServerErrBadRequest = 1000
|
||||
ServerErrUnauthorized = 1001
|
||||
ServerErrForbidden = 1002
|
||||
ServerErrNotFound = 1003
|
||||
ServerErrMethodNotAllowed = 1004
|
||||
ServerErrConflict = 1005
|
||||
ServerErrTooManyRequests = 1006
|
||||
ServerErrInternalServer = 1007
|
||||
ServerErrServiceUnavailable = 1008
|
||||
ServerErrTimeout = 1009
|
||||
ServerErrValidation = 1010
|
||||
)
|
||||
|
||||
// newAPIError builds an *APIError from a non-2xx response's status and raw body,
|
||||
// extracting the server's structured {"code":N} when the body is JSON.
|
||||
func newAPIError(status int, body []byte) *APIError {
|
||||
return &APIError{StatusCode: status, Body: string(body), Code: extractServerCode(body)}
|
||||
}
|
||||
|
||||
// extractServerCode pulls the server's structured error code from a JSON error
|
||||
// body ({"code":1003,...}). Returns 0 when the body isn't JSON or carries no code.
|
||||
func extractServerCode(body []byte) int {
|
||||
var env struct {
|
||||
Code int `json:"code"`
|
||||
}
|
||||
if json.Unmarshal(body, &env) == nil {
|
||||
return env.Code
|
||||
}
|
||||
return 0
|
||||
}
|
||||
|
||||
// parseResponse parses an HTTP response
|
||||
func parseResponse(resp *http.Response, target interface{}) error {
|
||||
defer resp.Body.Close()
|
||||
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
body, _ := io.ReadAll(resp.Body)
|
||||
return fmt.Errorf("HTTP error %d: %s", resp.StatusCode, string(body))
|
||||
return newAPIError(resp.StatusCode, body)
|
||||
}
|
||||
|
||||
if target == nil {
|
||||
|
||||
@@ -65,7 +65,11 @@ func (c *Client) InitializeByKB(ctx context.Context, kbID string, config *Initia
|
||||
return parseResponse(resp, nil)
|
||||
}
|
||||
|
||||
// UpdateKBConfig updates the model configuration for a knowledge base
|
||||
// UpdateKBConfig updates the model configuration for a knowledge base.
|
||||
//
|
||||
// Deprecated: the PUT /initialization/config endpoint binds KBModelConfigRequest
|
||||
// (fields llmModelId / embeddingModelId), not InitializationConfig, so this
|
||||
// method sends a shape the server rejects. Use SetKBModelConfig instead.
|
||||
func (c *Client) UpdateKBConfig(ctx context.Context, kbID string, config *InitializationConfig) error {
|
||||
resp, err := c.doRequest(ctx, http.MethodPut, fmt.Sprintf("/api/v1/initialization/config/%s", kbID), config, nil)
|
||||
if err != nil {
|
||||
@@ -74,6 +78,27 @@ func (c *Client) UpdateKBConfig(ctx context.Context, kbID string, config *Initia
|
||||
return parseResponse(resp, nil)
|
||||
}
|
||||
|
||||
// KBModelConfig points a knowledge base at already-registered models. Field
|
||||
// names match the server's KBModelConfigRequest (PUT
|
||||
// /initialization/config/:kbId). LLMModelID is required server-side;
|
||||
// EmbeddingModelID is optional (omitted when RAG indexing is disabled).
|
||||
type KBModelConfig struct {
|
||||
LLMModelID string `json:"llmModelId"`
|
||||
EmbeddingModelID string `json:"embeddingModelId,omitempty"`
|
||||
}
|
||||
|
||||
// SetKBModelConfig binds a knowledge base to already-registered models via PUT
|
||||
// /initialization/config/:kbId. Register models first with CreateModel; the
|
||||
// server rejects unknown model ids and refuses to change the embedding model of
|
||||
// a KB that already has documents.
|
||||
func (c *Client) SetKBModelConfig(ctx context.Context, kbID string, cfg *KBModelConfig) error {
|
||||
resp, err := c.doRequest(ctx, http.MethodPut, fmt.Sprintf("/api/v1/initialization/config/%s", kbID), cfg, nil)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return parseResponse(resp, nil)
|
||||
}
|
||||
|
||||
// CheckOllamaStatus checks if Ollama is running and accessible
|
||||
func (c *Client) CheckOllamaStatus(ctx context.Context) (bool, error) {
|
||||
resp, err := c.doRequest(ctx, http.MethodGet, "/api/v1/initialization/ollama/status", nil, nil)
|
||||
|
||||
+1
-1
@@ -441,7 +441,7 @@ func (c *Client) OpenKnowledgeFile(ctx context.Context, knowledgeID string) (str
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
body, _ := io.ReadAll(resp.Body)
|
||||
_ = resp.Body.Close()
|
||||
return "", nil, fmt.Errorf("HTTP error %d: %s", resp.StatusCode, string(body))
|
||||
return "", nil, newAPIError(resp.StatusCode, body)
|
||||
}
|
||||
filename := filenameFromContentDisposition(resp.Header.Get("Content-Disposition"))
|
||||
return filename, resp.Body, nil
|
||||
|
||||
@@ -212,3 +212,28 @@ func (c *Client) GetMCPServiceResources(ctx context.Context, serviceID string) (
|
||||
}
|
||||
return result.Data, nil
|
||||
}
|
||||
|
||||
// ResolveToolApprovalRequest is the body for resolving a pending tool-approval
|
||||
// raised during an agent run (session ask). Decision is "approve" or "reject".
|
||||
// ModifiedArgs optionally replaces the tool call arguments on approve; it must
|
||||
// be a JSON object when present.
|
||||
type ResolveToolApprovalRequest struct {
|
||||
Decision string `json:"decision"`
|
||||
Reason string `json:"reason,omitempty"`
|
||||
ModifiedArgs json.RawMessage `json:"modified_args,omitempty"`
|
||||
}
|
||||
|
||||
// ResolveToolApproval resolves a pending tool approval by id.
|
||||
// Server route: POST /api/v1/agent/tool-approvals/{pending_id}.
|
||||
func (c *Client) ResolveToolApproval(ctx context.Context, pendingID string, req *ResolveToolApprovalRequest) error {
|
||||
path := fmt.Sprintf("/api/v1/agent/tool-approvals/%s", pendingID)
|
||||
resp, err := c.doRequest(ctx, http.MethodPost, path, req, nil)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
var response struct {
|
||||
Success bool `json:"success"`
|
||||
Message string `json:"message,omitempty"`
|
||||
}
|
||||
return parseResponse(resp, &response)
|
||||
}
|
||||
|
||||
+26
-1
@@ -104,7 +104,32 @@ func (c *Client) GetMessagesBefore(
|
||||
return c.LoadMessages(ctx, sessionID, limit, &beforeTime)
|
||||
}
|
||||
|
||||
// SearchMessagesRequest defines the request structure for searching messages
|
||||
// MessageSearchMode is the search strategy for SearchMessages. It mirrors the
|
||||
// server enum in internal/types/message.go.
|
||||
type MessageSearchMode string
|
||||
|
||||
const (
|
||||
// MessageSearchModeKeyword searches by keyword only.
|
||||
MessageSearchModeKeyword MessageSearchMode = "keyword"
|
||||
// MessageSearchModeVector searches by vector similarity only.
|
||||
MessageSearchModeVector MessageSearchMode = "vector"
|
||||
// MessageSearchModeHybrid combines keyword and vector search (server default).
|
||||
MessageSearchModeHybrid MessageSearchMode = "hybrid"
|
||||
)
|
||||
|
||||
// AllMessageSearchModes returns every search mode the server recognises, in a
|
||||
// stable order. Callers (CLI flag validation, docs) should use this instead of
|
||||
// re-typing the set so they can't drift from the SDK.
|
||||
func AllMessageSearchModes() []MessageSearchMode {
|
||||
return []MessageSearchMode{
|
||||
MessageSearchModeKeyword, MessageSearchModeVector, MessageSearchModeHybrid,
|
||||
}
|
||||
}
|
||||
|
||||
// SearchMessagesRequest defines the request structure for searching messages.
|
||||
// Mode is a plain string mirroring the server's request DTO; pass a
|
||||
// MessageSearchMode constant cast to string, or leave empty for the server
|
||||
// default (hybrid).
|
||||
type SearchMessagesRequest struct {
|
||||
Query string `json:"query"`
|
||||
Mode string `json:"mode"`
|
||||
|
||||
@@ -21,6 +21,15 @@ const (
|
||||
ModelTypeASR ModelType = "ASR" // ASR (Automatic Speech Recognition) model
|
||||
)
|
||||
|
||||
// AllModelTypes returns every model type the server recognises, in a stable
|
||||
// order. Callers (CLI flag validation, docs) should use this instead of
|
||||
// re-typing the string set, so they can't drift from the SDK.
|
||||
func AllModelTypes() []ModelType {
|
||||
return []ModelType{
|
||||
ModelTypeEmbedding, ModelTypeRerank, ModelTypeKnowledgeQA, ModelTypeVLLM, ModelTypeASR,
|
||||
}
|
||||
}
|
||||
|
||||
// ModelSource represents the source of the model
|
||||
type ModelSource string
|
||||
|
||||
@@ -44,6 +53,21 @@ const (
|
||||
ModelSourceAzureOpenAI ModelSource = "azure_openai" // Azure OpenAI model
|
||||
)
|
||||
|
||||
// AllModelSources returns every model source the server recognises, in a stable
|
||||
// order. This is the broad set used for FILTERING existing records (model
|
||||
// list --source); creating a model only supports local/remote (the provider
|
||||
// identity goes in ModelParameters.provider). Use this instead of re-typing
|
||||
// the set so callers can't drift from the SDK.
|
||||
func AllModelSources() []ModelSource {
|
||||
return []ModelSource{
|
||||
ModelSourceLocal, ModelSourceRemote, ModelSourceAliyun, ModelSourceZhipu,
|
||||
ModelSourceVolcengine, ModelSourceDeepseek, ModelSourceHunyuan, ModelSourceMinimax,
|
||||
ModelSourceOpenAI, ModelSourceGemini, ModelSourceMimo, ModelSourceSiliconFlow,
|
||||
ModelSourceJina, ModelSourceOpenRouter, ModelSourceNvidia, ModelSourceNovita,
|
||||
ModelSourceAzureOpenAI,
|
||||
}
|
||||
}
|
||||
|
||||
// ModelParameters model parameters
|
||||
type ModelParameters map[string]interface{}
|
||||
|
||||
|
||||
+3
-3
@@ -281,7 +281,7 @@ func (c *Client) KnowledgeQAStream(
|
||||
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
body, _ := io.ReadAll(resp.Body)
|
||||
err := fmt.Errorf("HTTP error %d: %s", resp.StatusCode, string(body))
|
||||
err := newAPIError(resp.StatusCode, body)
|
||||
debugLogger.Debug("request_error_status", "error", err)
|
||||
return err
|
||||
}
|
||||
@@ -370,7 +370,7 @@ func (c *Client) ContinueStream(
|
||||
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
body, _ := io.ReadAll(resp.Body)
|
||||
return fmt.Errorf("HTTP error %d: %s", resp.StatusCode, string(body))
|
||||
return newAPIError(resp.StatusCode, body)
|
||||
}
|
||||
|
||||
// Use bufio to read SSE data line by line
|
||||
@@ -478,7 +478,7 @@ func (c *Client) SearchKnowledge(ctx context.Context, request *SearchKnowledgeRe
|
||||
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
body, _ := io.ReadAll(resp.Body)
|
||||
err := fmt.Errorf("HTTP error %d: %s", resp.StatusCode, string(body))
|
||||
err := newAPIError(resp.StatusCode, body)
|
||||
debugLogger.Debug("request_error_status", "error", err)
|
||||
return nil, err
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user