Repository navigation
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-autosuggeston Lake's Zetta (task ids only, never
content), taken as described in The agent bus. Lake's contract:docs/api/agent-bus.md,
docs/api/agent-launches.mdanddocs/api/train-agents.mdinoramasearch/lake.
Where it runs
Every Lake runs it:
- the operator's default library image (
orama-operatorinternal/controller/lake_defaults.goon
dev) isoramasearch/agent-autosuggest:3d9acf7; - Lake
prodon the managing clusterorama-production-cluster-01(namespacelake, the
development environment) pinsoramasearch/agent-autosuggest:3d9acf7in itsspec.agents; - the LakeSets
lake-nonprod(membersdev,stagingandtestingonorama-nonprod-cluster-01)
andlake-prod(memberssharedonorama-production-cluster-02andshared-uson
orama-production-cluster-03) take the operator default.
That commit is this release's tree without these notes, the /healthz version field and the
release test. Moving the operator default to :v0.1.0 is a separate change to the operator.
What it does not include
- A trained model. Every turn is a frontier model with few-shot retrieval; the corpus is SFT data
for a later model. - A large precedent set. The
corpuscontext ata882954holds one worked example, so every
turn gets that one example as precedent. - Any write. It proposes App actions for a person to confirm; ApplicationAgent performs them.
- Turn kinds. The task
kindis ignored; there is one behavior. - Durable traces. Traces are files under
TRACE_DIR, on the pod's/tmp; they are lost when the
pod is replaced and are not written to the workspace Zetta. - Workspace identity. Turns carry
customer_id; the agent does not read or forward the task's
workspace_id(#11). - Lease renewal for long turns, and back-off on empty bus reads beyond the ten-second long poll.
- Workspace context from the command line:
agent-autosuggestruns with no registries or Apps
and calls OpenAI directly.
Known issues
Security-relevant first.
- The workspace is not passed explicitly (oramasearch/agent-autosuggest#11):
the agent reads onlycustomer_idfrom the claimed task and sends it on everyworkspace_query
and App read, never the task's immutableworkspace_id. Lake binds task credentials to one
workspace, but the agent itself does not hold to it. - Traces hold workspace data on the pod. A trace carries the profile, including up to twelve
datasets' rows read by Scan my workspace, in/tmpof the agent pod rather than in the
workspace Zetta (agent-autosuggest#13). - A discover turn fails when the credential does not grant
list_apps
(oramasearch/lake#795): onlake-testing
the turn endsfailedwith "unauthorized: credential does not grant list_apps".apps.py
treats onlyunknown_capabilityas "no Apps"; anunauthorizedanswer fails the whole turn.
Lake'sdocs/api/agent-launches.mdalso says Lake builds the profile and hands Auto-Suggest no
key, while this agent reads the workspace, the registries, Apps and the model with the task
credential; the two sides disagree. - The lease is kept by activity only. The agent sends no heartbeat of its own. Lake renews a claim's lease on every accepted event and every capability call made with the task credential (lake
docs/api/agent-bus.md), so a turn can be reclaimed only if a single step between two such calls, such as one model call, outlastslease_seconds(600 seconds by default). Not observed. - The command line validates without workspace evidence:
agent-autosuggestre-runs
validate.defectswith no registry or App evidence, so its exit code reflects only the
catalogue and fallback checks (agent-autosuggest#14).
Verification
| Proof | Result |
|---|---|
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12) |
37 passed, 0 failed, 0 skipped: test_service.py 17, 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 (4 cases) and evals/data-apps.jsonl (2 cases) run through the service's enforcement and validation inside the suite above; all pass |
Live-model evals and the recorded traces/ |
Not run (needs a live model) |
| Linux image build (cluster BuildKit, from the tag) | Built from the tag v0.1.0 with build-agent.sh with the named contexts catalog (catalog-cf20d264) and corpus (agent-autosuggest-corpus corpus/, identical at a882954 and v0.1.0): linux/amd64, pushed as oramasearch/agent-autosuggest:0bc895a |
| Image digest | docker.io/oramasearch/agent-autosuggest:0bc895a@sha256:3dd3ae9f1335dbdef4a322778f44955fc838552a9b9201660070ffd8a8847391, also tagged :v0.1.0 (same digest); the Docker Hub repository answers 404 anonymously (private) |