Skip to content

Releases

Release v0.3.0

Choose a tag to compare

@homer6 homer6 released this 16 Nov 07:29
2dcb97e

Released 2026-11-16. A minor release. Since v0.2.0: bus back-pressure (a task is claimed only when a worker is free, with a per-customer limit), the licence, the security policy, base images pinned by digest and the public-tree cleanup. Image: docker.io/oramasearch/agent-project:v0.3.0, not published (see Known issues).

This release is the tree of dev with these notes and the version.

What it includes

Every pull request merged into dev since the v0.2.0 tag:

PR What it does
#45 The public-tree cleanup (see below)
#46 MIT LICENSE and COPYRIGHT (OramaSearch, Inc.), an SPDX-License-Identifier: MIT line in every source file (tools/spdx-headers.py), THIRD_PARTY_LICENSES, CONTRIBUTING.md, CLA.md, CODE_OF_CONDUCT.md, and the SBOM (sbom.spdx.json, sbom.cdx.json, tools/sbom.py)
#41 Security: the bus consumer claims a task only when a worker is free, and one customer cannot take every worker
#43 The Dockerfile names its base images by digest as well as by tag (python:3.12-slim, ghcr.io/astral-sh/uv:0.11.7), so a later build of the same source gets the same base
#42 SECURITY.md: how to report a vulnerability
#39 Records the v0.2.0 image digest in the v0.2.0 notes (documentation only)
#38 The v0.2.0 release promotion (dev → main), merged back into dev

A bus task is claimed only when a worker is free — #41

  • Every received task used to be claimed and queued, so one tenant's burst held claimed tasks (with their credentials) in memory and starved the others (#33).
  • lake_bus.work now claims only when a worker slot is free and receives nothing while all are busy. AGENT_BUS_WORKERS (default 4) sets the slots and AGENT_BUS_TENANT_WORKERS (default one fewer) caps one customer; at most 256 dispatch rows wait. receive passes the long poll's wait_ms.
  • Both settings are optional; their defaults apply when unset, so no operator change has to roll first.

The public-tree cleanup — #45

Nothing internal is left in the files that will be published: .public-exclude was added and then removed again once the agent files were rewritten to ship publicly; issue links became plain text, the image section shows a docker buildx build with the two named contexts, the release notes name no environment, and the package author is Orama Search Inc..

The licence — #46

Everything in this repository that Orama wrote is under the MIT licence. Contributors sign CLA.md once. THIRD_PARTY_LICENSES lists every runtime dependency with its licence text; none is incompatible with MIT distribution.

Before it rolls: the settings it needs

