Add pricing to a tool (avoid the NotFound trap)

Pricing is the step people forget. A tool registers fine, resolves fine, then every call fails because the pricing lookup found no row. This page covers the whole model: how pricing is declared, the license/mode/cost knobs, the usage_field that makes a reserve quantity-aware, and why free must be explicit. The mechanism is live in the fleet today. Deployed

If you’re building a tool from scratch, read Add a tool worker first — pricing is step 3 there. This page is the detail behind it.

No pricing row → NotFound on every call

The consumer gateway’s generation pipeline runs FetchResolvedPricing — a bare SELECT … FROM generation.tool_configs JOIN tool_config_licenses … LIMIT 1 with no COALESCE. A tool with no pricing rows returns zero rows → pgx.ErrNoRows → the call fails with the Go scan error query scan failed: no rows in result set surfaced as NotFound. The gateway now catches this and re-raises ToolNotPriced (FAILED_PRECONDITION) with an actionable message, but the fix is always the same: declare pricing. This is distinct from the Python-side unknown or inactive tool error, which means the generation.tools registry row itself is missing.

Where pricing lives

You declare pricing as class attributes on your tool — the same place you set model and operation. On every boot, after RegisterTool, WorkerFleet upserts the declared config into the registry via idempotent ON CONFLICT … DO UPDATE RPCs. Your code is the source of truth: edit a value, restart the worker, it re-applies. There is no separate seeding script.

The WorkerFleet._apply_tool_config sequence (fleet.py) is:

1. UpsertToolConfig — the config row (tool_type, config_scope, and usage_field).
2. UpsertToolLicensePricing — one per license you accept.
3. UpsertToolRateLimits — only if you declared a RateLimit.
4. UpsertToolCredentials — only if a credentials field is non-empty.

The whole config step is best-effort: a failure is logged, not fatal, so one misconfigured tool doesn’t strand the rest of the worker — but that tool then fails loudly at call time. Pricing is keyed by the tool’s model + operation (the stable Soundverse id used for both pricing and credential lookup), not by the class name.

The LicensePricing shape

The dataclass is tiny — see config.py:

soundverse/tools/config.py

@dataclass(frozen=True)
class LicensePricing:
    license: tool_pb2.License.ValueType
    cost_mode: tool_pb2.CostMode.ValueType = tool_pb2.COST_MODE_STATIC
    cost_base: int = 0                    # reserve-time hold / flat cost
    cost_increment: int = 0               # per-unit cost (DYNAMIC only)
    cost_base_multiplier: float = 1.0
    cost_increment_multiplier: float = 1.0

Declare pricing as a tuple with one entry per license the tool serves. Most tools price all five identically with a comprehension:

app/tools/my_tool.py (class attributes)

from soundverse.tools import LicensePricing
from soundverse_proto.generation.tool.v1 import tool_pb2

class MyTool(BaseTool[MyInput, MyOutput]):
    model = "my-model"
    operation = "generate"
    cost_unit = "seconds"          # a label for reporting; not a billing input
    usage_field = "seconds"        # see below — makes the reserve quantity-aware
    pricing = tuple(
        LicensePricing(
            license=lic,
            cost_mode=tool_pb2.COST_MODE_DYNAMIC,
            cost_base=10,           # reserve floor
            cost_increment=1,       # per reported unit
        )
        for lic in (
            tool_pb2.LICENSE_ROYALTY_FREE,
            tool_pb2.LICENSE_STANDARD,
            tool_pb2.LICENSE_DISTRIBUTION,
            tool_pb2.LICENSE_SYNC,
            tool_pb2.LICENSE_MASTER,
        )
    )

The five licenses

Each call carries a requested license; the resolved pricing row is looked up per license, so a license you don’t declare fails as unpriced when someone requests it.

Enum	Value	Meaning
LICENSE_UNSPECIFIED	0	Never declare pricing for this — it is the zero value.
LICENSE_ROYALTY_FREE	1	The default license for free/agent tools.
LICENSE_STANDARD	2	Standard consumer license.
LICENSE_DISTRIBUTION	3	Distribution rights.
LICENSE_SYNC	4	Sync (film/ad) rights.
LICENSE_MASTER	5	Master / full ownership — the paywalled tier.

