Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
# AGENTS.md: working in agent-application

The ApplicationAgent: builds web apps and data apps from a description, commits them to a lake repository, and deploys them as lake Apps after the person confirms. Built on agent-runtime. Epic: oramasearch/lake#297.
The ApplicationAgent: builds web apps and data apps from a description, commits them to a Lake repository, and deploys them as Lake Apps after the person confirms. Built on agent-runtime. Read `README.md` and `docs/README.md` first.

## Non-negotiables (org-wide)
- **No AI attribution** anywhere: no Co-Authored-By, no "Generated with", no mention of AI in commits, PRs, tags or release notes.
## Build and test
- Python with uv, never pip: `uv sync`, then `uv run --group dev pytest`.

## Non-negotiables
- **No AI attribution** anywhere: no AI Co-Authored-By trailer, no "Generated with", no mention of AI in commits, PRs, tags or release notes.
- **No time or size estimates.** Do the work; report concrete results.
- **Docs in the same change:** update README.md (and any docs page) with every code change.
- **Feature branch + PR.** Never push to `main`. PRs reference their issue with `Refs #N`, never an auto-close keyword.
- **Private by default.** This repo and its Docker Hub image `oramasearch/agent-application` are private; never make either public.
- **Feature branch + PR**, Conventional Commits. Never push to the default branch. PRs reference their issue with `Refs #N`, never an auto-close keyword.
- Never run a formatter over files you did not otherwise change.
- Never write the word "seam": name the mechanism (interface, extension point, boundary).
4 changes: 4 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@
# change of the digest, not a moved tag.
FROM python:3.12-slim@sha256:5e2bdb1b0d542d5039cffb8181c65930093949194a65c365dfb1b0fe13a4fa5b AS build
COPY --from=ghcr.io/astral-sh/uv:0.11.7@sha256:240fb85ab0f263ef12f492d8476aa3a2e4e1e333f7d67fbdd923d00a506a516a /uv /usr/local/bin/uv

# ApplicationAgent, published on Docker Hub as oramasearch/agent-application.
FROM python:3.12-slim AS build
COPY --from=ghcr.io/astral-sh/uv:0.11.7 /uv /usr/local/bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock README.md ./
COPY src ./src
Expand Down
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# agent-application

The ApplicationAgent: builds web apps and data apps from a description, commits them to a lake repository, and deploys them as lake Apps after the person confirms. Built on agent-runtime. Epic: oramasearch/lake#297.
The ApplicationAgent: builds web apps and data apps from a description, commits them to a lake repository, and deploys them as lake Apps after the person confirms. Built on agent-runtime.

Private. Its image is published **private** as `oramasearch/agent-application` on Docker Hub.
Its image is published as `oramasearch/agent-application` on Docker Hub.

The Dockerfile pins its bases by multi-platform index digest (lake#1003): `python:3.12-slim@sha256:5e2bdb1b…` for both stages and `ghcr.io/astral-sh/uv:0.11.7@sha256:240fb85a…`. Moving one is a reviewed change of its digest.

Expand Down Expand Up @@ -36,7 +36,7 @@ counts its tokens in the turn's workspace and enforces the account's model-token
holds no `OPENAI_API_KEY`; only the offline evals, which run for no workspace, call OpenAI directly. The model name is `APPLICATION_AGENT_MODEL`, else the Lake's `AGENT_MODEL` (set
by the operator from `spec.agents.model`), else `gpt-6.1-sol` (`docs/operations/service.md`).

