Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

17.3 KB
Raw Blame
// Package client provides the implementation for interacting with the WeKnora API
// The Agent management interfaces are used to manage custom agents (CRUD operations)
package client

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"strconv"
	"strings"
	"time"
)

// Agent represents an agent entity
type Agent struct {
	ID          string       `json:"id"`
	Name        string       `json:"name"`
	Description string       `json:"description"`
	Avatar      string       `json:"avatar"`
	IsBuiltin   bool         `json:"is_builtin"`
	TenantID    uint64       `json:"tenant_id"`
	CreatedBy   string       `json:"created_by"`
	Config      *AgentConfig `json:"config"`
	CreatedAt   time.Time    `json:"created_at"`
	UpdatedAt   time.Time    `json:"updated_at"`
	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.
// An empty ReasoningEffort retains the legacy Thinking boolean semantics.
type AgentConfig struct {
	AgentMode                   string                    `json:"agent_mode"`
	AgentType                   string                    `json:"agent_type,omitempty"`
	SystemPrompt                string                    `json:"system_prompt"`
	SystemPromptID              string                    `json:"system_prompt_id,omitempty"`
	ContextTemplate             string                    `json:"context_template"`
	ContextTemplateID           string                    `json:"context_template_id,omitempty"`
	ModelID                     string                    `json:"model_id"`
	RerankModelID               string                    `json:"rerank_model_id"`
	Temperature                 float64                   `json:"temperature"`
	MaxCompletionTokens         int                       `json:"max_completion_tokens"`
	Thinking                    *bool                     `json:"thinking"`
	ReasoningEffort             string                    `json:"reasoning_effort,omitempty"`
	CitationEnabled             *bool                     `json:"citation_enabled"`
	MaxIterations               int                       `json:"max_iterations"` // -1 = unlimited
	LLMCallTimeout              int                       `json:"llm_call_timeout,omitempty"`
	AllowedTools                []string                  `json:"allowed_tools"`
	MCPSelectionMode            string                    `json:"mcp_selection_mode"`
	MCPServices                 []string                  `json:"mcp_services"`
	SkillsSelectionMode         string                    `json:"skills_selection_mode"`
	SelectedSkills              []string                  `json:"selected_skills"`
	KBSelectionMode             string                    `json:"kb_selection_mode"`
	KnowledgeBases              []string                  `json:"knowledge_bases"`
	RetrieveKBOnlyWhenMentioned bool                      `json:"retrieve_kb_only_when_mentioned"`
	RetainRetrievalHistory      bool                      `json:"retain_retrieval_history"`
	ImageUploadEnabled          bool                      `json:"image_upload_enabled"`
	VLMModelID                  string                    `json:"vlm_model_id"`
	AudioUploadEnabled          bool                      `json:"audio_upload_enabled"`
	ASRModelID                  string                    `json:"asr_model_id"`
	ImageStorageProvider        string                    `json:"image_storage_provider"`
	SupportedFileTypes          []string                  `json:"supported_file_types"`
	DataAnalysisEnabled         bool                      `json:"data_analysis_enabled"`
	FAQPriorityEnabled          bool                      `json:"faq_priority_enabled"`
	FAQDirectAnswerThreshold    float64                   `json:"faq_direct_answer_threshold"`
	FAQScoreBoost               float64                   `json:"faq_score_boost"`
	WebSearchEnabled            bool                      `json:"web_search_enabled"`
	WebSearchMaxResults         int                       `json:"web_search_max_results"`
	WebSearchProviderID         string                    `json:"web_search_provider_id,omitempty"`
	WebFetchEnabled             bool                      `json:"web_fetch_enabled"`
	WebFetchTopN                int                       `json:"web_fetch_top_n,omitempty"`
	MultiTurnEnabled            bool                      `json:"multi_turn_enabled"`
	HistoryTurns                int                       `json:"history_turns"`
	EmbeddingTopK               int                       `json:"embedding_top_k"`
	KeywordThreshold            float64                   `json:"keyword_threshold"`
	VectorThreshold             float64                   `json:"vector_threshold"`
	RerankTopK                  int                       `json:"rerank_top_k"`
	RerankThreshold             float64                   `json:"rerank_threshold"`
	EnableQueryExpansion        bool                      `json:"enable_query_expansion"`
	EnableRewrite               bool                      `json:"enable_rewrite"`
	RewritePromptSystem         string                    `json:"rewrite_prompt_system"`
	RewritePromptUser           string                    `json:"rewrite_prompt_user"`
	QueryUnderstandModelID      string                    `json:"query_understand_model_id,omitempty"`
	FallbackStrategy            string                    `json:"fallback_strategy"`
	FallbackResponse            string                    `json:"fallback_response"`
	FallbackPrompt              string                    `json:"fallback_prompt"`
	QuestionSuggestions         *QuestionSuggestionConfig `json:"question_suggestions,omitempty"`
}

type QuestionSuggestionConfig struct {
	Starters  StarterSuggestionConfig  `json:"starters"`
	FollowUps FollowUpSuggestionConfig `json:"follow_ups"`
}

type StarterSuggestionConfig struct {
	Enabled bool     `json:"enabled"`
	Mode    string   `json:"mode"`
	Items   []string `json:"items"`
	Count   int      `json:"count"`
}

type FollowUpSuggestionConfig struct {
	Enabled                        bool     `json:"enabled"`
	Mode                           string   `json:"mode"`
	Count                          int      `json:"count"`
	ModelID                        string   `json:"model_id,omitempty"`
	AdditionalInstruction          string   `json:"additional_instruction,omitempty"`
	Categories                     []string `json:"categories,omitempty"`
	MaxContextTurns                int      `json:"max_context_turns"`
	SuppressOnFallback             bool     `json:"suppress_on_fallback"`
	SuppressWhenAnswerAsksQuestion bool     `json:"suppress_when_answer_asks_question"`
	KnowledgeFallback              bool     `json:"knowledge_fallback"`
	AllowRegenerate                bool     `json:"allow_regenerate"`
}

// CreateAgentRequest represents the request to create an agent.
// JSON field names mirror internal/handler.CreateAgentRequest.
type CreateAgentRequest struct {
	Name        string       `json:"name"`
	Description string       `json:"description"`
	Avatar      string       `json:"avatar"`
	Config      *AgentConfig `json:"config"`
}

// UpdateAgentRequest represents the request to update an agent.
// JSON field names mirror internal/handler.UpdateAgentRequest.
type UpdateAgentRequest struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	// Avatar is omitted when nil to preserve the stored value. A pointer to
	// an empty string explicitly clears the avatar.
	Avatar *string      `json:"avatar,omitempty"`
	Config *AgentConfig `json:"config"`
}