Nothing required. AGENT_BUS_WORKERS and AGENT_BUS_TENANT_WORKERS (#41) are optional, with defaults. The other variables are unchanged from v0.2.0.

What it does not include

Deferred, not in this release:

  • #44: claiming bus tasks by reference and naming the task on every call; it needs the matching Lake change.

Otherwise unchanged from v0.2.0.

Known issues

Security-relevant first. All open at this tag.

  1. #47 (release blocker for publishing): the image is built on python:3.12-slim, which bundles GPL and LGPL userland, so the image is not published. It is built and kept in the project's non-public Docker Hub repository until it moves to a scratch base with static binaries.
  2. #34: turn traces keep workspace content on the pod's disk (TRACE_DIR), outside the workspace Zetta.
  3. #17: the task's workspace is not passed explicitly on data-plane calls and delegated turns. Lake scopes the task credential to the task's workspace.
  4. #28: the analysis fallback does not read get_dataset's typed columns.
  5. #27: designing does not detect class imbalance or report imbalanced runs by PR-AUC and lift.
  6. The catalogue build context is produced outside this repository; a public user needs a published catalogue to build the image.

Where it has run

The v0.3.0 tree had not run on a development environment when it was released. Lakes run the operator's default image of this agent; the changes since v0.2.0 are proven by the test suite only. Moving a Lake to :v0.3.0 is a separate operator change.

The image

Built from the tag v0.3.0 (2dcb97e) with BuildKit (linux/amd64, the repository's Dockerfile, with the catalog context catalog-cf20d264 (the same as v0.2.0) and the corpus context from agent-project-corpus v0.3.0's corpus/), then tagged :v0.3.0 on that digest without rebuilding:

docker.io/oramasearch/agent-project:2dcb97e@sha256:c85d9a5906bb57f948bcc15bf1be7fd0c6be21976bafed408dbc755a54f5a3aa, also tagged :v0.3.0 (same digest).

It is pushed only to the project's non-public Docker Hub repository, which answers 404 anonymously. Pinning it on a Lake is a separate change.

Verification

Proof Result
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12, release branch) 97 passed, 0 failed, 0 skipped; 97 tests. Includes tests/test_release.py (the declared version has these notes, indexed)
SPDX headers (python3 tools/spdx-headers.py --check) Every source file carries the header
SBOM (python3 tools/sbom.py --version v0.3.0, then --check) Regenerated on the release commit; --check passes
Batch generation, and a live turn through Lake's model gateway Not run (needs a live model and a Lake)
Linux image build (BuildKit, linux/amd64, from the tag) Built from v0.3.0: oramasearch/agent-project:2dcb97e, also :v0.3.0, sha256:c85d9a5906bb57f948bcc15bf1be7fd0c6be21976bafed408dbc755a54f5a3aa

Release v0.2.0

Choose a tag to compare

@homer6 homer6 released this 25 Oct 21:08
e8324f6

agent-project v0.2.0

Released 2026-10-25. A minor release. Three changes since v0.1.0: two fixes from the
2026-10-21 security review and a change in what a Lake turn returns. Private repository and image,
docker.io/oramasearch/agent-project:v0.2.0. Tracking issue:
agent-project#35.

This release is the tree of dev at db8835f with these notes and the version.

What it includes

Every pull request merged into dev since v0.1.0:

PR Change
#29 The service token is compared in constant time, and turns are refused when it is unset (#23)
#31 A turn's credential goes only to Lake at the service's own LAKE_URL (#30)
#32 A Lake turn designs a pipeline, or proposes a solution, without a write (lake#796); prompt v7
#26 Docs: the v0.1.0 image digest recorded in its notes
#25 main merged back into dev after v0.1.0

The service token is always required — #29