**A turn's credential goes only to Lake at this service's own `LAKE_URL`** (#30). Lake capabilities
**A turn's credential goes only to Lake at this service's own `LAKE_URL`**. Lake capabilities
and the model gateway are always reached at `LAKE_URL`; a turn's `lake_url` is ignored, so the
bearer is never sent to a host the caller names. With `LAKE_URL` unset, or not an absolute
http(s) URL without user info, query or fragment, every turn is refused before a request is made.
Expand All @@ -58,7 +58,7 @@ writes. A follow-up turn must carry the reviewed object in `context.confirmed_pr
does the agent commit the files, create or update the App, deploy it, and follow its rollout.
The follow waits up to three minutes for Ready: a starting pod's Degraded or failed probe is not
judged, only a state that is still there at the deadline (re-read with `get_app`). When the App
logs are unavailable the reply says so and never gives that as the reason it failed (#16).
logs are unavailable the reply says so and never gives that as the reason it failed.
Retries reuse a repository or App with the proposal's exact name in the same customer, so a
failure after either row is created can resume from the reviewed proposal.
Every customer-owned read (repositories, datasets, services, App state, and image-build state)
Expand All @@ -77,7 +77,7 @@ phase, and deploys the built image. Baked-only Apps skip the image build.
## Repairing and changing an App

Lake also starts `repair` turns (an App failed) and `change` turns (more instructions for an App)
on an existing App named by `context.app_id` (lake#1207). The agent reads the App's events,
on an existing App named by `context.app_id`. The agent reads the App's events,
runtime logs, newest build, source and bindings, and proposes the change as a diff of the files it
changes. Confirmed, it commits them to the App's repository in one commit (each write a drip),
rebuilds when new packages need an image, redeploys and follows the rollout. An auto-fix turn,
Expand All @@ -88,7 +88,7 @@ which lake grants only when the person opted in and attempts remain, applies its

`uv run pytest` covers the service, bus, proposal rules, confirmation gate, deployment calls, and
generated Apps loaded by the pinned app-runtime revision, and whether a generated Streamlit App's sidebar
filters reach every metric, chart and table (agent-application#64): the App runs under Streamlit's
filters reach every metric, chart and table: the App runs under Streamlit's
`AppTest` over a SQLite copy of its dataset and each filter is chosen in turn
(`agent_application.app_filters`). Every proposal is also refused when a widget's value is assigned and
never used. The generation and change prompts require every filter to apply to the whole page, `OR`
Expand Down
2 changes: 1 addition & 1 deletion docs/building/apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ reads on the bare function, with the line and the right form: such code compiles

Generated Apps read only what the page shows: SQL aggregates (`GROUP BY`, `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`)
and row-level reads paged with `LIMIT`/`OFFSET`. Validation and repair flag a literal `sql(...)` statement that reads
rows with neither a `LIMIT` nor an aggregate (#51): it copies a whole table into the App, and Lake refuses an App query
rows with neither a `LIMIT` nor an aggregate: it copies a whole table into the App, and Lake refuses an App query
past 5,000 rows (`too_many_rows`). The workspace's SQL has no joins, so combined data comes from a table a pipeline
writes.

Expand Down
4 changes: 2 additions & 2 deletions docs/building/repair.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Repairing and changing an App

Lake starts two more kinds of ApplicationAgent turn on an App that already exists
([lake#1207](https://github.com/oramasearch/lake/issues/1207), lake `docs/api/notifications.md`):
(lake#1207, lake `docs/api/notifications.md`):

- **`repair`**: the App failed. Its rollout ended Degraded, failed or crash-looping, or its image
build failed. The person pressed *Fix with the Application Agent*, or auto-fix started it.
Expand All @@ -18,7 +18,7 @@ prompt is `prompts/repair-v1.md`.
With the turn's read-only credential, scoped to the person's own permissions:

- the App's lifecycle events (`receive_app_events` from the first retained one);
- its runtime logs (`app_logs`). When lake cannot answer them (lake#1206), the agent says so in
- its runtime logs (`app_logs`). When lake cannot answer them, the agent says so in
what it sends the model and works from the events, the build log and the source. It never gives
missing logs as the reason the App failed;
- its newest image build and the build log (`list_builds`, `build_logs`);
Expand Down
2 changes: 1 addition & 1 deletion docs/evals/scenarios.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The cases require:
the baked runtime is required;
- a static internal forecast guide with no unnecessary binding;
- a Streamlit customer-insights dashboard with sidebar filters for country, segment and a signup
date range, where every filter applies to every metric, chart and table (agent-application#64).
date range, where every filter applies to every metric, chart and table.

The rule grader validates the complete proposal, framework, bindings, and scenario-specific source
markers. It also requires the dashboard to read datasets, schema, and governed SQL, and the CRUD
Expand Down
11 changes: 5 additions & 6 deletions docs/operations/service.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,21 +15,20 @@ person's delegated credential remains inside the claimed task body.

The model is `APPLICATION_AGENT_MODEL` when it is set, else `AGENT_MODEL`, else `gpt-6.1-sol`. The Orama
operator sets `AGENT_MODEL` on every library agent pod from the Lake's `spec.agents.model`, so the
Lake's model choice reaches this agent; `APPLICATION_AGENT_MODEL` is this agent's own override
([agent-application#22](https://github.com/oramasearch/agent-application/issues/22)). `/healthz`
Lake's model choice reaches this agent; `APPLICATION_AGENT_MODEL` is this agent's own override. `/healthz`
reports the model in use.

A turn keeps nothing on the pod's disk (agent-application#21). The pod serves every workspace, and
A turn keeps nothing on the pod's disk. The pod serves every workspace, and
a turn's message and answer, including the generated App source, are that workspace's content,
which belongs in its workspace Zetta. No trace file is written: the answer goes back on the bus (or
in the `/v1/turn` response) with its `trace_id`, and lake keeps it in the task's record in the
turn's workspace Zetta (lake `docs/api/agent-bus.md`). `TRACE_DIR` is no longer read.

The image runs as UID 10001, exposes port 8080, and is private as
`oramasearch/agent-application`. The repository and image must remain private.
The image runs as UID 10001, exposes port 8080, and is published as
`oramasearch/agent-application`.


A turn's credential goes only to Lake at this service's own `LAKE_URL` (agent-application#30): Lake
A turn's credential goes only to Lake at this service's own `LAKE_URL`: Lake
capabilities and the model gateway are always reached there, and a `lake_url` in the turn is
ignored, so the bearer is never sent to a host the caller names. With `LAKE_URL` unset, or not an
absolute http(s) URL without user info, query or fragment, every turn is refused before any request
Expand Down
12 changes: 6 additions & 6 deletions docs/releases/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ One page per tagged release, newest first. A page states what the release includ
not include, known issues, verification output, and where the image runs. The first release lists
everything the agent does.

A release has one `vX.Y.Z` name shared by the Git tag, the GitHub release and the private Docker Hub
A release has one `vX.Y.Z` name shared by the Git tag, the GitHub release and the Docker Hub
image tag `oramasearch/agent-application:vX.Y.Z`. The image tag names the digest built from the Git
tag and deployed; it is never produced by a second build.

Expand All @@ -13,12 +13,12 @@ tag and deployed; it is never produced by a second build.
| [v0.2.7](v0.2.7.md) | 2026-10-27 | A patch: files read exactly; filters applied everywhere |
| [v0.2.6](v0.2.6.md) | 2026-10-26 | A patch: repository paths are written without '.' components, so a confirmed App at path '.' commits |
| [v0.2.5](v0.2.5.md) | 2026-10-26 | A patch: repository paths are written without '.' components, so a confirmed App at path '.' commits |
| [v0.2.4](v0.2.4.md) | 2026-10-26 | A patch: a conversation is seeded from Lake's history after a restart (#55) |
| [v0.2.3](v0.2.3.md) | 2026-10-26 | A patch: generated Apps aggregate in SQL and page their reads (#51); fallback model `gpt-6.1-sol` |
| [v0.2.2](v0.2.2.md) | 2026-10-26 | A patch: generated Apps call `zetta()` before its reads; `zetta.sql(...)` is refused before commit (#47) |
| [v0.2.1](v0.2.1.md) | 2026-10-25 | A patch: `repair` and `change` turns on an existing App, as a confirmed diff committed in one commit, with Lake's opt-in auto-fix (lake#1207) |
| [v0.2.4](v0.2.4.md) | 2026-10-26 | A patch: a conversation is seeded from Lake's history after a restart |
| [v0.2.3](v0.2.3.md) | 2026-10-26 | A patch: generated Apps aggregate in SQL and page their reads; fallback model `gpt-6.1-sol` |
| [v0.2.2](v0.2.2.md) | 2026-10-26 | A patch: generated Apps call `zetta()` before its reads; `zetta.sql(...)` is refused before commit |
| [v0.2.1](v0.2.1.md) | 2026-10-25 | A patch: `repair` and `change` turns on an existing App, as a confirmed diff committed in one commit, with Lake's opt-in auto-fix |
| [v0.2.0](v0.2.0.md) | 2026-10-25 | Security-review fixes (constant-time service token, refused when unset; the turn credential only to `LAKE_URL`; no turn trace on disk), Lake secret references, and the Lake's `AGENT_MODEL` |
| [v0.1.0](v0.1.0.md) | 2026-10-17 | The first release: the turn API and `/healthz`, the agent-bus worker, the propose-then-confirm App build and deploy through lake, prompt `v1`, and the private image |
| [v0.1.0](v0.1.0.md) | 2026-10-17 | The first release: the turn API and `/healthz`, the agent-bus worker, the propose-then-confirm App build and deploy through lake, prompt `v1`, and the image |

`pyproject.toml`'s `[project].version` is the one place the version is set; `GET /healthz` reports
it, and `tests/test_release.py` fails when that version has no page here.
37 changes: 15 additions & 22 deletions docs/releases/v0.1.0.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
# agent-application v0.1.0

**Released 2026-10-17. The first release.** One Python service, the **Application Agent**, and one
private image, `docker.io/oramasearch/agent-application:v0.1.0`. Proprietary to Orama; private
repository and image.
image, `docker.io/oramasearch/agent-application:v0.1.0`.

The Application Agent builds web apps and data apps for a person from a description, and deploys
them as lake Apps only after that person confirms. A first turn reads the workspace facts it needs
Expand Down Expand Up @@ -97,12 +96,12 @@ list; anything else is refused before a request is made): `list_datasets`, `get_

Lake grants a confirmed turn's credential `create_repository`, `commit_repository_files`,
`create_app`, `build_app`, `get_build` and `deploy_app` only when `agent_turn` verified the
confirmation against the stored proposal (lake#561).
confirmation against the stored proposal.

### The model

- Every model call goes to lake's model gateway, `<lake_url>/openai/v1`, with the turn's own
credential as the API key (lake#248). Lake counts the tokens against the turn's workspace and
credential as the API key. Lake counts the tokens against the turn's workspace and
enforces the account's model-token limit. The service holds no provider key.
- Chat Completions with JSON output, up to 10 tool rounds per answer and up to 2 repair rounds in
which the validation failures are sent back to the model.
Expand Down Expand Up @@ -148,7 +147,7 @@ confirmation against the stored proposal (lake#561).

### The image

`docker.io/oramasearch/agent-application`, **private** on Docker Hub.
`docker.io/oramasearch/agent-application` on Docker Hub.

- Two stages on `python:3.12-slim`: the build stage copies `uv` 0.11.7 from
`ghcr.io/astral-sh/uv:0.11.7` and runs `uv sync --frozen --no-dev --no-editable`; the runtime
Expand All @@ -174,14 +173,11 @@ confirmation against the stored proposal (lake#561).

Every Lake runs it.

| Lake | Image |
|---|---|
| `prod` on the managing cluster `orama-production-cluster-01` (namespace `lake`; the development environment) | `oramasearch/agent-application:3a38da8`, pinned in its `spec.agents` |
| The LakeSet `lake-nonprod`: members `dev`, `staging`, `testing` on `orama-nonprod-cluster-01` | The operator default (`internal/controller/lake_defaults.go` on `dev`): `oramasearch/agent-application:3a38da8` |
| The LakeSet `lake-prod`: members `shared` on `orama-production-cluster-02`, `shared-us` on `orama-production-cluster-03` | The operator default, the same image |
Every Lake takes the operator default (`internal/controller/lake_defaults.go`),
`oramasearch/agent-application:3a38da8`, unless its resource pins another image in `spec.agents`.

v0.1.0 is that running commit plus these notes, the release test and `version` in `/healthz`.
Moving the operator default and Lake `prod`'s pin to `:v0.1.0` is a separate operator change.
Moving the operator default to `:v0.1.0` is a separate operator change.

## What it does not include

Expand All @@ -204,25 +200,22 @@ Security-relevant first.
1. **Turn traces hold workspace content outside the workspace Zetta.** Every turn writes the
person's message and the whole answer (the generated source) as JSON to `TRACE_DIR` on the pod's
`/tmp`, kept until the pod is replaced. The org rule is that workspace data lives in the
workspace Zetta. [agent-application#21](https://github.com/oramasearch/agent-application/issues/21).
workspace Zetta. agent-application#21.
2. **`POST /v1/turn` is unauthenticated when `AGENT_SERVICE_TOKEN` is unset.** The operator always
sets it; a hand-run service without it accepts any caller (who still needs a valid lake
credential to do anything). [agent-application#23](https://github.com/oramasearch/agent-application/issues/23).
3. **Secret references in a proposal use the old form, which lake now refuses**
([agent-application#19](https://github.com/oramasearch/agent-application/issues/19)): the prompt
credential to do anything). agent-application#23.
3. **Secret references in a proposal use the old form, which lake now refuses**: the prompt
and the validator propose `{"secret": "<name>"}`, and lake's `create_app` answers
`invalid_input`, so an App that needs a secret environment variable cannot be created by the
agent.
4. **A repository with the same name in another workspace makes the deploy fail with a conflict**
([agent-application#18](https://github.com/oramasearch/agent-application/issues/18)):
4. **A repository with the same name in another workspace makes the deploy fail with a conflict**:
`ensure_repository` matches by name and customer, not workspace.
5. **No explicit workspace IDs, and no idle backoff on the bus**
([agent-application#3](https://github.com/oramasearch/agent-application/issues/3)): calls rely on
5. **No explicit workspace IDs, and no idle backoff on the bus**: calls rely on
the task credential for the workspace, and the receive loop does not hold to at most one empty
receive per minute.
6. **The Lake's agent model setting does not reach this agent.** The operator sets `AGENT_MODEL`
from `spec.agents.model`; the agent reads `APPLICATION_AGENT_MODEL`, so it always uses its
default `gpt-5.5`. [agent-application#22](https://github.com/oramasearch/agent-application/issues/22).
default `gpt-5.5`. agent-application#22.
7. **The model is offered reads a design turn cannot make.** `lake_read` lists `build_logs`,
`get_build` and `receive_build_events`, which lake grants only on a confirmed turn; on a design
turn they come back as errors to the model.
Expand All @@ -236,5 +229,5 @@ Security-relevant first.
| Release test | `tests/test_release.py` reads the version from `pyproject.toml` and the installed package, and fails when `docs/releases/v<version>.md` or its index line is missing |
| `/healthz` version | `test_healthz_reports_the_release_version`: `version` is the installed package's version |
| Live model evals (`application-agent-evals`) | 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`: linux/amd64, pushed as `oramasearch/agent-application:4607d85` |
| Image digest | `docker.io/oramasearch/agent-application:4607d85@sha256:126faa961f393518fdc18d03c5e97e67158a3e3158fb822c796cd0abb7ccb8c6`, also tagged `:v0.1.0` (same digest); the Docker Hub repository answers 404 anonymously (private) |
| Linux image build (BuildKit, from the tag) | Built from the tag `v0.1.0`: linux/amd64, pushed as `oramasearch/agent-application:4607d85` |
| Image digest | `docker.io/oramasearch/agent-application:4607d85@sha256:126faa961f393518fdc18d03c5e97e67158a3e3158fb822c796cd0abb7ccb8c6`, also tagged `:v0.1.0` (same digest) |
Loading