Component'ler

Özet

Bir component, platformun yetenek birimidir: tek bir iş yapan tipli, version'lanmış, container'lanmış bir kod parçası — bir görüntü oku, bir detektör çalıştır, bir ses frame'ini normalleştir, bir kuyruğa yaz. Birçok backend'de yeniden kullanılabilir ve tek bir takıma aittir.
Bir component ne tükettiğini, ne ürettiğini ve nasıl yapılandırılabileceğini bildirir — tipli input akışları, tipli output akışları, tipli parametreler, isteğe bağlı dosya yuvaları. Bu bildirim, platformun her diğer katmanının okuduğu sözleşmedir.
Component'lerin değişmez release'leri vardır. Her publish bir prerelease oluşturur; promotion, bir prerelease'i yayınlanmış bir version'a dönüştürür. Backend'ler belirli release'leri sabitler, böylece promotion herhangi bir çalışan deployment'ı değiştirmez.
Bir component davranışa sahiptir. Bir backend kompozisyona sahiptir. Bir deployment runtime'a sahiptir. Üç ilkeli ayrı tutmak, tek bir yeteneğin kodu çatallamadan birçok ürünü güçlendirmesini sağlayan şeydir.
Çoğu component durumsuz fonksiyondur: input girer, output çıkar. Durum, virtual akışlar ve özel pull politikaları, onlara ihtiyaç duyan durumlar için gelişmiş konulardır; temel şekil çoğu gerçek component'i kapsar.

Bir component gerçekte nedir

Bir component, platformun modellediği en küçük yeniden kullanılabilir yetenek birimidir. Somut olarak, ne tükettiğini, ne ürettiğini ve nasıl yapılandırılabileceğini bildiren bir manifestle, container'lanmış bir worker olarak paketlenmiş tipli bir fonksiyondur. O bildirim — component.yml — her diğer katmanın okuduğu sözleşmedir: backend'ler onu deploy'dan önce graf kablolamasını tip-kontrol etmek için kullanır, katalog onu keşif için kullanır, runtime onu worker'ın container'ının ne beklediğini belirlemek için kullanır.

Granülerlik bilinçlidir. Çıplak bir fonksiyon bağımsız çalışmak için fazla küçüktür: manifest yok, container yok, version'lama yok. Tüm bir pipeline ürünler arasında yeniden kullanmak için fazla büyüktür. Bir component, bir işin sabitlenebilen, doğrulanabilen, yeniden kullanılabilen, değiştirilebilen ve tek başına işlem yapılabilen bir birime eşlendiği düzeyde durur. Tipli sözleşme ve değişmez release modeli, o birimi yalnızca izole değil, birleştirilebilir kılan şeydir.

Varsayılan sözleşme, component'lerin graf sınırında durumsuz olmasıdır. Fonksiyon tipli input'ları tüketir ve tipli output'lar üretir; diğer her şey — model ağırlıkları, yapılandırma, isteğe bağlı durum, yan kanal olayları — component'in ihtiyaç duyduğunda bildirdiği mekanizmadır. O varsayılan, çoğu component'i küçük tutar ve zamanlayıcının onları serbestçe paralelleştirmesini sağlar. Opt-in'ler, onlara ihtiyaç duyan durumlar için vardır ve her biri runtime'ın vertex'i nasıl zamanlayabileceğini kısıtlar ki bu, component'leri basit tutmak için doğru baskıdır.

Zihinsel model

  ┌──── component release (immutable) ─────┐
  │                                        │
  │   component.yml      src/              │
  │   ┌─────────────┐    ┌─────────────┐   │
  │   │ language    │    │ Python or   │   │
  │   │ inputs[]    │    │ C++ code    │   │
  │   │ outputs[]   │    │             │   │
  │   │ config      │    │ implements  │   │
  │   │ files       │    │ the typed   │   │
  │   │ tags        │    │ function    │   │
  │   └─────────────┘    └─────────────┘   │
  │                                        │
  └────────────────────┬───────────────────┘
                       │  pinned by
                       ▼
                 backend vertex

