Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sirenspec.dev/llms.txt

Use this file to discover all available pages before exploring further.

SirenSpec follows Semantic Versioning. This page mirrors the CHANGELOG.md in the repository.

​
0.1.2 — 2026-05-28

A reliability and authoring-ergonomics release driven by early-user feedback. No breaking changes.

​
Added

  • Load-time workflow linter — load_workflow() and sirenspec validate now run a static linter before execution:
    • working_dot_node_id (error) — rejects {{ working.<node_id>.* }} when <node_id> is a known node; the canonical form is {{ <node_id>.output }}.
    • unknown_namespace (warning) — flags top-level names that are neither a reserved namespace (inputs/env/item/index/total) nor a known node ID, catching typos before they raise an error at runtime.
  • | json_or_default('...') filter — fires when a key is missing, when the value is an empty string, and when the value cannot be parsed as JSON. See Interpolation.
  • Safe builtins in when: expressions — len, bool, str, int, float, abs, min, max are available, e.g. len(working.items) > 0. __builtins__ remains otherwise blank. See YAML Reference.
  • retry_on_guardrail on retry policies — when true, output guardrail checks run inside the retry loop so a GuardrailViolation triggers another provider call instead of an immediate failure. guardrail_violation is also accepted as a retry trigger. See Retry Policies.
  • Factory inputs: exposed as {{ inputs.key }} — resolved factory inputs: values are available as named template vars in the spawned agent’s system prompt, in addition to the existing user-message join.
  • WorkflowLintError is now exported from the top-level sirenspec package.

​
Changed

  • | default('...') now fires on empty strings — previously it engaged only on a missing key; it now also fires when the resolved value is "".
  • for_each accepts native lists and fenced JSON — the loop source may be a native Python list, a plain JSON array, or a fenced ```json block, so upstream tool and agent outputs work without post-processing.
  • env_file: is loaded eagerly in load_workflow() — environment values are applied before the workflow is returned, so provider clients that read os.environ at init time see the correct values. An EnvFileShadowWarning is emitted when an env_file key is already present in os.environ as an empty string. See YAML Reference.
  • CLI trace output suppresses branch-not-taken nodes — NodeCompleteEvent gains a skip_reason field (branch_not_taken / budget_exceeded); intentionally untraversed branches no longer appear as noise in the terminal, while budget_exceeded skips still print clearly.

​
Fixed

  • Python tool config interpolation — {{ ... }} templates inside a Python tool’s module, function, and args are now resolved (recursively through nested dicts and lists), matching HTTP tool config behaviour.

​
0.1.1 — 2026-05-23

Maintenance release — CI/CD and release-tooling fixes, README rebrand copy, and badge/link updates. No library behaviour changes.

​
0.1.0 — 2026-05-23

Initial public release: the YAML-first workflow engine, agent/swrm/factory/tool/workflow/human node types, OpenAI/Anthropic/Ollama providers, streaming execution, guardrails, budgets, retry policies, token accounting, the Typer CLI, cassette-based testing, and the sirenspec.schema.json artifact.