Model structure

Upload a model's layers and weights, read them back, replay a prediction through them and see what every layer computes.

The architecture of a model: its layers, weights and biases as a kaimei.structure.v1 document, the scene the dashboard draws, a replay of one prediction through the graph, and what every layer computed for an input. The Python client builds the spec from a fitted estimator; these endpoints are what it calls, and what you call to write a converter of your own.

Executable families (networks of supported layers, trees, forests of at most 30 trees) are run by the API for explanations, predictions and analyses. Anything else is drawable but needs a remote inference URL to be queried.

#The structure spec

A spec is a JSON object with format: "kaimei.structure.v1", a family and the layers or nodes. Tensors are nested lists, or references: {"$tensor": "key"} for a binary tensor uploaded separately, {"$b64": …} for an inline float32 buffer, or {"$shape": [...], "stats": {...}} for a tensor described without its values (drawable, not executable).

family	Content	Executable
`network`	`layers`: an ordered list. Each layer has an `id`, a `type`, its tensors and optional `inputs` naming the layers it reads (defaults to the previous one). Dense weights are `(out, in)`: `y = W x + b`. A dotted `path` groups layers into blocks.	Yes, unless `approximate`
`tree`	`nodes`: `{id, feature, threshold, left, right}` for splits, `{id, leaf: true, output}` for leaves (a class distribution or a value); `root` names the first node. Up to 8,000 nodes.	Yes
`ensemble`	`trees`: a list of tree specs, averaged. Up to 30 trees.	Yes
`ensemble_summary`	`importances` per feature, for forests too large to inline.	No

Two shorthands are accepted and normalised to a network: format: "linear" (weight, bias, feature_names, optional activation) and format: "mlp" (a list of dense layers).

Layer type	Fields
`input`	`names` (feature names) or `shape` `[h, w, c]` for an image input
`dense / linear`	`units`, `weight` `(out, in)`, `bias`, optional `activation`
`conv2d`	`weight` `(out, in/groups, kh, kw)`, `bias`, `stride`, `padding` (`same`, `valid` or explicit), `dilation`, `groups`, optional `activation`
`maxpool / avgpool`	`size`, `stride`, `padding`, `ceil_mode`, `count_include_pad`
`adaptive_avgpool / adaptive_maxpool / global_avgpool / global_maxpool`	`output_size` for adaptive pools
`batchnorm`	`gamma`, `beta`, `mean`, `var`, `eps`
`normalize / rescaling`	per-channel `scale`, `offset`, or `mean` and `std`
`standardize`	`center`, `scale` per feature (a folded StandardScaler)
`layernorm`	`gamma`, `beta`, `eps`
`embedding`	`weight` `(vocab, dim)`
`activation`	`activation`: relu, relu6, leaky_relu, elu, gelu, silu, hardswish, hardsigmoid, sigmoid, tanh, softmax; `alpha` for leaky_relu and elu
`add / concat / multiply`	`inputs`: the layers to combine (residual add, channel concat, broadcasting multiply for squeeze-excitation)
`flatten`	optional `order: "chw"` for PyTorch heads
`pad2d`	`padding` per side
`dropout`	no-op at inference; kept so the drawing matches the code

Top-level fields: feature_names, task, labels or outputs, framework, name, summary, architecture, and approximate: true when a layer was passed through unmodelled. kaimei.extract_structure(estimator) in the Python client produces this document from scikit-learn, Keras and PyTorch objects.

A small network spec

{
  "format": "kaimei.structure.v1",
  "family": "network",
  "framework": "sklearn",
  "task": "binary_classification",
  "feature_names": [
    "tenure_months", "monthly_spend", "support_tickets"
  ],
  "labels": ["stay", "churn"],
  "layers": [
    {
      "id": "input",
      "type": "input",
      "names": [
        "tenure_months", "monthly_spend", "support_tickets"
      ]
    },
    {
      "id": "standardize",
      "type": "standardize",
      "center": [24.0, 62.0, 1.2],
      "scale": [18.0, 30.0, 1.6]
    },
    {
      "id": "hidden",
      "type": "dense",
      "units": 4,
      "activation": "relu",
      "weight": [
        [0.8, -0.3, 0.5],
        [-0.6, 0.9, 0.2],
        [0.1, 0.4, -0.7],
        [0.3, -0.2, 0.9]
      ],
      "bias": [0.1, -0.2, 0.05, 0.0]
    },
    {
      "id": "output",
      "type": "dense",
      "units": 1,
      "activation": "sigmoid",
      "weight": [[-1.2, 0.9, 0.7, 1.1]],
      "bias": [-0.3]
    }
  ]
}

