librarian

Documentation

Index

• type AnalysisOutput
• type GraphCallback
• type Inquiry
• type InquiryProcessor
  • func NewInquiryProcessor(generator TextGenerator, inquiryStore *InquiryStore, ...) *InquiryProcessor
  • func (p *InquiryProcessor) ProcessAnswers(ctx context.Context, sessionKey string, messages []session.Message) error
• type InquiryStore
  • func NewInquiryStore(client *ent.Client, logger *zap.SugaredLogger) *InquiryStore
  • func (s *InquiryStore) CountPendingBySession(ctx context.Context, sessionKey string) (int, error)
  • func (s *InquiryStore) DismissInquiry(ctx context.Context, id uuid.UUID) error
  • func (s *InquiryStore) ListPendingInquiries(ctx context.Context, sessionKey string, limit int) ([]Inquiry, error)
  • func (s *InquiryStore) ResolveInquiry(ctx context.Context, id uuid.UUID, answer, knowledgeKey string) error
  • func (s *InquiryStore) SaveInquiry(ctx context.Context, inq Inquiry) error
• type KnowledgeGap
• type MessageProvider
• type ObservationAnalyzer
  • func NewObservationAnalyzer(generator TextGenerator, logger *zap.SugaredLogger) *ObservationAnalyzer
  • func (a *ObservationAnalyzer) Analyze(ctx context.Context, observations []memory.Observation) (*AnalysisOutput, error)
• type ObservationKnowledge
• type ObservationProvider
• type ProactiveBuffer
  • func NewProactiveBuffer(analyzer *ObservationAnalyzer, processor *InquiryProcessor, ...) *ProactiveBuffer
  • func (b *ProactiveBuffer) SetGraphCallback(cb GraphCallback)
  • func (b *ProactiveBuffer) Start(wg *sync.WaitGroup)
  • func (b *ProactiveBuffer) Stop()
  • func (b *ProactiveBuffer) Trigger(sessionKey string)
• type ProactiveBufferConfig
• type TextGenerator
• type Triple

Types

type AnalysisOutput

type AnalysisOutput struct {
	Extractions []ObservationKnowledge `json:"extractions"`
	Gaps        []KnowledgeGap         `json:"gaps"`
}

AnalysisOutput is the combined result from observation analysis.

type GraphCallback

type GraphCallback = types.TripleCallback

GraphCallback is an optional hook for saving graph triples.

type Inquiry

type Inquiry struct {
	ID                  uuid.UUID
	SessionKey          string
	Topic               string
	Question            string
	Context             string
	Priority            string // low, medium, high
	Status              string // pending, resolved, dismissed
	Answer              string
	KnowledgeKey        string
	SourceObservationID string
	CreatedAt           time.Time
	ResolvedAt          *time.Time
}

Inquiry represents a pending question to ask the user.

type InquiryProcessor

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

InquiryProcessor detects user answers to pending inquiries and saves knowledge.

func NewInquiryProcessor

func NewInquiryProcessor(
	generator TextGenerator,
	inquiryStore *InquiryStore,
	knowledgeStore *knowledge.Store,
	logger *zap.SugaredLogger,
) *InquiryProcessor

NewInquiryProcessor creates a new inquiry processor.

func (*InquiryProcessor) ProcessAnswers

func (p *InquiryProcessor) ProcessAnswers(ctx context.Context, sessionKey string, messages []session.Message) error

ProcessAnswers checks recent messages against pending inquiries for answer matches.

type InquiryStore

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

InquiryStore provides CRUD operations for knowledge inquiries.

func NewInquiryStore

func NewInquiryStore(client *ent.Client, logger *zap.SugaredLogger) *InquiryStore

NewInquiryStore creates a new inquiry store.

func (*InquiryStore) CountPendingBySession

func (s *InquiryStore) CountPendingBySession(ctx context.Context, sessionKey string) (int, error)

CountPendingBySession returns the number of pending inquiries for a session.

func (*InquiryStore) DismissInquiry

func (s *InquiryStore) DismissInquiry(ctx context.Context, id uuid.UUID) error

DismissInquiry marks an inquiry as dismissed.

func (*InquiryStore) ListPendingInquiries

func (s *InquiryStore) ListPendingInquiries(ctx context.Context, sessionKey string, limit int) ([]Inquiry, error)

