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.
Installation
uv add sirenspec
# or
pip install sirenspec
Public API
SirenSpec exposes three names at the top level:
from sirenspec import load_workflow, execute, Workflow
| Name | Type | Description |
|---|
load_workflow | function | Load and validate a YAML workflow file. |
execute | async function | Execute a validated workflow. |
Workflow | class | Pydantic model representing a workflow. |
load_workflow
Load and validate a workflow file, returning a Workflow instance.
from sirenspec import load_workflow
workflow = load_workflow("workflow.yaml")
def load_workflow(filepath: str | Path) -> Workflow: ...
| Exception | When |
|---|
FileNotFoundError | The file does not exist. |
ValueError | YAML is malformed or fails schema validation. |
execute
Execute a workflow asynchronously and return a structured trace dict.
import asyncio
from sirenspec import load_workflow, execute
workflow = load_workflow("workflow.yaml")
trace = asyncio.run(execute(workflow, user_input="What is the capital of France?"))
print(trace["output"])
# {"reply": "Paris is the capital of France."}
print(trace["summary"]["status"])
# "success"
async def execute(workflow: Workflow, user_input: str) -> dict[str, Any]: ...
| Parameter | Type | Description |
|---|
workflow | Workflow | Validated workflow instance from load_workflow. |
user_input | str | The initial user message passed to the first (root) node. |
sirenspec run JSON output. See the CLI Reference for field descriptions.
Usage in an Async Context
If you’re already in an async context (FastAPI, asyncio script, etc.), await the call directly:
import asyncio
from sirenspec import load_workflow, execute
async def main() -> None:
workflow = load_workflow("workflow.yaml")
trace = await execute(workflow, user_input="Hello")
print(trace["output"])
asyncio.run(main())
Error Handling
from sirenspec import load_workflow, execute
try:
workflow = load_workflow("workflow.yaml")
except FileNotFoundError as exc:
print(f"File not found: {exc}")
except ValueError as exc:
print(f"Invalid workflow: {exc}")
trace = await execute(workflow, user_input="Hello")
if trace["summary"]["status"] == "failed":
for node in trace["nodes"]:
if node["error"]:
print(f"Node '{node['id']}' failed: {node['error']}")
The Workflow Model
Workflow is a Pydantic v2 model. You can inspect it directly or construct one programmatically:
from sirenspec import Workflow
from sirenspec.core.models import AgentDefinition, Node
workflow = Workflow(
version="0.1",
agents={
"assistant": AgentDefinition(
model="openai:gpt-4o-mini",
system="You are a helpful assistant.",
)
},
nodes={
"answer": Node(agent="assistant", writes="output.reply")
},
)
