Academy
4. Declaring and Validating Inputs
Define typed, required or optional inputs — files, dates, keywords, choices — so every run is validated before it starts.
Every Live Artifact begins with its inputs — the values that change from one run to the next. An input can be a file to process, a date range, a target keyword, a list of choices, or any other typed parameter. These inputs are declared once during the forging step and then validated automatically at each run. If a required input is missing or has the wrong type, the run won't start. This front-gate validation eliminates wasted credits and failed runs caused by incomplete or malformed data. Think of the input declaration as a contract: it tells every future user — including teammates who install your artifact — exactly what the workflow expects before a single credit is spent.
You declare inputs during the forge step, either when converting a successful mission or when describing a new workflow in plain language on the forge page. In both paths, @oupi identifies what varies between runs and proposes an input form. For each input you specify: (1) a descriptive name, (2) a type — free text, date, number, file from your file space, or a fixed set of allowed choices, (3) whether it is required or optional. When forging from a mission, @oupi already knows which parameters drove the original task, so it pre-fills sensible defaults. When forging from plain language, it asks you explicitly: "What changes between runs — a file, a date, a keyword?" Your answers become the input schema.
Required vs. optional is a design decision with real consequences. Mark an input as required when the workflow cannot produce a meaningful result without it — e.g., the spreadsheet to clean or the target market to analyze. Mark it optional when a sensible default or omission is acceptable — e.g., an extra keyword filter or a custom date override. At run time, OUPI validates the form: required fields must be filled, types must match (a date field won't accept free text), and choice fields restrict the user to the allowed values. File inputs pull from your file space. This validation fires before execution begins, so no credits are consumed on a malformed run.
When naming inputs, write for the teammate who will install your artifact from the marketplace, not for yourself. Use clear labels like "Invoice PDF (required)" or "Reporting period — start date" instead of cryptic shorthand. Good names reduce clarification questions and failed runs.
Use choice-type inputs whenever the set of valid values is known and finite (e.g., department names, output languages, report formats). This prevents typos, enforces consistency across runs, and makes the artifact easier for others to use after sharing or marketplace installation.
Validation also protects automated runs. When a Live Artifact is triggered by a schedule or an external event (webhook, watcher), the event's data is mapped to the declared inputs. If the mapping fails validation — a missing required field, a type mismatch — the run is blocked and logged in the history with its inputs and verdict, so you can diagnose the issue without guessing. This is especially important for unattended workflows where no one is filling the form manually.
Open the forge page (Live Artifacts → Forge). Describe a workflow you run regularly — e.g., "Summarize a PDF and extract key dates." When @oupi asks what varies, declare at least three inputs: one required file, one optional date, and one choice field. Review the generated input form, then test-run it to confirm validation catches a missing required field.
Inputs are the contract of a Live Artifact: typed, labeled, required or optional, validated before every run. Declare them during the forge step — from a mission or plain language. Use clear names and choice fields for consistency. Required inputs block execution when missing; optional ones allow flexibility. Validation applies equally to manual runs and automated triggers, protecting credits and ensuring reliable results across your team.