Skip to content

Releases

Release v0.3.0

Choose a tag to compare

@homer6 homer6 released this 16 Nov 07:25
cc43317

Released 2026-11-16. A minor release. The agent's licence and open-source preparation, the image's bases pinned by digest, and the engine-issue link in refusals made a setting, since v0.2.1. Refusals no longer link to a tracker unless one is configured, a change a person can see, which is why this is a minor release and not a patch. Image: docker.io/oramasearch/agent-ask-orama:v0.3.0.

This release is the tree of dev after #66 (50a3a4c), with these notes, the version and the README's release line. The prompt is still v17.

What changed

Every pull request merged into dev since v0.2.1 (git log --first-parent v0.2.1..origin/dev):

PR What it does
#60 Merges main back into dev after the v0.2.1 release; nothing new
#61 Records the v0.2.1 image digest in the v0.2.1 notes; documentation only
#63 Adds a security policy, SECURITY.md: how to report a vulnerability privately, and what we commit to
#64 Pins the Dockerfile's base images (python:3.12-slim, ghcr.io/astral-sh/uv:0.11.7) by digest as well as by tag
#67 Prepares the tree for a public export: the engine-issue link in refusals becomes the ZETTA_ISSUE_URL setting, the reports of an earlier live eval run are removed, and internal links, names and wording are removed from the README, the docs and the release notes
#66 The MIT licence: LICENSE, COPYRIGHT, an SPDX header in every source file, THIRD_PARTY_LICENSES, CONTRIBUTING.md, CLA.md, CODE_OF_CONDUCT.md, and the SBOM (sbom.spdx.json, sbom.cdx.json, tools/sbom.py)

The licence — #66

agent-ask-orama is released under the MIT licence, copyright OramaSearch, Inc. (LICENSE, COPYRIGHT). Every source file carries SPDX-License-Identifier: MIT, added and checked by tools/spdx-headers.py. THIRD_PARTY_LICENSES lists the licence of every dependency. Contributions are made under CLA.md (contributors assign copyright to OramaSearch, Inc.), following CONTRIBUTING.md and CODE_OF_CONDUCT.md. tools/sbom.py writes the software bill of materials in SPDX 2.3 and CycloneDX, regenerated for this release.

A security policy — #63

SECURITY.md says how to report a vulnerability privately and what we commit to in reply.

The engine-issue link is a setting — #67

