router/semantic: semantic seed type and surface generator (slice 15)

internal/router/semantic/seeds.go

@@ -0,0 +1,69 @@
+package semantic
+
+// SemanticSeed is an intermediate specification whose label is known before
+// any surface text is generated. The important invariant is:
+//
+//	semantic identity → deterministic surface generation
+//
+// NOT:
+//
+//	sentence → model guesses label
+type SemanticSeed struct {
+	// ID uniquely identifies this seed within the corpus factory.
+	ID string `json:"id"`
+
+	// Route is the coarse semantic route this seed maps to.
+	Route SemanticRoute `json:"route"`
+
+	// Family groups seeds that share the same semantic operation.
+	// All surfaces derived from one seed share a SplitGroup.
+	Family string `json:"family"`
+
+	// OperationID identifies the concrete operation (tool, capability, etc.)
+	// that this seed represents. Empty for seeds without a concrete operation.
+	OperationID string `json:"operation_id,omitempty"`
+
+	// SplitGroup is the group ID for train/eval splitting.
+	// All surfaces from one seed must share this.
+	SplitGroup string `json:"split_group"`
+
+	// VerbForms are the imperative/stative verbs that express this seed's
+	// action or query. For action seeds, these are the command verbs.
+	// For knowledge seeds, these are the query-opening words.
+	VerbForms []string `json:"verb_forms,omitempty"`
+
+	// Subjects are the targets/objects of the action or query.
+	// For HA actions: entity names. For tools: service names.
+	Subjects []string `json:"subjects,omitempty"`
+
+	// Objects are additional objects or arguments.
+	Objects []string `json:"objects,omitempty"`
+
+	// Values are quantified values (durations, amounts, etc.)
+	Values []string `json:"values,omitempty"`
+
+	// Tags are metadata tags applied to all generated surfaces from this seed.
+	Tags []string `json:"tags,omitempty"`
+}
+
+// SurfaceGenerator generates surface forms from a seed. Each generator
+// produces meaning-preserving forms that are less tied to the deterministic
+// command grammar, tagged by template category.
+type SurfaceGenerator struct {
+	// Name identifies this generator for provenance tracking.
+	Name string
+
+	// Fn generates surface forms from a seed.
+	Fn func(seed SemanticSeed) []GeneratedSurface
+}
+
+// GeneratedSurface is one surface form derived from a seed.
+type GeneratedSurface struct {
+	Text   string `json:"text"`
+	// TemplateCategory identifies which template produced this surface.
+	TemplateCategory string `json:"template_category"`
+	// FastPathMatched is set after fast-path classification.
+	FastPathMatched bool `json:"-"`
+	// ExpectedRoute is the route this surface should map to.
+	ExpectedRoute SemanticRoute `json:"-"`
+}