Skip to main content

Acumos model runner for Python models

Project description

Acumos Python Model Runner User Guide

Build Status

The acumos_model_runner package installs a command line tool acumos_model_runner for running models created by the Acumos Python client library.

The model runner provides an HTTP API for invoking model methods, as well as a Swagger UI for documentation. See the tutorial for more information on usage.


You will need a Python 3.4+ environment in order to install acumos_model_runner. You can use Anaconda (preferred) or pyenv to install and manage Python environments.

The acumos_model_runner package can be installed with pip:

$ pip install acumos_model_runner

Command Line Usage

usage: acumos_model_runner [-h] [--host HOST] [--port PORT]
                           [--workers WORKERS] [--timeout TIMEOUT]
                           [--cors CORS]

positional arguments:
  model_dir          Directory containing a dumped Acumos Python model

optional arguments:
  -h, --help         show this help message and exit
  --host HOST        The interface to bind to
  --port PORT        The port to bind to
  --workers WORKERS  The number of gunicorn workers to spawn
  --timeout TIMEOUT  Time to wait (seconds) before a frozen worker is
  --cors CORS        Enables CORS if provided. Can be a domain, comma-
                     separated list of domains, or *

Acumos Python Model Runner Tutorial

This tutorial demonstrates how to use the Acumos Python model runner with an example model.

Creating A Model

An Acumos model must first be defined using the Acumos Python client library. For illustrative purposes, a simple model with deterministic methods is defined below.

from collections import Counter

from acumos.session import AcumosSession
from acumos.modeling import Model, List, Dict

def add(x: int, y: int) -> int:
    '''Adds two numbers'''
    return x + y

def count(strings: List[str]) -> Dict[str, int]:
    '''Counts the occurrences of words in `strings`'''
    return Counter(strings)

model = Model(add=add, count=count)

session = AcumosSession()
session.dump(model, 'example-model', '.')

Executing results in the following directory:

└── example-model

Running A Model

Now the acumos_model_runner command line tool can be used to run the saved model.

$ acumos_model_runner example-model/
[2018-08-08 12:16:57 -0400] [61113] [INFO] Starting gunicorn 19.9.0
[2018-08-08 12:16:57 -0400] [61113] [INFO] Listening at: (61113)
[2018-08-08 12:16:57 -0400] [61113] [INFO] Using worker: sync
[2018-08-08 12:16:57 -0400] [61151] [INFO] Booting worker with pid: 61151

Using A Model

The model HTTP API can be explored via its generated Swagger UI. The Swagger UI of example-model above can be accessed by navigating to http://localhost:3330 in your web browser.

Below are some screenshots of the Swagger UI for example-model.

Model APIs

The Swagger UI enumerates model method APIs, as well as APIs for accessing model artifacts. Below, the APIs corresponding to the add and count methods are listed under the methods tag.

Model APIs

Count Method API

Expanding the documentation for the count method reveals more information on how to invoke the API.

Model Method

Count Method Request

The Swagger UI provides an input form that can be used to try out the count API with sample data.

Model Method Request

Count Method Response

The response from the count API shows that everything is working as expected!

Model Method Response

Acumos Python Model Runner Release Notes

v0.2.25, 04 June 2020

  • Fix backward compatibility issue with old models ACUMOS-4164

v0.2.24, 15 May 2020

  • Fix OpenAPI spec generation for empty inputs ACUMOS-4010
  • Allow the model runner to use raw data types ACUMOS-3956
  • Receive the licence profile from the running micro-service ACUMOS-3161

v0.2.3, 23 January 2020

  • larkparser lark-parser<0.8.0 pinning to prevent error
  • Fixing issue with using 0.6.0 model metadata schema - works with model metadata versions <0.6.0 and 0.6.0
  • python removing 3.4 support


  • Fixed 404 bug for model artifact resources caused by relative model directory
  • Fixed incorrect media type for protobuf resource


  • Upgraded Swagger UI from v2 to v3


  • Overhaul of model runner API
  • Added support for application/json via Content-Type and Accept headers
  • Added automatic generation of OpenAPI Specification and Swagger UI
  • Added support for CORS


Acumos Python Model Runner Developer Guide


We use a combination of tox, pytest, and flake8 to test acumos_model_runner. Code which is not PEP8 compliant (aside from E501) will be considered a failing test. You can use tools like autopep8 to “clean” your code as follows:

$ pip install autopep8
$ cd python-model-runner
$ autopep8 -r --in-place --ignore E501 acumos_model_runner/ testing/ examples/

Run tox directly:

$ cd python-model-runner
$ tox

You can also specify certain tox environments to test:

$ tox -e py34  # only test against Python 3.4
$ tox -e flake8  # only lint code

And finally, you can run pytest directly in your environment (recommended starting place):

$ pytest
$ pytest -s   # verbose output

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for acumos-model-runner, version 0.2.6
Filename, size File type Python version Upload date Hashes
Filename, size acumos_model_runner-0.2.6-py2.py3-none-any.whl (19.1 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size acumos_model_runner-0.2.6.tar.gz (15.7 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page