Documentation
¶
Overview ¶
Package jev asks Jev, TypeSafe's System One model, typed questions through a Provider, by default OpenRouter's TypeSafe-compatible API. A Judge adds what a service needs around the API client in jev/systemone: one switch, the API key from the environment, a retry of transient failures, a cool-down that keeps an outage from becoming a retry storm, and a status. Every failure is a fallback with a reason, never an error to handle. A request waits on the network, so nothing on a scheduling path may make one.
Index ¶
Constants ¶
const ( DefaultURL = "https://openrouter.ai/api" DefaultModel = "~typesafe/jev-latest" DefaultAPIKeyEnv = "OPENROUTER_API_KEY" DefaultTimeout = 10 * time.Second )
The defaults reach Jev through OpenRouter's TypeSafe-compatible API.
const MaxTimeout = time.Minute
MaxTimeout bounds one request, so an evaluation never holds its caller for long.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Decision ¶
type Decision struct {
Outcome Outcome
// Reason and Detail say why a fallback fell back.
Reason Reason
Detail string
// Response holds the validated answers, the model that gave them and
// what the request consumed. It is set when Outcome is Accepted.
Response *systemone.Response
// Requests counts the requests sent, a retry included, and Duration
// how long they took.
Requests int
Duration time.Duration
}
Decision is an evaluation's result. Use the answers only when Outcome is Accepted; on a fallback, take the path the workflow takes without Jev.
type Judge ¶
type Judge struct {
// Config returns the current settings.
Config func() Settings
// Provider returns the provider for settings and a key. Nil uses a
// systemone.Client for the settings' URL and model.
Provider func(settings Settings, key string) Provider
// Getenv reads the API key. Nil uses os.Getenv.
Getenv func(string) string
// Now supplies the time. Nil uses time.Now.
Now func() time.Time
// contains filtered or unexported fields
}
Judge asks Jev on behalf of every caller of a service. Share one Judge, so an outage cools every caller down together. A nil Judge is off.
func (*Judge) Evaluate ¶
Evaluate asks r's questions. While the Judge is off it returns a disabled fallback without sending anything. It sends nothing while the provider cools down, retries a timeout or an unavailable provider once, and waits for at most two requests of the configured timeout. When ctx ends it returns a cancelled fallback.
type Mode ¶
type Mode string
Mode is the Judge's state as Status reports it.
const ( ModeDisabled Mode = "disabled" // ModeUnconfigured is an enabled Judge without its API key or with // invalid settings; every evaluation falls back. ModeUnconfigured Mode = "unconfigured" ModeReady Mode = "ready" // ModeDegraded is an enabled Judge whose latest request failed or that // is cooling down; evaluations fall back while it cools. ModeDegraded Mode = "degraded" )
type Provider ¶
type Provider interface {
Evaluate(context.Context, systemone.Request) (systemone.Response, error)
}
Provider answers System One requests. A Judge's default provider is a systemone.Client; tests use jevtest.
type Reason ¶
type Reason string
Reason says why an evaluation fell back instead of using Jev's answers.
const ( // ReasonDisabled is an evaluation asked while the Judge is off. Nothing // is sent. ReasonDisabled Reason = "disabled" // ReasonUnconfigured is an enabled Judge whose API key is not set or // whose settings are invalid. ReasonUnconfigured Reason = "unconfigured" // ReasonCoolingDown is an evaluation not sent while the provider recovers // from rate limits or an outage. ReasonCoolingDown Reason = "cooling_down" ReasonTimeout Reason = "timeout" ReasonRateLimited Reason = "rate_limited" ReasonUnavailable Reason = "unavailable" // ReasonRejected is a request refused, before sending or by the // provider: bad credentials, an invalid or oversized request. ReasonRejected Reason = "rejected" // ReasonUnusable is a response that does not answer the questions in // the shape they require. ReasonUnusable Reason = "unusable" // ReasonCancelled is an evaluation whose context ended while it ran. ReasonCancelled Reason = "cancelled" )
type Settings ¶
type Settings struct {
Enabled bool
// URL is the base of a TypeSafe-compatible API; requests go to
// <URL>/v1/systemone.
URL string
Model string
APIKeyEnv string
// Timeout bounds one request.
Timeout time.Duration
}
Settings say whether a Judge asks Jev and how it reaches Jev. Enabled is the one switch for every evaluation a Judge serves. The API key is the name of an environment variable; its value never becomes a setting or a record.
func DefaultSettings ¶
func DefaultSettings() Settings
DefaultSettings are disabled settings with every other field at its default.
type Status ¶
type Status struct {
Mode Mode `json:"mode"`
Model string `json:"model,omitempty"`
Reason Reason `json:"reason,omitempty"`
Detail string `json:"detail,omitempty"`
CoolingUntil *time.Time `json:"cooling_until,omitempty"`
}
Status reports the Judge's mode, the configured model and the latest failure since the last success.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package jevtest supplies a fake Jev provider for tests.
|
Package jevtest supplies a fake Jev provider for tests. |
|
Package systemone is a client for TypeSafe's System One API, which answers typed questions about a state: a Choice selects one supplied option, a Score rates against supplied levels, and a Noul is the probability that a proposition holds.
|
Package systemone is a client for TypeSafe's System One API, which answers typed questions about a state: a Choice selects one supplied option, a Score rates against supplied levels, and a Noul is the probability that a proposition holds. |