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
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version

## Unreleased

- **Budget meter and Costs page.** The top bar shows what the namespace picked spent against its budget, used and
left, highlighted when near or over, and follows the namespace switcher; it opens the details for a day, week or
month. **Costs** in the left menu shows spend by day, model and resource, and sets the namespace's budget
([Budgets](docs/budgets.md#the-meter-and-the-costs-page)).

## 0.7.0 <small>October 10, 2026</small> {id="0.7.0"}

- **Prometheus metrics.** Lens can serve `/metrics` for Prometheus and Grafana: jobs by status and pipeline, imports,
Expand Down
18 changes: 17 additions & 1 deletion docs/budgets.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,23 @@ Asking a routine to run from the app or the API when it's over budget is refused
Every five minutes the scheduler looks at every budget. One that crosses `warn_at` or its cap gets an alert, once per
period: on the budget (`alert`) and as a `budget.near` or `budget.over` row in its activity history.

## The meter and the Costs page

The top bar shows what the namespace picked in the switcher spent, against its budget: "$1.20 / $5" with a bar, gold
once the budget is near (`warn_at`) and red when it's used up. It counts the budget's own period (day, week or month);
without a budget it shows what was spent over the period you pick (day, week or month, remembered in this browser).
With "All namespaces" it shows what all of Lens spent (admins only), against the budget for all of Lens when one is set.
Clicking it opens the details: used and left, the spend for the period you pick and the models it went to.

**Costs** in the left menu has the rest for the same namespace and period: spend by day, by model, what cost most
(routines, pipelines, workflows, chats, documents), by namespace (for all of Lens), the namespace's budget to set or
change (admins), and every other budget with how much of it is used.

`GET /api/v1/budgets/meter?ns=&period=&detail=` serves both. Anyone who can read a namespace sees its meter; all of
Lens is admins'. A namespace's spend is the calls that count for it: its jobs, and requests to its own pages.

## Refine later

Forecasting from a routine's schedule (its runs left this period), per-person budgets, budget warnings sent through
notifications and the weekly digest, and the assistant answering "where do my budgets stand?" in chat.
notifications and the weekly digest, and the assistant answering "where do my budgets stand?" in chat. The meter could
count chats in a namespace (they aren't attributed to one yet) and show a forecast to the end of the period.
42 changes: 39 additions & 3 deletions fastapi_backend/app/api/v1/routes/budgets.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,13 @@

from __future__ import annotations

from typing import Literal

from fastapi import APIRouter, HTTPException, Query

from app.api.deps import AdminReader, AdminWriter, Db, domain_errors
from app.domain import auth, budgets
from app.schemas.budgets import BudgetSet, BudgetStatus
from app.api.deps import Acl, AdminReader, AdminWriter, CurrentUser, Db, domain_errors
from app.domain import auth, budgets, store
from app.schemas.budgets import BudgetMeter, BudgetSet, BudgetStatus
from app.schemas.common import Ok

router = APIRouter(tags=["budgets"])
Expand All @@ -20,6 +22,40 @@ def list_budgets(user: AdminReader, db: Db) -> list[BudgetStatus]:
return [budgets.status(db, b["resource"], b) for b in budgets.all_budgets(db)]


def _named(db, rows):
for r in rows:
table, _, key = r["resource"].partition(":")
row = db.one("SELECT name, title FROM $r", r=store.R(table, int(key))) if key.isdigit() else None
r["name"] = ((row or {}).get("name") or (row or {}).get("title")) or None
return rows


@router.get("/budgets/meter")
def budget_meter(
user: CurrentUser,
acl: Acl,
db: Db,
ns: str | None = Query(None, description="a namespace; none for all of Lens (admins)"),
period: Literal["day", "week", "month"] | None = Query(None, description="none: the budget's own period, else month"),
detail: bool = Query(False, description="also by day, by model and what cost most"),
) -> BudgetMeter:
"""What a namespace (or all of Lens) spent this day, week or month, against its budget when it has one: the top
bar's meter, and with `detail` the costs page. Anyone who can read a namespace sees its meter; admins see all of
Lens's."""
if ns:
resource = f"space:{acl.namespace(ns)}"
ref = resource
elif user.admin:
resource, ref = None, budgets.GLOBAL
else:
raise HTTPException(403, "only admins see what all of Lens spent; pick a namespace")
out = budgets.meter(db, resource, ref, period, detail)
if detail:
_named(db, out["top"])
_named(db, out.get("by_namespace") or [])
return BudgetMeter(namespace=ns, **out)


@router.get("/budgets/status")
def budget_status(user: AdminReader, db: Db, resource: str = RESOURCE) -> BudgetStatus:
"""Where a resource's budget stands, and what its next run will likely cost (also without a budget)."""
Expand Down
71 changes: 66 additions & 5 deletions fastapi_backend/app/domain/activity.py
Original file line number Diff line number Diff line change
Expand Up @@ -451,22 +451,83 @@ def spent(db, resource, since=None):
return round(float(row.get("usd") or 0), 6), int(row.get("tokens") or 0)


def top(db, prefix=None, since=None, limit=20):
"""The resources that cost most since a time, of one table (`routine`) or any: [{resource, cost_usd, tokens, calls}]."""
p = {"n": limit, "p": f"{prefix}:" if prefix else ""}
def top(db, prefix=None, since=None, limit=20, within=None):
"""The resources that cost most since a time, of one table (`routine`) or any, and only calls that also count for
`within` (a namespace, `space:3`) when given: [{resource, cost_usd, tokens, calls}]."""
p = {"p": f"{prefix}:" if prefix else ""}
inner = "kind != 'run' AND array::len(resources ?? []) > 0"
if within:
inner += " AND resources CONTAINS $w"
p["w"] = within
if since:
inner += " AND at >= $since"
p["since"] = since
rows = db.rows(
"SELECT resources AS resource, math::sum(cost_usd ?? 0) AS cost_usd, math::sum((tokens_in ?? 0) + (tokens_out ?? 0)) AS tokens, "
f"count() AS calls FROM (SELECT resources, cost_usd, tokens_in, tokens_out FROM activity WHERE {inner} SPLIT resources) "
"WHERE string::starts_with(resources, $p) GROUP BY resource ORDER BY cost_usd DESC, tokens DESC LIMIT $n",
"WHERE string::starts_with(resources, $p) GROUP BY resource",
**p,
)
for r in rows:
r["cost_usd"] = round(float(r.get("cost_usd") or 0), 6)
return rows
# sorted here: the database doesn't order grouped rows by an aggregate reliably
return sorted(rows, key=lambda r: (-r["cost_usd"], -(r.get("tokens") or 0)))[:limit]


def _scoped(resource, since):
where, p = ["kind != 'run'"], {}
if resource:
where.append("resources CONTAINS $res")
p["res"] = resource
if since:
where.append("at >= $since")
p["since"] = since
return " AND ".join(where), p


def by_model(db, resource=None, since=None):
"""What each model cost since a time, for a resource (or everything), most first: [{model, cost_usd, tokens, calls,
estimate}]. Calls with no model (webhooks, web tools) are under model None."""
where, p = _scoped(resource, since)
rows = db.rows(
"SELECT model, math::sum(cost_usd ?? 0) AS cost_usd, math::sum((tokens_in ?? 0) + (tokens_out ?? 0)) AS tokens, "
f"count() AS calls, count({_unpriced_sql()}) AS unpriced FROM activity WHERE {where} GROUP BY model",
**p,
)
out = [
{
"model": r.get("model"),
"cost_usd": round(float(r.get("cost_usd") or 0), 6),
"tokens": int(r.get("tokens") or 0),
"calls": r.get("calls") or 0,
"estimate": (r.get("unpriced") or 0) > 0,
}
for r in rows
]
return sorted(out, key=lambda r: (-r["cost_usd"], -r["tokens"]))


def by_day(db, resource=None, since=None):
"""What a resource (or everything) cost each day (UTC) since a time, oldest first: [{day, cost_usd, tokens, calls}].
Days with nothing are left out."""
where, p = _scoped(resource, since)
rows = db.rows(
"SELECT day, math::sum(cost_usd ?? 0) AS cost_usd, math::sum((tokens_in ?? 0) + (tokens_out ?? 0)) AS tokens, "
"count() AS calls FROM (SELECT string::slice(at, 0, 10) AS day, cost_usd, tokens_in, tokens_out FROM activity "
f"WHERE {where}) GROUP BY day",
**p,
)
out = [
{
"day": r["day"],
"cost_usd": round(float(r.get("cost_usd") or 0), 6),
"tokens": int(r.get("tokens") or 0),
"calls": r.get("calls") or 0,
}
for r in rows
if r.get("day")
]
return sorted(out, key=lambda r: r["day"])


def _unpriced_sql():
Expand Down
36 changes: 36 additions & 0 deletions fastapi_backend/app/domain/budgets.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
PERIODS = ("run", "day", "week", "month")
ON_OVER = ("ask", "skip", "assistant")
TABLES = ("routine", "pipeline", "workflow", "space")
GLOBAL = "all" # the budget for all of Lens (set in setup); the meter measures "all namespaces" against it
REF = re.compile(r"^(routine|pipeline|workflow|space):(\d+)$")
FIELDS = "resource, usd, tokens, period, on_over, warn_at, note, by, updated_at, alert"
LOOKBACK_DAYS = 30 # the past runs an estimate is drawn from
Expand Down Expand Up @@ -267,3 +268,38 @@ def sweep(db, cfg, now=None, every=None):
)
made.append({"resource": res, **alert})
return made


# ---------- the meter (top bar) and the costs page ----------
VIEW_PERIODS = ("day", "week", "month")
TOP_TABLES = ("routine", "pipeline", "workflow", "chat", "recording", "extension", "sensor", "note_page") # what "top" lists


def meter(db, resource, budget_ref=None, period=None, detail=False, now=None):
"""What a namespace (`space:<id>`), or all of Lens (resource None), spent this period, against its budget when it
has one: {resource, period, since, spent: {usd, tokens, estimate}, budget: status | None}. The period is the one
asked for, else the budget's own (day, week or month), else month. `budget_ref` is the budget to measure against
(the namespace's own by default). With `detail`, also by_day, by_model and top (what cost most in it)."""
budget_ref = budget_ref if budget_ref is not None else resource
b = get(db, budget_ref) if budget_ref else None
st = status(db, budget_ref, b, now) if b else None
if period not in VIEW_PERIODS:
period = b["period"] if b and b.get("period") in VIEW_PERIODS else "month"
since = activity._since(period, now)
t = activity.totals(db, resource, since)
out = {
"resource": resource,
"period": period,
"since": since,
"spent": {"usd": t["cost_usd"], "tokens": t["tokens_in"] + t["tokens_out"], "estimate": t["estimate"]},
"calls": t["calls"] - (t["by_kind"].get("run") or {}).get("calls", 0),
"budget": st,
}
if detail:
out["by_day"] = activity.by_day(db, resource, since)
out["by_model"] = activity.by_model(db, resource, since)
top = activity.top(db, None, since, 40, within=resource)
out["top"] = [r for r in top if r["resource"].split(":")[0] in TOP_TABLES][:12]
if resource is None:
out["by_namespace"] = activity.top(db, "space", since, 50)
return out
37 changes: 37 additions & 0 deletions fastapi_backend/app/schemas/budgets.py
Original file line number Diff line number Diff line change
Expand Up @@ -60,3 +60,40 @@ class BudgetStatus(ResponseModel):
left: dict[str, float] | None = None
share: float | None = Field(None, description="the largest share of a cap spent (1 is all of it)")
share_after_next: float | None = Field(None, description="the share once the next run (estimated) is done")


class DaySpend(ResponseModel):
day: str = Field(description="YYYY-MM-DD (UTC)")
cost_usd: float
tokens: int
calls: int


class ModelSpend(ResponseModel):
model: str | None = Field(None, description="none: calls with no model (webhooks, web tools)")
cost_usd: float
tokens: int
calls: int
estimate: bool


class TopSpend(ResponseModel):
resource: str
cost_usd: float
tokens: int
calls: int
name: str | None = Field(None, description="what the resource is called, when it has a name")


class BudgetMeter(ResponseModel):
resource: str | None = Field(None, description="space:<id>, or none for all of Lens")
namespace: str | None = None
period: Literal["day", "week", "month"]
since: str | None = None
spent: Spent
calls: int
budget: BudgetStatus | None = Field(None, description="where the budget it is measured against stands; none without one")
by_day: list[DaySpend] | None = None
by_model: list[ModelSpend] | None = None
top: list[TopSpend] | None = None
by_namespace: list[TopSpend] | None = None
32 changes: 32 additions & 0 deletions fastapi_backend/tests/api/test_budgets.py
Original file line number Diff line number Diff line change
Expand Up @@ -169,3 +169,35 @@ def test_the_periodic_check_warns_once_per_period(db, cfg):
assert [a["state"] for a in budgets.sweep(db, cfg)] == ["over"]
assert budgets.sweep(db, cfg) == []
assert [r["action"] for r in activity.history(db, "workflow:1", kind="run")] == ["budget.over", "budget.near"]


def test_the_meter_follows_the_namespace_and_its_budget(client, db, h):
sid = store.ns_id(db, "pods")
other = store.ns_id(db, "news")
rid = routine(client, h, "Digest")
activity.record("out", "model.chat", [f"space:{sid}", f"routine:{rid}"], db=db, model="gpt", cost_usd=0.3, tokens_in=100, tokens_out=20)
activity.record("out", "model.chat", [f"space:{sid}"], db=db, model="local", tokens_in=50)
activity.record("out", "model.chat", [f"space:{other}"], db=db, model="gpt", cost_usd=2.0, tokens_in=10)

m = client.get("/api/v1/budgets/meter", headers=h, params={"ns": "pods"}).json()
assert (m["resource"], m["period"], m["spent"]["usd"], m["spent"]["tokens"], m["calls"]) == (f"space:{sid}", "month", 0.3, 170, 2)
assert m["budget"] is None and m["by_day"] is None

budgets.put(db, f"space:{sid}", usd=0.5, period="week")
m = client.get("/api/v1/budgets/meter", headers=h, params={"ns": "pods", "detail": True}).json()
assert m["period"] == "week" and m["budget"]["state"] == "ok" and m["budget"]["left"]["usd"] == 0.2
assert [x["model"] for x in m["by_model"]] == ["gpt", "local"] and len(m["by_day"]) == 1
assert m["top"] == [{"resource": f"routine:{rid}", "cost_usd": 0.3, "tokens": 120, "calls": 1, "name": "Digest"}]
assert client.get("/api/v1/budgets/meter", headers=h, params={"ns": "pods", "period": "day"}).json()["period"] == "day"

# all of Lens: admins, against the one budget for everything
m = client.get("/api/v1/budgets/meter", headers=h, params={"detail": True}).json()
assert m["resource"] is None and m["spent"]["usd"] == 2.3 and m["budget"] is None
assert [x["resource"] for x in m["by_namespace"]] == [f"space:{other}", f"space:{sid}"]
assert m["by_namespace"][0]["name"] == "news"

make_user(db, "ed@x.io", "editor password 1", roles={"pods": "editor"})
e = login(client, "ed@x.io", "editor password 1")
assert client.get("/api/v1/budgets/meter", headers=e, params={"ns": "pods"}).json()["spent"]["usd"] == 0.3
assert client.get("/api/v1/budgets/meter", headers=e).status_code == 403
assert client.get("/api/v1/budgets/meter", headers=e, params={"ns": "news"}).status_code == 404
73 changes: 73 additions & 0 deletions nextjs-frontend/__tests__/budget-meter.test.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { render, screen } from "@testing-library/react";
import "@testing-library/jest-dom";

import { BudgetMeter } from "@/components/costs/budget-meter";

const budgetMeter = jest.fn();
let archive = { namespace: "pods" as string | null, admin: false, isPartial: () => false };
jest.mock("@/app/openapi-client", () => ({ Budgets: { budgetMeter: (o: unknown) => budgetMeter(o) } }));
jest.mock("@/lib/api/browser", () => ({ useApiClient: () => ({}), data: (p: Promise<unknown>) => p }));
jest.mock("@/lib/hooks/session", () => ({ useArchive: () => archive }));

function show() {
const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
return render(
<QueryClientProvider client={qc}>
<BudgetMeter />
</QueryClientProvider>,
);
}

const status = (share: number, state: string) => ({
resource: "space:1",
state,
share,
spent: { usd: share * 5, tokens: 100, estimate: false },
left: { usd: Math.max(0, 5 - share * 5) },
budget: { resource: "space:1", usd: 5, period: "week", on_over: "ask", warn_at: 0.8 },
next: { runs: 0, basis: "" },
});

afterEach(() => budgetMeter.mockReset());

describe("the top bar's budget meter", () => {
it("shows used and left against the namespace's budget, highlighted when near", async () => {
budgetMeter.mockResolvedValue({
resource: "space:1",
namespace: "pods",
period: "week",
spent: { usd: 4.5, tokens: 100, estimate: false },
calls: 3,
budget: status(0.9, "near"),
});
show();
const btn = await screen.findByRole("button", { name: /Spent this week in pods, \$0\.50 left/ });
expect(btn).toHaveTextContent("$4.50 / $5.00");
expect(btn.className).toContain("bg-gold-surface");
expect(budgetMeter).toHaveBeenCalledWith(
expect.objectContaining({ query: expect.objectContaining({ ns: "pods" }) }),
);
});

it("shows what was spent when there's no budget, and nothing for a member on all namespaces", async () => {
budgetMeter.mockResolvedValue({
resource: "space:1",
period: "month",
spent: { usd: 1.25, tokens: 100, estimate: false },
calls: 3,
budget: null,
});
const { unmount } = show();
expect(await screen.findByRole("button", { name: /Spent this month in pods\. Details/ })).toHaveTextContent(
"$1.25",
);
unmount();

archive = { namespace: null, admin: false, isPartial: () => false };
budgetMeter.mockClear();
const { container } = show();
expect(container).toBeEmptyDOMElement();
expect(budgetMeter).not.toHaveBeenCalled();
});
});
10 changes: 10 additions & 0 deletions nextjs-frontend/app/(app)/costs/page.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import type { Metadata } from "next";

import { CostsPage } from "@/components/costs/costs-page";

export const metadata: Metadata = { title: "Costs" };

/** Costs: what the namespace picked (or all of Lens) spent, by day, model and resource, against its budget. */
export default function Page() {
return <CostsPage />;
}
Loading
Loading