Repository navigation
Release v0.2.0
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/turnchecks the bearer withhmac.compare_digest. A wrong or
missing bearer is401; with no token configured every turn is503. - Credential destination (#40). Every Lake read and the model gateway use
LAKE_URLwith the
turn's bearer. A turn that names another host, scheme or port is served fromLAKE_URLanyway. - Conversation ownership (#46).
lake_bus.turn_bodypasses the claim reply'stask_id,
customer_idandworkspace_idto the turn asclaim. Another account, a member using another
kind, an invalid claim and every direct/v1/turncall start a new, empty conversation. The
body'sconversation_idis 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 mostworkers - 1workers. 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_DIRis
ignored and theDockerfileno 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_projectas the person) and refuses
a missing one in the turn, with how to go on; acompile_pipelinewithcreate_projectfor a
taken name is refused asconflict; - proposes a new project's pipeline as one
compile_pipelinewithcreate_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_TOKENis 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_drafteval.
Known issues
Security-relevant first. All open at this tag.
- #45 (LSR-180, low): the two
request-side parts are fixed here (#38 refuses turns with an empty token; #40 pins Lake's
address toLAKE_URL). Still open: the service starts without a token, and the token is one
shared credential, not per service or per launch. - 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). - #12: no explicit
workspace_idon
data-plane calls and delegations, and no idle backoff on the bus. - #27: the draft's lock hashes are read
frompypi.org, not confirmed reachable from the pod, and no livemethodology_drafteval. - #25,
#23: the live evals have not run on
v12 to v16, nor the count evals. - lake#1191: outside the Quickstart, Ask Orama
cannot find "the last-uploaded dataset", becauselist_datasetshas no upload time. - #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) |