contextor

README

Contextor

Contextor 是一个以 Go 语言实现的先进"上下文工程"SDK，专为构建具备长期记忆、深度上下文理解能力和严格安全隔离的多租户 AI 应用而设计。

🚀 核心特性

• 三层知识图谱架构: 完整保留原始信息，构建语义网络
• 双时间轴时序管理: 区分"事件发生时间"和"信息获知时间"
• LLM 驱动的冲突解决: 智能处理新旧信息矛盾，保留完整变更历史
• 混合搜索策略: 结合向量搜索、全文搜索和图遍历的三步检索
• 原生多租户隔离: 内置用户级和会话级双重数据隔离
• 异步处理管道: 高性能的数据注入和知识提取

🏗️ 技术架构

• 语言: Go 1.24+
• 数据库: SurrealDB (图数据库 + 文档存储 + 向量搜索)
• 缓存: Redis (会话状态 + 异步任务队列)
• LLM 集成: 支持 OpenAI、Anthropic 等多种模型

📦 快速开始

安装

go get github.com/gonewx/contextor

基本用法

package main

import (
    "log"
    "github.com/gonewx/contextor"
)

func main() {
    // 初始化客户端
    client, err := contextor.NewClient(`{
        "surrealdb_url": "ws://localhost:8000",
        "redis_url": "redis://localhost:6379",
        "openai_api_key": "your-api-key"
    }`)
    if err != nil {
        log.Fatal(err)
    }

    // 创建会话
    session, err := client.Session.Start("tenant-123")
    if err != nil {
        log.Fatal(err)
    }

    // 注入数据
    err = client.Memory.Ingest(session.ID(), "项目截止日期是2025年12月31日")
    if err != nil {
        log.Fatal(err)
    }

    // 检索上下文
    results, err := client.Retriever.Search(session.ID(), "截止日期是什么时候？")
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("检索结果: %+v", results)
}

🔧 开发环境设置

前置要求

• Go 1.24+
• Docker & Docker Compose
• Make

启动开发环境

# 克隆项目
git clone https://github.com/gonewx/contextor.git
cd contextor

# 启动依赖服务
make dev-env

# 运行测试
make test

# 构建项目
make build

📚 文档

• 架构设计
• 快速入门指南
• 自定义 LLM 端点配置
• API 文档
• 架构决策记录

🤝 贡献

我们欢迎社区贡献！请查看 CONTRIBUTING.md 了解如何参与项目开发。

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

• 项目主页
• 问题反馈
• 讨论区

---

注意: 本项目目前处于开发阶段，API 可能会发生变化。建议在生产环境使用前等待 v1.0 正式版本。

Documentation

Overview

Package contextor provides a simple, user-friendly SDK for the Contextor knowledge management and context retrieval system.

This package serves as the main entry point for developers who want to integrate Contextor into their applications. It provides a clean, intuitive API that abstracts away the complexity of the internal services.

Basic usage:

client, err := contextor.NewClient(config)
if err != nil {
	log.Fatal(err)
}

// Ingest some data
result, err := client.Ingest("tenant-123", "session-456", "Important project deadline is December 31st, 2025")
if err != nil {
	log.Fatal(err)
}

// Search for relevant context
response, err := client.Search("tenant-123", "session-456", "What is the project deadline?")
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Context: %s\n", response.Context)

Index

• type Client
  • func NewClient(configInput interface{}) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) HealthCheck() error
  • func (c *Client) Ingest(tenantID, sessionID, text string) (*IngestResponse, error)
  • func (c *Client) IngestWithOptions(req *IngestRequest) (*IngestResponse, error)
  • func (c *Client) Search(tenantID, sessionID, query string) (*SearchResponse, error)
  • func (c *Client) SearchWithOptions(req *SearchRequest) (*SearchResponse, error)
  • func (c *Client) StartAsyncProcessing(ctx context.Context) error
• type ClientConfig
• type IngestRequest
• type IngestResponse
• type SearchRequest
• type SearchResponse

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the main entry point for the Contextor SDK. It provides simple methods for ingesting data and searching for context.

func NewClient

func NewClient(configInput interface{}) (*Client, error)

NewClient creates a new Contextor client with the given configuration. The config parameter can be either a JSON string or a ClientConfig struct.

func (*Client) Close

func (c *Client) Close() error

Close gracefully shuts down the client and releases resources

func (*Client) HealthCheck

func (c *Client) HealthCheck() error

HealthCheck performs a health check on all underlying services

func (*Client) Ingest

func (c *Client) Ingest(tenantID, sessionID, text string) (*IngestResponse, error)

Ingest adds new text data to the knowledge base for the specified tenant and session. This operation is asynchronous - the method returns immediately with a task ID, while the actual processing happens in the background.

func (*Client) IngestWithOptions

func (c *Client) IngestWithOptions(req *IngestRequest) (*IngestResponse, error)

