Sophios

Sophios is a Python-first authoring layer for Common Workflow Language (CWL) workflows. It lets users describe command-line tool contracts, compose those tools into workflow DAGs, compile the graph to inspectable CWL, and run locally or prepare schema-validated compute submissions.

Documentation

The documentation is available on readthedocs.

Quick Start

See the installation guide for more details, but:

For pip users:

pip install sophios

Sophios installs its Python workflow-building and validation dependencies with the package. Some workflows also depend on external system tools such as Docker, Podman, Graphviz, Node.js, or the command-line programs invoked by your CWL tools.

For conda users / developers:

See the installation guide for developers

from pathlib import Path

from sophios.api.python.workflow import Step, Workflow


echo = Step(clt_path=Path("cwl_adapters") / "echo.cwl")
echo.inputs.message = "Hello World"

workflow = Workflow([echo], "hello_python")
compiled = workflow.compile()
compiled.write_cwl("autogenerated")
compiled.write_job_inputs("autogenerated")

For the file-native YAML path, the CLI still supports .wic workflows:

sophios --yaml docs/tutorials/helloworld.wic --graphviz --run_local --outdir helloworld_output --quiet

Sophios compiles both Python-authored workflows and .wic workflows to CWL. Users should inspect important generated DAGs and CWL artifacts before relying on edge inference in production workflows.

Python API

The public Python API is split into three deliberate surfaces:

• sophios.api.python.tool_builder builds CWL CommandLineTool contracts.
• sophios.api.python.workflow composes Step and Workflow DAGs.
• sophios.compute_request packages compiled workflows for compute submission.

Use Workflow([steps], "name") to make the DAG explicit, Step(clt_path=...) for existing CWL tools, Step(tool) or tool.to_step() for in-memory tool-builder handoff, and workflow.compile() to produce the public compiled CWL boundary.

Edge Inference

Sophios can infer many linear edges based on CWL types, file formats, and naming conventions. In Python workflows, leaving a required step input unbound allows the compiler to apply the same inference mechanism used by .wic workflows. Inference is useful, but it is not a substitute for reviewing generated artifacts when correctness matters.

Subworkflows

Subworkflows are very useful for creating reusable, composable building blocks. As shown above, recursive subworkflows are fully supported, and the edge inference algorithm has been very carefully constructed to work across subworkflow boundaries.

Explicit CWL

Sophios produces ordinary CWL artifacts. Users do not need to write raw CWL for the common path, but generated CWL remains available for inspection, execution by CWL runners, and advanced integration.