semantic

Documentation

Overview

Package semantic provides semantic intent matching for Phase 2 intelligent routing. It uses embedding similarity to match user queries to predefined intents.

Index

• type EmbeddingEngine
• type IntentDefinition
• type IntentsFile
• type MatchResult
• type Tier
  • func NewTier(engine EmbeddingEngine, threshold float64) *Tier
  • func (t *Tier) GetIntentCount() int
  • func (t *Tier) GetIntents() []*IntentDefinition
  • func (t *Tier) GetMetrics() map[string]interface{}
  • func (t *Tier) GetThreshold() float64
  • func (t *Tier) Initialize(intentsPath string) error
  • func (t *Tier) IsEnabled() bool
  • func (t *Tier) MatchIntent(query string) (*MatchResult, error)
  • func (t *Tier) MatchIntentInterface(query string) (interface{}, error)
  • func (t *Tier) SetThreshold(threshold float64)
  • func (t *Tier) Shutdown() error

Types

type EmbeddingEngine

type EmbeddingEngine interface {
	// Embed computes the embedding vector for a text
	Embed(text string) ([]float32, error)

	// CosineSimilarity computes the cosine similarity between two vectors
	CosineSimilarity(a, b []float32) float64

	// IsEnabled returns whether the engine is ready
	IsEnabled() bool
}

EmbeddingEngine defines the interface for computing embeddings. This allows the semantic tier to work with the embedding engine.

type IntentDefinition

type IntentDefinition struct {
	// Name is the unique identifier for the intent
	Name string `yaml:"name" json:"name"`

	// Description explains what the intent represents
	Description string `yaml:"description" json:"description"`

	// Examples are sample queries that match this intent
	Examples []string `yaml:"examples" json:"examples"`

	// Embedding is the pre-computed embedding vector for the intent
	// This is computed from the description and examples
	Embedding []float32 `yaml:"-" json:"-"`
}

IntentDefinition represents a single intent with its metadata and examples.

type IntentsFile

type IntentsFile struct {
	Intents []IntentDefinition `yaml:"intents"`
}

IntentsFile represents the structure of the intents.yaml file.

type MatchResult

type MatchResult struct {
	// Intent is the matched intent name
	Intent string `json:"intent"`

	// Confidence is the similarity score (0.0-1.0)
	Confidence float64 `json:"confidence"`

	// LatencyMs is the time taken for matching in milliseconds
	LatencyMs int64 `json:"latency_ms"`
}

MatchResult represents the result of semantic intent matching.

type Tier

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

Tier provides semantic intent matching using embedding similarity. It pre-computes intent embeddings at startup and matches queries against them.

func NewTier

func NewTier(engine EmbeddingEngine, threshold float64) *Tier

NewTier creates a new semantic tier instance.

Parameters:

• engine: The embedding engine for computing embeddings
• threshold: Minimum confidence score for a match (default: 0.85)

Returns:

• *Tier: A new tier instance

func (*Tier) GetIntentCount

func (t *Tier) GetIntentCount() int

GetIntentCount returns the number of loaded intents.

Returns:

• int: The number of intents

func (*Tier) GetIntents

func (t *Tier) GetIntents() []*IntentDefinition

GetIntents returns all loaded intents.

Returns:

• []*IntentDefinition: A slice of all intents

func (*Tier) GetMetrics

func (t *Tier) GetMetrics() map[string]interface{}

GetMetrics returns metrics about semantic tier usage.

Returns:

• map[string]interface{}: Metrics including match count, hit rate, avg latency

func (*Tier) GetThreshold

func (t *Tier) GetThreshold() float64

GetThreshold returns the confidence threshold.

Returns:

• float64: The confidence threshold

func (*Tier) Initialize

func (t *Tier) Initialize(intentsPath string) error

Initialize loads intents from the YAML file and pre-computes embeddings.

Parameters:

• intentsPath: Path to the intents.yaml file

Returns:

• error: Any error encountered during initialization

func (*Tier) IsEnabled

func (t *Tier) IsEnabled() bool

IsEnabled returns whether the semantic tier is ready for matching.

Returns:

• bool: true if the tier is initialized and ready

func (*Tier) MatchIntent

func (t *Tier) MatchIntent(query string) (*MatchResult, error)

MatchIntent finds the best matching intent for a query. Returns nil if no intent matches above the confidence threshold.

Parameters:

• query: The user query to match

Returns:

• *MatchResult: The match result, or nil if no match
• error: Any error encountered during matching

func (*Tier) MatchIntentInterface

func (t *Tier) MatchIntentInterface(query string) (interface{}, error)

MatchIntentInterface matches an intent and returns the result as an interface type. This is used by the intelligence service to avoid circular imports.

func (*Tier) SetThreshold

func (t *Tier) SetThreshold(threshold float64)

SetThreshold updates the confidence threshold.

Parameters:

• threshold: The new threshold value

func (*Tier) Shutdown

func (t *Tier) Shutdown() error

Shutdown gracefully shuts down the semantic tier.

Returns:

• error: Any error encountered during shutdown