Job specs | everyn

How Everyn captures reusable work instructions, model choices, and output contracts.

A job spec is the durable work contract for a class of Everyn work. It is more than a prompt: it includes the goal, instructions, output mode, selected model, output schema, and review expectations that subsequent runs should follow.

Job specs are reusable. A run does not execute an unversioned idea; it executes a pinned job spec version. That makes sample results, revisions, full runs, retries, and exports easier to explain later.

Job spec contract

Job spec versus job spec version

Object	Meaning
Job spec	Mutable product object representing a reusable class of work.
Job spec version	Immutable snapshot of instructions, model, mode, and output schema.
Run	Execution record that pins one job spec version.

When a job spec is patched, subsequent runs can use a new version. Existing runs keep the version they pinned.

Output modes

Mode	Use it when
`add_columns`	Each source row should receive one generated object with new fields. Lead scoring, classification, enrichment, and sentiment extraction usually start here.
`create_rows`	Each source row may produce zero, one, or many child records. Use this when the output is a list of findings, contacts, references, or extracted items.

Output schema rules

Good output schemas are explicit enough for consistent validation:

use stable machine field names such as fit_score or evidence_url
include descriptions that explain how to produce the field
use enum when the accepted values are known
use numeric bounds for scores or confidence values
represent uncertainty with fields such as confidence, needs_review, or a nullable optional field
avoid hidden business rules that are not encoded in the job spec

Column names should stay stable because they become output keys and export columns. If the schema needs a breaking change, treat the revised job spec version as a new contract and run another sample.

Drafting workflow

Inspect the dataset columns and representative rows.
Restate the goal in product terms.
Choose add_columns or create_rows.
Draft the output schema and review criteria.
Pick a runnable model from the model catalog.
Run a limited sample.
Review outputs and failures.
Revise the job spec if the sample exposes ambiguity.
Use the approved version for the full run.

Example: lead/account scoring

A lead scoring job spec might use add_columns with fields like:

Field	Type	Description
`fit_score`	integer	Score from 1 to 5 for fit against the target customer profile.
`fit_reason`	string	Concise reason for the score using evidence from the row or research.
`territory_signal`	enum	Whether the account appears in a priority territory.
`evidence_url`	string	Public source used to support the score, when available.
`needs_review`	boolean	Whether the row should be inspected before use.

Common mistakes

Treating a prompt as the entire job spec.
Creating output fields with unstable names like result1.
Asking for private business context that later runs cannot access.
Omitting review criteria and then treating subjective output as final.
Changing schema after a sample without running another sample.
Starting a run before checking whether the model ID is supported.