Making Cog containers self-describing

A model container is easier to use when the platform knows its inputs. app.nz cogs can provide that schema directly, but the control plane also tries to discover it during warmup so the UI can render a real prediction form instead of a raw JSON box.

This is one of the small details that turns a container runtime into a product.

Warm first, introspect second

The control plane does not introspect an idle model. It first warms the model:

choose hardware start local container or RunPod pod wait for health discover schema mark ready

That ordering matters. A Cog server may not expose a useful OpenAPI document until the app has imported Python, initialized the predictor, and registered routes.

Multiple readiness paths

Different containers expose readiness differently. app.nz tries the common paths:

• /health-check
• /healthz
• /openapi.json

The best path is an honest health-check that reports SETUP until weights are loaded and the model can serve. If a container reports ready too early, the first user prediction pays the remaining setup time.

From schema to UI

Once the OpenAPI or Cog schema is available, app.nz can infer:

• input names,
• types,
• defaults,
• required fields,
• file inputs,
• output shape.

The frontend can render controls for the model instead of asking the user to hand-write JSON. That is especially useful for image, video, and audio cogs where inputs often include dimensions, prompts, seeds, strength values, and uploaded files.

No schema is still allowed

Some images will not expose schema cleanly. The platform should still let the model run. In that case, app.nz keeps the raw prediction API available and the UI falls back to a generic JSON input.

The rule is progressive enhancement: schema makes the experience nicer, but lack of schema should not block power users.

Why introspection happens in the control plane

The model image should not need an app.nz-specific SDK to become usable. If it follows common Cog conventions, app.nz can discover enough. That lowers the cost of bringing existing images into the platform.

It also keeps schema tied to the image that is actually running. A stale hand-written form can drift from the container. Introspection reduces that drift.

The reliability edge

Schema discovery is also an early smoke test. If /openapi.json fails, if the process is not serving HTTP, or if the response is malformed, the model may still be marked ready only after the platform understands what failed.

For users, the symptom becomes actionable: "the container started but did not expose a schema" is much better than "prediction failed."