Introduction

packflow is a software development kit (SDK) that simplifies the development process and standardizes packaging of AI/ML running on streaming data sources.

What does Packflow do? Packflow provides a framework for writing, running, and packaging inference code. It offers a standardized structure (the InferenceBackend class) for writing model execution logic, provides the runtime backbone that executes models with built-in profiling and preprocessing, and includes tools to bundle code into portable zip archives. This means you write your inference code once using Packflow's structure, and Packflow handles both the optimized execution and creation of shareable packages for transfer between systems.

Many existing packaging frameworks are catered towards inference APIs and often require custom preprocessing steps. This can be particularly challenging when dealing with data sources that typically generate data one row at a time in key-value pairs (e.g., firewall logs or message streams).

Packflow, however, is optimized to run models on either individual events or batches of events, streamlining development and reducing the need for additional preprocessing. By leveraging Packflow, teams can focus on building and deploying models with custom out-of-the-box workflows and utilities, significantly reducing the time and effort required to onboard new capabilities.

Getting Started

The following instructions quickly walk through how to install Packflow and serve user documentation.

Installing Packflow

Prerequisite Requirements

• Python (version 3.10+)

Installation from PyPI

1. Packflow can be installed directly from PyPI:

pip install packflow

Documentation

Packflow documentation is hosted at https://dow-cdao.github.io/packflow/. Pre-built HTML is also available on the gh-pages branch.

To build and serve documentation locally:

1. Install system prerequisites: Pandoc (required in addition to the pandoc Python package) and make¹
2. Navigate to the docs folder: cd docs
3. Install Python dependencies: pip install -r requirements.txt
4. Run make dev to serve with live reloading at https://127.0.0.1:8000/

Usage

Packflow provides a flexible base class called an InferenceBackend that allows users to build highly scalable platform- and tool-agnostic inference code, enabling simplified sharing across environments.

Additionally, Packflow's CLI can assist with creating projects, gathering environmental information, and creating distributable code packages for sharing reproducible inference code between disconnected environments.

Dummy Inference Backend

To create a dummy Inference Backend, update the inference.py file to the following:

from packflow import InferenceBackend


class Backend(InferenceBackend):
    def execute(self, inputs):
        """
        Simply print 'Hello, world!' then return the input data
        """
        print('Hello, world!')
        return inputs

Load and Run the Inference Backend

In a different Python file or from the command line in the same directory, execute the following:

from packflow.loaders import LocalLoader

backend = LocalLoader('inference:Backend').load()

backend({"sample": "data"})
# >> {"sample": "data"}

Recent Changes

0.4.1

• Expanded NumPy compatibility to support releases providing Python 3.14 wheels.
• Added Python 3.13 and 3.14 to the supported runtime metadata.

0.4.0

Recent updates include improvements to configuration structure and new CLI capabilities:

• New: Interactive packflow create command with guided prompts for project setup
• Renamed backend.validate() to backend.check_io() for clarity
• Project templates simplified for better first-run experience
• Added tests.py to project templates with integrated validation and testing
• Removed standalone validate.py from templates
• Default PackflowConfig version now set to 0.1.0 when not specified
• Added questionary dependency for interactive CLI prompts
• Custom configuration keys in packflow.yaml should now be placed under an extra: field for cleaner validation
• Backend configuration can now be defined directly in packflow.yaml instead of separate JSON files
• Name validation relaxed to allow numbers and hyphens (not as first character)
• New packflow validate and packflow --version commands
• Environment variables can be specified in packflow.yaml and are set automatically during packflow operations
• packflow export now respects .gitignore patterns
• verbose defaults to false to reduce log output
• Backend configuration supports output_keys field to declare expected output fields

For projects using custom top-level keys in packflow.yaml, nest them under extra: to maintain compatibility with current validation.

0.3.0

• Initial release

Contributing

Contributions to Packflow are welcomed and highly encouraged! Please refer to the CONTRIBUTING.md guide for more information and guidelines for contributing to Packflow.

Authors

Packflow is developed and maintained by Booz Allen Hamilton on behalf of the Federal Government of the United States of America and the Department of War's Chief Digital and Artificial Intelligence Office (CDAO).

License

packflow is distributed under the terms of the MIT license. Please refer to the LICENSE for more information of acceptable usage and distribution of Packflow.