Repository navigation
Releases
Release v0.3.1
Released 2026-11-16. A patch release. The README no longer references internal issues, since v0.3.0. Nothing the agent does has changed. Image: docker.io/oramasearch/agent-autosuggest:v0.3.1.
This release is the tree of dev after #41 (e89830a), with these notes and the version.
What changed
Every pull request merged into dev since v0.3.0 (git log --first-parent v0.3.0..origin/dev):
| PR | What it does |
|---|---|
| #40 | Records the v0.3.0 image digest in the v0.3.0 notes; documentation only |
| #41 | Cleans the README: the internal issue references are removed, and a duplicated line in A turn keeps nothing on the pod is dropped |
No source file under src/ changed, the Dockerfile is unchanged, and no setting is new or removed (git diff v0.3.0..v0.3.1 -- src Dockerfile is empty).
Not included
- Claiming tasks by reference and naming the task on every call (#34): deferred for review, not in this release.
- Unchanged from v0.3.0 otherwise.
Known issues
Security-relevant first. Unchanged from v0.3.0.
- The image bundles GPL and LGPL code (#37): it is built on
python:3.12-slim(Debian: glibc, bash, coreutils, dpkg, readline). The move toscratchwith static binaries is deferred; it is noted here and does not block this release. - Library agents hold live task credentials for every tenant they serve: one shared pod runs every tenant's turns with their task credentials.
- The workspace is not passed explicitly (#11): the agent sends only
customer_idon its reads, never the task'sworkspace_id. - The lease is kept by activity only. Lake renews a claim's lease on every capability call made with the task credential, so a turn is reclaimed only if one step outlasts
lease_seconds. Not observed. - The command line validates without workspace evidence (#14).
- Corpus drafts fail validation: the corpus's examples do not choose a registry level for S-1. The image keeps the
a882954corpus.
Where it has run
The v0.3.1 tree had not run on a development environment when it was released. Lakes take the operator's default image; moving it to :v0.3.1 is a separate operator change.
The image
Built from the tag v0.3.1 (c630000) with BuildKit (linux/amd64, the repository's Dockerfile, with the same contexts as v0.3.0: the catalog context catalog-cf20d264 and the corpus context agent-autosuggest-corpus-a882954), then tagged :v0.3.1 on that digest without rebuilding:
docker.io/oramasearch/agent-autosuggest:c630000@sha256:8908162a6d34a8a928fd41c18b8a50c5033d5fb7a623d20491e3ae06640e682f, also tagged :v0.3.1 (same digest). The image is published on Docker Hub; its GPL/LGPL base is a known issue (#37).
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, on the release branch) |
78 tests: 78 passed, 0 failed, 0 skipped. test_service.py 17, test_turn_destinations.py 15, test_service_auth.py 13, test_lake_1153_shapes.py 7, test_bus_backpressure.py 6, test_solution_evals.py 5, test_lake_bus.py 4, test_apps.py 3, test_solutions.py 3, test_app_evals.py 2, test_release.py 2, test_catalog.py 1 |
| Offline evals (no model) | evals/runtime-solutions.jsonl and evals/data-apps.jsonl, run through enforcement and validation inside the suite above; all pass |
| Version | pyproject.toml and uv.lock 0.3.1; the installed package reports it and these notes exist and are indexed (tests/test_release.py) |
SPDX headers (python3 tools/spdx-headers.py --check) |
Passed |
SBOM (python3 tools/sbom.py --version v0.3.1 --check) |
Passed, regenerated for v0.3.1 |
| Live-model evals | Not run (needs a live model) |
| Dev environment | Not run (above) |
| Linux image build (BuildKit, from the tag) | Built from v0.3.1 (c630000): oramasearch/agent-autosuggest:c630000, also :v0.3.1, sha256:8908162a6d34a8a928fd41c18b8a50c5033d5fb7a623d20491e3ae06640e682f |
Release v0.3.0
Released 2026-11-16. A minor release. The agent's licence and open-source preparation, the bus consumer bounded so a task is claimed only when a worker is free, and the image's bases pinned by digest, since v0.2.0. The bounded bus changes behaviour a caller can see and adds settings, which is why this is a minor release and not a patch. Image: docker.io/oramasearch/agent-autosuggest:v0.3.0.
This release is the tree of dev after #35 (24121d0), with these notes and the version (#38).
What changed
Every pull request merged into dev since v0.2.0 (git log --first-parent v0.2.0..origin/dev):
| PR | What it does |
|---|---|
| #28 | Merges main back into dev after the v0.2.0 release; nothing new |
| #29 | Records the v0.2.0 image digest in the v0.2.0 notes; documentation only |
| #32 | Adds a security policy, SECURITY.md: how to report a vulnerability privately, and what we commit to |
| #33 | 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 |
| #31 | Claims a bus task only when a worker is free to run it, and limits one customer's share of the workers |
| #36 | 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) |
| #35 | Prepares the tree for a public export: internal links, names and wording removed from the README, the docs and the release notes |
The licence — #36
agent-autosuggest 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 runtime 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 — #32
SECURITY.md says how to report a vulnerability privately and what we commit to in reply.
A bus task is claimed only when a worker is free — #31
- Nothing is received while every worker is busy, so claimed tasks (and their credentials) no longer pile up in memory, and a task this replica cannot run stays unclaimed on the bus for another replica.
AGENT_BUS_WORKERS(default 4) run at once; one customer holds at mostAGENT_BUS_TENANT_WORKERS(default one fewer), and a freed worker goes to the waiting customer holding the fewest, so one tenant's burst cannot take every worker.- At most 256 dispatch rows wait, never a claimed body. The receive uses the long poll's
wait_ms.
The image's bases are pinned by digest — #33
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.
Prepared for a public export — #35
Links to issues and pull requests, internal names, local paths and wording are removed from the README, the docs and the earlier release notes. The agent files (AGENTS.md) ship with the repository.
Behaviour changes to know before it rolls
- The bus consumer runs at most
AGENT_BUS_WORKERSturns at once and leaves the rest on the bus, unclaimed. - One customer holds at most
AGENT_BUS_TENANT_WORKERSworkers while others wait.
Settings it needs
No setting is required. Two optional settings are new, each with the default above: AGENT_BUS_WORKERS and AGENT_BUS_TENANT_WORKERS. git diff v0.2.0..v0.3.0 -- src adds no other environment read.
Not included
- Claiming tasks by reference and naming the task on every call (#34, for lake#871): deferred for review, not in this release.
- Unchanged from v0.2.0 otherwise, except that bus back-pressure is now included.
Known issues
Security-relevant first.
- The image bundles GPL and LGPL code (#37): it is built on
python:3.12-slim(Debian: glibc, bash, coreutils, dpkg, readline), so the image is not published. It moves toscratchwith static binaries before it is. - Library agents hold live task credentials for every tenant they serve: one shared pod runs every tenant's turns with their task credentials.
- The workspace is not passed explicitly (#11): the agent sends only
customer_idon its reads, never the task'sworkspace_id. - The lease is kept by activity only. Lake renews a claim's lease on every capability call made with the task credential, so a turn is reclaimed only if one step outlasts
lease_seconds. Not observed. - The command line validates without workspace evidence (#14).
- Corpus drafts fail validation: the corpus's examples do not choose a registry level for S-1. The image keeps the
a882954corpus.
Closed since v0.2.0: #23 (the bus claimed tasks before a worker was free), by #31.
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 with BuildKit (linux/amd64, the repository's Dockerfile, with the catalog context catalog-cf20d264 and the corpus context agent-autosuggest-corpus-a882954), then tagged :v0.3.0 on that digest without rebuilding:
docker.io/oramasearch/agent-autosuggest:9d38f4e@sha256:865cb6d404a05b3a8e0597cf9e2973865862dddd6f72e323a1e79c4b4dcd47f8, 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, on the release branch) |
78 tests: 78 passed, 0 failed, 0 skipped. test_service.py 17, test_turn_destinations.py 15, test_service_auth.py 13, test_lake_1153_shapes.py 7, test_bus_backpressure.py 6 (new), test_solution_evals.py 5, test_lake_bus.py 4, test_apps.py 3, test_solutions.py 3, test_app_evals.py 2, test_release.py 2, test_catalog.py 1 |
| Offline evals (no model) | evals/runtime-solutions.jsonl and evals/data-apps.jsonl, run through enforcement and validation inside the suite above; all pass |
| Version | pyproject.toml and uv.lock 0.3.0; the installed package reports it and these notes exist and are indexed (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 |
| Live-model evals | Not run (needs a live model) |
| Dev environment | Not run (above) |
| Linux image build (BuildKit, from the tag) | Built from v0.3.0 (9d38f4e): oramasearch/agent-autosuggest:9d38f4e, also :v0.3.0, sha256:865cb6d404a05b3a8e0597cf9e2973865862dddd6f72e323a1e79c4b4dcd47f8 |
Release v0.2.0
agent-autosuggest v0.2.0
Released 2026-10-25. A minor release. Four changes since v0.1.0: a churn solution
whose feature plans are ready is suggested instead of declined (prompt v5), and the three fixes
from the 2026-10-21 security review. Private repository and image,
docker.io/oramasearch/agent-autosuggest:v0.2.0. Tracking issue:
#25.
This release is the tree of dev at 9b45383 (the merge of #18) with these notes and the version.
What it includes
Every pull request merged into dev since v0.1.0 (git log --first-parent v0.1.0..origin/dev):
| PR | Change |
|---|---|
| #24 | Suggest a churn solution whose feature plans are ready, instead of declining it as "transform first" (lake#1153); prompt v5 |
| #20 | POST /v1/turn compares the service token in constant time, and refuses every turn when AGENT_SERVICE_TOKEN is unset (#19) |
| #22 | A turn's credential is sent only to Lake at the service's own LAKE_URL (#21) |
| #18 | A turn keeps no trace on the pod's disk (#13) |
| #17, #16 | The v0.1.0 image digest in its notes, and the v0.1.0 release merge brought back into dev |
Ready data is suggested, and a real transform names its Lake capability (prompt v5) — #24
Scan my workspace suggested nothing on lake-dev: it declined every churn table and asked for an
"approved snapshot/as_of setup" Lake has no way to make
(lake#1153).
solutions.enforce: a runnable solution the model declines as "transform first" is suggested
instead when every methodology at the chosen level plansreadyon one dataset
(methodologies.ready_dataset). The model's preparation becomes arequired_firststep, and the
grounding names the dataset and the cutoff Lake inferred (inferred.as_of).methodologiesreads zetta's realtransform_requiredshape and Lake'sperformed_by. A real
transform is declined astransform first: <name>: <description>. Lake does it with <capability>.
Withoutperformed_bythe agent falls back to the same mapping.validate: a "transform first" that names no Lake capability (plan_features,upload_dataset,
workspace_sql,create_dataset_from_query,generate_dataset) is a defect, handed back in the
repair round.- Prompt
v5(PROMPT_VERSION = "v5"): a ready composition is suggested with its preparation in
required_first; thetimerole is met by a snapshot column or a declaredas_of; "approved
snapshot" requests are forbidden.v4is kept inprompts/.
It pairs with lake#1189 (plan_features from a
dataset alone, with its snapshot cutoff, and performed_by). Against a Lake without it, a table with
a date column still plans transform_required; the agent then declines it naming
plan_features/upload_dataset, but suggests nothing for it.
The service token is compared in constant time and always required — #20
turn_refusal() checks the bearer with hmac.compare_digest over bytes. With
AGENT_SERVICE_TOKEN unset or empty, POST /v1/turn answers 503 to every turn (in v0.1.0 the
route was open). A wrong or missing bearer is 401, as before. Turns from Lake's agent bus are
unaffected.
A turn's credential goes only to the service's own LAKE_URL — #22
In v0.1.0 a turn's lake_url and zetta_base_url chose where the turn's bearer was sent.
- The model gateway and Lake's capabilities (
workspace_query,list_apps, ...) are always reached
atLAKE_URL. A turn'slake_urlis ignored. zetta_base_url(Scan my workspace) is accepted only onLAKE_URL's origin and under its path,
with no user info, query, fragment, backslash or dot segments. Anything else refuses the turn.- With
LAKE_URLunset, or not an absolute http(s) URL, every turn that would send a credential is
refused before any request.
No turn trace on the pod's disk — #18
A turn no longer writes <TRACE_DIR>/<trace_id>.json, and the service no longer reads TRACE_DIR;
the Dockerfile drops its default. The answer still carries trace_id, and Lake keeps the whole
answer in the task's sealed record in the turn's workspace Zetta.
Before it rolls: the settings it needs
| Setting | Needed by | Rendered by the operator |
|---|---|---|
AGENT_SERVICE_TOKEN |
#20: without it every direct turn is refused (503) |
Yes, on every library agent |
LAKE_URL |
#22: without it (or not absolute http(s)) every turn that sends a credential is refused | Yes (Lake's internal URL) |
AUTOSUGGEST_MODEL |
Unchanged; the model name | Yes (with AGENT_MODEL, both set to the Lake's agent model) |
TRACE_DIR |
No longer read (#18) | Still set to /tmp/traces; ignored |
Nothing new is needed from the operator. For the best answers on date-bearing tables, Lake should
carry lake#1189 (merged into lake dev).
Where it has run
c5145f4(#24) ran on lake-dev: pinned asoramasearch/agent-autosuggest:c5145f4on the
devmember of the LakeSetlake-nonprod(orama-operatorconfig/clusters/sets/lake-nonprod.yaml,
orama-operator#982), with lakedev-aa9fefd5. Lake'stools/e2e/agents.pyT6 ("Scan my workspace
keeps its Opportunities") passed there on 2026-10-25.- #20, #22 and #18 have not run on dev. They merged after that build. No image of
dev's head
ran on any cluster before this release; they are proven by the test suite below only. - Every other Lake runs the operator's default,
oramasearch/agent-autosuggest:v0.1.0
(orama-operatorinternal/controller/lake_defaults.go).
The image
Built from the tag v0.2.0 (a00146a) on the cluster BuildKit with build-agent.sh (linux/amd64, the repository's Dockerfile, with the catalog context catalog-cf20d264 and the corpus context agent-autosuggest-corpus-a882954), then tagged :v0.2.0 on that digest without rebuilding:
docker.io/oramasearch/agent-autosuggest:a00146a@sha256:5bfd6b393df92a8ba8cd2ea1998050ba353b99dccd145fdbdb261163c810817f, 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.
What it does not include
Unchanged from v0.1.0, except that traces are no longer kept
at all:
- A trained model. Every turn is a frontier model with few-shot retrieval.
- A large precedent set. The
corpuscontext ata882954holds one worked example. - Any write. App actions are proposals for a person to confirm; ApplicationAgent performs them.
- Turn kinds. The task
kindis ignored. - Workspace identity. Turns carry
customer_id; the task'sworkspace_idis not forwarded (#11). - Lease renewal for long turns beyond activity, and back-off on empty bus reads.
- Bus back-pressure (#23): tasks are claimed before a worker is free.
- Workspace context from the command line.
Known issues
Security-relevant first. All open at this tag.
- The bus claims tasks before a worker is free
(#23, LSR-075, medium, denial of
service):lake_bus.workclaims every received task into the executor's unbounded queue, so one
tenant's burst holds task credentials in the process and delays other tenants while their leases
run. The fix is the port of agent-ask-orama#47. - Library agents hold live task credentials for every tenant they serve
(lake#871): one shared pod runs every tenant's
turns with their task credentials. - The workspace is not passed explicitly
(#11): the agent sends only
customer_idon its reads, never the task'sworkspace_id. - The lease is kept by activity only. Lake renews a claim's lease on every capability call made
with the task credential, so a turn is reclaimed only if one step, such as one model call, outlasts
lease_seconds(600 by default). Not observed. - The command line validates without workspace evidence
(#14). - Corpus drafts fail validation
(agent-autosuggest-corpus#15):
the corpus's examples do not choose a registry level for S-1. The image keeps thea882954corpus.
Closed since v0.1.0: #13 (#18),
#19 (#20),
#21 (#22), and
lake#795 (a discover turn failing on list_apps).
Verification
| Proof | Result |
|---|---|
Test suite (uv run --frozen --group dev pytest -q -ra, macOS arm64, Python 3.12.11, on the release branch) |
... |
Release v0.1.0
agent-autosuggest v0.1.0
Released 2026-10-17. The first release. One Python package, agent-autosuggest, and one private
image, docker.io/oramasearch/agent-autosuggest:v0.1.0. Proprietary to Orama; private repository and
image.
Auto-Suggest is the Lake library agent that reads a profile (a business situation and its data)
and proposes what is worth building. Its answer is a project profile, the object
agent-project consumes: ranked suggested Opportunities, each naming a catalogue solution (S-n),
its level, its methodologies and whether the workspace can run it, and declined entries with the
reason. In Lake it backs Design → Discover Opportunities, Scan my workspace, and Ask Orama's
"what could I build?" subagent call. It is not a trained model: a frontier model, reached through
Lake's model gateway, is given the solutions catalogue, the workspace's current registries and
Apps, and few-shot precedent retrieved from agent-autosuggest-corpus.
v0.1.0 is the same tree as commit 3d9acf7 (the merge of #12, the model gateway), which every Lake
already runs, plus these notes, a version field in /healthz, and the test that ties the version
to this page.
What it includes
One turn
run_turn in src/agent_autosuggest/service.py, the same for the bus and for POST /v1/turn:
- The profile. Taken from
profile, or fromcontext.profile; it must carrytablesor
connections. A turn-levelrequestis copied onto it. With no profile butzetta_base_urland
zetta_token(Scan my workspace, lake#269),workspace.pyreads it itself:
GET <zetta_base_url>/v1/list_datasets, thenget_datasetfor each of the first twelve, keeping
database, name, columns and rows. A workspace with no datasets is answered "load data first". - The workspace's registries and data evidence, read for every turn through Lake's
POST <lake_url>/v1/workspace_querywith the turn'slake_tokenandcustomer_id
(methodologies.py,solutions.py):list_methodologies,analyze_datasetper dataset,
plan_featuresper dataset and runnable methodology,list_solutions, andget_solutionfor a
cited solution. On an engine withoutlist_solutionsit keeps the methodology-only behavior; if
list_methodologiesis unknown too, onlyM-1is treated as runnable. - Ship Apps and builds, read directly from Lake as
GET <lake_url>/v1/<capability>
(apps.py):list_apps,list_builds, then for up to twelve of eachget_app/get_build
and a non-blockingreceive_app_events/receive_build_events(from_sequence: 1,
wait_ms: 0). Anunknown_capabilityanswer from a list call falls back to "no Apps"; any other
error fails the turn. - The model call. The system prompt is
prompts/v4.md(PROMPT_VERSION = "v4"in
agent.py), plus the catalogue ids and names, the solution, methodology and App evidence, and
up to three retrieved worked examples (AUTOSUGGEST_SHOTS). The model is reached through Lake's
gateway at<lake_url>/openai/v1with the turn'slake_token(falling back tozetta_token) as
the API key (model.py, lake#248), so Lake counts the tokens in the turn's workspace and
enforces the account's limit. A turn without a Lake URL and credential is refused. The model is
AUTOSUGGEST_MODEL(defaultgpt-4o), or the turn's ownmodel. - Enforcement and validation.
solutions.enforceattaches each Opportunity's registry status
(S-n, selected level, composed methodology ids,runnable; missing production components named;
Band-B sketches declined with their promotion condition) and moves what the engine cannot run to
declined.apps.enforcerewrites every App delivery to a proposal for ApplicationAgent
(agent: agent-application,turn_kind: app,status: proposed,confirmation_required: true)
and keeps only these proposable actions:create_app,deploy_app,build_app,
rollback_app,scale_app,start_app,stop_app,restart_app,delete_app,
set_app_env,unset_app_env,set_app_auth,set_app_zetta_binding,bind_service_to_app,
unbind_service_from_app,create_service_and_bind_to_app,cancel_build.validate.defects
then rejects claims that contradict the registries (unknown solution or methodology ids,
non-runnable work suggested, Opportunities not grounded in the profile's columns, numerical
success claims, App contract violations). One repair round hands the defects back to
the model; what remains is returned indefects. - The answer:
{ok: true, trace_id, result: {project_profile, few_shot_from, prompt_version, defects}}, or{ok: false, error}. Every successful turn writes a trace
<TRACE_DIR>/<trace_id>.json(profile, evidence, result; never the credential).
Auto-Suggest never performs an App action or any other write: every Lake call it makes is a read.
It does not look at the task's kind; every turn is one suggestion.
HTTP API
agent-autosuggest-serve listens on PORT (8080), standard library ThreadingHTTPServer:
| Route | Answer |
|---|---|
GET /healthz |
200 {ok, agent, examples, model, version}, or 503 when the corpus is missing or empty (answering zero-shot would be a different agent). Unauthenticated |
POST /v1/turn |
One turn (body as above: profile, context.profile, or zetta_base_url + zetta_token; optional request, lake_url, lake_token, customer_id, model). 200 with the answer when ok, 422 {ok: false, error} otherwise, 400 when the body is not JSON, 401 when AGENT_SERVICE_TOKEN is set and the bearer does not match |
| anything else | 404 |
The agent bus
lake_bus.py (the same file as in the other library agents) starts a background thread when
LAKE_URL, AGENT_BUS_TOKEN and AGENT_BUS_AGENT (default agent-autosuggest) are set. Through
Lake, with this agent's own bus credential, never Zetta's token:
GET /v1/receive_agent_tasks {agent, from_sequence, wait_ms: 10000}long-polls the tasks on
agent-tasks.<agent>(task ids only), starting from sequence 1 at every start;POST /v1/claim_agent_task {task_id, agent}for each; aconflictornot_foundmeans another
replica won and the task is skipped. The claim answers the task body with the task'slat.
credential aslake_token/zetta_token; the claim'scustomer_idis copied into the turn;- up to four claimed turns run at once;
POST /v1/publish_agent_eventsendsprogress
("Working on it"), thenresultwith the whole answer orfailedwith its error.
A failed receive is logged and retried after two seconds. The code sends no heartbeat (Lake renews the lease on each capability call made with the task
credential) and does not send workspace_id; Lake uses the task row's own workspace.
Command line
| Script | What it does |
|---|---|
agent-autosuggest <profile.json> [--corpus PATH] [--model NAME] [--shots N] |
One suggestion for a profile file, printed as JSON. Calls OpenAI directly with your own OPENAI_API_KEY and no workspace (no registries, no Apps). Exit 0 clean, 2 with defects (still printed), 1 when nothing parseable came back |
agent-autosuggest-serve |
The service above |
Environment
| Variable | Meaning |
|---|---|
PORT |
Listen port (default 8080) |
AUTOSUGGEST_CORPUS |
The retrieval corpus, JSON lines (image: /app/corpus/autosuggest-sft-v3.jsonl) |
AUTOSUGGEST_MODEL |
Model name (default gpt-4o; the operator sets the Lake's agent model) |
AUTOSUGGEST_SHOTS |
Worked examples per turn (default 3; service only) |
ZETTA_CATALOG |
The built solutions catalogue (image: /app/catalog/catalog.json). Unreadable or with no solutions, every turn fails (catalog.Unavailable) |
ZETTA_BRIDGE |
Without ZETTA_CATALOG: the zetta-bridge checkout whose modules/zetta/scripts/build_catalog.py builds the catalogue (otherwise found by walking up from the package) |
TRACE_DIR |
Where traces go (default /tmp/agent-autosuggest-traces; the operator sets /tmp/traces) |
LAKE_URL |
Lake's address: the bus, and the default for turns that carry no lake_url |
AGENT_BUS_TOKEN |
This agent's bus credential, minted by the operator |
AGENT_BUS_AGENT |
The agent key it takes tasks under |
AGENT_SERVICE_TOKEN |
When set, the bearer POST /v1/turn requires |
OPENAI_API_KEY |
Command line only; the service never uses it |
The image
Dockerfile: a python:3.12-slim build stage runs uv sync --frozen --no-dev --no-editable
(uv 0.11.7); the runtime stage is python:3.12-slim with the virtualenv, user 10001, port 8080,
entrypoint agent-autosuggest-serve. It needs two named build contexts:
catalog:catalog.jsonandcatalog.source.json, built by zetta'sscripts/build_catalog.py
from the solutions-designs plan. The build used for the running image is
codex-work/build/contexts/catalog-cf20d264(zettacf20d264, solutions-designsf335525a,
built 2026-10-11);corpus:autosuggest-sft-v3.jsonlfromagent-autosuggest-corpusata882954(its v0.1.0
tree), contextcodex-work/build/contexts/agent-autosuggest-corpus-a882954.
Built on the cluster BuildKit by codex-work/build/scripts/build-agent.sh with AGENT_CONTEXTS
naming both. Published private as oramasearch/agent-autosuggest.
How Lake reaches it
- The Orama operator runs it as a library agent of every Lake: one Deployment and one Service on
port 8080, probed on/healthz, non-root with a read-only root filesystem and a writable/tmp.
It setsLAKE_URL,PORT,TRACE_DIR,AUTOSUGGEST_MODEL,AGENT_SERVICE_TOKEN,
AGENT_BUS_TOKENandAGENT_BUS_AGENT. - Lake learns the agent's address from
LAKE_AGENT_ENDPOINTS(key=url) and presents
LAKE_AGENT_SERVICE_TOKENas the bearer on direct calls. - Turns arrive as tasks on
agent-tasks.agent-autosuggest...