A CNN spec with binary tensors

{
  "format": "kaimei.structure.v1",
  "family": "network",
  "framework": "pytorch",
  "task": "multiclass_classification",
  "layers": [
    {
      "id": "input",
      "type": "input",
      "shape": [224, 224, 3]
    },
    {
      "id": "normalize",
      "type": "normalize",
      "mean": [0.485, 0.456, 0.406],
      "std": [0.229, 0.224, 0.225]
    },
    {
      "id": "features.0.conv",
      "path": "features.0",
      "type": "conv2d",
      "stride": 2,
      "padding": "same",
      "activation": "relu6",
      "weight": {"$tensor": "features.0.conv.weight"},
      "bias": {"$tensor": "features.0.conv.bias"}
    },
    {
      "id": "features.1.dw",
      "path": "features.1",
      "type": "conv2d",
      "groups": 32,
      "padding": "same",
      "weight": {"$tensor": "features.1.dw.weight"}
    },
    …,
    {"id": "pool", "type": "global_avgpool"},
    {
      "id": "classifier",
      "type": "dense",
      "units": 1000,
      "activation": "softmax",
      "weight": {"$tensor": "classifier.weight"},
      "bias": {"$tensor": "classifier.bias"}
    }
  ]
}

#Retrieve the structure document

GET/v1/models/{model}/structureAPI key or session

The architecture document the dashboard renders: stats and the rendering scale (tier, whether the browser can replay the forward pass), layers grouped from the spec, the blocks tree implied by node paths, a colour legend, the output head, the 3-D scene (nodes with position, kind, formula, inputs and args; edges; camera) and the parameters with statistics, previews and, when small enough, values.

Models with an uploaded structure return it; built-in models return the reference architecture. Any other model gets a schematic: its inputs and output only, with architecture, fidelity and source set to schematic, schematic and derived, and a summary inviting a structure upload.

Path parameters

modelstringrequired

Model id or slug.

Query parameters

include_valuesbooleanoptionaldefault true

Inline parameter values when they are small enough.

max_inlineintegeroptionaldefault 4096

Values per tensor to inline, 0 to 200,000.

treeintegeroptionaldefault 0

Which member of a forest the scene draws.

rootstringoptional

Only this block of the model (a node path).

depthintegeroptional

Block levels below root to include, 0 to 64.

detailstringoptionaldefault "full"

full or summary; summary omits tensor previews.

Returns

A model.structure document.

doc = client.models.structure("churn-net-docs", detail="summary")
print(doc.architecture, doc.fidelity, doc.runnable, doc.scale["tier"])
for layer in doc.layers:
    print(layer["label"], layer["units"], layer["parameters"], layer["kinds"])

block = client.models.structure("encoder", root="encoder.layers.17", depth=2)

curl https://api.kaimei.ai/v1/models/churn-net-docs/structure?detail=summary \
  -H "Authorization: Bearer $KAIMEI_API_KEY"

200 OKResponse