Release değişmez yapıttır. Bir backend onu bir vertex olarak sabitler, parametrelerini ve dosyalarını bağlar ve akışlarını kablolar. Aynı release birçok backend'de bir vertex olarak oturabilir; her backend kendi bağlamalarını ve kendi graf bağlamını taşır. Promotion yeni bir yayınlanmış satır kaydeder; sabitleme, bir backend'i bundan izole eden şeydir — release_v3'ü sabitlemiş bir backend, v4 varsayılan olduktan sonra v3 çalıştırmaya devam eder.

Release'in takıldığı graf için Backend'ler ve input'larının ve output'larının karşıladığı tipli akış sözleşmesi için Tipler sayfalarına bakın.

"Tipli fonksiyon" size gerçekte ne kazandırır

"Component sözleşmesi neyi garanti eder" diye sorduğunuz ilk seferde bu çerçeveyi kullanın.

Bildirilen tipli sözleşme manifestte küçüktür — akış başına birkaç satır — ve diğer her yerde yük taşır. Backend'in tip çıkarımı, bir Image çıktısını bir [BoundingBox] input'una kablolamayı reddetmek için onu kullanır. CLI, bir parametre eksik olduğunda anlamlı hata mesajları render etmek için onu kullanır. Katalog, component'leri işledikleri modalitelere göre filtrelemek için onu kullanır. Runtime, component'in başlangıçta hangi container kaynaklarına ihtiyaç duyduğunu belirlemek için onu kullanır.

Component yazarı sözleşmeyi bir kez yazar; her diğer taraf — graf yazarları, sonraki tüketiciler, ops takımları, daha sonraki bakımcılar — onu okur. Sözleşmeyi bildirmek, kablolama ve parametre hatalarını, başarısız bir deploy'a ertelemek yerine, backend'in tip çıkarımının onları yakaladığı düzenleme zamanına taşır. Bu, manifestin isteğe bağlı yerine zorunlu olmasının pratik nedenidir.

Tipli değerlerin kendileri üç yerden birinden gelir: pipelang atomik tipleri (Double, String, Int64), onlardan inşa edilen bileşik tipler ([BoundingBox], Maybe<String>, (Image, [Double])) veya platformun tip kayıt defterinden adlandırılmış tipler (Image, Tensor, AudioFrame, BoundingBox). Adlandırılmış tipler alan adı anlamları taşır: bir Image yalnızca bir bayt tensörü değildir, görüntü işleyen her component'in üzerinde anlaştığı tipli değerdir, sonraki tüketicilerin yeniden türetmek yerine doğrudan okuduğu şekil, kanal sırası ve meta veriyle.

Image, Tensor ve geri kalanını destekleyen kayıt defteri için Adlandırılmış tipler sayfasına bakın.

Varsayılan olarak durumsuz, davranış geçmiş gerektirdiğinde durumlu

Varsayılanı kullanın; duruma yalnızca sonraki çıktı gerçekten önceki çıktılara bağlı olduğunda başvurun.

Varsayılan component, durumsuz bir fonksiyondur: runtime onu aynı vertex için birçok kez eşzamanlı olarak çağırabilir, çünkü hiçbir çağrı bir diğerine bağlı değildir. Bu, zamanlayıcının tek bir vertex'i yük altında CPU çekirdeklerine yaymasını veya sıralamayı koordine etmeden bağımsız çağrıları paralel çalıştırmasını sağlar.

Durum bildirmek o sözleşmeyi değiştirir. Component, platformdan çağrılar arasında bellek kalıcılaştırmasını ve fonksiyonu vertex başına teker teker çağırmasını ister, böylece önceki çağrının next state'i sonrakine görünür. Vertex geçmişe bağımlı hale gelir: tracker'lar, kayan pencereler, oturum haritaları, konuşma belleği, debouncing ve "yalnızca N saniyelik buffer'lanmış sesten sonra yay"ın hepsi doğru davranmak için duruma ihtiyaç duyar. Durumlu bir vertex replika başına serisaldır ki bu, duruma ihtiyaç duymayan component'lerden durumu uzak tutmak için doğru baskıdır.

