Documentation
¶
Overview ¶
Package guide holds the logic behind Pulse's guidance surfaces — Recommend (an intent to ranked draft requests) and Explain (a request to plain-language steps).
It is NO-EXECUTE, like internal/descriptor: it reads the instance snapshot (pruned ontology, instance manifest, Purposes) and never imports internal/service or internal/processing (TestGuideNoExecutionImports). Everything it says is derived from declared guidance metadata; nothing here runs a request. Cohort-bound Recommend also reads the cohort's schema and validates each draft through the caller's Bound.Predict, and Explain checks a request through the caller's Checks — no-execute predicts over the header and schema, never a record.
Index ¶
- Constants
- func Explain(inst *descx.InstanceSnapshot, req descriptor.ExplainRequest, checks Checks) (*descriptor.ExplainResult, error)
- func Recommend(inst *descx.InstanceSnapshot, req descriptor.RecommendRequest) (*descriptor.RecommendResult, error)
- func RecommendBound(inst *descx.InstanceSnapshot, req descriptor.RecommendRequest, b Bound) (*descriptor.RecommendResult, error)
- func Routes(intentID string) []descriptor.Alternative
- func ValidateExplainRequest(req descriptor.ExplainRequest) (descriptor.ExplainRoot, descriptor.ExplainDetail, error)
- func ValidateRequest(req descriptor.RecommendRequest) error
- type Bound
- type Checks
Constants ¶
const BindingsPerOperator = 3
BindingsPerOperator is K: the most field bindings bound mode drafts for one operator. Hints pin roles; the rest take schema order.
const DefaultLimit = 10
DefaultLimit caps the recommendations when the request sets no Limit.
Variables ¶
This section is empty.
Functions ¶
func Explain ¶
func Explain(inst *descx.InstanceSnapshot, req descriptor.ExplainRequest, checks Checks) (*descriptor.ExplainResult, error)
Explain describes what the request root in req will do (request mode) for the instance inst. Steps come from each slot's structure plus its operator's plain purpose; checks supply the inferred defaults, the advisories and predict's verdict. Every sentence passes the instance's prose scrub, and no hidden operator is named.
func Recommend ¶
func Recommend(inst *descx.InstanceSnapshot, req descriptor.RecommendRequest) (*descriptor.RecommendResult, error)
Recommend answers an UNBOUND recommend request (no cohort) for the instance inst: the operators the pruned ontology says serve the intent, each as a placeholder skeleton, ranked and capped.
func RecommendBound ¶
func RecommendBound(inst *descx.InstanceSnapshot, req descriptor.RecommendRequest, b Bound) (*descriptor.RecommendResult, error)
RecommendBound answers a COHORT-BOUND recommend request: each serving operator's slots are bound to the cohort's fields (hints first, then up to BindingsPerOperator bindings in schema order), every draft is predict-validated through b.Predict, an invalid one is dropped, and each survivor carries predict's advisories. A draft that still needs a value only the caller can choose is kept with Bound false and Needs naming it.
func Routes ¶
func Routes(intentID string) []descriptor.Alternative
Routes returns a copy of the tooling routes declared for an intent (feature spellings, unfiltered by any instance), or nil when the intent declares none. The MCP author-request prompt reads it to point the tooling intents straight at their tools.
func ValidateExplainRequest ¶
func ValidateExplainRequest(req descriptor.ExplainRequest) (descriptor.ExplainRoot, descriptor.ExplainDetail, error)
ValidateExplainRequest checks the parts of req that need no cohort: exactly one request root (request mode) or exactly one result root with at most its own request companion (response mode: Request beside a Response, Composed beside a ComposedResponse, Chain beside a ChainResponse, Facet beside a FacetResult), and a known detail level. It returns the root and the effective detail.
func ValidateRequest ¶
func ValidateRequest(req descriptor.RecommendRequest) error
ValidateRequest checks the parts of req that need no cohort — the intent, level and limit — so a caller can refuse a bad request before it opens the cohort.
Types ¶
type Bound ¶
type Bound struct {
Cohort *types.Cohort
Schema *encoding.Schema
Predict func(*types.Request) *descriptor.Envelope
// Weight is the cohort's suggested row weight — the field Inspect
// reports as suggested_weight (descx.SuggestWeight over the SPSS
// sidecar's weight variable) — or "" when none. A weight-only
// operator (AGG_WEIGHTED_MEAN) binds its weight to it; without one
// it drafts with the weight as a need.
Weight string
}
Bound is what cohort-bound mode knows about the cohort: its schema (header and schema block only) and Predict, which validates one draft against that cohort without executing it. Predict never reads a record; it is the caller's in-process predict, carrying the instance's options and the cohort's sidecar facts.
type Checks ¶
type Checks struct {
Request func(*types.Request) (*descriptor.Envelope, error)
Compose func(*types.ComposedRequest) (*descriptor.Envelope, error)
Chain func(*types.ChainRequest) (*descriptor.Envelope, error)
Facet func(*types.FacetRequest) (*descriptor.Envelope, error)
}
Checks is the no-execute validation the caller (the facade) runs for Explain's request mode: each check predicts its root over the root's cohort — header, schema and sidecar, never a record — and returns predict's envelope. An error ends Explain (a cohort that cannot be read). A nil check is skipped, and Explain says what it could not check. Request is called only for a request (or Compose slot, or a chain's first stage) that names a cohort, Chain and Facet only when their root names one; Compose always.
Source Files