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:

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

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

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 with with_evidence; decisions.record_failure records 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.

pub fn without_evidence(failure: Failure) -> Failure

The failure without the evidence it points at.

✨ Search Document