Blueprint

Package blueprint is what a template costs to run, worked out before you deploy.

Specification

/v1/blueprint is what a template costs to run, worked out before you deploy. Each deployable blueprint is a compose stack; this capability turns one into the two things a deploying org and the console need — its SBOM, the bill of container images the stack runs, and a compute-cost estimate, a per-hour rate derived from the services' summed CPU and memory footprint through a documented rate card. It is implemented in hanzoai/cloud at apps/blueprint.

Motivation

A template economy needs a price that can be explained rather than merely asserted. The rate this capability computes is what the platform shows as the monthly cost per template AND the basis the deploy path meters the deploying org on — which makes it the number the author royalty is taken from, so it has to come from a real rate card, not a fabricated figure (apps/blueprint/blueprint.go:15-32).

Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.

§1 Reference content, no store

The blueprints are embedded in the binary (embed.FS) and validated once at mount — a malformed fixture fails the mount closed, because a broken blueprint must never reach a deploy sizing or a price card (apps/blueprint/blueprint.go, build). There is no per-tenant state and no database; the capability owns no store.

§2 Addresses

Three operations under /v1/blueprint. The list and health are typed. GET /v1/blueprint/sbom is declared with prose beside the route instead: one address answers two shapes at 200 — ?template=<id> returns a bare estimate, no parameter returns the batch — and a typed operation declares one Out, so either shape would publish the other as a lie (apps/blueprint/blueprint.go:120-125). Health is deliberately not JWT-gated, because liveness must be probe-able; it also discloses the active rate card.

§3 The rate card is disclosed, not implied

An estimate carries the basis its rates came from, and the live card — after the operator's env overlay, applied once at mount — is itself readable, so a client that must explain a published price can (apps/blueprint/estimate.go). This is the distinction from the sbom capability: that one stores a dependency SBOM keyed by image digest — the packages INSIDE one image — while this one derives the bill of IMAGES a stack runs and prices the footprint. Different granularity, kept orthogonal.

§4 Tenancy, money, events, telemetry, stage, upstream

There is no tenant in the data: every caller reads the same embedded blueprints and the same card. The capability is free (plugin/blueprint/main.go, cloud.Free); the metering it feeds happens on the deploy path, against the rate this capability computed. It publishes nothing to the bus. Beyond the request span it emits structured log lines only. Stage ga: it is the platform plane's pricing basis, part of the self-service core — the manifest row carries no stage field yet, so the declaration here is what the row inherits when stage lands in manifest.App. It derives from no OSS upstream; the blueprints it embeds describe OSS stacks, which is data about them, not a fork of them.

Rationale

The alternative is to price templates by hand, one number per template in a catalog. That number cannot be explained, goes stale the day a stack adds a service, and silently diverges from what the deploy path meters. Deriving the price from the stack's own compose file through one disclosed card keeps the shown price and the metered price the same computation.

Security Considerations

The capability holds no secrets and no tenant data, so the exposure is economic: a wrong implementation misprices compute. Understated, every deploy of a template bills less than it costs and the author royalty is computed from the wrong base; a tampered rate overlay does the same deliberately. The controls are that the card is env-set by the operator, applied once at mount, and disclosed on every estimate — a wrong price is at least a visible one, and the fail-closed mount means a blueprint that cannot be parsed and priced is never shown at all.

Four surfaces

Quickstart

export HANZO_API_KEY=sk-...   # console.hanzo.ai → API keys

Then the first call — a read that needs nothing but the key. GET /v1/blueprint, operation get_blueprint:

hanzo blueprint get

import { Configuration, BlueprintApi } from 'hanzoai';

const api = new BlueprintApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getBlueprint();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import BlueprintApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = BlueprintApi(client).get_blueprint()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.BlueprintAPI.GetBlueprint(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, blueprint_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = blueprint_api::get_blueprint(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.BlueprintApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new BlueprintApi(client).getBlueprint();

curl https://api.hanzo.ai/v1/blueprint \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "blueprint",
         "arguments": {
           "op": "get_blueprint",
           "input": {}
         }
       }
     }'

Answers 200 with object — ok.

Endpoints

All Hanzo APIs · Interactive reference