{
  "object": "model.structure",
  "version": 2,
  "model_id": "mdl_ec2f5d3a8098280a8964",
  "name": "Churn net (docs)",
  "framework": "sklearn",
  "task": "binary_classification",
  "architecture": "network",
  "fidelity": "exact",
  "source": "upload",
  "summary": "Uploaded architecture. Every dense weight and bias below is the tensor used to compute the prediction.",
  "runnable": true,
  "focus_node": "output",
  "stats": {
    "nodes": 11,
    "scene_nodes": 13,
    "edges": 12,
    "parameters": 27,
    "tensors": 10,
    "layers": 4,
    "depth": 6,
    "blocks": 0,
    "trees": 0
  },
  "scale": {
    "tier": "small",
    "parameters": 27,
    "nodes": 11,
    "tensors": 10,
    "blocks": 0,
    "browser_replay": true,
    "weights_available": true,
    "previews": false,
    "collapse": false,
    "truncated": false,
    "root": "",
    "depth": null
  },
  "layers": [
    {
      "id": "inputs",
      "label": "Inputs",
      "node_ids": [
        "tenure_months", "monthly_spend", "support_tickets"
      ],
      "block": "",
      "units": 1,
      "parameters": 0,
      "position": 0,
      "kinds": ["input"],
      "repeat": null
    },
    {
      "id": "hidden",
      "label": "hidden",
      "node_ids": ["hidden", "hidden__relu"],
      "block": "",
      "units": 4,
      "parameters": 16,
      "position": 6,
      "kinds": ["activation", "linear"],
      "repeat": null
    },
    …
  ],
  "blocks": [],
  "legend": [
    {"kind": "input", "label": "Input", "color": "#3ec8ff"},
    {
      "kind": "linear",
      "label": "Linear layer",
      "color": "#8aa4ff"
    },
    {
      "kind": "activation",
      "label": "Activation",
      "color": "#ff6bb5"
    },
    …
  ],
  "head": {
    "kind": "binary_classification",
    "labels": ["stay", "churn"],
    "positive_label": "churn",
    "positive_index": 1,
    "threshold": 0.5,
    "vector_node": "probabilities",
    "explanation_node": "output"
  },
  "scene": {
    "nodes": [
      {
        "id": "hidden",
        "kind": "linear",
        "op": "dense",
        "mesh": "slab",
        "label": "hidden",
        "formula": "W x + b",
        "stage": 2.0,
        "position": [6.1, 0.0, 0.0],
        "units": 4,
        "parameter_ids": ["hidden.weight", "hidden.bias"],
        "executable": true,
        "activation": "relu",
        "inputs": [
          "standardize__tenure_months",
          "standardize__monthly_spend",
          "standardize__support_tickets"
        ],
        "args": {}
      },
      …
    ],
    "edges": [
      {
        "id": "tenure_months>standardize__tenure_months",
        "source": "tenure_months",
        "target": "standardize__tenure_months",
        "kind": "data"
      },
      …
    ],
    "camera": {
      "position": [9.02, 3.42, 20.28],
      "target": [7.78, 0.0, 0.0]
    }
  },
  "parameters": [
    {
      "id": "hidden.weight",
      "node_id": "hidden",
      "name": "weight",
      "role": "weight",
      "label": "hidden weight",
      "learned": true,
      "shape": [4, 3],
      "numel": 12,
      "stats": {
        "min": -0.7,
        "max": 0.9,
        "mean": 0.191667,
        "std": 0.528297,
        "l2": 1.946792,
        "abs_mean": 0.491667,
        "sparsity": 0.0,
        "numel": 12
      },
      "values_included": true,
      "available": true,
      "values": [0.8, -0.3, 0.5, …]
    },
    …
  ]
}

#Upload a structure

PUT/v1/models/{model}/structureAPI key or session

Store a kaimei.structure.v1 spec on a registered model, replacing any previous one. The spec is compiled and validated; an unusable spec returns 400 with the code and param that failed (invalid_structure, unsupported_layers, tensor_missing).

Tensors referenced as {"$tensor": key} must already be uploaded with PUT …/structure/tensors/{key}. The Python client's upload_structure does both from a fitted estimator.

Path parameters

modelstringrequired

Model id or slug.

Body parameters

(body)objectrequired

The spec itself. See the structure spec.

Returns

The compiled structure document, as GET returns it.

spec = {
    "format": "kaimei.structure.v1", "family": "network", "task": "binary_classification",
    "feature_names": ["tenure_months", "monthly_spend", "support_tickets"], "labels": ["stay", "churn"],
    "layers": [
        {"id": "input", "type": "input", "names": ["tenure_months", "monthly_spend", "support_tickets"]},
        {"id": "standardize", "type": "standardize", "center": [24.0, 62.0, 1.2], "scale": [18.0, 30.0, 1.6]},
        {"id": "hidden", "type": "dense", "units": 4, "activation": "relu", "weight": W1.tolist(), "bias": b1.tolist()},
        {"id": "output", "type": "dense", "units": 1, "activation": "sigmoid", "weight": W2.tolist(), "bias": b2.tolist()},
    ],
}
client.models.upload_structure("churn-net-docs", spec)

# or straight from the estimator (extracts, uploads large tensors as binary, then PUTs the spec)
client.models.upload_structure("churn-net-docs", clf)

