knowledge

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 1, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package knowledge defines golem's portable knowledge-base facade.

The facade deliberately uses Eino's schema.Document and retriever.Retriever types. A vector database, an embedding model, and document extraction are implementation details of an optional module; the agent only needs scoped indexing, enumeration, deletion, moving, and search.

Index

Constants

View Source 
const (
	MetadataOwner      = "golem.owner"
	MetadataGroup      = "golem.group"
	MetadataTenant     = "golem.tenant"
	MetadataDocID      = "golem.doc_id"
	MetadataTitle      = "golem.title"
	MetadataSource     = "golem.source"
	MetadataCreatedAt  = "golem.created_at"
	MetadataChunk      = "golem.chunk"
	MetadataChunkCount = "golem.chunk_count"
)

Metadata keys are stable across Eino vector-store implementations.

View Source 
const (
	ToolNameListKnowledge        = "ListKnowledgeBase"
	ToolNameIndexKnowledge       = "IndexKnowledge"
	ToolNameSearchKnowledge      = "SearchKnowledge"
	ToolNameMoveKnowledge        = "UpdateKnowledgeScope"
	ToolNameDeleteKnowledge      = "DeleteKnowledge"
	ToolNameListOwnerKnowledge   = "ListOwnerKnowledgeBase"
	ToolNameSearchOwnerKnowledge = "SearchOwnerKnowledge"
)

Variables

This section is empty.

Functions

func ContextText 

func ContextText(documents []*schema.Document, maxChars int) string

ContextText renders retrieved passages as clearly delimited reference material. Content is data supplied by a knowledge author, not an instruction, so the boundary is part of the facade rather than left to every model integration.

func DocumentOwnedBy 

func DocumentOwnedBy(scope Scope, docID string) func(Metadata) bool

DocumentOwnedBy returns the exact write-replacement predicate. All three fields, including blanks, must match; using ReadableBy here could replace a shared document when a caller merely has read access to it.

func DocumentReadableBy 

func DocumentReadableBy(scope Scope, docID string) func(Metadata) bool

DocumentReadableBy returns the read predicate for one document id.

func FirstChunk 

func FirstChunk(metadata Metadata) bool

FirstChunk returns whether a chunk is the document representative used for document-level listing.

func MetadataFor 

func MetadataFor(scope Scope, docID, title, source string, createdAt time.Time, chunk, chunkCount int) map[string]any

MetadataFor builds the canonical metadata map for one chunk.

func NewRetriever 

func NewRetriever(base KnowledgeBase, scope Scope, topK int, filter func(Metadata) bool) retriever.Retriever

NewRetriever returns an Eino retriever restricted to scope.

func ReadableBy 

func ReadableBy(scope Scope) func(Metadata) bool

ReadableBy returns the security predicate for a read. Blank request identities are omitted, avoiding the blank-as-wildcard vulnerability.

func ScopeForMetadata 

func ScopeForMetadata(values map[string]any) (Scope, Target)

ScopeForMetadata returns the exact owning scope and target of a chunk.

func WritableBy 

func WritableBy(scope Scope) func(Metadata) bool

WritableBy returns the document-level write predicate. A request may write its own personal scope and the group/tenant scopes it explicitly carries; read access alone is not enough to delete or move somebody else's document.

Types

type AdminTools 

type AdminTools struct {
	IsAdmin func(context.Context) bool
	// contains filtered or unexported fields
}

AdminTools is the explicit read-only escape hatch for unattended owners that nobody logs into. The authorization function is supplied by the embedding application; core never guesses who an administrator is.

func NewAdminTools 

func NewAdminTools(base KnowledgeBase, isAdmin func(context.Context) bool) *AdminTools

NewAdminTools constructs administrator-only knowledge listing/search tools.

func (*AdminTools) List 

func (t *AdminTools) List() []tool.InvokableTool

List implements tools.Builtin.

type Entry 

type Entry struct {
	DocID      string    `json:"docId"`
	Title      string    `json:"title"`
	Location   string    `json:"location,omitempty"`
	ChunkCount int       `json:"chunkCount"`
	CreatedAt  time.Time `json:"createdAt"`
	Target     Target    `json:"target"`
}

Entry is one indexed document, not one chunk.

type FilteredKnowledgeBase 

type FilteredKnowledgeBase interface {
	KnowledgeBase
	SearchFiltered(ctx context.Context, scope Scope, query string, topK int, filter func(Metadata) bool) ([]*schema.Document, error)
}

FilteredKnowledgeBase is an optional extension for implementations that can apply metadata filters before ranking. It keeps fixed document allow-lists complete when a backend's top-K search would otherwise discard an allowed document before the facade can filter it.

type KnowledgeBase 

type KnowledgeBase interface {
	Index(ctx context.Context, source Source) (string, error)
	List(ctx context.Context, scope Scope, offset, limit int) (Page, error)
	Delete(ctx context.Context, scope Scope, docID string) error
	Move(ctx context.Context, scope Scope, docID string, target Target) (Entry, bool, error)
	Search(ctx context.Context, scope Scope, query string, topK int) ([]*schema.Document, error)
}

KnowledgeBase is the facade implemented by optional knowledge modules.

