Liking cljdoc? Tell your friends :D

com.blockether.vis.internal.loop.trajectory

ATIF trajectory of one vis-agent run.

vis-agent --trajectory PATH writes the run as one ATIF-v1.8 document. Harbor and its viewer read this format:

user step the prompt agent step one for each iteration: thinking, prose, model and effort tool call one python_execution call for each code block, with its code observation the stdout and the error of that block final_metrics the token and cost totals of the run subagents one embedded trajectory for each Council child

The final agent step carries the final answer. Vis facts without an ATIF field go to extra: iteration, block status, Activity, repairs, timeouts and the run profile. The Activity of a block has one row for each host function call, with its operation, arguments, result, state and duration. Each agent step has the tokens and the cost of its provider call in metrics. The extra of the document has the run status and evaluation, and for a --persist run the session usage and the saved goal.

A Council child comes from its persisted turns, so its steps have the token counts and the cost of each iteration. The observation of the step that started the child refers to the child trajectory. The total cost of the run includes the cost of the children.

The CLI result has two shapes: engine keywords, or the snake_case string keys of a --persist run through the gateway. build reads the canonical wire shape of both.

Before the write, each known credential value becomes [REDACTED]: the provider keys and tokens in ~/.vis/*-auth.json, in the provider configuration and from api_key_command, the gateway token, the values of secret settings, keychain and command values of environment:, and values of the environment, .env and environment: whose names contain KEY, TOKEN, SECRET, PASSWORD or CREDENTIAL. Each value also matches in its JSON-escaped and URL-encoded forms. Credentials that their form shows also become [REDACTED]: private PEM keys, passwords in URLs, credential headers and well-known API key and token formats. Base64 text that holds a known value or one of these forms becomes [REDACTED] too. Vis does not find other secrets in the text. Only the owner can read the file.

ATIF trajectory of one `vis-agent` run.

`vis-agent --trajectory PATH` writes the run as one ATIF-v1.8 document. Harbor
and its viewer read this format:

  user step      the prompt
  agent step     one for each iteration: thinking, prose, model and effort
  tool call      one `python_execution` call for each code block, with its `code`
  observation    the stdout and the error of that block
  final_metrics  the token and cost totals of the run
  subagents      one embedded trajectory for each Council child

The final agent step carries the final answer. Vis facts without an ATIF
field go to `extra`: iteration, block status, Activity, repairs, timeouts
and the run profile. The Activity of a block has one row for each host
function call, with its operation, arguments, result, state and duration.
Each agent step has the tokens and the cost of its provider call in
`metrics`. The `extra` of the document has the run status and evaluation,
and for a `--persist` run the session usage and the saved goal.

A Council child comes from its persisted turns, so its steps have the token
counts and the cost of each iteration. The observation of the step that
started the child refers to the child trajectory. The total cost of the run
includes the cost of the children.

The CLI result has two shapes: engine keywords, or the snake_case string keys
of a `--persist` run through the gateway. [[build]] reads the canonical wire
shape of both.

Before the write, each known credential value becomes `[REDACTED]`: the
provider keys and tokens in `~/.vis/*-auth.json`, in the provider
configuration and from `api_key_command`, the gateway token, the values of
secret settings, keychain and command values of
`environment:`, and values of the environment, `.env` and `environment:` whose
names contain KEY, TOKEN, SECRET, PASSWORD or CREDENTIAL. Each value also
matches in its JSON-escaped and URL-encoded forms. Credentials that their
form shows also become `[REDACTED]`: private PEM keys, passwords in URLs,
credential headers and well-known API key and token formats. Base64 text that
holds a known value or one of these forms becomes `[REDACTED]` too. Vis does not
find other secrets in the text. Only the owner can read the file.
raw docstring

buildclj

(build result
       {:keys [prompt started-at-ms profile iterations turn-position subagents
               session-usage goal]})

ATIF document of one finished run. result is the CLI result map. Options:

:prompt the user prompt :started-at-ms the time when the run started :profile the run options that shape the agent :iterations the persisted iterations of the turn of the run. A persisted run returns no trace, so they give its agent steps. :turn-position the position of that turn. It gives the refs of its forms. :subagents the Council children of the run: agent rows with their turns, and each turn with its persisted iterations in trace :session-usage the usage rollup of a persisted session :goal the saved goal of a persisted session

ATIF document of one finished run. `result` is the CLI result map. Options:

:prompt         the user prompt
:started-at-ms  the time when the run started
:profile        the run options that shape the agent
:iterations     the persisted iterations of the turn of the run. A persisted
                run returns no `trace`, so they give its agent steps.
:turn-position  the position of that turn. It gives the refs of its forms.
:subagents      the Council children of the run: agent rows with their
                `turns`, and each turn with its persisted iterations in
                `trace`
:session-usage  the usage rollup of a persisted session
:goal           the saved goal of a persisted session
sourceraw docstring

export!clj

(export! path result opts)

Build the trajectory of one run, redact the known credentials and write it to path. opts are the options of build.

Build the trajectory of one run, redact the known credentials and write it to
`path`. `opts` are the options of [[build]].
sourceraw docstring

known-secretsclj

(known-secrets {:keys [env files providers settings environment]})

Credential values that a trajectory must not carry, longest first:

:env environment values whose names contain KEY, TOKEN, SECRET, PASSWORD or CREDENTIAL :files JSON credential files: each string under a credential key :providers the provider configuration: each string under a credential key :settings the values of secret settings :environment the values that Vis gives to child processes: an environment: value from the keychain or a command, and a .env or environment: value under a credential name, as [[name source value]]

Values with fewer than 8 characters do not count.

Credential values that a trajectory must not carry, longest first:

  :env        environment values whose names contain KEY, TOKEN, SECRET,
              PASSWORD or CREDENTIAL
  :files      JSON credential files: each string under a credential key
  :providers  the provider configuration: each string under a credential key
  :settings   the values of secret settings
  :environment  the values that Vis gives to child processes: an
              `environment:` value from the keychain or a command, and a
              `.env` or `environment:` value under a credential name, as
              `[[name source value]]`

Values with fewer than 8 characters do not count.
sourceraw docstring

redactclj

(redact data secrets)

Replace each secrets value in each string of data with [REDACTED].

Replace each `secrets` value in each string of `data` with `[REDACTED]`.
sourceraw docstring

redactorclj

(redactor secrets)

Build the function that replaces, in each string of a value, each of secrets and each credential that its form shows with [REDACTED]. Build it once for an export.

Build the function that replaces, in each string of a value, each of `secrets` and
each credential that its form shows with `[REDACTED]`. Build it once for an export.
sourceraw docstring

run-secretsclj

(run-secrets)

The known credentials of this process and of the bound workspace, with their forms: also the gateway token and the provider keys that api_key_command gave.

The known credentials of this process and of the bound workspace, with their forms:
also the gateway token and the provider keys that `api_key_command` gave.
sourceraw docstring

saved-jsonclj

(saved-json root records read-turns)
(saved-json root records read-turns secrets)

Encode one saved session and its children as a redacted ATIF document. read-turns gives the turns of one session on demand. Each of secrets, by default run-secrets, becomes [REDACTED].

Encode one saved session and its children as a redacted ATIF document.
`read-turns` gives the turns of one session on demand. Each of `secrets`, by default
[[run-secrets]], becomes `[REDACTED]`.
sourceraw docstring

schema-versionclj

The ATIF version of each trajectory that Vis writes.

The ATIF version of each trajectory that Vis writes.
sourceraw docstring

secret-formsclj

(secret-forms values)

The credentials in values as an export shows them: each value of 8 characters or more, with its JSON-escaped and URL-encoded forms.

The credentials in `values` as an export shows them: each value of 8 characters or
more, with its JSON-escaped and URL-encoded forms.
sourceraw docstring

setting-secretsclj

(setting-secrets settings)

The values of the secret settings in settings, {setting-id value}, with their forms.

The values of the secret settings in `settings`, `{setting-id value}`, with their forms.
sourceraw docstring

write!clj

(write! path document)

Write document to path as JSON and return path. Vis writes a private temporary file next to path, then moves it there, so only the owner can read the trajectory.

Write `document` to `path` as JSON and return `path`. Vis writes a private
temporary file next to `path`, then moves it there, so only the owner can read
the trajectory.
sourceraw docstring

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close