Skip to content

Release v0.2.0

Choose a tag to compare

@homer6 homer6 released this 25 Oct 21:08
· 31 commits to main since this release
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: 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.0 tree has not run on the dev environment. On the dev member of lake-nonprod only
agent-autosuggest had a dev-<sha> pin; every other library agent, Ask Orama included, runs the
operator's default oramasearch/agent-ask-orama:v0.1.0. The browser check of the Quickstart on
lake-dev (lake#1182) was the coordinator's and is not part of this release's proof.

The image

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

docker.io/oramasearch/agent-ask-orama:11013b6@sha256:54b79ed75658a0684923c9965313fd43c4055055c7ad2ba10e832e07b4b46711, also tagged :v0.2.0 (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) 142 tests: 142 passed, 0 failed, 0 skipped. tests/test_agent.py 74, 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.0, these notes exist and are indexed, /healthz reports it with prompt v16)
Offline evals Run inside the test suite (a fake Lake and a scripted model); counted above
Live evals (ask-orama-evals) Not run on v15 or v16 (they need a live model and a person's Lake key)
Linux image build (cluster BuildKit, from the tag) Built from v0.2.0 with build-agent.sh: oramasearch/agent-ask-orama:11013b6, also :v0.2.0, sha256:54b79ed75658a0684923c9965313fd43c4055055c7ad2ba10e832e07b4b46711; private (404 anonymously)