SigOpt Python API

This is the SigOpt Python API client. Use this to natively call SigOpt API endpoints to create experiments and report data.

For the complete API documentation, visit https://sigopt.com/docs.

Take a look in examples for example usage.

Getting Started

Install the sigopt python modules with pip install sigopt.

Sign up for an account at https://sigopt.com. In order to use the API, you'll need your API token from your user profile.

To call the API, instantiate a connection with your token.

Authentication Option 1 (preferred)

Insert your API token into the environment variable SIGOPT_API_TOKEN, and instantiate a connection:

from sigopt import Connection
conn = Connection()

Authentication Option 2

Authenticate each connection with your API token directly (will override any token set via environment variable):

from sigopt import Connection
conn = Connection(client_token=api_token)

Issuing Requests

Then, you can use the connection to issue API requests. An example creating an experiment and running the optimization loop:

experiment = conn.experiments().create(
  name='New Experiment',
  parameters=[{ 'name': 'param1', 'type': 'double', 'bounds': { 'min': 0, 'max': 1.0 }}],
)

suggestion = conn.experiments(experiment.id).suggestions().create()
value = evaluate_metric(suggestion) # Implement this, the return  value should be a number
conn.experiments(experiment.id).observations().create(
  'suggestion': suggestion.id,
  'value': value,
)

Authentication

Your API token does not have permission to view or modify information about individual user accounts, so it is safe to include when running SigOpt in production.

Endpoints

Endpoints are grouped by objects on the Connection. For example, endpoints that interact with experiments are under conn.experiments. ENDPOINT_GROUP(ID) operates on a single object, while ENDPOINT_GROUP() will operate on multiple objects.

POST, GET, PUT and DELETE translate to the method calls create, fetch, update and delete. To retrieve an experiment, call conn.experiments(ID).fetch(). To create an experiment call conn.experiments(ID).create(). Parameters are passed to the API as named arguments.

Just like in the resource urls, suggestions and observations are under experiments. Access these objects with conn.experiments(ID).suggestions and conn.experiments(ID).observations. The REST endpoint POST /v1/experiments/1/suggestions then translates to conn.experiments(ID).suggestions().create().

Testing

To run the included tests, you'll need to install pytest and mock (with pip install pytest mock). Then, just run

PYTHONPATH=. python -m pytest -rw -v test