curl -X PUT https://api.kaimei.ai/v1/models/churn-net-docs/structure \
  -H "Authorization: Bearer $KAIMEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "kaimei.structure.v1", "family": "network", "task": "binary_classification",
    "feature_names": ["tenure_months", "monthly_spend", "support_tickets"], "labels": ["stay", "churn"],
    "layers": [
      {"id": "input", "type": "input", "names": ["tenure_months", "monthly_spend", "support_tickets"]},
      {"id": "hidden", "type": "dense", "units": 4, "activation": "relu", "weight": {"$tensor": "hidden.weight"}, "bias": [0.1, -0.2, 0.05, 0.0]},
      {"id": "output", "type": "dense", "units": 1, "activation": "sigmoid", "weight": [[-1.2, 0.9, 0.7, 1.1]], "bias": [-0.3]}
    ]
  }'

200 OKResponse

{
  "object": "model.structure",
  "model_id": "mdl_ec2f5d3a8098280a8964",
  "architecture": "network",
  "fidelity": "exact",
  "runnable": true,
  "stats": {
    "nodes": 11,
    "parameters": 27,
    "tensors": 10,
    "layers": 4
  },
  …: …
}

#Remove a structure

DELETE/v1/models/{model}/structureAPI key or session

Delete the uploaded spec and its binary tensors. The model stays registered; it is no longer executable unless it has a remote or built-in inference.

Path parameters

modelstringrequired

Model id or slug.

Returns

A deletion receipt with object: "model.structure".

client.models.delete_structure("churn-net-docs")

curl -X DELETE https://api.kaimei.ai/v1/models/churn-net-docs/structure \
  -H "Authorization: Bearer $KAIMEI_API_KEY"

200 OKResponse

{
  "id": "mdl_ec2f5d3a8098280a8964",
  "object": "model.structure",
  "deleted": true
}

#Trace one prediction

POST/v1/models/{model}/structure/traceAPI key or session

Replay one input through the architecture and narrate it: the output, the drivers of the final score (which incoming node moved it, and by how much), a narrative sentence per node, and a frame per node with its activation vector, a summary (size, max, mean, L2, active units, argmax), an intensity in [0, 1] for colouring and, for linear layers, the contributions of each input node and the bias. For a forest, tree picks the tree to walk; a trace still averages every tree for the output.

For large models pass detail: "summary" and nodes: frames then carry statistics and a sampled vector for the chosen nodes only; the output head is always included.

Path parameters

modelstringrequired

Model id or slug.

Body parameters

inputobjectrequired

A feature row.

detailstringoptionaldefault "full"

full or summary.

nodesarray of stringsoptional

Node ids to return frames for (up to 2,000). Default: every node.

treeintegeroptionaldefault 0

Member of a forest to walk.

Returns

A model.structure.trace.

trace = client.models.trace_structure("churn-net-docs",
                                      input={"tenure_months": 3, "monthly_spend": 91.5, "support_tickets": 4})
print(trace.output)             # {'label': 'churn', 'probability': 0.9163, ...}
for line in trace.narrative:
    print(line["text"])
# tenure months enters as 3.0.
# tenure months: (3 − 24) / 18 = -1.167.
# hidden = -0.2533.  relu: relu(-0.2533) = 0. ...

curl -X POST https://api.kaimei.ai/v1/models/churn-net-docs/structure/trace \
  -H "Authorization: Bearer $KAIMEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"tenure_months": 3, "monthly_spend": 91.5, "support_tickets": 4}}'

200 OKResponse

