Artifacts

Agent calls return immutable Artifact objects. They are useful results for inspection, validation, logging, and compatibility APIs. The normal Source Work → Planner Compile → Author flow hands off through the current run directory, so it does not require passing artifacts between those calls.

from scrambo import Artifact, ValidationReport

Field or method	Meaning
`name`	The stage name supplied by your program.
`kind`	The kind of agent task that produced it.
`execution_id`	The unique accepted execution of that task.
`result`	Structured result data, such as `result["brief"]`, `result["plan"]`, or generated media records.
`llm_invoked`	Whether this result required a model call.
`cached`	Whether Scrambo reused matching prior work.
`input_ref()`	A compact compatibility reference for APIs that explicitly accept an artifact.

ValidationReport adds:

Field or method	Meaning
`passed`	`True` when all selected validators passed.
`findings`	Structured findings suitable for logging or custom routing.
`md`	A readable Markdown report.
`require_passed()`	Raises `ScramboValidationError` if the report failed.

Stable prompts and stable stage names allow Scrambo to reuse work when inputs and upstream artifacts have not changed. A changed prompt, media input, base timeline revision, model setting, or upstream artifact creates new work. Treat caching as an optimization, not as program state: always express the complete intent needed by the call.