Getting Started

This guide covers Packflow installation and basic usage of the CLI to create a simple Packflow project.

Installing Packflow

Prerequisites

• Python (version 3.10+)

Install from PyPI

Packflow can be installed directly from PyPI:

pip install packflow

Install from Source

For development or to install from source:

# Clone repository and navigate to the root directory
git clone https://github.com/dow-cdao/packflow.git
cd packflow

# Install package
pip install .

# For contributors: install in editable mode with dev dependencies
pip install -e .[dev]

# Alternative: use Poetry for dependency management
poetry install --with dev

# For contributors: install pre-commit hooks
pre-commit install

Documentation

Packflow documentation is hosted at https://dow-cdao.github.io/packflow/. For instructions on building documentation locally, see the README.

Important

If a “Not Found” error page is received when first accessing the documentation, wait a moment for the server to fully start and refresh the page.

Building Documentation from Source

The following are required to build documentation from source:

• Python (version 3.10+)

• Pip

• Packflow (the version corresponding to the docs being served)

• Pandoc - Must be installed separately, from system package manager (see Pandoc installation instructions)

• make command (xcode-select on macOS and WSL on Windows, or build-essential on Linux)

Steps to build and serve documentation:

# Navigate to docs folder
cd docs

# Install Python dependencies
pip install -r requirements.txt

# Serve documentation with live updates (development)
make dev

# OR serve static multi-version documentation (production)
make prod-serve

# Access the documentation in a web browser at http://127.0.0.1:8000/

Creating a Packflow Project

This section covers the initial setup process for creating a Packflow project, defining an Inference Backend, and running Packflow’s validation checks on the input/output requirements of the Inference Backend.

Step 1: Create the project structure

Initialize a new project by running packflow create hello-world. An interactive wizard will prompt for a project description, version, and maintainer email. Defaults can be accepted by pressing Enter.

Note

Project names must start with a letter and may contain letters, digits, hyphens, and underscores. To skip interactive prompts (e.g. in CI), pass --no-input.

This creates a new directory named hello-world with the following structure:

hello-world/
├── packflow.yaml
├── LICENSE.txt
├── MODEL_CARD.md
├── README.md
├── requirements.txt
├── inference.py
└── tests.py

Step 2: Write the Inference Backend

Open inference.py. The template contains a passthrough backend that returns inputs unchanged. Replace the execute() method with logic for the analytic. For this example, the backend doubles the value under the key number:

inference.py

from packflow import InferenceBackend


class Backend(InferenceBackend):
    def execute(self, inputs):
        outputs = []
        for row in inputs:
            outputs.append({"doubled": row["number"] * 2})
        return outputs

Step 3: Test the Backend (Optional)

A tests.py file is included as a starting point for testing the backend with pytest. This file is optional and not required for validation or export. To use it, update the sample inputs to match the backend’s expected format:

tests.py

import pytest
from packflow.loaders import LocalLoader


@pytest.fixture
def backend():
    """Load the backend as configured in packflow.yaml"""
    return LocalLoader.from_project(".")


def test_backend_loads(backend):
    """Backend initializes without error."""
    assert backend is not None


def test_check_io(backend):
    """Backend I/O passes Packflow's format checks."""
    sample_inputs = [
        {"number": 5},
        {"number": 10},
    ]
    outputs = backend.check_io(sample_inputs)
    assert outputs is not None


def test_backend_output_values(backend):
    """Verify specific output values for known inputs."""
    outputs = backend([{"number": 5}])
    assert outputs[0]["doubled"] == 10

Run the tests from inside the project directory:

pip install pytest
pytest tests.py

The test_check_io test calls backend.check_io(), which runs sample data through the backend and checks that outputs meet Packflow’s format requirements (correct types, matching row counts, JSON-serializable values). If any checks fail, an exception with details of the issue is raised.

Step 4: Validate the project

Use the packflow validate command to check that the project structure and configuration are complete:

packflow validate

This checks for required files (packflow.yaml, requirements.txt), recommended files (README.md, MODEL_CARD.md, LICENSE.txt), metadata completeness, and runs a smoke test to verify the backend can be loaded.

Pass -v for detailed output showing each check.

Step 5: Package for distribution

Once the backend is implemented, tested, and validated, create a distributable archive:

packflow export

This produces a zip file (e.g. hello_world-0.1.0.zip) in the current directory. See Preparing for Distribution for details on what is included in the archive and how to prepare a project for sharing.

Next Steps

Please see the Creating a Custom Backend section of this site for more detailed information on building custom Inference Backends with Packflow.