{
  "object": "model.structure.trace",
  "model_id": "mdl_ec2f5d3a8098280a8964",
  "runnable": true,
  "detail": "full",
  "output": {
    "label": "churn",
    "probability": 0.91626639,
    "probabilities": {"stay": 0.08373361, "churn": 0.91626639},
    "value": 0.91626639,
    "threshold": 0.5
  },
  "drivers": [
    {
      "from": "hidden__relu",
      "label": "relu",
      "input": [0.0, 1.735, 0.0, 1.0283],
      "delta": 2.6927,
      "share": 0.8998
    },
    {
      "from": "bias",
      "label": "Bias",
      "input": -0.3,
      "delta": -0.3,
      "share": 0.1002
    }
  ],
  "narrative": [
    {
      "node_id": "tenure_months",
      "label": "tenure months",
      "text": "tenure months enters as 3.0."
    },
    {
      "node_id": "standardize__tenure_months",
      "label": "tenure months",
      "text": "tenure months: (3 − 24) / 18 = -1.167."
    },
    …
  ],
  "frames": [
    {
      "index": 6,
      "node_id": "hidden",
      "op": "dense",
      "label": "hidden",
      "intensity": 0.5611,
      "value": [-0.2533, 1.735, -0.8983, 1.0283],
      "summary": {
        "size": 4,
        "max_abs": 1.735,
        "mean_abs": 0.97875,
        "l2": 2.2224,
        "active": 4,
        "argmax": 1
      },
      "text": "hidden = -0.2533.",
      "contributions": [
        {
          "from": "standardize__tenure_months",
          "input": -1.1667,
          "delta": [-0.9333, 0.7, -0.1167, -0.35],
          "label": "tenure months"
        },
        …,
        {
          "from": "bias",
          "input": [0.1, -0.2, 0.05, 0.0],
          "delta": [0.1, -0.2, 0.05, 0.0],
          "label": "Bias"
        }
      ]
    },
    …
  ],
  "path": [
    "tenure_months", "monthly_spend", "support_tickets",
    "standardize__tenure_months", …, "output__sigmoid"
  ]
}

#What every layer computes

POST/v1/models/{model}/structure/activationsAPI key or session

Run one input through an uploaded network and return what each layer computed, the data behind the dashboard's Sight view. Every stage reports its intensity, active_fraction and top_units (strongest channels or units). The detailed stages (nodes, or by default up to 24 feature maps plus the output) add the Σ|a| energy of every channel, the maps of the channels strongest ones, a saliency map (mean |a| over channels) and, for vectors up to 4,096 units, every value.

Maps are area-averaged until their long side is at most max_side cells and travel as base64 uint8 with their value range; kaimei.activations.decode restores them. cam adds class attention (Grad-CAM) toward target at the named layers when it fits a time budget estimated from the forward pass; otherwise the stage says why.

Path parameters

modelstringrequired

Model id or slug.

Body parameters

inputobjectrequired

A feature row (an image for a CNN).

nodesarray of stringsoptional

Stages to detail, up to 64. Default: the API picks the feature maps worth seeing plus the output.

channelsintegeroptionaldefault 8

Strongest channel maps per detailed spatial stage, 1 to 32.

max_sideintegeroptionaldefault 56

Longest side of a shipped map, 4 to 112 cells.

unitsintegeroptionaldefault 16

Strongest units or channels listed for every stage, 1 to 256.

camarray of stringsoptional

Up to 4 layer ids to compute class attention for.

targetinteger | stringoptional

Class index or label the attention explains. Default: the predicted class.

Returns

A model.structure.activations record: output, target, stages, the ids of the detailed stages and forward_ms.

A spatial stage of a CNN adds shape [h, w, c], energy per channel, maps (the strongest channels, each {channel, range, data}), a saliency map and, when requested, cam with the attention map or a skipped reason. Forests have no activations.

result = client.models.activations("cats-dogs-photos", input={"photo": photo}, channels=8)
print(result.output["label"], result.forward_ms)
for stage in result.stages:
    if stage["detailed"]:
        print(stage["node_id"], stage["op"], stage["intensity"], stage["top_units"][:3])

focused = client.models.activations("cats-dogs-photos", input={"photo": photo},
                                    nodes=["features.17"], cam=["features.17"], target="dog")

curl -X POST https://api.kaimei.ai/v1/models/churn-net-docs/structure/activations \
  -H "Authorization: Bearer $KAIMEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"tenure_months": 3, "monthly_spend": 91.5, "support_tickets": 4}, "units": 4}'

200 OKResponse

