Skip to content

Release v0.1.0

Choose a tag to compare

@homer6 homer6 released this 17 Oct 23:00
· 49 commits to main since this release
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 on 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.md and docs/api/train-agents.md in oramasearch/lake.

Where it runs

Every Lake runs it:

  • the operator's default library image (orama-operator internal/controller/lake_defaults.go on
    dev) is oramasearch/agent-autosuggest:3d9acf7;
  • Lake prod on the managing cluster orama-production-cluster-01 (namespace lake, the
    development environment) pins oramasearch/agent-autosuggest:3d9acf7 in its spec.agents;
  • the LakeSets lake-nonprod (members dev, staging and testing on orama-nonprod-cluster-01)
    and lake-prod (members shared on orama-production-cluster-02 and shared-us on
    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 corpus context at a882954 holds 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 kind is 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-autosuggest runs with no registries or Apps
    and calls OpenAI directly.

Known issues

Security-relevant first.

  1. The workspace is not passed explicitly (oramasearch/agent-autosuggest#11):
    the agent reads only customer_id from the claimed task and sends it on every workspace_query
    and App read, never the task's immutable workspace_id. Lake binds task credentials to one
    workspace, but the agent itself does not hold to it.
  2. Traces hold workspace data on the pod. A trace carries the profile, including up to twelve
    datasets' rows read by Scan my workspace, in /tmp of the agent pod rather than in the
    workspace Zetta (agent-autosuggest#13).
  3. A discover turn fails when the credential does not grant list_apps
    (oramasearch/lake#795): on lake-testing
    the turn ends failed with "unauthorized: credential does not grant list_apps". apps.py
    treats only unknown_capability as "no Apps"; an unauthorized answer fails the whole turn.
    Lake's docs/api/agent-launches.md also 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.
  4. 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, outlasts lease_seconds (600 seconds by default). Not observed.
  5. The command line validates without workspace evidence: agent-autosuggest re-runs
    validate.defects with 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)