When Ask Orama says a methodology is not supported yet, it names the engine issue that tracks it (zetta#N). The link to that issue now comes from ZETTA_ISSUE_URL, a template with {n} for the number (for example https://github.com/<owner>/zetta/issues/{n}). Unset, the issue is named without a link, so an install never points people at a tracker it was not given. Prompt v17's one line that carried a fixed tracker address reads the same way; v14 to v16 stay as they were, for trace history.

The eval reports of an earlier live run are removed from reports/; its README says how a report is produced.

The image's bases are pinned by digest — #64

Each FROM and COPY --from names the multi-platform index digest its tag pointed to, so a later build of the same source gets the same base. A new base is a reviewed change of the digest.

Before it rolls: settings

No setting is required. One optional setting is new: ZETTA_ISSUE_URL (above). The settings of v0.2.0 still apply (AGENT_SERVICE_TOKEN and LAKE_URL required, both rendered by the operator). git diff v0.2.1..v0.3.0 -- src adds no other environment read.

Not included

  • Claiming tasks by reference and naming the task on every call (#65, for lake#871): deferred for review, not in this release.
  • No conversation memory across restarts (conversations are in memory, bounded).
  • No explicit workspace ids on data-plane calls, and no idle backoff on the bus.
  • No live eval results for prompts v12 to v17, and no live methodology_draft eval.

Known issues

Security-relevant first. All open at this tag.

  1. The image bundles GPL and LGPL code (#68): it is built on python:3.12-slim (Debian: glibc, bash, coreutils, dpkg, readline), so the image is not published. It moves to scratch with static binaries before it is.
  2. The eval grader passes a reply that names no issue when ZETTA_ISSUE_URL is unset (#69): the grader accepts the issue's name or its link, and with no link configured the empty link matches every reply. One test fails on it: tests/test_agent.py::test_evals_are_generated_from_the_index_and_graded_by_rules.
  3. #12: no explicit workspace_id on data-plane calls and delegations, and no idle backoff on the bus.
  4. #27: the draft's lock hashes are read from pypi.org, not confirmed reachable from the pod, and no live methodology_draft eval.
  5. #25, #23: the live evals have not run on v12 to v17, nor the count evals.
  6. lake#1191: outside the Quickstart, Ask Orama cannot find "the last-uploaded dataset", because list_datasets has no upload time.
  7. #3: models are listed by project id instead of project name.

Where it has run

The v0.3.0 tree had not run on a development environment when it was released. Lakes take the operator's default image; moving it to :v0.3.0 is a separate operator change.

The image

Built from the tag v0.3.0 (cc43317) with BuildKit (linux/amd64, the repository's Dockerfile), then tagged :v0.3.0 on that digest without rebuilding:

docker.io/oramasearch/agent-ask-orama:cc43317@sha256:937e30a4280cb6a86110c031f84ee7ca1048475ea19b373c7192e2feb083783f, also tagged :v0.3.0 (same digest).

Pinning it on a Lake is a separate change to the operator's defaults or the Lake's resource.

Verification

Proof Result
Test suite (uv run --frozen --group dev pytest -q -ra, macOS arm64, Python 3.12, release branch) 146 tests: 145 passed, 1 failed (#69, fails alone too), 0 skipped. tests/test_agent.py 78 (1 failed), tests/test_turn_destinations.py 16, tests/test_conversations.py 13, tests/test_service_auth.py 13, tests/test_methodology_draft.py 7, tests/test_bus_backpressure.py 6, tests/test_conversation_owner.py 5, tests/test_lake_bus.py 5, tests/test_release.py 3 (the installed package is 0.3.0, these notes exist and are indexed, /healthz reports it with prompt v17)
Offline evals Run inside the test suite (a fake Lake and a scripted model); counted above
Live evals (ask-orama-evals) Not run (they need a live model and a person's Lake key)
Version pyproject.toml and uv.lock 0.3.0 (tests/test_release.py)
SPDX headers (python3 tools/spdx-headers.py --check) Passed
SBOM (python3 tools/sbom.py --version v0.3.0 --check) Passed, regenerated for v0.3.0
Dev environment Not run (above)
Linux image build (BuildKit, from the tag) Built from v0.3.0: oramasearch/agent-ask-orama:cc43317, also :v0.3.0, sha256:937e30a4280cb6a86110c031f84ee7ca1048475ea19b373c7192e2feb083783f

Release v0.2.1

Choose a tag to compare

@homer6 homer6 released this 26 Oct 03:02
5f7bf2b

agent-ask-orama v0.2.1

Released 2026-10-25. A patch release. One change since v0.2.0: prompt v17, which
follows Lake's Quickstart after the person confirms a model (lake#1204). Private repository and image,
docker.io/oramasearch/agent-ask-orama:v0.2.1. Tracking issue:
#57.

It is a patch: no setting, route or turn shape changes for a caller. With an older Lake the turn
behaves as in v16.

This release is the tree of dev at 3c9685c (everything in the table below) with these notes, the
version and the README's release line.

What changed

Every pull request merged into dev since v0.2.0:

PR Change
#56 Prompt v17: follows the Quickstart after a confirm (says what started and what comes next, reads quickstart_status when asked about progress, proposes the corrected train_quickstart as a card after a failure, never tells the person to configure an engine setting). lake#1204
#55 Records the v0.2.0 image digest in the v0.2.0 notes
#54 Merges main back into dev after v0.2.0

Prompt v17: following the Quickstart after a confirm (#56)

On lake-dev, after Steve confirmed a clustering model, Ask Orama answered "Done: train_quickstart."
and, asked whether training had finished, told him to "configure the segmentation K range", which a
person cannot do. v17 is v16 plus Following the Quickstart after a confirm:

  • after a confirm, it says what started and what comes next, never "Done: train_quickstart";
  • asked about progress, it reads quickstart_status for the page's quickstart_id in the same turn;
  • after a failure (quickstart_state: failed, a failed proposal, or the person saying so), it says
    why in the person's words (model_problem) and proposes the corrected train_quickstart as a card;
  • it never tells the person to "configure" graph hints, a K range, a holdout or any engine setting.

quickstart_text reads Lake's new page keys (quickstart_state, model, model_problem,
quickstart_next) and gives the training, failed and done states their own direction. The deciding
state is unchanged. PROMPT_VERSION is v17; v14 to v16 stay in prompts/. See
docs/quickstart/.

Before it rolls: settings

No new setting. The settings of v0.2.0 still apply
(AGENT_SERVICE_TOKEN and LAKE_URL required, both rendered by the operator).

v17 needs the Lake that sends the Quickstart's state on each turn:
lake#1213, merged into lake's dev on 2026-10-25 and
not in a lake release yet (lake v0.7.0 does not have it). Against an older Lake the page carries no
quickstart_state and every Quickstart turn is treated as deciding, as in v16.

Not included

Unchanged from v0.2.0:

  • no conversation memory across restarts (conversations are in memory, bounded);
  • no explicit workspace ids on data-plane calls, and no idle backoff on the bus
    (#12);
  • no startup failure when AGENT_SERVICE_TOKEN is missing, and no per-service or per-launch
    authentication (#45);
  • no live eval results for prompts v12 to v17, and no live methodology_draft eval.

Known issues

Security-relevant first. All open at this tag.

  1. #45 (LSR-180, low): the service starts
    without a token, and the token is one shared credential, not per service or per launch.
  2. Lake-side findings that reach this agent, open in other repos:
    lake#922 (LSR-013),
    lake#985 (LSR-118),
    lake#989 (LSR-183),
    orama-operator#793 (LSR-044).
  3. #12: no explicit workspace_id on
    data-plane calls and delegations, and no idle backoff on the bus.
  4. #27: the draft's lock hashes are read
    from pypi.org, not confirmed reachable from the pod, and no live methodology_draft eval.
  5. #25,
    #23: the live evals have not run on
    v12 to v17, nor the count evals. v17 has not been run against a live Lake carrying lake#1213.
  6. lake#1191: outside the Quickstart, Ask Orama
    cannot find "the last-uploaded dataset", because list_datasets has no upload time.
  7. #3: models are listed by project id
    instead of project name.

Where it has run

The v0.2.1 tree has not run on the dev environment. At this tag the dev member of
lake-nonprod pins oramasearch/agent-ask-orama:7a044af (the v0.2.0 tree, prompt v16); no build of
#56 has been pinned there. Steve asked for the release on 2026-10-25 ("merge it all, cut releases,
push all to nonprod"
), together with the lake change it pairs with.

The image

Built from the tag v0.2.1 (5f7bf2b) on the cluster BuildKit with build-agent.sh (linux/amd64, the
repository's Dockerfile), then tagged :v0.2.1 on that digest without rebuilding:

docker.io/oramasearch/agent-ask-orama:5f7bf2b@sha256:577fe7778fa532e962d958f35cb5c8f00132c782e36ccd1c0e5cbb38a56f9301, also tagged :v0.2.1 (same digest). The Docker Hub
repository answers 404 anonymously (private).

It is not rolled anywhere yet: pinning it on an environment is a separate change to the operator's set
files, through dev, testing, staging and prod in order.

Verification

Proof Result
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12.11, release branch) 145 tests: 145 passed, 0 failed, 0 skipped. tests/test_agent.py 77 (3 new for v17), tests/test_turn_destinations.py 16, tests/test_conversations.py 13, tests/test_service_auth.py 13, tests/test_methodology_draft.py 7, tests/test_bus_backpressure.py 6, tests/test_conversation_owner.py 5, tests/test_lake_bus.py 5, tests/test_release.py 3 (the installed package is 0.2.1, these notes exist and are indexed, /healthz reports it with prompt v17)
Offline evals Run inside the test suite (a fake Lake and a scripted model); counted above
Live evals (ask-orama-evals) Not run on v17 (they need a live model, a person's Lake key and a Lake with lake#1213)
Linux image build (cluster BuildKit, from the tag) Built from v0.2.1 with build-agent.sh: oramasearch/agent-ask-orama:5f7bf2b, also :v0.2.1, sha256:577fe7778fa532e962d958f35cb5c8f00132c782e36ccd1c0e5cbb38a56f9301; private (404 anonymously)

Release v0.2.0

Choose a tag to compare

@homer6 homer6 released this 25 Oct 21:08
11013b6

agent-ask-orama v0.2.0

Released 2026-10-25. A minor release. Seven pull requests since v0.1.1: the
2026-10-21 security-review fixes (five findings), prompt v15 (propose only what can work) and
prompt v16 (Lake's Quickstart model step). Private repository and image,
docker.io/oramasearch/agent-ask-orama:v0.2.0. Tracking issue:
#51.

It is a minor release, not a patch, because three behaviours change for a caller: a turn is refused
when AGENT_SERVICE_TOKEN or LAKE_URL is missing, a turn's own lake_url is ignored, and a
conversation continues only through Lake's prior_turn on the bus (a direct /v1/turn call keeps
no conversation).

This release is the tree of dev at 7a044af (everything in the table below) with these notes, the
version and the README's release line.

What changed

PR Change
#38 The service token is compared in constant time, and every turn is refused (503) when AGENT_SERVICE_TOKEN is unset or empty (it used to be open). Issue #37
#40 A turn's credential goes only to this service's own LAKE_URL; the turn's lake_url is ignored, and a turn is refused when LAKE_URL is unset or not an absolute http(s) URL. Issue #39
#46 LSR-008: a conversation is keyed by Lake's claim (customer, workspace, task) and continues only when Lake's prior_turn names the task that last continued it, never by a named conversation_id. Issue #42
#47 LSR-075: the bus worker claims a task only when a worker is free to run it, with a fair share per customer. Issue #43
#48 LSR-076: conversation memory is bounded (count, turns, bytes, idle expiry), a failed turn leaves the history as it was, and no trace file is written per turn. Issue #44
#49 Prompt v15: only proposals that can work, one proposal for a new project, and Lake's record of each earlier proposal (lake#1193, lake#1194)
#50 Prompt v16: the Quickstart's model step answered from the dataset, ideas first (lake#1182)

Security-review fixes

These come from the Lake pre-launch security review
(epic orama-bridge#223, this repo's
findings in #41).

  • Service token (#38). POST /v1/turn checks the bearer with hmac.compare_digest. A wrong or
    missing bearer is 401; with no token configured every turn is 503.
  • Credential destination (#40). Every Lake read and the model gateway use LAKE_URL with the
    turn's bearer. A turn that names another host, scheme or port is served from LAKE_URL anyway.
  • Conversation ownership (#46). lake_bus.turn_body passes the claim reply's task_id,
    customer_id and workspace_id to the turn as claim. Another account, a member using another
    kind, an invalid claim and every direct /v1/turn call start a new, empty conversation. The
    body's conversation_id is still echoed, never used as a memory key.
  • Bus backpressure (#47). A slot is taken before claim_agent_task; while every worker is busy
    nothing more is received. One customer holds at most workers - 1 workers. At most 256 dispatch
    rows (no body, no credential) wait in the process.
  • Bounded memory, no trace on disk (#48). Least recently used conversations and the oldest whole
    turns are dropped past the limits below. A turn logs one line (trace_id, kind, prompt version,
    conversation id, rounds, outcome), never the message, the answer or the key. TRACE_DIR is
    ignored and the Dockerfile no longer sets it.

Prompt v15: propose only what can work (#49)

On lake-dev Ask Orama proposed compile_intent on a project that did not exist, then pointed the
person back at the failed proposal. v15:

  • reads the project a proposal names before recording it (get_project as the person) and refuses
    a missing one in the turn, with how to go on; a compile_pipeline with create_project for a
    taken name is refused as conflict;
  • proposes a new project's pipeline as one compile_pipeline with create_project: true;
  • reads Lake's record of the conversation's proposals (context.proposals: pending, confirmed,
    failed with its error, withheld) as the truth, so after a failure "create it then" gets a new,
    corrected proposal; a reply that points at a failed proposal is corrected once.

See docs/proposals/.

Prompt v16: the Quickstart's model step (#50)

v16 is v15 plus the Quickstart (lake#1182). A turn whose page has quickstart_id carries the
dataset, its columns and the index, and:

  • the dataset is known, so it never asks which one;
  • it leads with ideas tied to the columns: a yes-or-no model, a derived target, M-3 clustering,
    Auto-Suggest opportunities, an analysis, an Application Agent app such as a dashboard;
  • it proposes the strongest model at once as train_quickstart, so one Confirm starts it; a bundle
    is separate proposals; a generated corpus only when nothing else fits or the person asks.

Outside the Quickstart too, "what could I build?" is answered with ideas, never routed to a corpus
agent. See docs/quickstart/. v14 and v15 stay in prompts/.

Before it rolls: settings

Setting Needed Who sets it
AGENT_SERVICE_TOKEN Required now: unset or empty refuses every turn (503) The operator, already (a generated random token)
LAKE_URL Required now: unset or not an absolute http(s) URL refuses every turn The operator, already
AGENT_MODEL Unchanged The operator, already
ASK_ORAMA_CONVERSATIONS (256), ASK_ORAMA_CONVERSATION_TURNS (20), ASK_ORAMA_CONVERSATION_BYTES (1 MiB), ASK_ORAMA_CONVERSATIONS_BYTES (64 MiB), ASK_ORAMA_CONVERSATION_IDLE_SECONDS (3600) Optional; defaults apply Nobody today
AGENT_BUS_WORKERS (4), AGENT_BUS_TENANT_WORKERS (workers - 1) Optional; defaults apply Nobody today
TRACE_DIR No longer read The operator still sets it and a /tmp volume; both are unused

Nothing new is needed from the operator. v15 and v16 work best with the Lake that carries
lake#1198 (compile_pipeline's create_project,
context.proposals on each turn) and lake#1199 (the
Quickstart conversation, derived_target and M-3 on train_quickstart). Both are merged into lake's
dev and are not in a lake release yet (lake v0.7.0 has neither). Against an older Lake: a new
project's proposal is withheld by Lake's schema, the turn has no proposal record to read, and a
Quickstart proposal with derived_target or M-3 is withheld with the reason. The agent's own
project check works with any Lake.

Not included

  • No conversation memory across restarts: conversations are in memory, now bounded.
  • No explicit workspace ids on data-plane calls, and no idle backoff on the bus
    (#12).
  • No startup failure when AGENT_SERVICE_TOKEN is missing (turns are refused instead), and no
    per-service or per-launch authentication (#45).
  • No live eval results for prompts v12 to v16, and no live methodology_draft eval.

Known issues

Security-relevant first. All open at this tag.

  1. #45 (LSR-180, low): the two
    request-side parts are fixed here (#38 refuses turns with an empty token; #40 pins Lake's
    address to LAKE_URL). Still open: the service starts without a token, and the token is one
    shared credential, not per service or per launch.
  2. Lake-side findings that reach this agent, open in other repos:
    lake#922 (LSR-013, a delegated turn is not
    attenuated to the parent task), lake#985
    (LSR-118, task credentials keep cross-account repository reads),
    lake#989 (LSR-183, confirmation gates do not
    establish a separate human confirmer),
    orama-operator#793 (LSR-044, the
    shared agent-service credential).
  3. #12: no explicit workspace_id on
    data-plane calls and delegations, and no idle backoff on the bus.
  4. #27: the draft's lock hashes are read
    from pypi.org, not confirmed reachable from the pod, and no live methodology_draft eval.
  5. #25,
    #23: the live evals have not run on
    v12 to v16, nor the count evals.
  6. [lake#1191](https://github.com/oramasea...
Read more

Release v0.1.1

Choose a tag to compare

@homer6 homer6 released this 20 Oct 02:31
4283ce5

agent-ask-orama v0.1.1

Released 2026-10-19. A patch release. One change since v0.1.0: prompt v14, which
answers questions about using Lake from Lake's own Docs. Private repository and image,
docker.io/oramasearch/agent-ask-orama:v0.1.1.

This release is the tree of dev at 4058229 (v0.1.0, the v0.1.0 image digest in its notes
(#32), and
#33) with these notes and the version.

What changed

How-to questions are answered from the Docs (prompt v14) — #33

"How do I load my first dataset?", the first suggestion on Lake's home, was answered with a "Lake
Console → datasets" page, an "Upload dataset" button and Parquet, none of which Lake has
(lake#817). Prompt v14 adds Questions about using
Lake: answer from the Docs
:

  • read list_docs with the subject's words, then get_doc, and answer from that guide; say so when
    no guide covers the question;
  • name pages, tabs and buttons exactly as the guide and the navigation show them, as an arrow path
    (Data → Datasets → Load data → Upload), and never invent or rename one;
  • link each page and the guide;
  • name only the formats and limits the guide states.

v14 also says "in Lake" where v13 said "in Lake Console". v13 is kept in prompts/. Both Docs
capabilities are public reads, so the turn can call them with the person's key; nothing new is
written.

It pairs with lake#830, in lake
v0.3.0, which makes the Datasets guide
carry the exact answer. Against an older Lake the agent still reads that Lake's guide.

A how_to eval case

evals.py grades the home's question by rules: the answer must read the Docs, name and link
Data → Datasets → Load data (/train/data), and name no refused format and no "Lake Console"
page. A sentence that turns a person away from a refused format ("Parquet is not accepted: save it as
CSV first") does not count as offering it. See docs/how-to/README.md.

Not included

Unchanged from v0.1.0: no conversation memory across restarts,
no explicit workspace ids, no idle backoff on the bus, no live methodology_draft eval, and no
live eval results for prompts v12, v13 or v14.

Known issues

Security-relevant first. All open at this tag; none is new.

  1. #12: no explicit workspace_id on
    data-plane calls and delegations, and no idle backoff on the bus.
  2. #27: the draft's lock hashes are read
    from pypi.org, not confirmed reachable from the pod, and no live methodology_draft eval.
  3. #25,
    #23: the live evals have not run on
    v12, v13 or v14, nor the count evals.
  4. #3: models are listed by project id
    instead of project name.
  5. The how_to eval's refusal check is a word list: "Parquet is unsupported" still counts as
    offering Parquet. It errs strict.

Where it runs

Nowhere yet. The operator's default Agent Library (orama-operator internal/controller/lake_defaults.go
on dev) names oramasearch/agent-ask-orama:v0.1.0, which every LakeSet member takes. Moving it to
:v0.1.1 is a separate operator change, rolled through dev → testing → staging → prod.

The image

Built from the tag v0.1.1 (4283ce5) on the cluster BuildKit with build-agent.sh (linux/amd64,
the same Dockerfile as v0.1.0), then tagged :v0.1.1 on that digest without rebuilding:

docker.io/oramasearch/agent-ask-orama:4283ce5@sha256:8a9166ace9aa96be0b12b7f93b51a8a345cfed4b426390058b4e930aca8f400b,
also tagged :v0.1.1 (same digest). The Docker Hub repository answers 404 anonymously (private).

Verification

Proof Result
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12) 80 tests: 80 passed, 0 failed, 0 skipped. tests/test_agent.py 65 (two new: the v14 rules are in the prompt; the how_to grader fails the recorded lake-dev answer on all five rules and passes a Docs-based one, including a refusal of Parquet), tests/test_methodology_draft.py 7, tests/test_lake_bus.py 5, tests/test_release.py 3 (the installed package is 0.1.1, these notes exist and are indexed, /healthz reports it)
Offline evals Run inside the test suite (a fake Lake and a scripted model); counted above
Live evals (ask-orama-evals) Not run on v14 (needs a live model and a person's Lake key)
Linux image build (cluster BuildKit, from the tag) Built from v0.1.1 with build-agent.sh: oramasearch/agent-ask-orama:4283ce5, also :v0.1.1, sha256:8a9166ace9aa96be0b12b7f93b51a8a345cfed4b426390058b4e930aca8f400b; private (404 anonymously)

Release v0.1.0

Choose a tag to compare

@homer6 homer6 released this 17 Oct 22:55
c2a4752

agent-ask-orama v0.1.0

Released 2026-10-17. The first release. One Python service, agent-ask-orama, and one private
image, docker.io/oramasearch/agent-ask-orama:v0.1.0. Proprietary to Orama; private repository and
image.

Ask Orama is the general agent for all of Lake (lake#228,
zetta#1018) and the first entry of Lake's Agent
Library. Lake shows it as a panel on every page and sends it every message asked there. It works as
the person who asked, with the key Lake delegates for that turn and never a credential of its own. It
reads whatever Lake capability that person may read, proposes every change (Lake runs it only
when the person confirms), and delegates to the specialized library agents and to agents the
person built, through Lake. It also writes the first draft of a workspace methodology for Lake's New
Methodology drawer.

This release is the tree of dev at 591e662 (main 6baa70d plus
#29, prompt v13) with these notes, the
release test and the version field of GET /healthz added.

What it includes

The conversational turn (prompt v13)

agent.py runs one turn as a tool loop of at most MAX_ROUNDS = 10 model rounds. The active prompt
is PROMPT_VERSION = "v13" (prompts/v13.md); v1 to
v12 stay in the package for trace history (prompts).

At the start of every turn it reads, as the person:

  • Lake's /v1/openapi.json, from which the capability index is derived: every capability Lake
    serves, including every workspace engine capability by its own name (lake#650), less the
    ceremonies a person performs, named one by one in EXCLUDED_CAPABILITIES (signing up and in,
    second factors, account and key recovery, minting certificates, SVIDs, JWTs, grants, session keys
    and sealed secrets, decrypt and read_secret). On an older Lake without named engine
    capabilities, engine calls go through workspace_query / workspace_act by the engine's name.
    (capabilities)
  • list_mcp_connection_tools {allowed_only: true}: the workspace's allowed connected MCP tools,
    added to the instructions by their <prefix>__<tool> name (lake#652; MCP).

The model has five tools:

Tool What it does
lake_read {capability, input?} Calls a Lake read as the person (GET or POST as the OpenAPI says), adding the turn's customer_id. A capability that changes something is refused and must be proposed
lake_propose {capability, input, impact} Records a proposal in the answer. Nothing is sent to Lake; the person confirms it in Lake
compare_models {project?} Every trained model (or one project's) from list_models, ranked by held-out score, best first, in one read (agent-ask-orama#14; models)
mcp_tool {tool, arguments?, impact?} A connected tool: a read runs through Lake's read_mcp_tool and its answer is marked as data from an outside server, never instructions; a change is only proposed, as call_mcp_tool
delegate {agent, request, kind?, context?} Lake's agent_turn to another agent, then follows the returned task with receive_agent_events for up to FOLLOW_SECONDS = 240

Behavior the code enforces on those tools:

  • Delegation targets, under lake#763's names: agent-project (Project Agent, Pipelines),
    agent-autosuggest (Auto-Suggest Agent, Opportunities), agent-application (Application Agent,
    always sent as kind app), agent-experiments (Experiments Agent, which requires kind
    experiment, experiment_status or experiment_explain), agent-eval-generator (Eval Generator
    Agent), agent-autosuggest-corpus and agent-project-corpus (the corpus agents,
    agent-ask-orama#28), and any agent the person built, by id. A context carrying
    confirmed_proposal or confirmed_promotion is refused: only Lake forwards a confirmed experiment
    object (experiments, apps,
    agents).
  • Methodologies: a proposal naming a methodology is refused unless this turn's
    list_methodologies registry marks it runnable; an older engine without the registry is treated
    as supporting only M-1 churn / GBDT classification (methodologies).
  • Solutions: solution reads (get_solution, get_policy, get_experiment, list_ledger,
    get_monitor, get_roi_readout) and solution actions (create_solution, run_solution,
    create_policy, update_policy, decide, approve_decision) need this turn's list_solutions
    read first; a sketch or a missing foundation is refused with its condition
    (solutions).
  • Long reads are trimmed by their items with each list's exact count, a paged answer's total
    and cursor are kept, and a value with no list is cut with a note (OBSERVATION_LIMIT = 20000
    characters; agent-ask-orama#21, reads).
  • Agent pages: a turn asked from /design/agents, /design/agent, /train/agents or
    /train/agent tells the model whether the person is designing or training an agent (lake#653).
  • A turn out of tool rounds ends with an honest partial answer, marked incomplete: true, and
    is a failure, never a success (agent-ask-orama#14).

The methodology_draft turn (lake#688)

methodology_draft.py, prompt DRAFT_PROMPT_VERSION = "methodology_draft_v1". Lake's New
Methodology drawer sends a turn of kind methodology_draft with the person's description and
context: {name?, target_kind?}. The answer is three files: methodology.json, methodology.py
(fit, predict and score at module level) and requirements.lock, whose every pin carries the
SHA-256 of each wheel looked up at https://pypi.org/pypi/<name>/<version>/json (the model never
writes a hash). The draft is checked the way Lake's Validate checks it; a failing draft gets one
repair round (MAX_ROUNDS = 2), then is answered ok: false with its findings. Nothing is written:
the person reviews it and Lake's Create commits it.

The model, through Lake

Every model call of a turn goes to <lake_url>/openai/v1 with the turn's own lake_token as the API
key (model.py, lake#248), so Lake counts the tokens in the turn's workspace and enforces the
account's model-token limit. The service holds no provider key. The model is ASK_ORAMA_MODEL
(default gpt-5.5).

HTTP API

agent-ask-orama-serve, standard library ThreadingHTTPServer on 0.0.0.0:$PORT (8080):

Route Request Answer
GET /healthz none {ok, agent, version, model, prompt_version}; version is new in this release, read from the installed package
POST /v1/turn {conversation_id?, message, lake_token, customer_id, page?, lake_url?, kind?, context?}; with AGENT_SERVICE_TOKEN set, Authorization: Bearer <token> is required (otherwise 401) A turn: {ok, conversation_id, trace_id, reply, reads, proposals, delegations, rounds, incomplete}. With kind: "methodology_draft": {ok, rounds, reply, result: {kind, name, reason, files, findings, prompt_version}, conversation_id, trace_id} or {ok: false, findings, error}. HTTP 200 when ok, 422 otherwise (including a turn out of rounds, whose partial answer is error), 400 for a body that is not JSON, 404 for any other route

A turn without message, lake_token or a Lake address (lake_url or LAKE_URL) answers
ok: false. Conversations are kept in memory by conversation_id. Every turn writes a trace JSON
file to TRACE_DIR (the message, page, answer and prompt version; never the key).

The agent bus (how turns arrive)

lake_bus.py starts a background thread when LAKE_URL, AGENT_BUS_TOKEN and AGENT_BUS_AGENT are
set (the agent name defaults to agent-ask-orama); without them it logs that the bus is not
configured and only /v1/turn serves. Every bus call goes through Lake's HTTP API with the agent's
own bus credential as the bearer; the agent never holds the bus's token:

  1. GET /v1/receive_agent_tasks {agent, from_sequence, wait_ms: 10000} long-polls the
    agent-tasks.<agent> topic on Lake's own Zetta, whose messages carry task ids, never content. It
    starts at sequence 1 on every start and continues from next_sequence; a failed receive is
    retried after 2 seconds.
  2. POST /v1/claim_agent_task {task_id, agent} for each task. A conflict or not_found (another
    replica, or a finished task) is skipped. The claim's answer is the turn's body, carrying the
    task's own credential as lake_token.
  3. The turn runs exactly as POST /v1/turn would, on a pool of 4 workers.
  4. POST /v1/publish_agent_event publishes progress ("Working on it"), then result with the
    whole answer, or failed with the error (a turn out of rounds is failed). An exception in a
    turn is an answer, never a dead worker.

The agent sends no workspace_id on these calls and does not renew its claim's lease itself: Lake
takes the workspace from the task row and its credential (lake docs/api/agent-bus.md).

C...

Read more