{
  "object": "model.structure.activations",
  "model_id": "mdl_ec2f5d3a8098280a8964",
  "runnable": true,
  "output": {
    "label": "churn",
    "probability": 0.91626639,
    "probabilities": {"stay": 0.08373361, "churn": 0.91626639},
    "value": 0.91626639,
    "threshold": 0.5
  },
  "target": {"index": 1, "label": "churn"},
  "input": null,
  "stages": [
    {
      "index": 0,
      "node_id": "tenure_months",
      "label": "tenure months",
      "op": "input",
      "kind": "input",
      "units": 1,
      "intensity": 0.6351,
      "summary": {
        "size": 1,
        "max_abs": 3.0,
        "mean_abs": 3.0,
        "l2": 3.0,
        "active": 1,
        "argmax": 0
      },
      "active_fraction": 1.0,
      "detailed": false,
      "top_units": [
        {"index": 0, "value": 3.0}
      ]
    },
    …,
    {
      "index": 6,
      "node_id": "hidden",
      "label": "hidden",
      "op": "dense",
      "kind": "linear",
      "units": 4,
      "intensity": 0.5611,
      "summary": {
        "size": 4,
        "max_abs": 1.735,
        "mean_abs": 0.97875,
        "l2": 2.2224,
        "active": 4,
        "argmax": 1
      },
      "active_fraction": 1.0,
      "detailed": true,
      "top_units": [
        {"index": 1, "value": 1.735},
        {"index": 3, "value": 1.028333},
        {"index": 2, "value": -0.898333},
        {"index": 0, "value": -0.253333}
      ],
      "values": {
        "shape": [4],
        "range": [-0.898333, 1.735],
        "encoding": "u8",
        "data": "PwD/Qw=="
      }
    },
    …
  ],
  "detailed": [
    "standardize__tenure_months", "standardize__monthly_spend",
    "standardize__support_tickets", "hidden", …
  ],
  "channels": 8,
  "max_side": 56,
  "forward_ms": 0.47
}

#List binary tensors

GET/v1/models/{model}/structure/tensorsAPI key or session

The binary tensors uploaded for this model with their shapes, sizes, statistics and whether the current spec referenced them.

Path parameters

modelstringrequired

Model id or slug.

Returns

A list with total_bytes.

tensors = client.models.tensors("churn-net-docs")
print(tensors.total_bytes)
for item in tensors.data:
    print(item["key"], item["shape"], item["dtype"], item["bytes"], item["referenced"])

curl https://api.kaimei.ai/v1/models/churn-net-docs/structure/tensors \
  -H "Authorization: Bearer $KAIMEI_API_KEY"

200 OKResponse

{
  "object": "list",
  "data": [
    {
      "object": "model.structure.tensor",
      "model_id": "mdl_ec2f5d3a8098280a8964",
      "key": "hidden.weight",
      "shape": [4, 3],
      "dtype": "f32",
      "numel": 12,
      "bytes": 50,
      "compression": "zlib",
      "stats": {
        "min": -0.7,
        "max": 0.9,
        "mean": 0.191667,
        "std": 0.528297,
        "l2": 1.946792,
        "abs_mean": 0.491667,
        "sparsity": 0.0,
        "numel": 12,
        "histogram": {
          "counts": [2, 0, …],
          "edges": [-0.7, -0.566667, …]
        }
      },
      "referenced": true
    }
  ],
  "total_bytes": 50
}

#Upload a binary tensor

PUT/v1/models/{model}/structure/tensors/{key}API key or session

Upload one weight tensor as raw little-endian bytes, zlib-compressed by default, and reference it from the spec as {"$tensor": "key"}. Keys are dotted module paths with an optional parameter name (encoder.layers.0.q.weight): letters, digits, . _ - : /, at most 200 characters.

Up to 250 million values per tensor and 512 MB compressed per upload; 20,000 uploads per hour per organization. Uploading the same key again replaces the tensor.

Path parameters

modelstringrequired

Model id or slug.

keystringrequired

Tensor key.

Query parameters

shapestringrequired

Comma-separated dimensions, for example 768,3072.

dtypestringoptionaldefault "f32"

f16, f32 or f64, little-endian.

compressionstringoptionaldefault "zlib"

zlib or none.

Body parameters

(body)bytesrequired

The buffer, with Content-Type: application/octet-stream.

Returns

A model.structure.tensor with statistics.

import numpy as np

W1 = np.array([[0.8, -0.3, 0.5], [-0.6, 0.9, 0.2], [0.1, 0.4, -0.7], [0.3, -0.2, 0.9]], dtype=np.float32)
client.models.upload_tensors("churn-net-docs", {"hidden.weight": W1})
# then PUT a spec that says "weight": {"$tensor": "hidden.weight"}

python -c "import numpy as np, zlib, sys; sys.stdout.buffer.write(zlib.compress(np.load('w1.npy').astype('<f4').tobytes()))" > w1.z
curl -X PUT "https://api.kaimei.ai/v1/models/churn-net-docs/structure/tensors/hidden.weight?shape=4,3&dtype=f32&compression=zlib" \
  -H "Authorization: Bearer $KAIMEI_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @w1.z

200 OKResponse

