53-Model Card Template v1.0 | Chapter 10 — Deployment Interfaces & Implementation Bindings (API / Function Prototypes)

Home ／ Docs-Technical WhitePaper ／ 53-Model Card Template v1.0

Chapter 10 — Deployment Interfaces & Implementation Bindings (API / Function Prototypes)

I. Purpose & Scope

• Standardize deployment-stage external interfaces (REST/gRPC/CLI) and implementation bindings (function prototypes, types & error semantics, idempotency/retry/audit), ensuring production inference is reproducible, auditable, and rollback-ready, and aligned with Data/Parameter/Error/Pipeline volumes.
• For path quantities (arrival time/phase), the text must explicitly show gamma(ell) and d ell; the data side records delta_form ∈ {general, factored}; all expressions are parenthesized; publication requires p_dim = 1.0.

II. Prerequisites & Inputs

• Data & splits: align with Dataset Card Ch. 4/6/7/10 (Schema/Splits/QC/API).
• Training & weights: align with this volume’s Ch. 6 (train_config.yaml, best.ckpt, env snapshot).
• Coverage & covariance: align with Error Budget Card (coverage k/alpha/quantile, Σ PD).
• Parameters & freshness: align with Parameter Card (freshness.policy, cov_group).
• Citations & versions: “volume + version + anchor (P/S/M/I)”, anchor coverage ≥ 90%; public v1.* only.

III. Error Model & Return Envelope

• Error classes: E_INPUT / E_DIM / E_GATE / E_SYNC / E_UQ / E_DRIFT / E_INTERNAL.
• Unified envelope:

{

"status":"OK|ERROR",

"code":0,

"error":{"type":"E_*","message":"...","details":{}},

"payload":{},

"metrics":{"latency_ms":87,"retries":0},

"anchors":["EFT.WP.Core.Equations v1.1:S20-1"],

"version":"1.0.0",

"checksum":"sha256:..."

}

IV. REST OpenAPI (excerpt)

openapi: 3.0.3

info: { title: "Model Inference API", version: "1.0.0" }

servers: [{ url: "https://api.example.com/v1" }]

components:

securitySchemes: { bearerAuth: { type: http, scheme: bearer } }

schemas:

InferRequest:

type: object

required: [idempotency_key, inputs]

properties:

idempotency_key: { type: string }

inputs: { type: array, items: { type: object } }

options:

type: object

properties:

coverage: { type: string, enum: ["k","alpha","quantile"] }

return_uq: { type: boolean, default: true }

InferResponse:

type: object

properties:

status: { type: string }

payload: { type: object }

uq: { type: object }

anchors: { type: array, items: { type: string } }

version: { type: string }

checksum: { type: string }

paths:

/models/{id}/infer:

post:

security: [{ bearerAuth: [] }]

summary: "Idempotent inference"

parameters: [{ in: path, name: id, required: true, schema: { type: string } }]

requestBody:

required: true

content: { application/json: { schema: { $ref: "#/components/schemas/InferRequest" } } }

responses:

"200": { description: "OK", content: { application/json: { schema: { $ref: "#/components/schemas/InferResponse" } } } }

"409": { description: "Idempotency conflict" }

/models/{id}/validate:

post:

summary: "Validate gates G1–G8 & report stops"

responses: { "200": { description: "Validation report" } }

V. gRPC (proto excerpt)

syntax = "proto3";

package model.v1;

message Ctx { string idempotency_key = 1; string coverage = 2; bool return_uq = 3; }

message InferRequest { Ctx ctx = 1; bytes inputs = 2; } // inputs: Avro/JSON/Parquet

message InferResponse {

string status = 1;

bytes payload = 2; // outputs

bytes uq = 3; // optional UQ bundle

repeated string anchors = 4;

string version = 5;

string checksum = 6;

}

service Inference {

rpc Infer (InferRequest) returns (InferResponse);

rpc Validate (InferRequest) returns (InferResponse);

}

VI. CLI (excerpt)

# Idempotent inference

mdl infer mdl-core \

--idempotency_key run42+p010+win001 \

--inputs @samples.json \

--coverage k --return_uq true \

--out outputs/predictions.json

# Gate validation

mdl validate mdl-core --out reports/validate_report.json

VII. Implementation Bindings (I60–I69)

