Repository navigation
Releases
Release v0.3.0
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.worknow claims only when a worker slot is free and receives nothing while all are busy.AGENT_BUS_WORKERS(default 4) sets the slots andAGENT_BUS_TENANT_WORKERS(default one fewer) caps one customer; at most 256 dispatch rows wait.receivepasses the long poll'swait_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.
- #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. - #34: turn traces keep workspace content on the pod's disk (
TRACE_DIR), outside the workspace Zetta. - #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.
- #28: the analysis fallback does not read
get_dataset's typed columns. - #27: designing does not detect class imbalance or report imbalanced runs by PR-AUC and lift.
- 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
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'slake_urlis never used for it; zetta_base_urlandlake_urlare accepted only onLAKE_URL's origin and under its path, with
no user info, query, fragment, backslash or./..segment; any other address refuses the turn;- with
LAKE_URLunset, every turn that would send its credential is refused; - a turn that names no
zetta_base_urlstill uses the environment'sZETTA_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; itsresult.pipelineis 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_intentstores a graph in a project, so the methodology design calls it, and the
validator requires it, only when the turn names a project.- Prompt
v7for the methodology design (v6 plus that rule and the routing wording). Solution
operation stays onv5;v1tov6stay 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.
- #34: every service turn writes a trace
(the turn without its tokens, the task and the full result, which carry workspace content) to
TRACE_DIRon the pod's disk, outside the workspace Zetta. Found by this release. - #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. - #17: the task's
workspace_idis not
passed explicitly on data-plane calls and delegated turns, and the idle bus receive runs more
often than once a minute. - lake#989 (LSR-183): Lake's agent confirmation
gates do not establish a separate human confirmer. This agent's proposals rely on those gates. - Lake e2e T7 has not run against this image (above).
- #28: the foundation's analysis
fallback dropsget_dataset's typed column objects (zetta#1299), so on a current engine it yields
no columns whenanalyze_datasetreturns none. - #27: no class-imbalance detection or
PR-AUC/lift reporting. - 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
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 carriesresultsof a scored list, ranked list,
scores, forecast or segment table, the agent reads Lake's App and build state and adds an
app_handoffproposal for anagent-applicationturn of kindapp. - 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-experimentsturn proposal (kindexperiment).
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 setsLAKE_URL,PORT,TRACE_DIR,PROJECT_MODEL,AGENT_SERVICE_TOKEN,
AGENT_BUS_TOKEN(this agent's own bus credential) andAGENT_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...