type KnowledgeRetrieval 

type KnowledgeRetrieval struct {
	Scope  Scope
	Query  string
	TopK   int
	Filter func(Metadata) bool
}

KnowledgeRetrieval describes an explicit lookup, useful for unattended runs such as event triage that must not derive scope from untrusted input.

type Metadata 

type Metadata struct {
	Owner      string    `json:"owner,omitempty"`
	Group      string    `json:"group,omitempty"`
	Tenant     string    `json:"tenant,omitempty"`
	DocID      string    `json:"docId,omitempty"`
	Title      string    `json:"title,omitempty"`
	Source     string    `json:"source,omitempty"`
	CreatedAt  time.Time `json:"createdAt,omitempty"`
	Chunk      int       `json:"chunk,omitempty"`
	ChunkCount int       `json:"chunkCount,omitempty"`
}

Metadata is the portable, typed view of knowledge chunk metadata.

func ReadMetadata 

func ReadMetadata(values map[string]any) Metadata

ReadMetadata converts Eino metadata into the domain view. It accepts the common JSON number forms as well as native ints because vector backends often deserialize metadata before returning it.

type Page 

type Page struct {
	Entries []Entry `json:"entries"`
	HasMore bool    `json:"hasMore"`
}

Page is a document listing page. HasMore avoids an expensive count query.

type RetrievalConfig 

type RetrievalConfig struct {
	TopK     int
	MaxChars int
}

RetrievalConfig controls automatic retrieval attached to agent runs.

type Scope 

type Scope struct {
	Owner  string
	Group  string
	Tenant string
}

Scope is the identity a knowledge document can be owned by and the identities a request may read. Blank group and tenant values mean that the corresponding scope does not exist; they never mean "any".

func NewScope 

func NewScope(owner, group, tenant string) Scope

NewScope normalizes identity values at a boundary.

func (Scope) HasGroup 

func (s Scope) HasGroup() bool

HasGroup reports whether this scope names a group.

func (Scope) HasTenant 

func (s Scope) HasTenant() bool

HasTenant reports whether this scope names a tenant.

func (Scope) Owning 

func (s Scope) Owning(target Target) Scope

Owning returns the exact metadata scope used when a document is written to target. Exactly one identity is set; the other fields are blank.

func (Scope) Reachable 

func (s Scope) Reachable(target Target) bool

Reachable reports whether the caller has the identity needed to write to a target. Refusing an unreachable target prevents a successful-looking write that nobody can ever read back.

type ScopedRetriever 

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

ScopedRetriever adapts a KnowledgeBase to Eino's retriever contract. A backend remains free to use its own filter DSL; the facade's scope is still applied by the base implementation before documents leave it.

func (*ScopedRetriever) Retrieve 

func (r *ScopedRetriever) Retrieve(ctx context.Context, query string, opts ...retriever.Option) ([]*schema.Document, error)

Retrieve implements retriever.Retriever.

type Source 

type Source struct {
	Scope     Scope
	Target    Target
	Title     string
	Text      string
	Location  string
	DocID     string
	CreatedAt time.Time
}

Source is content to index and its durable identity. DocID is required so indexing the same source replaces it instead of accumulating contradictory copies.

func NewPathSource 

func NewPathSource(scope Scope, target Target, title, location, docID string) Source

NewPathSource constructs a source whose content is read from Location by the knowledge implementation.

func NewTextSource 

func NewTextSource(scope Scope, target Target, title, text, location, docID string) Source

NewTextSource constructs a source whose content is already available.

func (Source) Validate 

func (s Source) Validate() error

Validate checks the invariants that all implementations need.

type Target 

type Target string

Target is the knowledge base a document belongs to. 

const (
	TargetOwn    Target = "own"
	TargetGroup  Target = "group"
	TargetTenant Target = "tenant"
)

func ParseTarget 

func ParseTarget(value string) (Target, bool)

ParseTarget parses the model-facing spelling of a target. "company" is accepted as a useful synonym for tenant, matching the Spring facade.

func TargetOrOwn 

func TargetOrOwn(value string) Target

TargetOrOwn returns the requested target, defaulting an omitted value to the caller's own knowledge base. Call ParseTarget when a typo must be rejected rather than treated as a default.

type Tools 

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

Tools exposes intentional knowledge operations. Automatic retrieval belongs to the agent option; these tools are for writing, inspecting, and repairing a knowledge base when the model needs explicit control.

func NewTools 

func NewTools(base KnowledgeBase, home storage.Home, options ...ToolsOption) *Tools

NewTools constructs the knowledge tool family. A nil home is allowed for text indexing; path-based indexing is refused without a containment boundary. Remote fetching is intentionally outside this facade so a model cannot turn indexing into an SSRF primitive.

func (*Tools) List 

func (t *Tools) List() []tool.InvokableTool

List implements tools.Builtin.

type ToolsOption 

type ToolsOption func(*Tools)

ToolsOption configures model-facing knowledge tools.

func WithPageSize 

func WithPageSize(size int) ToolsOption

WithPageSize sets the default listing page size, capped at 100.

func WithTopK 

func WithTopK(topK int) ToolsOption

WithTopK sets the default explicit search size.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.