Kalıcı durumun dışında kalan şey, process başına mekanizmadır: model tutamaçları, veritabanı istemcileri, derlenmiş regex'ler, başlangıçta yeniden üretilebilen önbellekler. Bunlar modül global'lerine veya kurulum hook'larına aittir, platformun kalıcı durumuna değil. Kalıcı durum, davranışsal bellek içindir — çağrılar arasında kaybı sonraki çağrının yaydığı şeyi değiştirecek değerler. Diğer her şey process-yereldir ve buna göre yaşar.

Yan etkiler virtual akışların arkasında yaşar

Bunu component'in grafın dışındaki dünyayla konuşması gerektiğinde kullanın: HTTP, WebSocket, cihazlar, SDK callback'leri, yeniden deneme anlamlarıyla dosya yazımları.

Çoğu component graf input'larından tüketir, deterministik bir fonksiyon çalıştırır ve graf output'larına yayar. Bazı component'lerin daha zor bir işi vardır: trafiği eşzamansız alan bir HTTP listener'ına, graf zamanlamasından bağımsız frame'ler üreten bir kamera thread'ine, token'ları bir callback aracılığıyla geri akıtan bir LLM SDK'sına, yeniden deneme işleme gerektiren bir dosya yazıcısına sahiptirler. Bu yan etkileri doğrudan grafa bakan fonksiyona iplemek, zamanlayıcının fonksiyonu ne zaman çağırmanın güvenli olduğunu belirlemesini imkansız kılar.

Virtual akışlar o işi izole eder. Virtual input, normal grafa bakan tick'in dışındaki kodla doldurulan component'e yerel bir kuyruktur: bir HTTP listener, bir cihaz thread'i, bir akış SDK callback'i. Component, virtual input'u pull request'ine dahil edebilir, böylece bu harici olaylar yine de normal akış mesajlarıyla aynı zamanlayıcıya görünür fonksiyon aracılığıyla akar. Virtual output bunun tersidir: component'in bir tick'ten döndürdüğü yan etki iş öğelerinin bir kuyruğu, bir bridge thread'inin eşzamansız yürüttüğü ve sonuçları virtual input aracılığıyla geri besleyebileceği.

Virtual akışları işlevsel kılan disiplin şudur: grafa bakan fonksiyon zamanlayıcıya görünür kalır. Yan etkiler kuyrukların arkasında yaşar; fonksiyon onları okur ve yazar; bridge IO'yu gerçekleştirir. O ayrım, bir component'in dış dünyayla konuşmasını sağlarken zamanlayıcının fonksiyonun ne zaman çalıştığına dair modelini korumasını sağlayan şeydir.

Release'ler değişmezdir; promotion bilinçlidir

Bu zihinsel modeli "backend'im neden yeni kodu almadı" diye akıl yürüttüğünüzde kullanın.

Her publish bir prerelease oluşturur: çağıranın test backend'lerinde deploy edebileceği özel doğrulanmış bir build. Promotion, bir prerelease'i bir yayınlanmış version'a dönüştüren ayrı, bilinçli adımdır: image kayıt defterine gider, component.yml'de bildirilen etiketler hareket eder (latest, default) ve version, workspace'in kitlesindeki herkes tarafından deploy edilebilir hale gelir. Version ID'si değişmez; yalnızca durumu değişir. Version, release kontrol listesinin her kuralını karşılayana kadar promotion reddedilir.

Backend'ler belirli release ID'lerini sabitler. Bir prerelease'i promote etmek, deploy edilmiş herhangi bir backend'in sabitlenmiş version'ını değiştirmez — backend, son deploy zamanında sabitlediği şeyi çalıştırmaya devam eder. Bir backend'i daha yeni bir release'e ileri yuvarlamak, açık bir vertex mutasyonu ve ardından bir yeniden deploy'dur. O ayrım, bozuk bir version'ı promote etmenin tek başına çalışan bir backend'i çökertememesinin nedenidir. Çalışan backend sabitlenmiştir; yeni release, katalogda yeni bir adreslenebilir yapıttır.

Tam publish + promote döngüsü için Publish anlamları sayfasına bakın.

Bir component neye sahiptir ve neye sahip değildir

