Project Structure
Initialize and structure a Python workflow project so releases can be built reproducibly and release runners can discover and execute its tasks.
A Python workflow project contains task classes, a Runner definition, and a tilebox.workflow.toml file. The Tilebox command-line tool uses these files to build a workflow release, discover the tasks it can execute, and make the release available to release runners after deployment.
Keep the project small and importable from its root. Release builds import the configured runner object, check that the Python runtime starts, and package the selected files into an immutable artifact.
Scaffold a workflow project
For a new Python workflow project, use the CLI to scaffold the local files. You can start from a small built-in example or copy a published workflow as a template. For a walkthrough through publication and your first job, follow Build and deploy a workflow project.
tilebox workflow init ./scene-qa --name "Scene QA"This creates a project in scene-qa. Omit the directory argument to use the current directory, or omit --name to use the directory’s name for the project.
The command creates tilebox.workflow.toml, pyproject.toml, and runner.py, then runs uv sync to install the Tilebox dependencies and create uv.lock. You’ll need uv installed.
Your project stays local until you publish its first release. You can add --description "Checks incoming scenes" to give the workflow a description when it is created in Tilebox.
Edit runner.py directly for prototypes, or move task code into a package as the workflow grows.
Template projects
Use --template to start from the latest published release of a workflow you can access. The source may belong to your organization or be shared with it. Browse public choices with tilebox workflow list --shared, or your own workflows with tilebox workflow list.
Replace <template-reference> with a workflow reference from the list:
tilebox workflow init ./scene-qa \
--template <template-reference> \
--name "Scene QA"Choose a new or empty directory for your copy. Review the downloaded code and dependencies, then run uv sync from that directory to install them.
Choose the directory and name
Use --name to give your workflow a new name; choosing a different directory alone keeps the template’s project name. Python packages and task names stay unchanged, so you can start editing without renaming the code.
If you omit the directory argument, the CLI creates one from the project name. Add --description to replace the template’s description with your own.
What the template includes
You get the files included in the published release: its Python source, dependencies, and lock file, along with the configuration needed to build your own releases. Tests, documentation, or other files left out of that release are not copied.
Deployment targets are left out so you can choose your own clusters. Follow Build and deploy a workflow project to set one up.
Your copy is independent. Publishing creates your own workflow, and future changes to the template do not automatically update your code.
Files to keep in version control
Commit your source files, pyproject.toml, uv.lock, and tilebox.workflow.toml. Keep the local Python environment (.venv/) and workflow link (.tilebox/) out of version control.
After cloning the repository, link your local project to the workflow you want to publish to.
Manual project structure
Use a layout where task code and the runner definition are importable from the project root.
- my-workflow/
- pyproject.toml
- uv.lock
- tilebox.workflow.toml
- my_workflow/
__init__.py- tasks.py
- runner.py
Define the Python project
Use a minimal pyproject.toml with the dependencies your workflow needs. For this example, only the Tilebox Python package is required.
[project]
name = "my-workflow"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"tilebox",
]Create the package directory and an empty __init__.py file so Python can import my_workflow.runner from the project root.
mkdir -p my_workflow
touch my_workflow/__init__.py
uv lockDefine tasks
Put task classes in a module that can be imported during release validation.
# my_workflow/tasks.py
from tilebox.workflows import ExecutionContext, Task
class ProcessScene(Task):
scene_id: str
@staticmethod
def identifier() -> tuple[str, str]:
return "tilebox.com/example/ProcessScene", "v1.0"
def execute(self, context: ExecutionContext) -> None:
context.current_task.display = f"ProcessScene({self.scene_id})"
context.logger.info("Processing scene", scene_id=self.scene_id)Use explicit identifiers for workflow code that will be published. A stable identifier lets existing jobs continue to run after refactors and compatible bug fixes.
Define the runner
Create a module that exports a Runner object. This object defines the task registrations for the workflow, and release builds import it during validation.
# my_workflow/runner.py
from tilebox.workflows import Runner
from tilebox.workflows.cache import LocalFileSystemCache
from my_workflow.tasks import ProcessScene
runner = Runner(
tasks=[ProcessScene],
cache=LocalFileSystemCache(),
)Configure the workflow release
Point tilebox.workflow.toml at the exported Runner object and include the files required by the release runner.
[workflow]
slug = "my-workflow"
root = "."
runner = "my_workflow.runner:runner"
[build]
include = [
"pyproject.toml",
"uv.lock",
"my_workflow/**",
]
exclude = [
".venv/**",
"**/__pycache__/**",
"**/*.pyc",
".pytest_cache/**",
]
use_gitignore = trueThe Tilebox command-line tool imports the runner object during build-release and publish-release, discovers its task identifiers, and records them in the workflow release. A release runner later loads the release artifact and invokes the Python runtime through the command-line tool.
If you assembled the project manually rather than using init, link it to an existing workflow before publishing. Create a workflow in Tilebox first if you do not have one yet.
Keep release artifacts small
Include source code, lock files, and small configuration. Exclude local virtual environments, test caches, downloaded provider data, model checkpoints, generated outputs, and other large runtime artifacts.
If a task needs a large model or reference file, fetch it lazily at runtime and cache it in a deterministic runner-local path such as ~/.cache/tilebox/.... The workflow should still work when a release runner starts with an empty cache.