Understanding and Using the Decision Package

Decision models (System One, Jev-style) in Geppetto — typed noul/choice/score questions, the LunaRoute adapter, profiles, Pi credentials and the JavaScript API.

Sections

Terminology & Glossary
📖 Documentation
Navigation
60 sectionsv0.1
📄 Understanding and Using the Decision Package — glaze help geppetto-decision-package
geppetto-decision-package

Understanding and Using the Decision Package

Decision models (System One, Jev-style) in Geppetto — typed noul/choice/score questions, the LunaRoute adapter, profiles, Pi credentials and the JavaScript API.

Tutorialgeppettodecisionsclassificationretrievalaiproviderssecuritydecision-typedecision-enginesystemone-api-keysystemone-base-url

Decision models in Geppetto

A decision model answers typed questions about a state without generating text. You declare each question's answer space, and the model returns a probability distribution over exactly that space. There is nothing to parse, an answer cannot fall outside the space, and every answer carries probabilities. LunaRoute serves such a model, djev, on its System One endpoint. TypeSafe's Jev uses the same question model.

pkg/decision is Geppetto's fourth model-service primitive, after inference (pkg/inference/engine), embeddings (pkg/embeddings) and rerank (pkg/rerank). It follows rerank's layering: core types and validation, a provider adapter, a settings factory, profile wiring, and a JavaScript binding.

Question types

TypeDeclaresAnswer fields
noula proposition; optional True/False descriptionsProbability that it is true
choice1–255 Options (name, description), in orderChoice, Confidence, Probabilities per option
score1–10 ordered Levelsfractional Score, Confidence, LevelProbabilities

All questions in one request share the state, which the provider counts once. Batching many questions into one request is cheaper and barely slower than asking one. On djev, twelve passage-relevance questions took about 0.6 s.

Option order matters to these models, so Options is a slice and the adapter sends it in slice order.

Go API

import (
    "github.com/go-go-golems/geppetto/pkg/decision"
    "github.com/go-go-golems/geppetto/pkg/decision/systemone"
)

p, err := systemone.New(systemone.Options{APIKey: key, Model: "djev"})
resp, err := p.Decide(ctx, decision.Request{
    State: map[string]any{"query": q, "corpus": "engineering design notes"},
    Questions: map[string]decision.Question{
        "route": {Type: decision.Choice, Instructions: "Which retrieval strategy fits?",
            Options: []decision.Option{{Name: "keyword", Description: "identifiers"}, {Name: "semantic", Description: "concepts"}}},
        "needs": {Type: decision.Noul, Instructions: "Does answering require documents?"},
        "complexity": {Type: decision.Score, Instructions: "How complex?",
            Levels: []string{"lookup", "single fact", "mechanism", "synthesis"}},
    },
})
resp.Answers["route"].Choice        // "semantic"
resp.Answers["needs"].Probability   // 0.91
decision.Gate(resp.Answers["needs"].Probability, 0.8, 0.5) // decision.Act

Decide validates the request (question ids [A-Za-z0-9_.-]{1,64}, type-specific fields only, option and level limits, data-URL images) and the response (one answer per question, of its type, with a finite probability for every declared option or level).

Errors wrap sentinels, which you test with errors.Is:

  • ErrInvalidRequest
  • ErrInvalidResponse
  • ErrUnavailable
  • ErrRateLimited
  • ErrNotGranted
  • ErrModelNotFound
  • ErrRequestTooLarge
  • ErrResponseTooLarge

Non-2xx responses are a *decision.ProviderError with the provider's Code, RequestID and RetryAfter.

Pi credentials

a, _ := pi.LoadAgentDir(pi.DefaultDir(os.Getenv(pi.EnvAgentDir)))
d, _ := a.Decider(ctx, "lunaroute/djev", pi.DecisionOptions{})

Decider uses the provider's base URL, any models.json headers, and Pi's credential (auth.json, then models.json apiKey). The endpoint comes from the model's provider: its baseUrl, else that provider's own default (lunaroute → https://gw.lunaroute.com/v1), else *pi.NoEndpointError. The decider's client is pinned to that origin (see the geppetto-credential-scope help topic). To try it:

go run ./cmd/examples/decision-pi-smoke run --query "how does the rebalance law preserve placements?"
go run ./cmd/examples/decision-pi-smoke run --query "..." --passage "first passage" --passage "second passage"

Profiles

profiles:
  djev:
    inference_settings:
      api:
        api_keys:
          systemone-api-key: ${LUNAROUTE_API_KEY}
        # base_urls: { systemone-base-url: https://gw.lunaroute.com/v1 }
      decision:
        type: systemone
        engine: djev

factory.NewSettingsFactoryFromInferenceSettings(s).NewProvider() builds the provider. Plain HTTP and local addresses need allow_http.decision and allow_local_networks.decision. CLI flags: --decision-type, --decision-engine, --decision-max-request-bytes, --decision-max-response-bytes, --systemone-api-key, --systemone-base-url.

JavaScript

const gp = require("geppetto");
const d = gp.decider(gp.inferenceProfiles.load(path).resolve("djev"));
const r = d.decide({
  state: { query },
  questions: {
    route: { type: "choice", instructions: "Which index?", options: { keyword: "identifiers", semantic: "concepts" } },
    needs: { type: "noul", instructions: "Needs documents?", true: "corpus facts" },
    hard:  { type: "score", instructions: "How hard?", levels: ["easy", "medium", "hard"] },
  },
});
r.answers.route.choice; r.answers.needs.probability; r.answers.hard.levelProbabilities;
const h = d.decideAsync(req); // { promise, cancel, close }

Choice options given as an object keep JavaScript insertion order. Unknown keys are rejected.

Limits and cautions

  • Decision models do not generate text. They are also weak at arithmetic, counting, and date comparison.
  • Option order changes probabilities. Test critical questions with the options reversed.
  • What the state says matters. Describing the corpus in the state moved a "needs retrieval?" probability from 0.08 to 0.99 in our probes.
  • The state is untrusted input. Treat a decision as an input to policy, not as an authorization.