There is no LICENSE_PRO

A common mistake copied from older notes. The real enum values are exactly the five above (plus UNSPECIFIED). Reference them from tool_pb2 — don’t invent names.

cost_mode: STATIC vs DYNAMIC

The two knobs are cost_base and cost_increment, and cost_mode decides whether the increment is used at all.

• COST_MODE_STATIC (the dataclass default) — a flat charge of cost_base per call. cost_increment is ignored. Reserve and settle are identical.
• COST_MODE_DYNAMIC — cost_base is a floor, and cost_increment is added per unit of reported usage. The worker calls ctx.report_usage(units); the settlement charges cost_base + cost_increment × units.

The reserve (up-front hold) and settle (final charge) math is identical byte-for-byte across the Go pricing path (core-mcp/internal/pricing/pricing.go) and the Python gateway path (core-gateway-consumer/app/enforcement/pricing.py):

the reserve/settle formula

estimate(planned) = ceil( cost_base·cost_base_multiplier
                          + [DYNAMIC and planned>0]  cost_increment·cost_increment_multiplier·planned )

actual(usage)     = ceil( cost_base·cost_base_multiplier
                          + [DYNAMIC]                cost_increment·cost_increment_multiplier·usage )

The two multipliers exist because cost_increment is an int64: to express a fractional per-unit rate (e.g. a per-second SFX price of 28.8 tokens), declare cost_increment=288, cost_increment_multiplier=0.1. See sfx_tool.py for a worked example.

The worker never bills

process() only calls ctx.report_usage(units) with raw usage. core-mcp (agent path) and core-gateway-consumer (consumer path) price and settle. cost_base is checked before generation as the reserve hold; cost_increment is applied at settlement. See the token ledger & money path.

usage_field: make the reserve quantity-aware

This is the trap that lets users generate for free. Compare the two formulas above: the settlement (actual) always adds the increment term in DYNAMIC mode, but the reserve (estimate) only adds it when planned > 0. planned comes from reading the tool’s declared usage_field out of the call payload.

So for a COST_MODE_DYNAMIC tool with cost_base=0 and no usage_field:

• reserve estimate = ceil(0) = 0,
• Reserve short-circuits on amount <= 0 → no balance check,
• the worker generates unconditionally,
• settle charges cost_increment × units after the asset already shipped — which silently fails for a broke user.

Result: unlimited free generations. The fix is to declare usage_field = the name of the input field that holds the planned count, so the reserve holds cost_increment × planned up front:

song generation — DYNAMIC, priced per version

class SongOrchestration(BaseTool[Any, SongGenOut]):
    operation = "generate_song"
    cost_unit = "songs"
    usage_field = "versions"        # the input field that holds the planned count (1–2)
    pricing = tuple(
        LicensePricing(
            license=lic,
            cost_mode=tool_pb2.COST_MODE_DYNAMIC,
            cost_increment=_PER_SONG_CREDITS,   # cost_base stays 0
        )
        for lic in ( ... )          # all five licenses
    )

With usage_field="versions", a request for 2 versions holds 2 × _PER_SONG_CREDITS before QueueTask, so a zero-balance user is rejected with INSUFFICIENT_FUNDS before generation. If fewer versions come back, settlement reconciles down to the actual count. When usage_field is empty, planned is 0 and you get the legacy base-only hold — which is exactly right for a STATIC tool, and exactly wrong for a DYNAMIC one with a zero base. Verified in song_gen.py.

DYNAMIC + cost_base=0 needs a usage_field

The rule of thumb: if cost_mode is DYNAMIC and cost_base is 0, you must set usage_field, or the reserve holds nothing and generation is free. Either add a usage_field, or give it a non-zero cost_base floor (see the stitch example below).

FREE must be explicit

“No pricing” is not free — it’s the NotFound trap. A free tool declares a real LicensePricing with cost_base=0 (the dataclass default) in COST_MODE_STATIC (also the default) for every license it serves:

a genuinely-free tool