ListPendingInquiries returns pending inquiries for a session, ordered by priority and creation time.

func (*InquiryStore) ResolveInquiry

func (s *InquiryStore) ResolveInquiry(ctx context.Context, id uuid.UUID, answer, knowledgeKey string) error

ResolveInquiry marks an inquiry as resolved with the user's answer and optional knowledge key.

func (*InquiryStore) SaveInquiry

func (s *InquiryStore) SaveInquiry(ctx context.Context, inq Inquiry) error

SaveInquiry persists a new inquiry to the database.

type KnowledgeGap

type KnowledgeGap struct {
	Topic       string   `json:"topic"`
	Question    string   `json:"question"`
	Context     string   `json:"context,omitempty"`
	Priority    string   `json:"priority"` // low, medium, high
	RelatedKeys []string `json:"relatedKeys,omitempty"`
}

KnowledgeGap represents a detected gap in knowledge that requires user clarification.

type MessageProvider

type MessageProvider func(sessionKey string) ([]session.Message, error)

MessageProvider retrieves messages for a session key.

type ObservationAnalyzer

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

ObservationAnalyzer uses LLM to analyze observations and extract knowledge/gaps.

func NewObservationAnalyzer

func NewObservationAnalyzer(generator TextGenerator, logger *zap.SugaredLogger) *ObservationAnalyzer

NewObservationAnalyzer creates a new observation analyzer.

func (*ObservationAnalyzer) Analyze

func (a *ObservationAnalyzer) Analyze(ctx context.Context, observations []memory.Observation) (*AnalysisOutput, error)

Analyze processes observations through LLM to extract knowledge and detect gaps.

type ObservationKnowledge

type ObservationKnowledge struct {
	Type       string           `json:"type"`       // preference, fact, rule, definition
	Category   string           `json:"category"`   // domain-specific category
	Content    string           `json:"content"`    // extracted knowledge content
	Confidence types.Confidence `json:"confidence"` // high, medium, low
	Key        string           `json:"key"`        // unique identifier for storage

	// Graph triple fields (optional).
	Subject   string `json:"subject,omitempty"`
	Predicate string `json:"predicate,omitempty"`
	Object    string `json:"object,omitempty"`
}

ObservationKnowledge represents knowledge extracted from conversation observations.

type ObservationProvider

type ObservationProvider func(ctx context.Context, sessionKey string) ([]memory.Observation, error)

ObservationProvider retrieves recent observations for a session key.

type ProactiveBuffer

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

ProactiveBuffer manages the async proactive librarian pipeline.

func NewProactiveBuffer

func NewProactiveBuffer(
	analyzer *ObservationAnalyzer,
	processor *InquiryProcessor,
	inquiryStore *InquiryStore,
	knowledgeStore *knowledge.Store,
	getMessages MessageProvider,
	getObservations ObservationProvider,
	cfg ProactiveBufferConfig,
	logger *zap.SugaredLogger,
) *ProactiveBuffer

NewProactiveBuffer creates a new proactive librarian buffer.

func (*ProactiveBuffer) SetGraphCallback

func (b *ProactiveBuffer) SetGraphCallback(cb GraphCallback)

SetGraphCallback sets the optional graph triple callback.

func (*ProactiveBuffer) Start

func (b *ProactiveBuffer) Start(wg *sync.WaitGroup)

Start launches the background processing goroutine.

func (*ProactiveBuffer) Stop

func (b *ProactiveBuffer) Stop()

Stop signals the background goroutine to drain and exit.

func (*ProactiveBuffer) Trigger

func (b *ProactiveBuffer) Trigger(sessionKey string)

Trigger enqueues a session for proactive analysis.

type ProactiveBufferConfig

type ProactiveBufferConfig struct {
	ObservationThreshold int
	CooldownTurns        int
	MaxPending           int
	AutoSaveConfidence   types.Confidence
}

ProactiveBufferConfig holds configuration for the proactive buffer.

type TextGenerator

type TextGenerator interface {
	GenerateText(ctx context.Context, systemPrompt, userPrompt string) (string, error)
}

TextGenerator abstracts LLM text generation for the librarian package.

type Triple

type Triple = types.Triple

Triple mirrors graph.Triple to avoid import cycles.