// PatchAgentRequest changes only the fields that are set; the rest of the
// agent is kept. JSON field names mirror internal/handler.PatchAgentRequest.
type PatchAgentRequest struct {
	Name        *string `json:"name,omitempty"`
	Description *string `json:"description,omitempty"`
	// AgentMode is "quick-answer" or "smart-reasoning". MCP and skills only
	// run in smart-reasoning, and switching to it turns multi-turn on.
	AgentMode    *string `json:"agent_mode,omitempty"`
	SystemPrompt *string `json:"system_prompt,omitempty"`
	ModelID      *string `json:"model_id,omitempty"`
	// KBSelectionMode is "all", "selected" or "none".
	KBSelectionMode *string `json:"kb_selection_mode,omitempty"`
	// KnowledgeBases replaces the selected knowledge bases; without
	// KBSelectionMode it also switches the mode to "selected".
	KnowledgeBases *[]string `json:"knowledge_bases,omitempty"`
	// MCPSelectionMode is "all", "selected" or "none".
	MCPSelectionMode *string `json:"mcp_selection_mode,omitempty"`
	// MCPServices replaces the selected MCP services; without
	// MCPSelectionMode it also switches the mode to "selected".
	MCPServices *[]string `json:"mcp_services,omitempty"`
	// SkillsSelectionMode is "all", "selected" or "none"; all/none clears SelectedSkills.
	SkillsSelectionMode *string `json:"skills_selection_mode,omitempty"`
	// SelectedSkills replaces the selected skill names; without
	// SkillsSelectionMode it also switches the mode to "selected".
	SelectedSkills   *[]string `json:"selected_skills,omitempty"`
	WebSearchEnabled *bool     `json:"web_search_enabled,omitempty"`
	MultiTurnEnabled *bool     `json:"multi_turn_enabled,omitempty"`
}