pricing = tuple(
    LicensePricing(license=lic, cost_base=0)     # STATIC, zero — free but present
    for lic in (
        tool_pb2.LICENSE_ROYALTY_FREE,
        tool_pb2.LICENSE_STANDARD,
        tool_pb2.LICENSE_DISTRIBUTION,
        tool_pb2.LICENSE_SYNC,
        tool_pb2.LICENSE_MASTER,
    )
)

This is how album-art (prompt_to_image.py) and the Agent One worker (agent_tool.py) price today. Note that STATIC + cost_base=0 is safe (a flat zero, nothing to hold), whereas DYNAMIC + cost_base=0 is the trap above.

Real shapes in the fleet

Free (STATIC)

Flat zero across all licenses — the album-art / agent shape. Present, so no NotFound; free, because both cost knobs are zero and STATIC ignores the increment.

pricing = tuple(LicensePricing(license=lic, cost_base=0) for lic in (...))

Per-unit (DYNAMIC)

Priced per reported unit, with a usage_field so the reserve is quantity-aware — the song_gen shape.

usage_field = "versions"
pricing = tuple(
    LicensePricing(license=lic, cost_mode=tool_pb2.COST_MODE_DYNAMIC,
                   cost_increment=_PER_SONG_CREDITS)
    for lic in (...)
)

Floor + per-unit

A per-call floor (cost_base) plus a per-unit increment settled from ctx.report_usage — the stitch shape (stitch_tool.py). The non-zero floor means it never hits the free-generation trap even without a usage_field.

cost_unit = "complexity"
pricing = tuple(
    LicensePricing(license=lic, cost_mode=tool_pb2.COST_MODE_DYNAMIC,
                   cost_base=_RESERVE_FLOOR_CREDITS,
                   cost_increment=_CREDITS_PER_COMPLEXITY)
    for lic in (...)
)

Fractional per-unit

A fractional per-second rate expressed via the increment multiplier (int64 increment can’t hold a fraction) — the SFX shape.

usage_field = "duration_seconds"
pricing = tuple(
    LicensePricing(license=lic, cost_mode=tool_pb2.COST_MODE_DYNAMIC,
                   cost_increment=_SFX_COST_INCREMENT,
                   cost_increment_multiplier=_SFX_COST_MULTIPLIER)
    for lic in (...)
)

Checklist

1. Declare pricing as a tuple with one LicensePricing per license you accept. Serving a license you didn’t price fails that call as unpriced.

2. Pick cost_mode. Flat charge → COST_MODE_STATIC with cost_base. Per-unit → COST_MODE_DYNAMIC with cost_increment.

3. If DYNAMIC, guard the reserve. Set usage_field to the input field holding the planned count, or set a non-zero cost_base floor. Never ship DYNAMIC + cost_base=0 + no usage_field.

4. For a free tool, be explicit — LicensePricing(license=lic, cost_base=0) (STATIC) per license. Not declaring pricing is the NotFound trap, not “free”.

5. Restart the worker. The fleet re-upserts the declared config on boot; there is no separate seed step.

6. Deploy DYNAMIC changes in the safe order. Publish the proto, add the generation.tool_configs.usage_field column, roll out core-database, then soundverse-py, then the workers (re-registration writes usage_field), then core-mcp + the gateway (the reserve sites) last so an empty usage_field fails to a safe base-only hold. Then flush the resolved_price:* Redis keys once — UpsertToolConfig invalidates the tool-hierarchy cache, not the 60-second resolved-price cache.

Changing pricing? Two caches, one restart

Pricing edits re-apply on worker restart, but the gateway/core-mcp keep a ~60s resolved_price:* cache that UpsertToolConfig does not invalidate. Flush it once after a pricing change or wait out the TTL. (Separately, changing your input/output schema — not pricing — needs a core-mcp restart; see core-mcp.)

Related

• Add a tool worker — pricing is step 3 of the full recipe
• Tool pricing model — the three-level scope cascade and how resolution works
• The token ledger & money path — estimate → reserve → settle
• Billing reconciliation — how surplus holds are settled back
• core-tool-sansaarm — the song_gen per-version pricing in context