Bir component kimliğine (görüntü adı artı workspace kapsamlı slug), diline (Python veya C++), bildirilen input ve output akış tiplerine, tipli config_schema'sına, modeller ve veri yuvaları için isteğe bağlı file_schema'sına, workspace dosyaları olarak geri commit ettiği çıktılar için isteğe bağlı generated_file_schema'sına ve src/ altındaki implementasyon kaynağına sahiptir. Ayrıca keşif meta verisine de sahiptir — katalog kategorisi ve modalite etiketleri, release'le seyahat eden README ve AGENT.yml.

Graf-şekilli hiçbir şeye sahip değildir. İçinde göründüğü backend, o backend'deki parametrelerinin vertex bağlamaları, yuvalarına bağlanan dosya ID'leri, output'larının açığa çıkarıldığı endpoint alias'ları, onu çalıştıran deployment, deployment'ı barındıran runtime — bunların hepsi backend-ve-deployment kaygılarıdır. Component yetenektir; diğer her şey kompozisyon ve runtime'dır.

O ayrım, tek bir component'in birçok ürünü güçlendirebilmesinin tüm nedenidir. Bir detektör component'i, bir depo-güvenliği backend'inde, bir perakende-trafik backend'inde ve bir klinik-görüntüleme backend'inde aynıdır; her backend onu farklı kablolar, farklı parametreler bağlar, farklı hesaplama üzerinde deploy eder. Component'in bunların hiçbirini bilmesi gerekmez.

Release kontrol listesi

Geçerli bir component tip denetiminden geçer; iyi bir component yalnızca manifest'inden güvenilirdir. Release kontrol listesi bu çıtanın yazıya dökülmüş hâlidir ve platform her version'ı ona göre tutar: herhangi bir kural open veya başarısız olduğu sürece promotion reddedilir. Onu karşılayan component'ler, implementasyonu hiç okumamış insanlar — ve agent'lar — tarafından kablolanabilir, değiştirilebilir ve işletilebilir.

Her kural version'ın güncel koduna göre değerlendirilir ve sağlandığının nasıl gösterileceğini söyler. Auto kurallarını platform her okumada koddan hesaplar. Live kurallar yalnızca tam olarak o kodun, bir runner çalıştırmış başarılı bir canlı testiyle geçer; version'ı yalnızca deploy eden bir çalıştırma hiçbirini kanıtlamaz. Review kurallar bir gözden geçirenin kontrol edebileceği kanıtla kaydedilir — dosya ve satır, ölçülen sayı, gözlenen çıktı. Koşullu kurallar, düzenledikleri özelliğe sahip olmayan bir component için not_applicable olabilir ve bir kişi gerekçesini belirterek bir kuraldan feragat edebilir (waive). Yeni kod publish etmek her live ve review kuralını yeniden open yapar.

Sözleşme

