knowledge

package
v0.16.2 Latest Latest
Warning

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

 Go to latest Published: Feb 11, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package knowledge provides a knowledge capture toolkit for the MCP data platform.

Index

Constants

View Source 
const (
	MinInsightTextLen   = 10
	MaxInsightTextLen   = 4000
	MaxEntityURNs       = 10
	MaxRelatedColumns   = 20
	MaxSuggestedActions = 5
	MaxApplyChanges     = 20
	MaxInsightIDs       = 50
)

Insight validation constraints.

View Source 
const (
	StatusPending    = "pending"
	StatusApproved   = "approved"
	StatusRejected   = "rejected"
	StatusApplied    = "applied"
	StatusSuperseded = "superseded"
	StatusRolledBack = "rolled_back"
)

Insight status constants.

View Source 
const DefaultLimit = 20

DefaultLimit is the default page size for list queries.

View Source 
const MaxLimit = 100

MaxLimit is the maximum page size for list queries.

Variables

This section is empty.

Functions

func NormalizeConfidence 

func NormalizeConfidence(c string) string

NormalizeConfidence returns the confidence value, defaulting to "medium" if empty.

func ValidateAction 

func ValidateAction(action string) error

ValidateAction checks whether an action value is valid.

func ValidateApplyChanges 

func ValidateApplyChanges(changes []ApplyChange) error

ValidateApplyChanges validates the changes slice for the apply action.

func ValidateCategory 

func ValidateCategory(c string) error

ValidateCategory checks whether a category value is valid.

func ValidateConfidence 

func ValidateConfidence(c string) error

ValidateConfidence checks whether a confidence value is valid. An empty string is valid and defaults to "medium".

func ValidateEntityURNs 

func ValidateEntityURNs(urns []string) error

ValidateEntityURNs validates the entity URN slice.

func ValidateInsightText 

func ValidateInsightText(text string) error

ValidateInsightText checks whether the insight text meets length requirements.

func ValidateRelatedColumns 

func ValidateRelatedColumns(cols []RelatedColumn) error

ValidateRelatedColumns validates the related columns slice.

func ValidateStatusTransition 

func ValidateStatusTransition(from, to string) error

ValidateStatusTransition checks whether a status transition is allowed.

func ValidateSuggestedActions 

func ValidateSuggestedActions(actions []SuggestedAction) error

ValidateSuggestedActions validates a slice of suggested actions.

Types

type ApplyChange 

type ApplyChange struct {
	ChangeType string `json:"change_type"`
	Target     string `json:"target"`
	Detail     string `json:"detail"`
}

ApplyChange represents a single change to apply to DataHub.

type ApplyConfig 

type ApplyConfig struct {
	Enabled             bool   `yaml:"enabled"`
	DataHubConnection   string `yaml:"datahub_connection"`
	RequireConfirmation bool   `yaml:"require_confirmation"`
}

ApplyConfig configures the apply_knowledge tool.

type Changeset 

type Changeset struct {
	ID               string         `json:"id"`
	CreatedAt        time.Time      `json:"created_at"`
	TargetURN        string         `json:"target_urn"`
	ChangeType       string         `json:"change_type"`
	PreviousValue    map[string]any `json:"previous_value"`
	NewValue         map[string]any `json:"new_value"`
	SourceInsightIDs []string       `json:"source_insight_ids"`
	ApprovedBy       string         `json:"approved_by"`
	AppliedBy        string         `json:"applied_by"`
	RolledBack       bool           `json:"rolled_back"`
	RolledBackBy     string         `json:"rolled_back_by,omitempty"`
	RolledBackAt     *time.Time     `json:"rolled_back_at,omitempty"`
}

Changeset records a set of changes applied to DataHub from insights.

type ChangesetFilter 

type ChangesetFilter struct {
	EntityURN  string
	AppliedBy  string
	Since      *time.Time
	Until      *time.Time
	RolledBack *bool
	Limit      int
	Offset     int
}

ChangesetFilter defines filtering criteria for listing changesets.

func (*ChangesetFilter) EffectiveLimit 

func (f *ChangesetFilter) EffectiveLimit() int

EffectiveLimit returns the limit to use, applying defaults and caps.

type ChangesetStore 

type ChangesetStore interface {
	InsertChangeset(ctx context.Context, cs Changeset) error
	GetChangeset(ctx context.Context, id string) (*Changeset, error)
	ListChangesets(ctx context.Context, filter ChangesetFilter) ([]Changeset, int, error)
	RollbackChangeset(ctx context.Context, id, rolledBackBy string) error
}

ChangesetStore persists and queries knowledge changesets.

func NewNoopChangesetStore 

func NewNoopChangesetStore() ChangesetStore

NewNoopChangesetStore creates a no-op ChangesetStore.

func NewPostgresChangesetStore 

func NewPostgresChangesetStore(db *sql.DB) ChangesetStore

NewPostgresChangesetStore creates a new PostgreSQL changeset store.