{
  "object": "model.structure.tensor",
  "model_id": "mdl_ec2f5d3a8098280a8964",
  "key": "hidden.weight",
  "shape": [4, 3],
  "dtype": "f32",
  "numel": 12,
  "bytes": 50,
  "compression": "zlib",
  "stats": {
    "min": -0.7,
    "max": 0.9,
    "mean": 0.191667,
    "std": 0.528297,
    "l2": 1.946792,
    "abs_mean": 0.491667,
    "sparsity": 0.0,
    "numel": 12
  },
  "referenced": null
}

#Delete a tensor

DELETE/v1/models/{model}/structure/tensors/{key}API key or session

Remove one uploaded tensor. A spec that still references it becomes unusable until the tensor is re-uploaded.

Path parameters

modelstringrequired

Model id or slug.

keystringrequired

Tensor key.

Returns

A deletion receipt whose id is {model_id}:{key}.

client.models.delete_tensor("churn-net-docs", "hidden.weight")

curl -X DELETE https://api.kaimei.ai/v1/models/churn-net-docs/structure/tensors/hidden.weight \
  -H "Authorization: Bearer $KAIMEI_API_KEY"

200 OKResponse

{
  "id": "mdl_ec2f5d3a8098280a8964:hidden.weight",
  "object": "model.structure.tensor",
  "deleted": true
}

#Read a parameter

GET/v1/models/{model}/structure/parameters/{parameter_id}API key or session

A window of one weight or bias tensor. Parameter ids come from the structure document (hidden.weight, standardize__tenure_months.center). JSON windows are limited to 20,000 values; format=f32 streams raw little-endian float32 bytes for windows up to 4 million values, with the geometry in X-Kaimei-* headers.

Path parameters

modelstringrequired

Model id or slug.

parameter_idstringrequired

Parameter id from the structure document.

Query parameters

offsetintegeroptionaldefault 0

First value, in flattened row-major order.

limitintegeroptionaldefault 4096

Values to return. At most 20,000 for JSON, 4,000,000 for f32.

formatstringoptionaldefault "json"

json or f32.

statsbooleanoptionaldefault false

Include summary statistics (JSON only).

previewintegeroptionaldefault 0

Side of a downsampled 2-D preview to include, 0 to 256 (JSON only).

treeintegeroptionaldefault 0

Member of a forest.

Returns

A model.structure.parameter, or application/octet-stream with headers X-Kaimei-Offset, X-Kaimei-Count, X-Kaimei-Total, X-Kaimei-Shape, X-Kaimei-Dtype and X-Kaimei-Available.

window = client.models.structure_parameter("churn-net-docs", "hidden.weight", limit=6, stats=True)
print(window.shape, window.total, window.values)      # [4, 3] 12 [0.8, -0.3, 0.5, -0.6, 0.9, 0.2]

# the whole tensor as float32, fetched as binary
weights = client.models.structure_parameter_values("churn-net-docs", "hidden.weight")
weights.reshape(window.shape)

curl "https://api.kaimei.ai/v1/models/churn-net-docs/structure/parameters/hidden.weight?limit=6&stats=true" \
  -H "Authorization: Bearer $KAIMEI_API_KEY"

# raw float32
curl "https://api.kaimei.ai/v1/models/churn-net-docs/structure/parameters/hidden.weight?format=f32&limit=1000000" \
  -H "Authorization: Bearer $KAIMEI_API_KEY" -D - --output hidden.weight.f32
# X-Kaimei-Offset: 0  X-Kaimei-Count: 12  X-Kaimei-Total: 12  X-Kaimei-Shape: 4,3  X-Kaimei-Dtype: f32

200 OKResponse

{
  "object": "model.structure.parameter",
  "id": "hidden.weight",
  "model_id": "mdl_ec2f5d3a8098280a8964",
  "node_id": "hidden",
  "name": "weight",
  "role": "weight",
  "label": "hidden weight",
  "shape": [4, 3],
  "offset": 0,
  "count": 6,
  "total": 12,
  "available": true,
  "values": [0.8, -0.3, 0.5, -0.6, 0.9, 0.2],
  "stats": {
    "min": -0.7,
    "max": 0.9,
    "mean": 0.191667,
    "std": 0.528297,
    "l2": 1.946792,
    "abs_mean": 0.491667,
    "sparsity": 0.0,
    "numel": 12
  }
}