contract.first (review) — contract designed before code. component.yml — inputs, outputs, configuration and file slots — is designed before the implementation and stays the source of truth. Graph authors, the catalog and agents read only the contract; code shaped first and described afterwards leaks its accidents into it. Meet it: Write component.yml from the task, the input and output shapes and the downstream consumers, then implement against it. Evidence: the contract decisions and why each port, parameter and slot has the shape it has.
contract.exact (live) — declared types match what the code emits. Every type the worker emits is declared in component.yml field for field, spelled and typed as the code writes it. A declared field the code never writes, or an emitted field the type does not declare, fails every item at run time. Meet it: Make the code write exactly the declared fields, or change the declaration to what the code means to emit. Proven by a recorded live test of the version in which every item passed type validation.
contract.reuse (review) — built only where nothing existing fits. A component exists only for logic worth reusing across backends or needing files, secrets or releases. A released component that fits, a built-in transformation or an inline transform vertex makes a new component a duplicate the catalog has to carry forever. Meet it: Search the catalog by capability and by input and output types, and compare contracts, not names. Evidence: the searches run and why each near fit falls short.
contract.standalone (review) — works and is described on its own. A component's contract and documents describe what it does with its own inputs and outputs. Another component appears only as an example of where its data can come from or go to, never as something it requires, because a graph author is free to wire it to anything that carries the type. Meet it: Remove wording that pairs the component with another one as a requirement; name the type it needs instead and keep other components to examples. Evidence: the summary and pick_when entries read without the paired component.
contract.typed_params (review) — parameters carry their constraints in the type. Valid values live in the type, not in prose: fixed choices are a refined String such as String<"fast" | "accurate">, optional values a Maybe, so a graph author cannot bind a value the code rejects. Meet it: Refine each config_schema type to its valid values. Evidence: each parameter whose type is a bare String or number and why its whole range is valid.
contract.secret_params (auto) — secrets are optional secret strings. A secret parameter is Maybe<String>, marked secret, defaulting to Nothing (), so an omitted secret is absent rather than an empty string a deploy has to refuse. Meet it: Declare every secret as type: 'Maybe<String>', secret: true, default: 'Nothing ()'.
contract.native_types (review) — registered types for platform data, and no one-field records. Images, audio, tensors, embeddings, masks, geometry, detections, depth and point clouds travel as the registered types, built through the SDK constructors. A hand-packed record type-checks today and breaks silently when the carrier evolves; a missing named type is a type-registry request, not an opaque inline record. Every custom record a port, parameter or state declares has at least two fields: a lone value travels as itself and a sequence of items as a list, never wrapped in a one-field custom record; a registered type travels as registered. Meet it: Emit and accept the registered types through the SDK, and unwrap any one-field custom record into the value it holds. Evidence: each port's, parameter's and state's type and, for any custom record, its fields and why no registered type carries it.
contract.oneof (review, conditional) — output arms are projections of one result. When several output shapes are valid, the component computes one canonical result and projects it into each oneof arm, choosing the arm once at startup from the connected sink type — never per message. Meet it: Implement one internal result and one projection per arm; resolve the arm at startup. Mark not applicable when no output is a oneof.
contract.files (review, conditional) — model files come through declared file slots. Weights, datasets and other files bind through file_schema slots that declare the real layout the worker loads. A worker that downloads at startup hides its real dependency, fails offline and cannot be pinned. A component serves a task family: another model its code can load through the same slot layout is another file in that slot, never another component, so the component's name, README, AGENT manifest and slot tag describe the task and the file format, never one model. A model's name, author attribution and license live on its file. Every fact that differs between models of the family (labels and the position of structural ones such as background, counts, shapes, input size, anchors, normalization, vocabulary) is read from the bound file, its metadata or a side file the slot's bundle layout declares; a fact no file carries is a parameter, defaulting to the library's own value where the library has one and required otherwise, never to one model's value, and an operating value the user may tune (a threshold) is a parameter whose default the file supplies when it carries one. The worker fails loudly when a fact is missing or disagrees with the file's tensors; the code never hard-codes one model's values. Code that fixes particular semantic classes for selection or special treatment belongs only to a component whose declared task names them; a class filter the user sets through a parameter is generic. Meet it: Declare a slot per file set with its real bundle layout and load only from it; read every per-model fact from the file, its metadata or a side file in the bundle, and take from a parameter only what no file carries and the operating values the user may tune, defaulting to the file's value when it carries one; keep model identity, attribution and license on the linked file. Evidence: each per-model fact the code uses and where it reads it. Mark not applicable when the component reads no files.
contract.resources (live) — hardware needs declared and true. GPU, memory and architecture needs are declared, and the declaration is what the component actually ran on. An undeclared need surfaces as a crash on the first runtime that lacks it. Meet it: Declare the hardware the worker needs; prove it with a recorded live test on a runtime matching the declaration.

Davranış