type DataHubClientWriter 

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

DataHubClientWriter is a real DataHubWriter implementation that delegates to the mcp-datahub client for read and write operations against DataHub.

func NewDataHubClientWriter 

func NewDataHubClientWriter(c *dhclient.Client) *DataHubClientWriter

NewDataHubClientWriter creates a DataHubClientWriter from an existing client. 

func (w *DataHubClientWriter) AddDocumentationLink(ctx context.Context, urn, linkURL, description string) error

AddDocumentationLink adds a documentation link to an entity.

func (*DataHubClientWriter) AddGlossaryTerm 

func (w *DataHubClientWriter) AddGlossaryTerm(ctx context.Context, urn, termURN string) error

AddGlossaryTerm adds a glossary term to an entity.

func (*DataHubClientWriter) AddTag 

func (w *DataHubClientWriter) AddTag(ctx context.Context, urn, tag string) error

AddTag adds a tag to an entity.

func (*DataHubClientWriter) GetCurrentMetadata 

func (w *DataHubClientWriter) GetCurrentMetadata(ctx context.Context, urn string) (*EntityMetadata, error)

GetCurrentMetadata retrieves current metadata for an entity from DataHub.

func (*DataHubClientWriter) RemoveTag 

func (w *DataHubClientWriter) RemoveTag(ctx context.Context, urn, tag string) error

RemoveTag removes a tag from an entity.

func (*DataHubClientWriter) UpdateDescription 

func (w *DataHubClientWriter) UpdateDescription(ctx context.Context, urn, description string) error

UpdateDescription sets the editable description for an entity.

type DataHubWriter 

type DataHubWriter interface {
	GetCurrentMetadata(ctx context.Context, urn string) (*EntityMetadata, error)
	UpdateDescription(ctx context.Context, urn string, description string) error
	AddTag(ctx context.Context, urn string, tag string) error
	RemoveTag(ctx context.Context, urn string, tag string) error
	AddGlossaryTerm(ctx context.Context, urn string, termURN string) error
	AddDocumentationLink(ctx context.Context, urn string, url string, description string) error
}

DataHubWriter provides write-back operations to DataHub.

type EntityInsightSummary 

type EntityInsightSummary struct {
	EntityURN  string   `json:"entity_urn"`
	Count      int      `json:"count"`
	Categories []string `json:"categories"`
	LatestAt   string   `json:"latest_at"`
}

EntityInsightSummary summarizes insights for a single entity.

type EntityMetadata 

type EntityMetadata struct {
	Description   string   `json:"description"`
	Tags          []string `json:"tags"`
	GlossaryTerms []string `json:"glossary_terms"`
	Owners        []string `json:"owners"`
}

EntityMetadata holds current metadata for an entity from DataHub.

type Insight 

type Insight struct {
	ID               string            `json:"id"`
	CreatedAt        time.Time         `json:"created_at"`
	SessionID        string            `json:"session_id"`
	CapturedBy       string            `json:"captured_by"`
	Persona          string            `json:"persona"`
	Category         string            `json:"category"`
	InsightText      string            `json:"insight_text"`
	Confidence       string            `json:"confidence"`
	EntityURNs       []string          `json:"entity_urns"`
	RelatedColumns   []RelatedColumn   `json:"related_columns"`
	SuggestedActions []SuggestedAction `json:"suggested_actions"`
	Status           string            `json:"status"`

	// Lifecycle fields (populated by migrations 000007 and 000008)
	ReviewedBy   string     `json:"reviewed_by,omitempty"`
	ReviewedAt   *time.Time `json:"reviewed_at,omitempty"`
	ReviewNotes  string     `json:"review_notes,omitempty"`
	AppliedBy    string     `json:"applied_by,omitempty"`
	AppliedAt    *time.Time `json:"applied_at,omitempty"`
	ChangesetRef string     `json:"changeset_ref,omitempty"`
}

Insight represents a captured domain knowledge insight.

type InsightFilter 

type InsightFilter struct {
	Status     string
	Category   string
	EntityURN  string
	CapturedBy string
	Confidence string
	Since      *time.Time
	Until      *time.Time
	Limit      int
	Offset     int
}

InsightFilter defines filtering criteria for listing insights.

func (*InsightFilter) EffectiveLimit 

func (f *InsightFilter) EffectiveLimit() int

EffectiveLimit returns the limit to use, applying defaults and caps.

type InsightStats 

type InsightStats struct {
	TotalPending int                    `json:"total_pending"`
	ByEntity     []EntityInsightSummary `json:"by_entity"`
	ByCategory   map[string]int         `json:"by_category"`
	ByConfidence map[string]int         `json:"by_confidence"`
	ByStatus     map[string]int         `json:"by_status"`
}

InsightStats holds aggregated insight statistics.

type InsightStore 