IngestWithOptions provides more control over the ingestion process

func (*Client) Search

func (c *Client) Search(tenantID, sessionID, query string) (*SearchResponse, error)

Search retrieves relevant context for the given query within the specified tenant and session.

func (*Client) SearchWithOptions

func (c *Client) SearchWithOptions(req *SearchRequest) (*SearchResponse, error)

SearchWithOptions provides more control over the search process

func (*Client) StartAsyncProcessing

func (c *Client) StartAsyncProcessing(ctx context.Context) error

StartAsyncProcessing starts the asynchronous task processing workers This must be called to process ingestion tasks that have been queued

type ClientConfig

type ClientConfig struct {
	// Database configuration
	SurrealDBURL       string `json:"surrealdb_url"`
	SurrealDBUsername  string `json:"surrealdb_username,omitempty"`
	SurrealDBPassword  string `json:"surrealdb_password,omitempty"`
	SurrealDBNamespace string `json:"surrealdb_namespace,omitempty"`
	SurrealDBDatabase  string `json:"surrealdb_database,omitempty"`
	RedisURL           string `json:"redis_url"`
	RedisPassword      string `json:"redis_password,omitempty"`

	// LLM configuration
	OpenAIAPIKey              string `json:"openai_api_key,omitempty"`
	OpenAIBaseURL             string `json:"openai_base_url,omitempty"`
	OpenAIModel               string `json:"openai_model,omitempty"`
	OpenAIEmbeddingAPIKey     string `json:"openai_embedding_api_key,omitempty"`
	OpenAIEmbeddingModel      string `json:"openai_embedding_model,omitempty"`
	OpenAIEmbeddingBaseURL    string `json:"openai_embedding_base_url,omitempty"`
	OpenAIEmbeddingDimensions int    `json:"openai_embedding_dimensions,omitempty"`
	AnthropicAPIKey           string `json:"anthropic_api_key,omitempty"`
	AnthropicBaseURL          string `json:"anthropic_base_url,omitempty"`
	AnthropicModel            string `json:"anthropic_model,omitempty"`
	LLMProvider               string `json:"llm_provider,omitempty"` // "openai" or "anthropic"

	// Optional advanced settings
	MaxRetries     int    `json:"max_retries,omitempty"`
	TimeoutSeconds int    `json:"timeout_seconds,omitempty"`
	LogLevel       string `json:"log_level,omitempty"`

	// Search configuration
	SearchMaxResults          int     `json:"search_max_results,omitempty"`
	SearchSimilarityThreshold float64 `json:"search_similarity_threshold,omitempty"`
	SearchVectorWeight        float64 `json:"search_vector_weight,omitempty"`
	SearchBM25Weight          float64 `json:"search_bm25_weight,omitempty"`
	SearchGraphWeight         float64 `json:"search_graph_weight,omitempty"`

	// Context configuration
	ContextMaxTokens       int  `json:"context_max_tokens,omitempty"`
	ContextIncludeMetadata bool `json:"context_include_metadata,omitempty"`

	// Reranking configuration
	RerankingEnabled            bool    `json:"reranking_enabled,omitempty"`
	RerankingTopK               int     `json:"reranking_top_k,omitempty"`
	RerankingDiversityThreshold float64 `json:"reranking_diversity_threshold,omitempty"`
}

ClientConfig represents the configuration for creating a new client

type IngestRequest

type IngestRequest struct {
	TenantID  string                 `json:"tenant_id"`
	SessionID string                 `json:"session_id,omitempty"`
	Text      string                 `json:"text"`
	Source    string                 `json:"source,omitempty"`
	Metadata  map[string]interface{} `json:"metadata,omitempty"`
	Priority  int                    `json:"priority,omitempty"`
}

IngestRequest represents a request to ingest data

type IngestResponse

type IngestResponse struct {
	TaskID    string    `json:"task_id"`
	Status    string    `json:"status"`
	Message   string    `json:"message"`
	Timestamp time.Time `json:"timestamp"`
}

IngestResponse represents the response from an ingest operation

type SearchRequest

type SearchRequest struct {
	TenantID        string           `json:"tenant_id"`
	SessionID       string           `json:"session_id,omitempty"`
	Query           string           `json:"query"`
	MaxResults      int              `json:"max_results,omitempty"`
	IncludeMetadata bool             `json:"include_metadata,omitempty"`
	TimeRange       *types.TimeRange `json:"time_range,omitempty"`
	EntityTypes     []string         `json:"entity_types,omitempty"`
}

SearchRequest represents a request to search for context

type SearchResponse

type SearchResponse struct {
	Context      string                 `json:"context"`
	TokenCount   int                    `json:"token_count"`
	EpisodeCount int                    `json:"episode_count"`
	EntityCount  int                    `json:"entity_count"`
	Metadata     map[string]interface{} `json:"metadata,omitempty"`
}

SearchResponse represents the response from a search operation