Component API

A component is a reusable typed unit of code — Python or C++ — declared by a component.yml manifest plus a src/ directory. This page is the single overview of the whole component surface: the manifest fields, the type system, and the Python and C++ runtime APIs. It stays at the overview level on purpose — the exhaustive per-field and per-module reference is delivered through the CLI and the in-shell agent (ppl docs get …, ppl docs tree), so the depth lives next to where you actually build.

The manifest

Every component carries a component.yml at its root declaring identity, build environment, typed I/O, config parameters, file and model dependencies, and optional HTTP endpoints. The manifest is its own reference — see Component contract for every field, with examples for config_schema, file_schema, generated_file_schema, cache, and http.

Type system

Every type: slot — I/O, config, and file bindings — uses the same type-expression grammar.

Type expression syntax — atomics, lists [T], generics T<U>, unions T | U, tuples (A, B), and records {f: T}.
Types — the type-system overview and the value-literal grammar that ppl backend change-parameter expects.
Named types — the catalog of Image, AudioFrame, Tensor, and the geometry primitives.
File type catalog — the file_type values a file_schema slot accepts.

Language APIs

The runtime API splits by language — one page each, both built on the manifest and type system above:

Python component API — the process() entrypoint, config and mutable sync, stateful and streaming patterns, virtual I/O, and the media wrappers. The fast-iteration language.
C++ component API — the component class, I/O shapes, runtime helpers, media wrappers, and domain clients. The performance language.

Agent brief

Agent metadata — the AGENT.yml / AGENT.json schema downstream agents read to pick a component out of the catalog.

Build and release

The manifest and the language APIs stop at the source; the lifecycle around them lives in the concept and flow pages.

Build systems — how build_system selects the image.
Install modes — build-time versus node-time install.
Release semantics — what publish packages, tags, and uploads.

Full reference in the CLI

The deep detail for every section above is one command away:

ppl docs get component-api/component-contract      # every manifest field, with examples
ppl docs get type-api/type-syntax        # the full type grammar
ppl docs get component-api/python/component    # Python entrypoint; swap the last segment per module
ppl docs get component-api/cpp/component        # C++ entrypoint; swap the last segment per module
ppl docs tree | grep '^component-api/'         # list every reference page