* fix(auth): record last-active-tenant preference on SwitchTenant * docs(auth): note SwitchTenant updating last-active-tenant preference * fix(auth): persist last-active tenant before SwitchTenant tokens RefreshToken re-resolves from this preference because refresh JWTs omit tenant_id. Fail the switch if the write fails so a 200 never returns a token pair whose later refresh would land in a different workspace. * fix(cli): align HybridSearch interfaces with SDK variadic options Client.HybridSearch gained ResourceURLOptions; CLI ChunksService and MCP knowledgeService still used the old signature, so *Client no longer satisfied those interfaces. * style(cli): wrap HybridSearch signatures under the 120-column lint --------- Co-authored-by: wizardchen <wizardchen@tencent.com> |
||
|---|---|---|
| .. | ||
| README.md | ||
| README_EN.md | ||
| agent.go | ||
| agent_manage.go | ||
| auth.go | ||
| chunk.go | ||
| client.go | ||
| env_var.go | ||
| evaluation.go | ||
| example.go | ||
| faq.go | ||
| go.mod | ||
| go.sum | ||
| initialization.go | ||
| knowledge.go | ||
| knowledgebase.go | ||
| knowledgebase_duplicate_test.go | ||
| log.go | ||
| log_test.go | ||
| mcp_service.go | ||
| message.go | ||
| message_suggestion.go | ||
| model.go | ||
| organization.go | ||
| resource_urls.go | ||
| resource_urls_test.go | ||
| session.go | ||
| skill.go | ||
| stream_errors.go | ||
| stream_errors_test.go | ||
| streaming_test.go | ||
| system.go | ||
| tag.go | ||
| tenant.go | ||
| web_search.go | ||
README_EN.md
WeKnora HTTP Client
This package provides a client library for interacting with WeKnora services, supporting all HTTP-based interface calls, making it easier for other modules to integrate with WeKnora services without having to write HTTP request code directly.
Main Features
The client includes the following main functional modules:
- Session Management: Create, retrieve, update, and delete sessions
- Knowledge Base Management: Create, retrieve, update, and delete knowledge bases
- Knowledge Management: Add, retrieve, and delete knowledge content
- Workspace Management: CRUD operations for workspaces
- Knowledge Q&A: Supports regular Q&A and streaming Q&A
- Chunk Management: Query, update, and delete knowledge chunks
- Message Management: Retrieve and delete session messages
- Model Management: Create, retrieve, update, and delete models
- Evaluation Function: Start evaluation tasks and get evaluation results
- Sandbox skills: Install a skill onto a sandbox config (zip upload, or ClawHub / SkillHub / GitHub source) and configure the environment variables it needs
- Auth: Login, refresh tokens, and switch the active workspace (
SwitchTenantrecords the last-active-tenant preference)
Usage
Creating Client Instance
import (
"context"
"github.com/Tencent/WeKnora/client"
"time"
)
// Create client instance
apiClient := client.NewClient(
"http://api.example.com",
client.WithToken("your-auth-token"),
client.WithTimeout(30*time.Second),
)
Workspace Configuration
You can set a default workspace with WithTenantID; the client will automatically send the X-Tenant-ID header:
tenantID := uint64(10000)
apiClient := client.NewClient(
"http://api.example.com",
client.WithToken("your-auth-token"),
client.WithTenantID(tenantID),
)
If a single request needs a different workspace, set TenantID in the request context. The value can be a uint64, *uint64, or a numeric string, and it will take precedence over the client default:
ctx := context.WithValue(context.Background(), "TenantID", uint64(10000))
// Pass ctx into any client method to switch to workspace 10000 for that request
Example: Create Knowledge Base and Upload File
// Create knowledge base
kb := &client.KnowledgeBase{
Name: "Test Knowledge Base",
Description: "This is a test knowledge base",
ChunkingConfig: client.ChunkingConfig{
ChunkSize: 500,
ChunkOverlap: 50,
Separators: []string{"\n\n", "\n", ". ", "? ", "! "},
},
ImageProcessingConfig: client.ImageProcessingConfig{
ModelID: "image_model_id",
},
EmbeddingModelID: "embedding_model_id",
SummaryModelID: "summary_model_id",
}
kb, err := apiClient.CreateKnowledgeBase(context.Background(), kb)
if err != nil {
// Handle error
}
// Upload knowledge file with metadata
metadata := map[string]string{
"source": "local",
"type": "document",
}
knowledge, err := apiClient.CreateKnowledgeFromFile(context.Background(), kb.ID, "path/to/file.pdf", metadata)
if err != nil {
// Handle error
}
Example: Create Session and Chat
// Create session
sessionRequest := &client.CreateSessionRequest{
KnowledgeBaseID: knowledgeBaseID,
SessionStrategy: &client.SessionStrategy{
MaxRounds: 10,
EnableRewrite: true,
FallbackStrategy: "fixed_answer",
FallbackResponse: "Sorry, I cannot answer this question",
EmbeddingTopK: 5,
KeywordThreshold: 0.5,
VectorThreshold: 0.7,
RerankModelID: "rerank_model_id",
RerankTopK: 3,
RerankThreshold: 0.8,
SummaryModelID: "summary_model_id",
},
}
session, err := apiClient.CreateSession(context.Background(), sessionRequest)
if err != nil {
// Handle error
}
// Regular Q&A
answer, err := apiClient.KnowledgeQA(context.Background(), session.ID, &client.KnowledgeQARequest{
Query: "What is artificial intelligence?",
})
if err != nil {
// Handle error
}
// Streaming Q&A
err = apiClient.KnowledgeQAStream(context.Background(), session.ID, "What is machine learning?", func(response *client.StreamResponse) error {
// Handle each response chunk
fmt.Print(response.Content)
return nil
})
if err != nil {
// Handle error
}
Example: Managing Models
// Create model
modelRequest := &client.CreateModelRequest{
Name: "Test Model",
Type: client.ModelTypeChat,
Source: client.ModelSourceInternal,
Description: "This is a test model",
Parameters: client.ModelParameters{
"temperature": 0.7,
"top_p": 0.9,
},
IsDefault: true,
}
model, err := apiClient.CreateModel(context.Background(), modelRequest)
if err != nil {
// Handle error
}
// List all models
models, err := apiClient.ListModels(context.Background())
if err != nil {
// Handle error
}
Example: Managing Knowledge Chunks
// List knowledge chunks
chunks, total, err := apiClient.ListKnowledgeChunks(context.Background(), knowledgeID, 1, 10)
if err != nil {
// Handle error
}
// Update chunk
updateRequest := &client.UpdateChunkRequest{
Content: "Updated chunk content",
IsEnabled: true,
}
updatedChunk, err := apiClient.UpdateChunk(context.Background(), knowledgeID, chunkID, updateRequest)
if err != nil {
// Handle error
}
Example: Getting Session Messages
// Get recent messages
messages, err := apiClient.GetRecentMessages(context.Background(), sessionID, 10)
if err != nil {
// Handle error
}
// Get messages before a specific time
beforeTime := time.Now().Add(-24 * time.Hour)
olderMessages, err := apiClient.GetMessagesBefore(context.Background(), sessionID, beforeTime, 10)
if err != nil {
// Handle error
}
Example: Install a sandbox skill from a registry
source must be explicit: @owner/slug for ClawHub, or a full GitHub / SkillHub URL. Bare owner/slug is rejected.
skillID, err := apiClient.InstallSandboxSkillFromSource(
context.Background(), sandboxConfigID, "@owner/slug")
if err != nil {
// Handle error
}
_ = skillID // follow /sandbox-configs/{id}/skills/{skillID}/install-events
Example: Retry a failed install
Installs usually fail for reasons the bundle cannot fix — an unreachable sandbox, a package index that timed out. The server still holds the archive, so the retry needs nothing from you.
skillID, err := apiClient.ReinstallSandboxSkill(context.Background(), sandboxConfigID, skillID)
if err != nil {
// Handle error
}
Example: Browse files of an installed skill
files, err := apiClient.ListSandboxSkillFiles(context.Background(), sandboxConfigID, skillID)
if err != nil {
// Handle error
}
content, err := apiClient.GetSandboxSkillFile(context.Background(), sandboxConfigID, skillID, "SKILL.md")
if err != nil {
// Handle error
}
_ = files
_ = content
Example: Configure a skill's environment variables
A skill declares the environment variables it needs when it is installed. Values live in two layers: a workspace value an admin sets for everybody, and a per-identity value that overrides it for the caller alone. No endpoint reads a stored value back; they only report whether one is set.
An API key and a web login are different identities: a personal value entered through the web UI does not apply to runs driven by an API key. Prefer workspace values for integrations.
// Workspace-wide, applies to everybody; requires Admin or above
skill, err := apiClient.SetSandboxSkillEnvValues(
context.Background(), sandboxConfigID, skillID,
map[string]string{"TAVILY_API_KEY": "tvly-xxxxx"})
if err != nil {
// Handle error
}
// Applies to the calling identity alone
err = apiClient.SetMySkillEnvVar(
context.Background(), skillID, "TAVILY_API_KEY", "tvly-yyyyy")
if err != nil {
// Handle error
}
// See what is still unset. Clearing a value is a delete, not a write of ""
groups, err := apiClient.ListMyEnvVars(context.Background())
if err != nil {
// Handle error
}
_ = skill
_ = groups
Complete Example
Please refer to the ExampleUsage function in the example.go file, which demonstrates the complete usage flow of the client.