Skip to content

Release v0.1.0

Choose a tag to compare

@homer6 homer6 released this 17 Oct 22:56
· 36 commits to main since this release
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 content) on
    agent-tasks.agent-project of its own Zetta. lake_bus.py, started by serve in a background
    thread when LAKE_URL, AGENT_BUS_TOKEN and AGENT_BUS_AGENT are all set:
    1. 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 from next_sequence;
      a failed receive is logged and retried after 2 seconds;
    2. calls claim_agent_task {task_id, agent} for each task; a conflict or not_found means
      another replica won and the task is skipped. The claim's answer is the turn body, with the
      task's own credential as lake_token and zetta_token, and the task's kind is copied into
      it;
    3. runs the turn on a pool of 4 workers, exactly as /v1/turn would;
    4. reports with publish_agent_event: progress ("Working on it"), then result with the whole
      answer, or failed with the error.
      The agent sends no workspace_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.
  • /v1/turn stays 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.json and catalog.source.json, built by zetta's scripts/build_catalog.py
    from the solutions-designs plan. The context used for 16e17d0 records zetta cf20d264 and
    solutions-designs f335525a, built 2026-10-11.
  • corpus: project-sft-v1.jsonl from agent-project-corpus at 4537bcb (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.go on
    orama-operator dev) is oramasearch/agent-project:16e17d0.
  • Lake prod on the managing cluster orama-production-cluster-01 (namespace lake, the
    development environment) pins oramasearch/agent-project:16e17d0 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.

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.

  1. agent-project#17: the agent does not
    pass the task's workspace_id explicitly 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.
  2. POST /v1/turn is unauthenticated when AGENT_SERVICE_TOKEN is unset. The operator always sets
    it on library agents; a hand-run agent-project-serve without it accepts turns from anyone who
    can reach the port (agent-project#23).
  3. lake#796: a build turn on an engine that serves
    list_solutions calls create_solution, which the Project Agent's turn key (workspace_query /
    workspace_openapi) does not grant, so the turn ends declined with a 403 defect instead of a
    pipeline design.
  4. 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)