POST /v1/turn checks the bearer with hmac.compare_digest instead of !=, and fails closed:
with AGENT_SERVICE_TOKEN unset or empty every turn is refused with 503 (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 LAKE_URL — #31

v0.1.0 took zetta_base_url and lake_url from the turn and sent the turn's bearer there. Now
service.run_turn settles every address before any request goes out:

  • the model gateway is always the service's own LAKE_URL; a turn's lake_url is never used for it;
  • zetta_base_url and lake_url are accepted only on LAKE_URL's origin and under its path, with
    no user info, query, fragment, backslash or ./.. segment; any other address refuses the turn;
  • with LAKE_URL unset, every turn that would send its credential is refused;
  • a turn that names no zetta_base_url still uses the environment's ZETTA_BASE_URL.

Behaviour change: a Lake turn never writes, and a named solution is a solution_proposal — #32

In v0.1.0 a request that named no methodology went to solution operation, which calls
create_solution and run_solution. Lake's turn key for the Project Agent deliberately grants no
solution action, so the turn ended declined with a 403 defect (lake#796). Now:

  • Only a request that names a solution operates one. Any other request is a pipeline design on
    the methodology path, on every engine; its result.pipeline is what Lake's build flow applies.
  • A Lake turn never builds. The solution action tools are not offered, and a call to one is
    rejected before it reaches the workspace. A named solution is answered as
    kind: solution_proposal: id, project, a live level, sources, production_ready / missing,
    the policy proposal and label definitions for sign-off, a reply ending Proposed, not built,
    applied: false. A proposal for an unread entry, a sketch or an absent level is declined. Lake
    creates the solution only when the person confirms (start_solution → confirm_solution). The
    command line keeps the build-and-operate flow.
  • compile_intent stores a graph in a project, so the methodology design calls it, and the
    validator requires it, only when the turn names a project.
  • Prompt v7 for the methodology design (v6 plus that rule and the routing wording). Solution
    operation stays on v5; v1 to v6 stay in the package.

A caller that read a solution result from a Lake turn now gets a solution_proposal instead. Lake's
e2e test T7 (a build turn returns a pipeline design) is owed: it needs this image on
lake-testing before it can pass.

Before it rolls: settings

Setting Needed by Rendered by
AGENT_SERVICE_TOKEN #29: without it every /v1/turn is refused with 503 the operator, already, on every library agent
LAKE_URL #31: without it every turn that carries a credential is refused the operator, already

No new setting is introduced. The model is still PROJECT_MODEL (default gpt-4o) or the turn's
model.

What it does not include

Unchanged from v0.1.0, and:

  • No turn trace off the pod's disk. The sibling agents stopped writing turn traces to disk in
    this wave; this one still does (#34).
  • No bus back-pressure. The agent-ask-orama fix for LSR-075 is not ported yet
    (#33).
  • No class-imbalance handling (#27).
  • No live model evaluation.

Known issues

Security-relevant first. All open at this tag.

  1. #34: every service turn writes a trace
    (the turn without its tokens, the task and the full result, which carry workspace content) to
    TRACE_DIR on the pod's disk, outside the workspace Zetta. Found by this release.
  2. #33 (LSR-075, medium, denial of
    service): the bus consumer claims every task it receives into an unbounded executor queue before a
    worker is free, so one tenant's burst holds other tenants' tasks and their leases.
  3. #17: the task's workspace_id is not
    passed explicitly on data-plane calls and delegated turns, and the idle bus receive runs more
    often than once a minute.
  4. lake#989 (LSR-183): Lake's agent confirmation
    gates do not establish a separate human confirmer. This agent's proposals rely on those gates.
  5. Lake e2e T7 has not run against this image (above).
  6. #28: the foundation's analysis
    fallback drops get_dataset's typed column objects (zetta#1299), so on a current engine it yields
    no columns when analyze_dataset returns none.
  7. #27: no class-imbalance detection or
    PR-AUC/lift reporting.
  8. zetta#989: the corpus trajectories used as
    few-shot precedent were generated with model-written observations.

Where it has run

The v0.2.0 tree has not run on the dev environment. No dev build of this repository was pinned
on lake-nonprod's dev member; every Lake runs oramasearch/agent-project:v0.1.0 from the
operator's default Agent Library. What has run is the test suite below.

The image

Built from the tag v0.2.0 (e8324f6) 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-project-corpus-4537bcb), then tagged :v0.2.0 on that digest without rebuilding:

docker.io/oramasearch/agent-project:e8324f6@sha256:dc94533fa32954cc710e1b9f774475977efe67c07858cd8e8fb5e6d723cf2545, 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.

Verification

Proof Result
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12) 91 tests: 91 passed, 0 failed, 0 skipped: test_apps.py 6, test_catalog.py 1, test_edit.py 7, test_experiments.py 7, test_foundations.py 4, test_lake_bus.py 4, test_methodologies.py 6, test_release.py 2, test_service.py 7, test_service_auth.py 13, test_solutions.py 10, test_turn_destinations.py 24
Release notes for the code's version tests/test_release.py reads [project].version from pyproject.toml (0.2.0), checks the installed package agrees, and fails if these notes are missing or not indexed
Live model evaluation Not run (needs a live model)
Lake e2e T7 Not run (needs this image on lake-testing)
Linux image build (cluster BuildKit, from the tag) Built from v0.2.0 with build-agent.sh: oramasearch/agent-project:e8324f6, also :v0.2.0, sha256:dc94533fa32954cc710e1b9f774475977efe67c07858cd8e8fb5e6d723cf2545; private (404 anonymously)

Release v0.1.0

Choose a tag to compare

@homer6 homer6 released this 17 Oct 22:56
0aea3f9

agent-project v0.1.0

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

The Project Agent is one of Lake's library agents. Given a person's intent and the workspace it
belongs to, it builds and operates catalogue Solutions, designs Pipelines for a methodology, and
proposes changes to an existing Pipeline, by calling tools against the live workspace and
deciding each next call from what the previous one returned. It is not a trained model: it is a
frontier model reached through Lake's model gateway, with the solutions catalogue as context and
few-shot trajectories retrieved from agent-project-corpus. Everything it returns is a design or a
proposal (applied: false); Lake applies a change only when the person confirms it.

This release is the same tree as commit 16e17d0 (the image oramasearch/agent-project:16e17d0
that every Lake already runs), plus these notes, the release test and the version field on
/healthz.

What it includes

Turns

A turn arrives on Lake's agent bus (below) or at POST /v1/turn, and service.run_turn sends it
down exactly one of these paths:

Turn How it is recognised What the agent does Answer
Solution foundation kind starts with solution: (Lake sends solution:<project>) foundation.propose: reads get_solution, analyze_dataset, get_dataset, and plan_features for every methodology composed at the chosen level, maps only columns those observations support, and lists any policy predicate it could not find in missing_predicates. No model call. result.foundation for the person to review; only Lake's later confirm_solution creates anything
Change request (edit mode) context.pipeline is an object and context.project is set edit.propose: reads list_solutions and list_methodologies, then the model calls list_datasets, get_dataset, analyze_dataset, plan_features and compile_intent; each proposed edit is checked in order against the graph (edit.simulate) {"kind": "proposal", "proposal": {edits, steps, run, problems, after, …}}. The reply is written from the checked edits, never by the model
Solution operation no methodology requested (or a solution named), and the workspace's list_solutions returns entries solutions.operate: chooses only from the live list_solutions entries, reads the module, and may build and run it (tools below) the solution result, the policy proposal for owner sign-off, or a decline that names the entry's issue or promotion condition
Methodology design a methodology is requested, or the engine answers list_solutions with unknown_capability agent.build: chooses only a runnable: true entry of the live list_methodologies, then reads the data, plans features and compiles the engine's pipeline shape a pipeline design naming dataset, methodology, model_kind, its features or transform-first step, and label when the method requires one; or a decline naming the registry's issue

On an engine that answers list_methodologies with unknown_capability, only M-1 (churn / GBDT
classification) is offered, and every other method is declined with that limitation stated.

After a design or operation, two read-only handoffs may be attached to the answer, both requiring
lake_url and lake_token in the turn and a person's confirmation before anything happens:

  • ApplicationAgent (apps.py): when the turn carries results of a scored list, ranked list,
    scores, forecast or segment table, the agent reads Lake's App and build state and adds an
    app_handoff proposal for an agent-application turn of kind app.
  • ExperimentsAgent (experiments.py): when a design names a methodology and dataset, the agent
    reads the project's studies and either explains a matching study or adds an unapplied
    agent-experiments turn proposal (kind experiment).

Every completed turn is checked by agent.defects (or solutions.defects): an unjustified call, a
methodology absent from or not runnable in the registry, a missing analyze_dataset,
plan_features or compile_intent, a mutation that changed nothing. The defects are returned with
the answer.

What makes it a trajectory

Every tool call after the first must carry because, naming the observation that justified it. The
loop rejects a call without one before running it, and tools.undisciplined also flags a
justification that refers to nothing already observed. A failing tool is returned as an observation
(<call> FAILED: …), never raised. At most 12 model rounds per build (MAX_CALLS), 8 in edit mode.

Tools and the capabilities they call

Workspace calls go to zetta_base_url + /v1/<capability> with zetta_token as the bearer
(node.py); in Lake that is Lake's own path to the workspace Zetta, so Lake's allow-lists and audit
apply. Reads are GET, actions POST.

Model-facing tool Capability called Kind Used by
list_solutions list_solutions read every turn but foundation (called by the runtime, not the model)
get_solution, get_policy, get_experiment, list_ledger, get_monitor, get_roi_readout same names read solution operation; get_solution also foundation
create_solution, run_solution, decide, approve_decision same names action solution operation. run_solution must name the project and graph create_solution returned; approve_decision runs only when the turn's approval explicitly approves that decision
list_methodologies list_methodologies read methodology design and edit mode (called by the runtime)
list_datasets, get_dataset, analyze_dataset, plan_features same names read design, edit, foundation
list_pipelines list_projects read design
list_explainers list_models read design
compile_intent compile_intent action design and edit; only project, methodology, solution, hints, name, input_id are sent (#20)
clean, merge, aggregate, temporal_split, model, forecast, uplift_model, detect_anomalies, recommendation, add_explanation, serve, update_pipeline none local design step design: recorded in the returned pipeline, nothing runs

Lake capabilities, called at lake_url + /v1/<capability> with the turn's lake_token, reads
only:

Purpose Capabilities
App handoff list_apps, get_app, receive_app_events, list_builds, get_build, receive_build_events
Experiments handoff list_experiments, get_experiment_study
Agent bus receive_agent_tasks (read), claim_agent_task, publish_agent_event (actions), with the agent's bus credential

App, build, study and agent-turn actions (create_app, deploy_app, build_image, start_study,
promote_trial, agent_turn and the rest listed in apps.PROPOSED_ONLY_ACTIONS and
experiments.PROPOSED_ONLY_ACTIONS) appear only inside proposals; the agent never calls them. It has
no policy create or update tool.

Prompts

Path Prompt Constant
Methodology design prompts/v6.md agent.PROMPT_VERSION = "v6", returned as prompt_version
Solution operation prompts/v5.md solutions.PROMPT_VERSION = "v5", returned as prompt_version
Edit mode inline in edit.PROMPT no version constant

prompts/v1.md to v4.md are still in the package but no code path reads them. The design prompt
is followed by the solutions catalogue (ids and names, and the methodology families) and up to
PROJECT_SHOTS retrieved examples.

The model

Every model call of a service turn goes to Lake's model gateway, <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,
and a turn without lake_url and a Lake credential is refused (foundation turns, which call no
model, excepted). The model is PROJECT_MODEL (default gpt-4o), or the turn's model.

HTTP API (agent-project-serve, port PORT, default 8080)

Standard library only (http.server.ThreadingHTTPServer).

Route Behaviour
GET /healthz 200 {ok, agent, version, examples, model}; 503 {ok: false, error, version} when the corpus is missing or empty, because answering zero-shot would be a different agent. version is the installed package's version (new in this release)
POST /v1/turn Body {"request": "...", "context": {...}}, or {"task": {...}} in the command line's task shape, plus zetta_base_url, zetta_token, lake_url, lake_token, and optionally kind, model, methodology, solution, level, sources, approval, results, result_tables, before. Answers 200 {ok: true, trace_id, result}, 422 {ok: false, error} when the turn failed, 400 when the body is not JSON, 401 without the bearer token when AGENT_SERVICE_TOKEN is set
anything else 404

Each completed turn is written as a trace, TRACE_DIR/<trace_id>.json, with lake_token and
zetta_token blanked.

How Lake reaches it

  • The 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. The
    operator sets LAKE_URL, PORT, TRACE_DIR, PROJECT_MODEL, AGENT_SERVICE_TOKEN,
    AGENT_BUS_TOKEN (this agent's own bus credential) and AGENT_BUS_AGENT=agent-project.
  • Lake learns its address from LAKE_AGENT_ENDPOINTS (agent-project=http://…:8080), which
    the operator writes.
  • Turns are dispatched over the agent bus. Lake publishes the task id (never the co...
Read more