diff --git a/internal/router/semantic/contract.go b/internal/router/semantic/contract.go new file mode 100644 index 0000000..d645d9c --- /dev/null +++ b/internal/router/semantic/contract.go @@ -0,0 +1,60 @@ +// Package semantic defines the coarse-route contract for the learned-router +// experiment. The existing seven-intent router remains authoritative; this +// package provides a six-class semantic layer that runs only in eval/shadow +// mode until it earns promotion. +// +// The six coarse routes are: +// +// - conversation — social turns, greetings, mood, jokes, open-ended chat +// - knowledge — questions seeking an answer (world, recall, calendar) +// - action — executable commands and reminders (act, reminder) +// - memory_write — structured or unstructured writes (fact, note) +// - system — time, date, quiet mode, self-management +// - uncertain — too little signal to decide; the authoritative router clarifies +// +// No capability, function, slot, or source information lives in this artifact. +// That is a later stage. The contract here is purely coarse-route + confidence. +package semantic + +// SemanticRoute — one of six coarse semantic classes. +type SemanticRoute string + +const ( + RouteConversation SemanticRoute = "conversation" + RouteKnowledge SemanticRoute = "knowledge" + RouteAction SemanticRoute = "action" + RouteMemoryWrite SemanticRoute = "memory_write" + RouteSystem SemanticRoute = "system" + RouteUncertain SemanticRoute = "uncertain" +) + +// AllRoutes is the ordered set of valid routes, for iteration and confusion +// matrix layout. +var AllRoutes = []SemanticRoute{ + RouteConversation, + RouteKnowledge, + RouteAction, + RouteMemoryWrite, + RouteSystem, + RouteUncertain, +} + +// SemanticRouteDecision — the output of a coarse router. No slots, no +// capability, no source — just the route, confidence, and whether the model +// chose to abstain. +type SemanticRouteDecision struct { + Route SemanticRoute + Confidence float64 + Abstain bool + ModelID string +} + +// ValidRoute reports whether r is one of the six defined routes. +func ValidRoute(r SemanticRoute) bool { + switch r { + case RouteConversation, RouteKnowledge, RouteAction, + RouteMemoryWrite, RouteSystem, RouteUncertain: + return true + } + return false +} diff --git a/internal/router/semantic/interface.go b/internal/router/semantic/interface.go new file mode 100644 index 0000000..81202c9 --- /dev/null +++ b/internal/router/semantic/interface.go @@ -0,0 +1,14 @@ +package semantic + +import "context" + +// SemanticRouter — the interface behind which experiment models run. The +// implementation decides whether to consume MatchText; the contract here is +// that Route returns a coarse decision without touching the authoritative +// router's Intent, slots, capability, or source. +// +// A nil implementation is a valid floor — the shadow harness records +// "no model" and continues. +type SemanticRouter interface { + Route(ctx context.Context, text string) (SemanticRouteDecision, error) +} diff --git a/internal/router/semantic/legacy.go b/internal/router/semantic/legacy.go new file mode 100644 index 0000000..ac5f811 --- /dev/null +++ b/internal/router/semantic/legacy.go @@ -0,0 +1,38 @@ +package semantic + +import "github.com/kami/maven/internal/router" + +// IntentToRoute maps the current seven-intent Decision.Intent to a coarse +// semantic route. The mapping is deterministic and exists only for +// baseline/evaluation — it does not change current routing behaviour. +// +// Mapping: +// +// chat → conversation +// query → knowledge +// act → action +// reminder → action +// fact → memory_write +// note → memory_write +// system → system +// unknown → uncertain +func IntentToRoute(intent router.Intent) SemanticRoute { + switch intent { + case router.IntentChat: + return RouteConversation + case router.IntentQuery: + return RouteKnowledge + case router.IntentAct: + return RouteAction + case router.IntentReminder: + return RouteAction + case router.IntentFact: + return RouteMemoryWrite + case router.IntentNote: + return RouteMemoryWrite + case router.IntentSystem: + return RouteSystem + default: + return RouteUncertain + } +}