Documentation
¶
Overview ¶
Package knowledge provides system knowledge indexing functionality. This file implements SystemKnowledgeIndexer for managing built-in knowledge about Agent capabilities, Golang best practices, and architecture principles.
Package knowledge provides document storage and vector-based semantic search.
Store manages documents with embedding vectors using PostgreSQL + pgvector. It supports metadata filtering and similarity search for conversation history and document retrieval.
Index ¶
- type Document
- type KnowledgeQuerier
- type Result
- type SearchOption
- type Store
- func (s *Store) Add(ctx context.Context, doc Document) error
- func (s *Store) Close() error
- func (s *Store) Count(ctx context.Context, filter map[string]string) (int, error)
- func (s *Store) Delete(ctx context.Context, docID string) error
- func (s *Store) ListBySourceType(ctx context.Context, sourceType string, limit int32) ([]Document, error)
- func (s *Store) Search(ctx context.Context, query string, opts ...SearchOption) ([]Result, error)
- type SystemKnowledgeIndexer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Document ¶
type Document struct {
ID string // Unique identifier
Content string // Document text content
Metadata map[string]string // Optional metadata (source, type, etc.)
CreateAt time.Time // Creation timestamp
}
Document represents a knowledge document. It contains the textual content and optional metadata. Metadata must be map[string]string to comply with chromem-go requirements.
type KnowledgeQuerier ¶
type KnowledgeQuerier interface {
// UpsertDocument inserts or updates a document
UpsertDocument(ctx context.Context, arg sqlc.UpsertDocumentParams) error
// SearchDocuments performs filtered vector search
SearchDocuments(ctx context.Context, arg sqlc.SearchDocumentsParams) ([]sqlc.SearchDocumentsRow, error)
// SearchDocumentsAll performs unfiltered vector search
SearchDocumentsAll(ctx context.Context, arg sqlc.SearchDocumentsAllParams) ([]sqlc.SearchDocumentsAllRow, error)
// CountDocuments counts documents matching filter
CountDocuments(ctx context.Context, filterMetadata []byte) (int64, error)
// CountDocumentsAll counts all documents
CountDocumentsAll(ctx context.Context) (int64, error)
// DeleteDocument deletes a document by ID
DeleteDocument(ctx context.Context, id string) error
// ListDocumentsBySourceType lists documents by source type
ListDocumentsBySourceType(ctx context.Context, arg sqlc.ListDocumentsBySourceTypeParams) ([]sqlc.ListDocumentsBySourceTypeRow, error)
}
KnowledgeQuerier defines the interface for database operations on knowledge documents. Following Go best practices: interfaces are defined by the consumer, not the provider (similar to http.RoundTripper, sql.Driver, io.Reader).
This interface allows Store to depend on abstraction rather than concrete implementation, improving testability and flexibility.
type SearchOption ¶
type SearchOption func(*searchConfig)
SearchOption configures search behavior using the functional options pattern. This follows Go best practices as seen in context.WithTimeout, grpc.Dial, etc.
func WithFilter ¶
func WithFilter(key, value string) SearchOption
WithFilter adds a metadata filter to restrict search results. Multiple calls to WithFilter add additional filters (AND logic). Example: WithFilter("source_type", "conversation")
func WithTopK ¶
func WithTopK(k int32) SearchOption
WithTopK sets the maximum number of results to return. Default is 5 if not specified. If k < 1, it will be clamped to 1 to ensure valid search configuration.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store manages knowledge documents with vector search capabilities. It handles embedding generation and vector similarity search using PostgreSQL + pgvector.
Store is safe for concurrent use by multiple goroutines.
func New ¶
New creates a new Store instance
Parameters:
- dbPool: PostgreSQL connection pool (pgxpool)
- embedder: AI embedder for generating vector embeddings
- logger: Logger for debugging (nil = use default)
Example:
store := knowledge.New(dbPool, embedder, slog.Default())
Design: Accepts dbPool and converts to KnowledgeQuerier interface internally. For testing, use NewWithQuerier to inject mock querier directly.
func NewWithQuerier ¶
NewWithQuerier creates a new Store instance with custom querier (useful for testing).
Parameters:
- querier: Database querier implementing KnowledgeQuerier interface
- embedder: AI embedder for generating vector embeddings
- logger: Logger for debugging (nil = use default)
Design: Accepts KnowledgeQuerier interface following "Accept interfaces, return structs" principle for better testability.
func (*Store) Add ¶
Add adds a document to the knowledge store. The document's content is automatically embedded using the configured embedder. Uses UPSERT (ON CONFLICT DO UPDATE) to handle both inserts and updates.
func (*Store) Count ¶
Count returns the number of documents matching the given filter. If filter is nil or empty, it returns the total count of all documents.
Parameters:
- ctx: Context for the operation
- filter: Metadata filter (e.g., map[string]string{"source_type": "conversation"})
Returns:
- int: Number of documents matching the filter
- error: If count fails
func (*Store) Delete ¶
Delete removes a document from the knowledge store.
Parameters:
- ctx: Context for the operation
- docID: Document ID to delete
Returns:
- error: If deletion fails
func (*Store) ListBySourceType ¶
func (s *Store) ListBySourceType(ctx context.Context, sourceType string, limit int32) ([]Document, error)
ListBySourceType lists all documents by source type without similarity calculation. This is useful for listing indexed files without needing embeddings.
Parameters:
- ctx: Context for the operation
- sourceType: Source type to filter by (e.g., "file", "conversation")
- limit: Maximum number of documents to return
Returns:
- []Document: List of documents ordered by creation time (newest first)
- error: If listing fails
func (*Store) Search ¶
Search performs semantic search on the knowledge store using functional options. It returns the most similar documents to the query, ordered by similarity score. Automatically applies 10-second timeout for vector search queries to prevent blocking.
Example usage:
results, err := store.Search(ctx, "AI safety",
knowledge.WithTopK(10),
knowledge.WithFilter("source_type", "conversation"))
type SystemKnowledgeIndexer ¶
type SystemKnowledgeIndexer struct {
// contains filtered or unexported fields
}
SystemKnowledgeIndexer manages indexing of system knowledge documents. It provides pre-defined knowledge about Agent capabilities, coding standards, and architectural principles.
Thread-safe: safe for concurrent use (protected by mu).
func NewSystemKnowledgeIndexer ¶
func NewSystemKnowledgeIndexer(store *Store, logger *slog.Logger) *SystemKnowledgeIndexer
NewSystemKnowledgeIndexer creates a new system knowledge indexer.
func (*SystemKnowledgeIndexer) ClearAll ¶
func (s *SystemKnowledgeIndexer) ClearAll(ctx context.Context) error
ClearAll removes all system knowledge documents. Useful for testing and manual reindexing. Thread-safe (uses mutex).
func (*SystemKnowledgeIndexer) IndexAll ¶
func (s *SystemKnowledgeIndexer) IndexAll(ctx context.Context) (int, error)
IndexAll indexes all default system knowledge documents. This method is called during application startup.
Features:
- Uses fixed document IDs (e.g., "system:golang-errors")
- UPSERT behavior (updates if already exists)
- Returns count of successfully indexed documents
- Thread-safe (uses mutex)
Returns: (indexedCount, error) Error: returns error if ALL documents failed to index
Source Files