decisions/model
A model is a function of a context and the sources it may read. It has
no other way to the world that decisions hands out, so the same
function runs in production, where sources capture what they read, and
under replay, where the record answers.
run is the only way to call a model. It puts the reads the model
received on its recommendation, so the record says what the model had:
- A model built with
new,overorcascadeis observed: every read thatSources.readanswered while the model ran is recorded. This is right for a model that uses every answer it asks for, such as one provider call or a rule. - A model built with
reportingreports what it received in its recommendation’sreads, and that report is believed. An agent loop whose tool can read and then fail uses this, so that a read the model never received is never on the record.
run also contains a model that raises: the caller gets
Error(Raised(..)), nothing the run set up is left behind, and a read
made after the model returned answers without being recorded.
import decisions/model
let accountant =
model.over(read_brief, fn(brief) { Ok(recommend_code(brief)) })
let assert Ok(recommendation) = model.run(accountant, context, sources)
capture stores what an outside system returned as evidence before the
model sees it, which is what makes a decision replayable without that
system.
Target-independent: builds for Erlang and JavaScript, with a small
foreign function on each for run.
Types
What a read returned, and the reference to the evidence that holds it.
pub type Captured {
Captured(ref: vocabulary.Ref, body: String)
}
Constructors
-
Captured(ref: vocabulary.Ref, body: String)
Where captured responses are kept, in the caller’s transaction. Evidence is never changed: a reference names one content.
pub type Evidence(tx) {
Evidence(
put: fn(tx, vocabulary.Ref, String) -> Result(Nil, String),
get: fn(tx, vocabulary.Ref) -> Result(String, String),
)
}
Constructors
-
Evidence( put: fn(tx, vocabulary.Ref, String) -> Result(Nil, String), get: fn(tx, vocabulary.Ref) -> Result(String, String), )
Why a model has no recommendation. A caller decides on a retry from the
variant, never from text; retryable says which ones a retry can help.
pub type Failure {
NotRecorded(read: String, argument: String)
ReadFailed(read: String, argument: String, reason: String)
Deadline(after: duration.Duration)
Raised(reason: String)
ProviderFailed(provider: String, reason: String)
Undecodable(reason: String)
Declined(reason: String)
WithEvidence(failure: Failure, evidence: List(vocabulary.Ref))
}
Constructors
-
NotRecorded(read: String, argument: String)The record holds no answer for this read or reference. Under replay the example is unanswerable; a retry cannot help.
-
ReadFailed(read: String, argument: String, reason: String)A source failed to answer a read or resolve a reference. A retry may help.
-
Deadline(after: duration.Duration)The model did not answer within its deadline. A retry may help.
-
Raised(reason: String)The model raised. A retry may help.
-
ProviderFailed(provider: String, reason: String)The model’s provider could not be reached or answered with an error: a transport failure, a timeout at the provider, a 5xx. A retry may help.
-
Undecodable(reason: String)The model answered with something that does not decode as the output. A retry may help.
-
Declined(reason: String)The model declined to recommend, or no stage of a cascade answered. A retry with the same context cannot help.
-
WithEvidence(failure: Failure, evidence: List(vocabulary.Ref))failure, pointing at evidence the model stored about it, such as the provider exchange that did not decode. Build it withwith_evidence;decisions.record_failurerecords the evidence on the failed attempt.
A rule, a classifier, one provider call, an agent, or a cascade of them.
Call one with run.
pub opaque type Model(output)
How a point reads its context into a value of its own type. The same
function serves the model (through over), the card
(decisions/view.context), the export and a replay, so all of them
receive the same value.
pub type Reader(context) =
fn(vocabulary.Manifest, Sources) -> Result(context, Failure)
How a reference is resolved to the content it names, as it was read:
from the store’s evidence or the application’s immutable data. The card
(decisions/view) and the export (decisions/learning.Archive) take
the same type. A reference the source does not hold is NotRecorded.
pub type Resolver =
fn(vocabulary.Ref) -> Result(String, Failure)
Everything a model may read.
pub type Sources {
Sources(
resolve: fn(vocabulary.Ref) -> Result(String, Failure),
read: fn(String, String) -> Result(Captured, Failure),
)
}
Constructors
-
Sources( resolve: fn(vocabulary.Ref) -> Result(String, Failure), read: fn(String, String) -> Result(Captured, Failure), )Arguments
- resolve
-
The content of a reference in the context.
- read
-
A named read beyond the context, with one argument. It returns the content with the reference to the evidence that holds it.
One step of a cascade: it recommends, or abstains with None.
pub type Stage(output) =
fn(vocabulary.Manifest, Sources) -> Result(
option.Option(vocabulary.Recommendation(output)),
Failure,
)
Values
pub fn capture(
evidence: Evidence(tx),
tx: tx,
source source: String,
request request: String,
fetch fetch: fn() -> Result(String, String),
) -> Result(Captured, String)
Read request from source through fetch, store the response as
evidence under a reference that names its content, and only then
return it. A failed fetch stores nothing.
pub fn cascade(
stages: List(
fn(vocabulary.Manifest, Sources) -> Result(
option.Option(vocabulary.Recommendation(output)),
Failure,
),
),
) -> Model(output)
A model whose first answering stage recommends. That stage’s own
recommender and explanation are kept, so the record shows which stage
answered, and only the reads that stage received are recorded: a stage
that abstained contributes none. When no stage answers the failure is
Declined.
pub fn describe(failure: Failure) -> String
The failure as one line of text, for a log or an operator.
pub fn digest(body: String) -> String
The revision capture gives a content: the SHA-256 of its text, in
lowercase hexadecimal. Equal bodies give equal revisions and different
bodies, in practice, different ones. A latest function for drift reads
the content as it is now and returns digest of it, so it follows the
same rule as the capture.
pub fn evidence_of(failure: Failure) -> List(vocabulary.Ref)
The evidence a failure points at; empty for a failure without any.
pub fn failure_decoder() -> decode.Decoder(Failure)
Decodes a failure written by failure_to_json.
pub fn failure_to_json(failure: Failure) -> json.Json
A failure as JSON, as a failed attempt’s entry keeps it.
pub fn new(
call: fn(vocabulary.Manifest, Sources) -> Result(
vocabulary.Recommendation(output),
Failure,
),
) -> Model(output)
An observed model. The reads it receives through Sources.read are
recorded by run; any reads the recommendation already names are kept
beside them.
pub fn over(
reader: fn(vocabulary.Manifest, Sources) -> Result(
context,
Failure,
),
decide: fn(context) -> Result(
vocabulary.Recommendation(output),
Failure,
),
) -> Model(output)
An observed model that decides from a typed context read by reader.
pub fn over_reporting(
reader: fn(vocabulary.Manifest, Sources) -> Result(
context,
Failure,
),
decide: fn(context) -> Result(
vocabulary.Recommendation(output),
Failure,
),
) -> Model(output)
A reporting model that decides from a typed context: the reads
reader makes are observed (a reader uses every answer it asks for),
and decide reports the reads its own loop received in its
recommendation’s reads. Both are recorded, and nothing else. This is
the shape of an agent whose tools can read and then fail.
pub fn recorded(
context context: List(#(vocabulary.Ref, String)),
reads reads: List(#(vocabulary.Ref, String)),
) -> Sources
Sources that answer from a record and from nothing else. A reference or
a read the record does not hold is NotRecorded. When the record holds
several reads of one name and argument, the last one answers: it is the
latest the model received.
pub fn reporting(
call: fn(vocabulary.Manifest, Sources) -> Result(
vocabulary.Recommendation(output),
Failure,
),
) -> Model(output)
A model that reports the reads it received in its recommendation’s
reads. run believes the report and records nothing it observed.
pub fn retryable(failure: Failure) -> Bool
Whether trying the same model on the same context again can give a different answer.
pub fn run(
model: Model(output),
context: vocabulary.Manifest,
sources: Sources,
) -> Result(vocabulary.Recommendation(output), Failure)
Run a model on a context and put the reads it received on its
recommendation. A model that raises gives Error(Raised(reason)).
pub fn stage(
model: Model(output),
) -> fn(vocabulary.Manifest, Sources) -> Result(
option.Option(vocabulary.Recommendation(output)),
Failure,
)
A model as one stage of a cascade: it answers with its recommendation,
a model that declines (Declined) abstains, and any other failure
stops the cascade. Its reads are observed as the model’s own are.
pub fn with_evidence(
failure: Failure,
evidence: List(vocabulary.Ref),
) -> Failure
failure, pointing at evidence the model stored about it. Evidence on
a failure that already carries some is added to it.