behavior.one_output (live) — one output per valid input. Every valid input yields exactly one value on every output port. Absence is said explicitly — a Nothing, an empty list, a documented value — never by skipping a tick, because downstream vertices schedule against each emission and a skipped tick stalls the graph. Meet it: Emit on every port for every input, with explicit absence. Proven by a recorded live test whose runner checks one output per input.
behavior.fail_loud (review) — invariants asserted, failures passed on whole. Impossible states are asserted at the boundary and trusted inside; there is no catch-and-continue and no fallback value standing in for a missing real one. An upstream service's failure reaches the output with its complete error object, so the cause is visible where it surfaces. Meet it: Assert at the boundary, remove silent fallbacks, return the full upstream error. Evidence: the file and line of each boundary assertion and error path.
behavior.logging (auto) — logs only through ppl::logger. A C++ component logs only through ppl::logger, so every line it writes reaches the platform's logs with its level and source. Its own C/C++ files under src/ (symlinks read through to what they name) do not use std::cout, std::cerr, std::clog, printf, wprintf (and their v-forms), puts, putchar, perror, dprintf / write / writev on descriptor 1 or 2, std::print / std::println / std::vprint_unicode with a format string first, or the stdout / stderr handles (fprintf(stderr, …), fputs(…, stdout)). Comments and string literals are not checked; the check is lexical and does not expand macros or resolve symbols. A directory under src/ that carries its own license file — named LICENSE, LICENCE, COPYING or UNLICENSE, alone or followed by . and a suffix (LICENSE.txt, LICENSE.hnswlib) — is vendored third-party code and is exempt with everything below it. A C++ component that breaks the rule is refused at upload. Meet it: Replace each write with ppl::logger::log (info) or ppl::logger::elog (error) from "pipelogic/logger/log.hpp", or ppl::logger::dlog (debug) from "pipelogic/logger/dlog.hpp". Vendor third-party code in its own directory under src/ together with its license file.
behavior.no_stall (live) — never blocks a shared stream. The component never holds a stream other vertices read. Anything that stops reading or holds input is a configuration choice documented as a hazard, because the worker cannot see the graph it is placed in. Meet it: Prove it with a recorded live test where one source feeds both this component and a plain passthrough probe, and the probe keeps receiving.
behavior.state (review) — stateless unless output depends on history. Persisted state holds only behavioral memory — values whose loss changes the next output. Model handles, clients and caches live per process. Declaring state serializes the vertex, so state that is not needed costs throughput. Meet it: Keep the component stateless, or justify each persisted field by the output it changes.
behavior.side_effects (review, conditional) — outside calls behind virtual streams. HTTP, devices, SDK callbacks and other outside work run behind virtual streams so the graph-facing function stays visible to the scheduler. Retries are bounded and documented. Meet it: Move outside calls behind virtual input and output; bound and document retries. Mark not applicable when the component calls nothing outside the graph.
behavior.live_params (review) — live-changeable only where safe. A parameter is mutable on a running deployment only when changing it mid-stream leaves every output correct. Meet it: Mark mutable only the parameters whose change the code applies safely between items.
behavior.upstream_parity (live, conditional) — as good and as fast as the code it wraps. A component wrapping an upstream model or library matches or beats the upstream code's output quality and speed on the same hardware. A wrapper that is worse than the code it wraps has no reason to exist. The reference is the upstream inference path for the declared task, every branch it takes on input properties and its preprocessing, decoding, suppression and thresholds included; steps that serve one upstream demo or deployment scene beyond the component's declared task (scene heuristics, filters fixed on classes the task does not name) are not part of it and are not carried into the component. Meet it: Measure output and latency against the upstream inference path on the same inputs and hardware in a recorded live test. Evidence: the upstream entry point used as the reference, the lease and the comparison. Mark not applicable when nothing upstream is wrapped.

Build

build.pinned (auto) — dependencies pinned exactly. Every dependency the manifest declares — src/requirements.txt for Python, xmake_packages for C++ — is pinned to one exact version, and packages the build system already provides are not restated, so a rebuild resolves the same packages. A system package the build image provides (pkgconfig::, cmake::, system::, apt::) takes its version from the image and names none. Meet it: Pin each requirement as pkg==X.Y.Z and each xmake package as name X.Y.Z (conan::name/X.Y.Z); write a system package as its bare name (pkgconfig::name); pick the build_system that carries the runtime's own packages.
build.license (auto) — license declared. The component declares the license its own code ships under, so whoever adds it to a backend knows what they may do with it. A model or other file bound through a file slot carries its own license on that file; the component license never covers or restates it. Meet it: Set the component license (SPDX id or text) to the license of the component's code alone; set each model file's license on the file.
build.no_secrets (auto) — no secret in source. No credential appears in source, manifest or assets. Secrets reach the worker only as secret parameters bound to workspace secrets. Meet it: Remove the credential, revoke it, and take it through a secret parameter.

Dokümanlar