// AgentResponse represents the API response containing a single agent
type AgentResponse struct {
	Success bool  `json:"success"`
	Data    Agent `json:"data"`
}

// AgentListResponse represents the API response containing a list of agents
type AgentListResponse struct {
	Success bool    `json:"success"`
	Data    []Agent `json:"data"`
}

// AgentPlaceholdersResponse represents the API response for placeholder definitions
type AgentPlaceholdersResponse struct {
	Success bool                       `json:"success"`
	Data    map[string]json.RawMessage `json:"data"`
}

// CreateAgent creates a new custom agent
func (c *Client) CreateAgent(ctx context.Context, request *CreateAgentRequest) (*Agent, error) {
	resp, err := c.doRequest(ctx, http.MethodPost, "/api/v1/agents", request, nil)
	if err != nil {
		return nil, err
	}

	var response AgentResponse
	if err := parseResponse(resp, &response); err != nil {
		return nil, err
	}

	return &response.Data, nil
}

// ListAgents retrieves all agents for the current tenant
func (c *Client) ListAgents(ctx context.Context) ([]Agent, error) {
	resp, err := c.doRequest(ctx, http.MethodGet, "/api/v1/agents", nil, nil)
	if err != nil {
		return nil, err
	}

	var response AgentListResponse
	if err := parseResponse(resp, &response); err != nil {
		return nil, err
	}

	return response.Data, nil
}

// GetAgent retrieves an agent by its ID
func (c *Client) GetAgent(ctx context.Context, agentID string) (*Agent, error) {
	path := fmt.Sprintf("/api/v1/agents/%s", agentID)
	resp, err := c.doRequest(ctx, http.MethodGet, path, nil, nil)
	if err != nil {
		return nil, err
	}

	var response AgentResponse
	if err := parseResponse(resp, &response); err != nil {
		return nil, err
	}

	return &response.Data, nil
}

// UpdateAgent updates an existing agent
func (c *Client) UpdateAgent(ctx context.Context, agentID string, request *UpdateAgentRequest) (*Agent, error) {
	path := fmt.Sprintf("/api/v1/agents/%s", agentID)
	resp, err := c.doRequest(ctx, http.MethodPut, path, request, nil)
	if err != nil {
		return nil, err
	}

	var response AgentResponse
	if err := parseResponse(resp, &response); err != nil {
		return nil, err
	}

	return &response.Data, nil
}

// PatchAgent changes only the fields set in request, keeping the rest of the
// agent, unlike UpdateAgent, which replaces the whole config.
func (c *Client) PatchAgent(ctx context.Context, agentID string, request *PatchAgentRequest) (*Agent, error) {
	path := fmt.Sprintf("/api/v1/agents/%s", agentID)
	resp, err := c.doRequest(ctx, http.MethodPatch, path, request, nil)
	if err != nil {
		return nil, err
	}

	var response AgentResponse
	if err := parseResponse(resp, &response); err != nil {
		return nil, err
	}

	return &response.Data, nil
}

// DeleteAgent deletes a custom agent by its ID
func (c *Client) DeleteAgent(ctx context.Context, agentID string) error {
	path := fmt.Sprintf("/api/v1/agents/%s", agentID)
	resp, err := c.doRequest(ctx, http.MethodDelete, path, nil, nil)
	if err != nil {
		return err
	}

	var response struct {
		Success bool   `json:"success"`
		Message string `json:"message,omitempty"`
	}

	return parseResponse(resp, &response)
}