type InsightStore interface {
	Insert(ctx context.Context, insight Insight) error
	Get(ctx context.Context, id string) (*Insight, error)
	List(ctx context.Context, filter InsightFilter) ([]Insight, int, error)
	UpdateStatus(ctx context.Context, id, status, reviewedBy, reviewNotes string) error
	Update(ctx context.Context, id string, updates InsightUpdate) error
	Stats(ctx context.Context, filter InsightFilter) (*InsightStats, error)
	MarkApplied(ctx context.Context, id, appliedBy, changesetRef string) error
	Supersede(ctx context.Context, entityURN string, excludeID string) (int, error)
}

InsightStore persists and queries captured insights.

func NewNoopStore 

func NewNoopStore() InsightStore

NewNoopStore creates a no-op InsightStore for use when no database is available.

func NewPostgresStore 

func NewPostgresStore(db *sql.DB) InsightStore

NewPostgresStore creates a new PostgreSQL insight store.

func ParseConfig 

func ParseConfig(cfg map[string]any) InsightStore

ParseConfig extracts an InsightStore from a configuration map. The store must be provided programmatically (not from YAML).

type InsightUpdate 

type InsightUpdate struct {
	InsightText string `json:"insight_text,omitempty"`
	Category    string `json:"category,omitempty"`
	Confidence  string `json:"confidence,omitempty"`
}

InsightUpdate holds fields that can be edited on a non-applied insight.

type NoopDataHubWriter 

type NoopDataHubWriter struct{}

NoopDataHubWriter is a no-op implementation for when DataHub write-back is not configured. 

func (*NoopDataHubWriter) AddDocumentationLink(_ context.Context, _, _, _ string) error

AddDocumentationLink is a no-op.

func (*NoopDataHubWriter) AddGlossaryTerm 

func (*NoopDataHubWriter) AddGlossaryTerm(_ context.Context, _, _ string) error

AddGlossaryTerm is a no-op.

func (*NoopDataHubWriter) AddTag 

func (*NoopDataHubWriter) AddTag(_ context.Context, _, _ string) error

AddTag is a no-op.

func (*NoopDataHubWriter) GetCurrentMetadata 

func (*NoopDataHubWriter) GetCurrentMetadata(_ context.Context, _ string) (*EntityMetadata, error)

GetCurrentMetadata returns empty metadata.

func (*NoopDataHubWriter) RemoveTag 

func (*NoopDataHubWriter) RemoveTag(_ context.Context, _, _ string) error

RemoveTag is a no-op.

func (*NoopDataHubWriter) UpdateDescription 

func (*NoopDataHubWriter) UpdateDescription(_ context.Context, _, _ string) error

UpdateDescription is a no-op.

type ProposedChange 

type ProposedChange struct {
	ChangeType       string   `json:"change_type"`
	Target           string   `json:"target"`
	CurrentValue     string   `json:"current_value"`
	SuggestedValue   string   `json:"suggested_value"`
	SourceInsightIDs []string `json:"source_insight_ids"`
}

ProposedChange represents a deterministic change proposal from synthesis.

type RelatedColumn 

type RelatedColumn struct {
	URN       string `json:"urn"`
	Column    string `json:"column"`
	Relevance string `json:"relevance"`
}

RelatedColumn represents a column related to an insight.

type SuggestedAction 

type SuggestedAction struct {
	ActionType string `json:"action_type"`
	Target     string `json:"target"`
	Detail     string `json:"detail"`
}

SuggestedAction represents a proposed catalog change.

type Toolkit 

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

Toolkit implements the knowledge capture toolkit.

func New 

func New(name string, store InsightStore) (*Toolkit, error)

New creates a new knowledge toolkit. If store is nil, a no-op store is used.

func (*Toolkit) Close 

func (*Toolkit) Close() error

Close releases resources.

func (*Toolkit) Connection 

func (*Toolkit) Connection() string

Connection returns the connection name for audit logging.

func (*Toolkit) Kind 

func (*Toolkit) Kind() string

Kind returns the toolkit kind.

func (*Toolkit) Name 

func (t *Toolkit) Name() string

Name returns the toolkit instance name.

func (*Toolkit) RegisterTools 

func (t *Toolkit) RegisterTools(s *mcp.Server)

RegisterTools registers the capture_insight tool with the MCP server.

func (*Toolkit) SetApplyConfig 

func (t *Toolkit) SetApplyConfig(cfg ApplyConfig, csStore ChangesetStore, writer DataHubWriter)

SetApplyConfig enables the apply_knowledge tool with its dependencies.

func (*Toolkit) SetQueryProvider 

func (t *Toolkit) SetQueryProvider(provider query.Provider)

SetQueryProvider sets the query execution provider.

func (*Toolkit) SetSemanticProvider 

func (t *Toolkit) SetSemanticProvider(provider semantic.Provider)

SetSemanticProvider sets the semantic metadata provider.

func (*Toolkit) Tools 

func (t *Toolkit) Tools() []string

Tools returns the list of tool names provided by this toolkit.

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.