docs.true (review) — documents say exactly what the code does. The README, the AGENT manifest and every description in component.yml are exactly true of the code. A document that oversells or drifts is a bug as severe as wrong output, because agents quote it to justify wiring. Meet it: Read each statement against the source. Evidence: the statements checked and the code each rests on.
docs.two_audiences (auto) — a README for people and an AGENT manifest for agents. The README explains how the component fits into pipelines and its caveats; the AGENT manifest says when to pick it, when not to, and how it behaves. Both pass the document rules. Meet it: Write both documents; ppl component rules --surface=readme and --surface=agent list what each must hold.
docs.hazards (review) — every hazard documented. Every way the component can stall a graph, drop data, cost money or fail is a caveat or behavior note, not only its happy path. Meet it: List the failure, stall, cost and limit cases from the code and document each. Evidence: the hazards found and where each is documented.
docs.refs (auto) — declared names referenced by role. Every role marker in the README resolves to what the manifest declares, and parameters are named through :param: markers rather than as bare words, so a rename cannot leave a stale name behind. Meet it: Use :param:, :type:, :input:, :output: and :component: markers for declared names; fix or drop each marker that resolves to nothing.

Görünüm

look.name (review) — named by what it does. The display name starts with an imperative verb and its object, with the engine in parentheses — "Build Vector Index (FAISS)", not "Vector Store (HNSW)" — so the catalog reads as a list of capabilities. The engine is the library or runtime the code runs, never a model or checkpoint bound through a file slot. Meet it: Rename the component to verb + object (Engine), with no model name in it.
look.icon (auto) — its own icon. The component carries its own icon, never the placeholder, so it is recognizable in every catalog row. Meet it: Draw a 512×512 icon — one silhouette, two or three flat colors, no text — and set it as the component avatar.
look.tags (auto) — category and modality tags. The component carries at least one category and one modality, the filters the catalog is browsed by. Meet it: Set the component's categories and modalities.

Kanıt

proof.tests (live) — self-contained tests pass against the version. The component's own tests cover empty, degenerate, malformed, boundary, large and real inputs and every output arm, asserting real values, and pass against the published version. Meet it: Ship the tests with the component and run them as the live test's runner. Proven by a recorded live test whose runners all exited 0.
proof.live (live) — output compared on chosen input. The published version ran live on input whose content was chosen for it, and its output content was compared with what that input should become. A ready deployment or a returned file id shows the graph ran, not what it produced. Meet it: Run a live test on a fixture you chose and compare the collected output. Evidence: the lease and the comparison.

Bunun yeri

Component'ler, kodun ne yaptığı için platformun yük taşıyan ilkelidir. Backend'ler onları birleştirir; deployment'lar onları çalıştırır; katalog onları keşfeder; tip sistemi nasıl birbirine kablolanacaklarını kısıtlar; release modeli davranışlarını zaman içinde yeniden üretilebilir tutar. Platformdaki diğer her kavram, component'leri yeniden kullanılabilir, birleştirilebilir, işletilebilir veya keşfedilebilir kılmak için vardır, böylece tek bir yetenek, her biri için özel yapışkan olarak yeniden uygulanmak yerine birçok ürüne hizmet eder.

Platformun component yazarlarından istediği disiplin küçüktür: tipli sözleşmeyi doğru bildir, varsayılan olarak durumsuz ol, duruma ve virtual akışlara yalnızca temel şekil sözleşmeyi ifade edemediğinde başvur ve release'leri değişmez olarak ele al. Karşılığında, platform graf tip-kontrolü, katalog keşfi, runtime zamanlaması, deployment, gözlemlenebilirlik ve kanıt döngüleri sağlar. Yazar fonksiyonu yazar; etrafındaki her şey platformun sorumluluğudur.

İlgili

Backend'ler — yayınlanmış component'leri tipli bir grafa kabloluyor.
Tipler — kötü kablolamayı runtime'dan önce yakalayan sözleşme.
Adlandırılmış tipler — Image, Tensor, AudioFrame arkasındaki kayıt defteri.
Publish anlamları — publish ve promote döngüsü ayrıntılı olarak.
File schema — bir component'in tükettiği ve ürettiği dosyaları bildir.
Build sistemleri — platform kaynağı doğrulanmış bir image'a nasıl dönüştürür.
Solution'lar — component + backend + deployment + yüzey, uçtan uca.
Quickstart — ilk göreviniz için rota seçici.