Skip to content

Releases

Release v0.3.1

Choose a tag to compare

@homer6 homer6 released this 16 Nov 08:33
c630000

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.

  1. The image bundles GPL and LGPL code (#37): it is built on python:3.12-slim (Debian: glibc, bash, coreutils, dpkg, readline). The move to scratch with static binaries is deferred; it is noted here and does not block this release.
  2. Library agents hold live task credentials for every tenant they serve: one shared pod runs every tenant's turns with their task credentials.
  3. The workspace is not passed explicitly (#11): the agent sends only customer_id on its reads, never the task's workspace_id.
  4. 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.
  5. The command line validates without workspace evidence (#14).
  6. Corpus drafts fail validation: the corpus's examples do not choose a registry level for S-1. The image keeps the a882954 corpus.

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

Choose a tag to compare

@homer6 homer6 released this 16 Nov 07:24
9d38f4e

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 most AGENT_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

  1. The bus consumer runs at most AGENT_BUS_WORKERS turns at once and leaves the rest on the bus, unclaimed.
  2. One customer holds at most AGENT_BUS_TENANT_WORKERS workers 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.

  1. 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 to scratch with static binaries before it is.
  2. Library agents hold live task credentials for every tenant they serve: one shared pod runs every tenant's turns with their task credentials.
  3. The workspace is not passed explicitly (#11): the agent sends only customer_id on its reads, never the task's workspace_id.
  4. 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.
  5. The command line validates without workspace evidence (#14).
  6. Corpus drafts fail validation: the corpus's examples do not choose a registry level for S-1. The image keeps the a882954 corpus.

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

Choose a tag to compare

@homer6 homer6 released this 25 Oct 21:08
a00146a

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 plans ready on one dataset
    (methodologies.ready_dataset). The model's preparation becomes a required_first step, and the
    grounding names the dataset and the cutoff Lake inferred (inferred.as_of).
  • methodologies reads zetta's real transform_required shape and Lake's performed_by. A real
    transform is declined as transform first: <name>: <description>. Lake does it with <capability>.
    Without performed_by the 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; the time role is met by a snapshot column or a declared as_of; "approved
    snapshot" requests are forbidden. v4 is kept in prompts/.

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
    at LAKE_URL. A turn's lake_url is ignored.
  • zetta_base_url (Scan my workspace) is accepted only on LAKE_URL's origin and under its path,
    with no user info, query, fragment, backslash or dot segments. Anything else refuses the turn.
  • With LAKE_URL unset, 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 as oramasearch/agent-autosuggest:c5145f4 on the
    dev member of the LakeSet lake-nonprod (orama-operator config/clusters/sets/lake-nonprod.yaml,
    orama-operator#982), with lake dev-aa9fefd5. Lake's tools/e2e/agents.py T6 ("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-operator internal/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 corpus context at a882954 holds one worked example.
  • Any write. App actions are proposals for a person to confirm; ApplicationAgent performs them.
  • Turn kinds. The task kind is ignored.
  • Workspace identity. Turns carry customer_id; the task's workspace_id is 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.

  1. The bus claims tasks before a worker is free
    (#23, LSR-075, medium, denial of
    service): lake_bus.work claims 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.
  2. 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.
  3. The workspace is not passed explicitly
    (#11): the agent sends only
    customer_id on its reads, never the task's workspace_id.
  4. 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.
  5. The command line validates without workspace evidence
    (#14).
  6. Corpus drafts fail validation
    (agent-autosuggest-corpus#15):
    the corpus's examples do not choose a registry level for S-1. The image keeps the a882954 corpus.

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) ...
Read more

Release v0.1.0

Choose a tag to compare

@homer6 homer6 released this 17 Oct 23:00
0bc895a

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:

  1. The profile. Taken from profile, or from context.profile; it must carry tables or
    connections. A turn-level request is copied onto it. With no profile but zetta_base_url and
    zetta_token (Scan my workspace, lake#269), workspace.py reads it itself:
    GET <zetta_base_url>/v1/list_datasets, then get_dataset for each of the first twelve, keeping
    database, name, columns and rows. A workspace with no datasets is answered "load data first".
  2. The workspace's registries and data evidence, read for every turn through Lake's
    POST <lake_url>/v1/workspace_query with the turn's lake_token and customer_id
    (methodologies.py, solutions.py): list_methodologies, analyze_dataset per dataset,
    plan_features per dataset and runnable methodology, list_solutions, and get_solution for a
    cited solution. On an engine without list_solutions it keeps the methodology-only behavior; if
    list_methodologies is unknown too, only M-1 is treated as runnable.
  3. 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 each get_app / get_build
    and a non-blocking receive_app_events / receive_build_events (from_sequence: 1,
    wait_ms: 0). An unknown_capability answer from a list call falls back to "no Apps"; any other
    error fails the turn.
  4. 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/v1 with the turn's lake_token (falling back to zetta_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 (default gpt-4o), or the turn's own model.
  5. Enforcement and validation. solutions.enforce attaches 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.enforce rewrites 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 in defects.
  6. 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:

  1. 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;
  2. POST /v1/claim_agent_task {task_id, agent} for each; a conflict or not_found means another
    replica won and the task is skipped. The claim answers the task body with the task's lat.
    credential as lake_token / zetta_token; the claim's customer_id is copied into the turn;
  3. up to four claimed turns run at once; POST /v1/publish_agent_event sends progress
    ("Working on it"), then result with the whole answer or failed with 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.json and catalog.source.json, built by zetta's scripts/build_catalog.py
    from the solutions-designs plan. The build used for the running image is
    codex-work/build/contexts/catalog-cf20d264 (zetta cf20d264, solutions-designs f335525a,
    built 2026-10-11);
  • corpus: autosuggest-sft-v3.jsonl from agent-autosuggest-corpus at a882954 (its v0.1.0
    tree), context codex-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 sets LAKE_URL, PORT, TRACE_DIR, AUTOSUGGEST_MODEL, AGENT_SERVICE_TOKEN,
    AGENT_BUS_TOKEN and AGENT_BUS_AGENT.
  • Lake learns the agent's address from LAKE_AGENT_ENDPOINTS (key=url) and presents
    LAKE_AGENT_SERVICE_TOKEN as the bearer on direct calls.
  • Turns arrive as tasks on agent-tasks.agent-autosuggest...
Read more