Repository navigation
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 content) on
agent-tasks.agent-projectof its own Zetta.lake_bus.py, started byservein a background
thread whenLAKE_URL,AGENT_BUS_TOKENandAGENT_BUS_AGENTare all set:- long-polls
receive_agent_tasks {agent, from_sequence, wait_ms: 10000}through Lake (it
never holds the bus's own token), starting at sequence 1 and continuing fromnext_sequence;
a failed receive is logged and retried after 2 seconds; - calls
claim_agent_task {task_id, agent}for each task; aconflictornot_foundmeans
another replica won and the task is skipped. The claim's answer is the turn body, with the
task's own credential aslake_tokenandzetta_token, and the task'skindis copied into
it; - runs the turn on a pool of 4 workers, exactly as
/v1/turnwould; - reports with
publish_agent_event:progress("Working on it"), thenresultwith the whole
answer, orfailedwith the error.
The agent sends noworkspace_id(Lake takes it from the task row) and does no lease handling of
its own; Lake renews the lease on each capability call made with the task credential.
- long-polls
/v1/turnstays for direct calls.
Command line ([project.scripts])
| Command | What it does |
|---|---|
agent-project <task.json> [--corpus PATH] [--model NAME] [--shots N] [--offline] |
One build from a task file against ZETTA_BASE_URL / ZETTA_TOKEN, printed as JSON. Exit 0 clean, 2 when the result has defects. Calls OpenAI directly with your own OPENAI_API_KEY, since it runs for no workspace. --offline skips the node: every observation says nothing ran |
agent-project-serve |
The service above |
Environment
| Variable | Read by | Meaning |
|---|---|---|
PORT |
service | listen port (default 8080) |
PROJECT_CORPUS |
service, CLI | the few-shot corpus, JSON lines (image: /app/corpus/project-sft-v1.jsonl) |
ZETTA_CATALOG |
catalogue | the built solutions catalogue (image: /app/catalog/catalog.json) |
ZETTA_BRIDGE |
catalogue | without ZETTA_CATALOG, the zetta-bridge checkout whose modules/zetta/scripts/build_catalog.py builds it |
PROJECT_MODEL |
service, CLI | model name (default gpt-4o) |
PROJECT_SHOTS |
service | retrieved examples per design turn (default 2) |
AGENT_SERVICE_TOKEN |
service | when set, the bearer token POST /v1/turn requires |
TRACE_DIR |
service | where traces are written (image: /tmp/agent-project-traces; the operator sets /tmp/traces) |
ZETTA_BASE_URL, ZETTA_TOKEN |
CLI; service fallback | the workspace when a turn names none |
LAKE_URL |
service, bus | Lake's address: the bus, and the model gateway when a turn names no lake_url |
AGENT_BUS_TOKEN, AGENT_BUS_AGENT |
bus | this agent's bus credential and the name it takes tasks under |
OPENAI_API_KEY |
CLI only | read by the OpenAI client; the service does not use it |
The image
Dockerfile: two stages on python:3.12-slim; uv 0.11.7 installs the locked, non-dev
dependencies into /app/.venv; the runtime runs as user 10001 (agent), exposes 8080 and starts
agent-project-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 context used for16e17d0records zettacf20d264and
solutions-designsf335525a, built 2026-10-11.corpus:project-sft-v1.jsonlfromagent-project-corpusat4537bcb(that repository's
v0.1.0 tree).
Published private as oramasearch/agent-project on Docker Hub. Built on the cluster BuildKit,
never with Docker on a workstation.
Digest: docker.io/oramasearch/agent-project:0aea3f9@sha256:4177bb8b99011680e67cdc5914626423062a9e0d7c9c1cd9e19477ed9ec31c44, also tagged :v0.1.0 (same digest).
Where it runs
Every Lake runs it.
- The Orama operator's default library image (
internal/controller/lake_defaults.goon
orama-operatordev) isoramasearch/agent-project:16e17d0. - Lake
prodon the managing clusterorama-production-cluster-01(namespacelake, the
development environment) pinsoramasearch/agent-project:16e17d0in 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.
v0.1.0 is that running commit plus these notes, the release test and the health version field.
Moving the operator default and the prod pin to :v0.1.0 is a separate operator change.
What it does not include
- A trained model. The agent is a frontier model with retrieved precedent; the corpus becomes
training data later (zetta#986). - Saving anything itself. Designs and edits are proposals; Lake applies them on the person's
confirmation. Policy changes are before/after proposals only. - Calling App, build, study or agent-turn actions. Those handoffs are proposals for a person to
confirm. - A local copy of the solution or methodology portfolio. Both come from the workspace each turn;
an older engine gets the M-1-only compatibility path. - Durable traces. Traces are files in the pod's
/tmp; they are not written to the workspace
Zetta and are lost when the pod restarts. - An offline evaluation. There is no eval command that runs without a live model.
Known issues
Security-relevant first.
- agent-project#17: the agent does not
pass the task'sworkspace_idexplicitly on its data-plane calls and delegated turns (Lake takes
it from the task credential today), and its idle bus receive runs back to back with a 10-second
wait, more often than the once-per-minute target. POST /v1/turnis unauthenticated whenAGENT_SERVICE_TOKENis unset. The operator always sets
it on library agents; a hand-runagent-project-servewithout it accepts turns from anyone who
can reach the port (agent-project#23).- lake#796: a build turn on an engine that serves
list_solutionscallscreate_solution, which the Project Agent's turn key (workspace_query/
workspace_openapi) does not grant, so the turn endsdeclinedwith a403defect instead of a
pipeline design. - zetta#989: the corpus trajectories used as
few-shot precedent were generated with model-written observations rather than ones a node
returned.
Verification
| Proof | Result |
|---|---|
Test suite (uv run --frozen pytest -q -ra, macOS arm64, Python 3.12) |
52 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_solutions.py 8 |
| Release notes for the code's version | tests/test_release.py reads [project].version from pyproject.toml, checks the installed package agrees, and fails if docs/releases/v<version>.md is missing, misnamed or not in the index |
| Live model evaluation | 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-project-corpus corpus/, identical at 4537bcb and v0.1.0): linux/amd64, pushed as oramasearch/agent-project:0aea3f9 |
| Image digest | docker.io/oramasearch/agent-project:0aea3f9@sha256:4177bb8b99011680e67cdc5914626423062a9e0d7c9c1cd9e19477ed9ec31c44, also tagged :v0.1.0 (same digest); the Docker Hub repository answers 404 anonymously (private) |