1. I60-infer(ctx, x) -> y | err
   • in: ctx{idempotency_key,coverage,return_uq}, x aligned with Dataset Card Ch. 4;
   • out: y (with units/dimensions) and optional uq;
   • errors: E_INPUT/E_DIM/E_GATE/E_SYNC/E_UQ/E_DRIFT/E_INTERNAL.
2. I61-validate_gate(card, gates[]) -> report.json: returns G1–G8 and stops_triggered.
3. I62-export_artifacts(fmt) -> {manifest, checksums}: fmt ∈ {zip,tgz}.
4. I63-path_align(path,inplace=false) -> path': verify gamma/measure/delta_form and step.
5. I64-derive_arrival(path,c_ref) -> T_arr: T_arr = ( ∫ ( n_eff / c_ref ) d ell ) (or factored-constant form).
6. I65-derive_phase(path,lambda_ref) -> Phi: Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell ).
7. I66-uq_delta(J, Σ) -> {u, u_c, U}; I67-cov_merge(blocks[]) -> Σ (PD check & jitter).
8. I68-rollback_fsm(event) -> state: trigger fallback/degrade.
9. I69-emit_audit(event) -> OK: append to audit.jsonl.

VIII. Path-Specific Rules

• Required: path.gamma_ell[], path.d_ell[], medium.n_eff_profile[], ref.c_ref, and (for phase) ref.lambda_ref; responses must echo delta_form.
• Unified forms:
  T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) or T_arr = ( ∫ ( n_eff / c_ref ) d ell );
  Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell ).
• Dimensional closure: call I70-dim_check before returning to ensure p_dim = 1.0; annotate units/dimensions in payload.meta.

IX. Idempotency, Retry & Audit

• Idempotency key: idempotency_key = f(model_id, inputs_hash, window, partition, …); repeated calls with the same key must not change outputs.
• Retry policy: retry_policy = {max_retries, backoff ∈ {const, exp, jitter}, deadline}; retries must not change idempotency_key or the input snapshot.
• Audit: log all writes/exports to audit.jsonl (time, actor, input hashes, bytes, signature, checksum).

X. Gate Mapping

• G1 Schema completeness (I/O vs contract); G2 Citation compliance (anchor coverage ≥ 90%);
• G3 Path conventions (blocks complete; step compliant); G4 Dimensional closure (p_dim = 1.0);
• G5 Freshness (clock_state="locked"); G6 Coverage consistency (k/alpha/quantile);
• G7 Covariance consistency (Σ PD & aligned with cov_group); G8 Uniqueness & acyclicity (record_id/checksum, lineage DAG).
• Trigger S1–S5 (dimension/freshness/path/covariance/citation) to block service or tag [Restricted].

XI. Machine-Readable Artifacts
A. inference_openapi.yaml (REST contract)
B. inference.proto (gRPC contract)
C. binding_spec.md (I/O fields, units/dimensions, coverage & error conventions)
D. rollback_fsm.yaml (rollback state machine)
E. validate_report.json (G1–G8 & stops_triggered)
F. report_manifest.yaml (artifact bundle with signatures/checksums)

XII. Anti-Patterns & Fixes

• Anti: returning T_arr = ∫ n_eff / c_ref d ell (no parentheses) → Fix: use parenthesized forms and echo units/dimensions.
• Anti: path response missing delta_form → Fix: echo in payload.meta and ensure it matches input.
• Anti: coverage mode differs from Error Budget → Fix: unify coverage.mode and declare in captions/manifests.
• Anti: no idempotency key → Fix: require idempotency_key and return 409 on conflict.

XIII. Cross-References

• Dataset Card: Ch. 10 (API/Manifest/Access).
• Error Budget Card: Ch. 8/9 (intervals & thresholds).
• Pipeline Card: Ch. 11 (Interfaces & Bindings), Ch. 12 (Outputs & Release).
• This volume: Ch. 4 (control equations), Ch. 6 (training), Ch. 7 (UQ).

XIV. Checklist

• inference_openapi.yaml / inference.proto / binding_spec.md / rollback_fsm.yaml ready and version-locked.
• Path interfaces explicit gamma/measure/delta_form; I70-dim_check passed, p_dim = 1.0.
• Coverage/covariance conventions unified; /validate passes G1–G8; citation anchor coverage ≥ 90%.
• Idempotency/retry/audit policies enabled; artifacts signed with checksums; non-compliances tagged [Restricted].