// CopyAgent creates a copy of an existing agent
func (c *Client) CopyAgent(ctx context.Context, agentID string) (*Agent, error) {
	path := fmt.Sprintf("/api/v1/agents/%s/copy", agentID)
	resp, err := c.doRequest(ctx, http.MethodPost, path, nil, nil)
	if err != nil {
		return nil, err
	}

	var response AgentResponse
	if err := parseResponse(resp, &response); err != nil {
		return nil, err
	}

	return &response.Data, nil
}

// GetAgentPlaceholders retrieves all available prompt placeholder definitions
func (c *Client) GetAgentPlaceholders(ctx context.Context) (map[string]json.RawMessage, error) {
	resp, err := c.doRequest(ctx, http.MethodGet, "/api/v1/agents/placeholders", nil, nil)
	if err != nil {
		return nil, err
	}

	var response AgentPlaceholdersResponse
	if err := parseResponse(resp, &response); err != nil {
		return nil, err
	}

	return response.Data, nil
}

// SuggestedQuestion represents a suggested question for an agent
type SuggestedQuestion struct {
	Question        string `json:"question"`                    // Question text
	Source          string `json:"source"`                      // Source: "faq", "document", or "agent_config"
	KnowledgeBaseID string `json:"knowledge_base_id,omitempty"` // Source knowledge base ID
	KnowledgeID     string `json:"knowledge_id,omitempty"`      // Source document ID (faq/document sources)
}

// SuggestedQuestionsRequest represents the options for getting suggested questions
type SuggestedQuestionsRequest struct {
	KnowledgeBaseIDs []string                    // Optional: override agent's KB scope
	KnowledgeIDs     []string                    // Optional: limit to specific knowledge items
	TagScopes        []SuggestedQuestionTagScope // Optional: limit to tags within their parent KBs
	Limit            int                         // Optional: max questions to return (default 6)
}

// SuggestedQuestionTagScope preserves the KB-local identity of tag IDs.
type SuggestedQuestionTagScope struct {
	KnowledgeBaseID string   `json:"knowledge_base_id"`
	TagIDs          []string `json:"tag_ids"`
}

// SuggestedQuestionsResponse represents the API response for suggested questions
type SuggestedQuestionsResponse struct {
	Success bool `json:"success"`
	Data    struct {
		Questions []SuggestedQuestion `json:"questions"`
	} `json:"data"`
}

// GetSuggestedQuestions retrieves suggested questions for the given agent,
// based on its associated knowledge bases. The returned questions can be
// displayed as quick-start prompts in the chat UI.
//
// When request is nil, uses the agent's default knowledge base configuration.
func (c *Client) GetSuggestedQuestions(ctx context.Context, agentID string, request *SuggestedQuestionsRequest) ([]SuggestedQuestion, error) {
	path := fmt.Sprintf("/api/v1/agents/%s/suggested-questions", agentID)

	query := url.Values{}
	if request != nil {
		if len(request.KnowledgeBaseIDs) > 0 {
			query.Set("knowledge_base_ids", strings.Join(request.KnowledgeBaseIDs, ","))
		}
		if len(request.KnowledgeIDs) > 0 {
			query.Set("knowledge_ids", strings.Join(request.KnowledgeIDs, ","))
		}
		if len(request.TagScopes) > 0 {
			encoded, err := json.Marshal(request.TagScopes)
			if err != nil {
				return nil, fmt.Errorf("marshal tag scopes: %w", err)
			}
			query.Set("tag_scopes", string(encoded))
		}
		if request.Limit > 0 {
			query.Set("limit", strconv.Itoa(request.Limit))
		}
	}

	resp, err := c.doRequest(ctx, http.MethodGet, path, nil, query)
	if err != nil {
		return nil, err
	}

	var response SuggestedQuestionsResponse
	if err := parseResponse(resp, &response); err != nil {
		return nil, err
	}

	return response.Data.Questions, nil
}