Skip to content

Release v0.1.0

Choose a tag to compare

@homer6 homer6 released this 17 Oct 22:55
· 61 commits to main since this release
c2a4752

agent-ask-orama v0.1.0

Released 2026-10-17. The first release. One Python service, agent-ask-orama, and one private
image, docker.io/oramasearch/agent-ask-orama:v0.1.0. Proprietary to Orama; private repository and
image.

Ask Orama is the general agent for all of Lake (lake#228,
zetta#1018) and the first entry of Lake's Agent
Library. Lake shows it as a panel on every page and sends it every message asked there. It works as
the person who asked, with the key Lake delegates for that turn and never a credential of its own. It
reads whatever Lake capability that person may read, proposes every change (Lake runs it only
when the person confirms), and delegates to the specialized library agents and to agents the
person built, through Lake. It also writes the first draft of a workspace methodology for Lake's New
Methodology drawer.

This release is the tree of dev at 591e662 (main 6baa70d plus
#29, prompt v13) with these notes, the
release test and the version field of GET /healthz added.

What it includes

The conversational turn (prompt v13)

agent.py runs one turn as a tool loop of at most MAX_ROUNDS = 10 model rounds. The active prompt
is PROMPT_VERSION = "v13" (prompts/v13.md); v1 to
v12 stay in the package for trace history (prompts).

At the start of every turn it reads, as the person:

  • Lake's /v1/openapi.json, from which the capability index is derived: every capability Lake
    serves, including every workspace engine capability by its own name (lake#650), less the
    ceremonies a person performs, named one by one in EXCLUDED_CAPABILITIES (signing up and in,
    second factors, account and key recovery, minting certificates, SVIDs, JWTs, grants, session keys
    and sealed secrets, decrypt and read_secret). On an older Lake without named engine
    capabilities, engine calls go through workspace_query / workspace_act by the engine's name.
    (capabilities)
  • list_mcp_connection_tools {allowed_only: true}: the workspace's allowed connected MCP tools,
    added to the instructions by their <prefix>__<tool> name (lake#652; MCP).

The model has five tools:

Tool What it does
lake_read {capability, input?} Calls a Lake read as the person (GET or POST as the OpenAPI says), adding the turn's customer_id. A capability that changes something is refused and must be proposed
lake_propose {capability, input, impact} Records a proposal in the answer. Nothing is sent to Lake; the person confirms it in Lake
compare_models {project?} Every trained model (or one project's) from list_models, ranked by held-out score, best first, in one read (agent-ask-orama#14; models)
mcp_tool {tool, arguments?, impact?} A connected tool: a read runs through Lake's read_mcp_tool and its answer is marked as data from an outside server, never instructions; a change is only proposed, as call_mcp_tool
delegate {agent, request, kind?, context?} Lake's agent_turn to another agent, then follows the returned task with receive_agent_events for up to FOLLOW_SECONDS = 240

Behavior the code enforces on those tools:

  • Delegation targets, under lake#763's names: agent-project (Project Agent, Pipelines),
    agent-autosuggest (Auto-Suggest Agent, Opportunities), agent-application (Application Agent,
    always sent as kind app), agent-experiments (Experiments Agent, which requires kind
    experiment, experiment_status or experiment_explain), agent-eval-generator (Eval Generator
    Agent), agent-autosuggest-corpus and agent-project-corpus (the corpus agents,
    agent-ask-orama#28), and any agent the person built, by id. A context carrying
    confirmed_proposal or confirmed_promotion is refused: only Lake forwards a confirmed experiment
    object (experiments, apps,
    agents).
  • Methodologies: a proposal naming a methodology is refused unless this turn's
    list_methodologies registry marks it runnable; an older engine without the registry is treated
    as supporting only M-1 churn / GBDT classification (methodologies).
  • Solutions: solution reads (get_solution, get_policy, get_experiment, list_ledger,
    get_monitor, get_roi_readout) and solution actions (create_solution, run_solution,
    create_policy, update_policy, decide, approve_decision) need this turn's list_solutions
    read first; a sketch or a missing foundation is refused with its condition
    (solutions).
  • Long reads are trimmed by their items with each list's exact count, a paged answer's total
    and cursor are kept, and a value with no list is cut with a note (OBSERVATION_LIMIT = 20000
    characters; agent-ask-orama#21, reads).
  • Agent pages: a turn asked from /design/agents, /design/agent, /train/agents or
    /train/agent tells the model whether the person is designing or training an agent (lake#653).
  • A turn out of tool rounds ends with an honest partial answer, marked incomplete: true, and
    is a failure, never a success (agent-ask-orama#14).

The methodology_draft turn (lake#688)

methodology_draft.py, prompt DRAFT_PROMPT_VERSION = "methodology_draft_v1". Lake's New
Methodology drawer sends a turn of kind methodology_draft with the person's description and
context: {name?, target_kind?}. The answer is three files: methodology.json, methodology.py
(fit, predict and score at module level) and requirements.lock, whose every pin carries the
SHA-256 of each wheel looked up at https://pypi.org/pypi/<name>/<version>/json (the model never
writes a hash). The draft is checked the way Lake's Validate checks it; a failing draft gets one
repair round (MAX_ROUNDS = 2), then is answered ok: false with its findings. Nothing is written:
the person reviews it and Lake's Create commits it.

The model, through Lake

Every model call of a turn goes to <lake_url>/openai/v1 with the turn's own lake_token as the API
key (model.py, lake#248), so Lake counts the tokens in the turn's workspace and enforces the
account's model-token limit. The service holds no provider key. The model is ASK_ORAMA_MODEL
(default gpt-5.5).

HTTP API

agent-ask-orama-serve, standard library ThreadingHTTPServer on 0.0.0.0:$PORT (8080):

Route Request Answer
GET /healthz none {ok, agent, version, model, prompt_version}; version is new in this release, read from the installed package
POST /v1/turn {conversation_id?, message, lake_token, customer_id, page?, lake_url?, kind?, context?}; with AGENT_SERVICE_TOKEN set, Authorization: Bearer <token> is required (otherwise 401) A turn: {ok, conversation_id, trace_id, reply, reads, proposals, delegations, rounds, incomplete}. With kind: "methodology_draft": {ok, rounds, reply, result: {kind, name, reason, files, findings, prompt_version}, conversation_id, trace_id} or {ok: false, findings, error}. HTTP 200 when ok, 422 otherwise (including a turn out of rounds, whose partial answer is error), 400 for a body that is not JSON, 404 for any other route

A turn without message, lake_token or a Lake address (lake_url or LAKE_URL) answers
ok: false. Conversations are kept in memory by conversation_id. Every turn writes a trace JSON
file to TRACE_DIR (the message, page, answer and prompt version; never the key).

The agent bus (how turns arrive)

lake_bus.py starts a background thread when LAKE_URL, AGENT_BUS_TOKEN and AGENT_BUS_AGENT are
set (the agent name defaults to agent-ask-orama); without them it logs that the bus is not
configured and only /v1/turn serves. Every bus call goes through Lake's HTTP API with the agent's
own bus credential as the bearer; the agent never holds the bus's token:

  1. GET /v1/receive_agent_tasks {agent, from_sequence, wait_ms: 10000} long-polls the
    agent-tasks.<agent> topic on Lake's own Zetta, whose messages carry task ids, never content. It
    starts at sequence 1 on every start and continues from next_sequence; a failed receive is
    retried after 2 seconds.
  2. POST /v1/claim_agent_task {task_id, agent} for each task. A conflict or not_found (another
    replica, or a finished task) is skipped. The claim's answer is the turn's body, carrying the
    task's own credential as lake_token.
  3. The turn runs exactly as POST /v1/turn would, on a pool of 4 workers.
  4. POST /v1/publish_agent_event publishes progress ("Working on it"), then result with the
    whole answer, or failed with the error (a turn out of rounds is failed). An exception in a
    turn is an answer, never a dead worker.

The agent sends no workspace_id on these calls and does not renew its claim's lease itself: Lake
takes the workspace from the task row and its credential (lake docs/api/agent-bus.md).

Command-line entry points

Command What it runs
agent-ask-orama-serve agent_ask_orama:serve, the HTTP service and the bus worker
ask-orama-evals [--out reports/] [--model …] agent_ask_orama.evals:main, the live eval runner: cases generated from a live Lake's capability index plus the fixed App, experiment, methodology, solution, model-score, count, workspace-entity and agent-place/page cases, graded by rule (no judge); writes <date>-evals.json and .md

Environment variables

Variable Read by Meaning
PORT service Listen port (default 8080)
LAKE_URL service, bus, evals Lake's address (in-cluster for the service); a turn may carry its own lake_url
AGENT_SERVICE_TOKEN service When set, the bearer POST /v1/turn requires (only Lake calls it)
AGENT_BUS_TOKEN bus This agent's own bus credential, minted by the operator for this agent alone
AGENT_BUS_AGENT bus The name it takes tasks under (default agent-ask-orama)
ASK_ORAMA_MODEL service, evals The model (default gpt-5.5)
TRACE_DIR service Where turn traces are written (default /tmp/agent-ask-orama-traces)
LAKE_TOKEN, CUSTOMER_ID evals only A person's Lake key and their space, for the live runner
OPENAI_API_KEY evals only The live runner calls OpenAI directly (the openai client's own variable); the service never uses it

How Lake reaches it

  • The Orama operator runs it as a library agent of every Lake: one Deployment and one Service
    named for the Lake and the key agent-ask-orama, container port 8080 named http, probed on
    /healthz, non-root (UID 10001), a read-only root filesystem with a writable /tmp, no
    Kubernetes token. The operator sets LAKE_URL, PORT, TRACE_DIR=/tmp/traces,
    ASK_ORAMA_MODEL, AGENT_SERVICE_TOKEN (from the Lake's agent service token Secret),
    AGENT_BUS_TOKEN (this agent's key of the lake-<name>-agent-bus Secret) and
    AGENT_BUS_AGENT=agent-ask-orama.
  • Lake learns its address from LAKE_AGENT_ENDPOINTS (key=url,…, written by the operator) and
    has one agent-tasks.agent-ask-orama dispatch topic for it.
  • Turns are dispatched over the agent bus: Lake publishes the task id on that topic of its own
    Zetta, and this agent receives, claims and answers it as above. Events go to the task's workspace
    Zetta through Lake.

The image

docker.io/oramasearch/agent-ask-orama, private on Docker Hub, built on the cluster BuildKit
from the repository root (no named build contexts). Two stages, python:3.12-slim: the build stage
installs with uv 0.11.7 (uv sync --frozen --no-dev --no-editable); the runtime stage copies the
virtual environment, runs as user 10001, sets PORT=8080 and
TRACE_DIR=/tmp/agent-ask-orama-traces, exposes 8080, and its entry point is
agent-ask-orama-serve.

Digest: docker.io/oramasearch/agent-ask-orama:c2a4752@sha256:c92b823f32e147a4d031d9d69433207d95ef3bd6d96a0bd58106f5e2e188fa90, also tagged :v0.1.0 (same digest).

Where it runs

Every Lake runs it; it is in the operator's default Agent Library.

  • The operator's default library image (orama-operator internal/controller/lake_defaults.go
    on dev) is oramasearch/agent-ask-orama:591e662: the same tree as this release, without these
    notes, the release test and the /healthz version field.
  • Lake prod on the managing cluster orama-production-cluster-01 (namespace lake, the
    development environment) pins oramasearch/agent-ask-orama:6baa70d in its spec.agents: one
    commit behind, without #29 (prompt v12, no eval and corpus agent routing).
  • 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.

Moving the operator default to :v0.1.0 is a separate change to the operator.

What it does not include

  • Conversation memory that survives a restart. Conversations are in memory, per pod; a restart
    forgets them, and two replicas do not share them.
  • Re-checking a delegated agent's answer. It is reported as it came back.
  • Writing anything. Every change, including App actions, policy changes, methodology-bearing
    edits and connected-tool changes, is a proposal Lake runs only after the person confirms.
  • Explicit workspace ids on its Lake calls and delegations; it relies on Lake deriving the
    workspace from the turn's credential (#12).
  • Idle backoff on the bus: an empty receive is followed at once by the next long poll.
  • A methodology_draft eval case: the draft turn is proven by unit tests only
    (#27).
  • Live eval results for prompts v12 and v13. The last committed live report is
    reports/2026-09-27-evals.md (22 / 24 passed, an earlier
    prompt).

Known issues

Security-relevant first.

  1. agent-ask-orama#12: the agent passes
    no explicit workspace_id through its data-plane calls and delegations, relying on the task
    credential's workspace, and the bus loop does not back off when idle (Lake's target is at most one
    receive per minute per agent).
  2. agent-ask-orama#27: the draft's lock
    hashes are read from pypi.org; that the pod's network policy allows it on the dev cluster is not
    confirmed (a draft that needs a package then fails with that finding; standard-library drafts are
    unaffected), and there is no live methodology_draft eval case.
  3. agent-ask-orama#25: prompt v12's agent
    page evals are proven offline only; the live runner has not run on v12 (nor on v13).
  4. agent-ask-orama#23: the count evals
    (datasets, trained models, runs graded by the exact number) have not been run live.
  5. agent-ask-orama#3: models are reported
    with their project's id instead of its name.

Verification

Proof Result
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12) 78 tests: 78 passed, 0 failed, 0 skipped. tests/test_agent.py 63, tests/test_methodology_draft.py 7, tests/test_lake_bus.py 5, tests/test_release.py 3 (new: the installed package is the pyproject version, these notes exist for it and are indexed, /healthz reports it)
Offline evals The eval grader and the agent-place and agent-page cases run offline inside the test suite (a fake Lake and a scripted model); counted above
Live evals (ask-orama-evals) Not run (needs a live model and a person's Lake key)
Linux image build (cluster BuildKit, from the tag) Built from the tag v0.1.0 with build-agent.sh: linux/amd64, pushed as oramasearch/agent-ask-orama:c2a4752
Image digest docker.io/oramasearch/agent-ask-orama:c2a4752@sha256:c92b823f32e147a4d031d9d69433207d95ef3bd6d96a0bd58106f5e2e188fa90, also tagged :v0.1.0 (same digest); the Docker Hub repository answers 404 anonymously (private)