dd_scenario.Client¶

class dd_scenario.Client(api_url=None, authorization=None, project_id=None, max_retries=3, proxies=None, cognitive_url=None)¶

Bases: object

The class to access containers in Decision Optimization.

To use the client:

from dd_scenario import Client
client = Client()

or if you want to access another project:

from dd_scenario import Client
client = Client(project_id="project id string",
                authorization="bearer authorization token",
                api_url='https://localhost/dd-scenario-api/v2')

Then use methods to work with scenario assets, tables and data:

Methods to work with model builders
Methods to work with containers
Methods to work with assets
Methods to work with tables
Solve api:
Notebook import/export:
- import_notebook()
- export_notebook()

Examples

To return the list of containers:

from dd_scenario import Client

client = Client()
# get list of available containers
containers = client.get_containers()

In the following example, the client session is closed when it’s no longer needed:

with Client() as client:
    for container in client.get_containers():
        # delete all container containing 'foo'
        if 'foo' in container['description']:
            client.delete(container)

__init__(api_url=None, authorization=None, project_id=None, max_retries=3, proxies=None, cognitive_url=None)¶

Creates a new Decision Optimization scenario client.

Parameters:	authorization – The authorization key. api_url (`str`, optional) – The scenario API url entry point. If not specified, the client will use default value: http://dd-scenario-api-svc:8450/dd-scenario-api/v2 max_retries (`int`, optional) – maximum number of retries. Default is 3. proxies (`dict`, optional) – Optional dictionary mapping protocol to the URL of the proxy.

add_asset_data(container, name, data=None)¶

Adds or updates asset data.

This is a direct mapping to REST API:

PUT /dd-scenario-api/v2/containers/{containerName}/tables/{tableName}

Parameters:	container – A `Container` or a container name as string. This `container` is used to indicate which container is to be updated. name – An asset name. data – A stream containing the data to upload.
Returns:	the asset metadata as `Asset`

add_table(container, name, new_data=None, category=None)¶

Adds table metadata.

This can add metadata by table id or table name.

Parameters:	container – A `Container` or a container name as string. This `container` is used to indicate which container is to be updated. name – A table name. new_data (`Table`) – A `Table` containing metadata to update.

add_table_data(container, name, category=None, data=None)¶

Adds table metadata.

This is a direct mapping to REST API:

PUT /dd-scenario-api/v2/containers/{container_name}/tables/{tableName}

Example

The following code uploads a pandas.DataFrame into a container:

with Client() as client:
    client.add_table_data(container_id, table_name, df,
                          category='input')

Parameters:	container – A `Container` or a container name as string. This `container` is used to indicate which container is to be updated. name – the name of the table. category (optional) – The category of the table (‘input’ or ‘output’) data (`pandas.DataFrame` or bytes) – The data to upload. If the data is a pandas.DataFrame, it is converted to csv first.

copy_container(container, metadata=None)¶

Copies a container.

This is a direct mapping to REST API:

POST /dd-scenario-api/v2/containers/{container_name}/copy

Parameters:	container – A `Container` or a container name as string. This is the source container. metadata (`Container`, optional) – new metadata to override, as a `Container`.
Returns:	The created container

create_asset(container, asset_meta=None)¶: Creates a new asset with given meta data.

create_container(parent_id, container)¶

Creates a container.

This is a direct mapping to REST API:

PUT /dd-scenario-api/v2/containers/

Parameters:	container (`Container`) – The container metadata
Returns:	The container.

create_model_builder(model_builder=None, **kwargs)¶

Creates a decision model_builder.

This is a direct mapping to REST API:

PUT /v2/decisions/

If this method is given an model_builder argument, that model_builder is used to initialize the values for the new model_builder. Otherwise, the **kwargs are used to initialize a ModelBuilder.

Example

Creates a model builder using the model builder name passed as kwargs:

model_builder = client.create_model_builder(name='test model_builder')

Creates a model builder using the model_builder passed as a ModelBuilder:

meta = ModelBuilder(name=’test model_builder’) model_builder = client.create_model_builder(model_builder=meta)

Parameters:	model_builder (`ModelBuilder`) – The model builder metadata used as initial data. **kwargs – kwargs used to initialize the ModelBuilder
Returns:	The decision model builder as a `ModelBuilder`

create_table(container, table_meta=None)¶: Creates a new table with given meta data.

delete_asset(container, name)¶

Deletes the asset.

This can delete the asset by id if asset is specified or by name if name is specified.

Parameters:	container – A `Container` or a container name as string name – An asset name.

delete_container(container)¶

Deletes the container.

This is a direct mapping to REST API:

DELETE /dd-scenario-api/v2/containers/{container_name}

Parameters:	container – A `Container` or a container name as string

delete_model_builder(model_builder)¶

Deletes the decision model.

This is a direct mapping to REST API:

DELETE /v2/decisions/{model_builder_name}

Parameters:	model_builder – A `ModelBuilder` or a name as string

delete_table(container, name)¶

Deletes the table.

Parameters:	container – A `Container` or a container name as string name – A table name.

delete_table_data(container, name)¶

Deletes table data.

This is a direct mapping to REST API:

DELETE /dd-scenario-api/v2/containers/{container_name}/tables/{tableName}/data

Parameters:	container – A `Container` or a container name as string name – the name of the table.

export_notebook(container, name, description=None)¶

Creates a notebook from a container’s model.

Parameters:

container – The container or container_id
name – the name of the notebook
descrition (Optional) – The notebook description

Returns:

A dict with the notebook creation info:

{
   'projectNotebookId': 'aeiou',
   'notebookId': 'aeiou',
   'notebookUrl': 'aeiou'
}

get_asset(container, name)¶

Gets asset metadata.

This can get the asset by id or by name.

Parameters:	container – A `Container` or a container name as string. name – An asset name
Returns:	A `Asset` instance.

get_asset_data(container, name)¶

Gets asset data.

This is a direct mapping to REST API:

GET /dd-scenario-api/v2/containers/{container_name}/assets/{assetName}/data

Parameters:	container – A `Container` or a container name as string. name – An asset name.
Returns:	The asset data as a byte array.

get_assets(container, name=None)¶

Returns assets for a container.

This is a direct mapping to REST API:

GET /dd-scenario-api/v2/containers/{container_name}/assets

Parameters:	container – A `Container` or a container name as string.
Returns:	A dict where keys are asset name and values are `Asset`.

get_container(parent_id, id)¶

Returns the container metadata.

This is a direct mapping to REST API:

GET /dd-scenario-api/v2/containers/{container_name}

Parameters:	id – A `Container` or a container name as string
Returns:	a list of `Container`

get_containers(parent_id, category=None)¶

Returns the list of containers.

Container type include:

scenario

inputset

model

This is a direct mapping to REST API:

GET /dd-scenario-api/v2/containers/

Parameters:	parent_id – The parent_id category – The container category.
Returns:	a list of `Container`

get_model_builder(name=None, id=None)¶

Returns the decision model builder metadata.

This is a direct mapping to REST API:

GET /v2/decisions/{model_builder_name}

where {model_builder_name} is the model builder name.

Parameters:	id (optional) – name of the decision model to look for. name (optional) – The name of the model builder to look for
Returns:	a list of `ModelBuilder`

get_model_builders(name=None)¶

Returns the list of decision model builders.

This is a direct mapping to REST API:

GET /v2/decisions/

Parameters:	name – An optional parameter. If given, only the model builders for which names match `name` are returned.
Returns:	a list of `ModelBuilder`

get_solve_status(container)¶

Queries and returns the solve status for the specified container.

Returns:	A `SolveStatus`

get_table(container, name)¶

Gets table metadata.

This is a direct mapping to REST API:

GET /dd-scenario-api/v2/containers/{containerName}/tables/{tableName}

Parameters:	container – A `Container` or a container name as string. name – A table name.
Returns:	A `Table` instance.

get_table_data(container, name, raw=False)¶

Gets table data.

Examples

Returns the specified table data as a dataframe:

with Client(project_context) as client:
    df = client.get_table_data(container, name)

Parameters:	container – A `Container` or a container name as string. name – the name of the table. raw – If set, data is returned as is from the server, without conversion into a pandas.DataFrame
Returns:	A `pandas.DataFrame` containing the data or the raw data.

get_table_type(container, name)¶

Gets table type.

Parameters:	container – A `Container` or a container name as string. name – the name of the table
Returns:	A `TableType` instance.

get_tables(container, category=None, name=None)¶

Returns all container table metadata.

This is a direct mapping to REST API:

GET /dd-scenario-api/v2/containers/{container_name}/tables

Parameters:	container – A `Container` or a container name as string. name – A name to filter tables with. category – The category of tables. Can be ‘input’, ‘output’ or None if both input and output tables are to be returned.
Returns:	A dict where keys are table name and values are `Table`.

get_tables_type(container)¶

Returns a dictionary of table types for each table.

This is a direct mapping to REST API:

GET /dd-scenario-api/v2/containers/{container_name}/tables/types

Parameters:	container – A `Container` or a container name as string.
Returns:	A dict which keys are table names and values are `TableType`’s.

import_notebook(container, notebook_id)¶

Updates container model from notebook.

Parameters:	container – The container or container_id name – the name of the notebook descrition (Optional) – The notebook description

solve(container, **kwargs)¶

Solves the scenario model of the container which id is specified.

This method returns as soon as the request is sent. Use Client.wait_for_completion() to wait for solve completion.

Parameters:	container – The Container or container id to solve() **kwargs – extra arguments passed to the solve using a SolveConfig

stop_solve(container)¶: Stops the solve for a scenario.

update_asset(container, name, new_data=None)¶

Updates asset metadata.

Parameters:	container – A `Container` or a container name as string. This `container` is used to indicate which container is to be updated. name – An asset name. new_data (`Asset`) – A `Asset` containing metadata to update.

update_container(container, new_data)¶

Updates container metadata.

This is a direct mapping to REST API:

PUT /dd-scenario-api/v2/containers/{container_name}

Examples

Updates a container with new data using the container name:

>>> new = Container()
>>> new.description = "new description"
>>> client.update_container(container_name}, new)

Get a container’s metadata, then replace description:

>>> container = client.get_container(container_name)
>>> container.description = "new description"
>>> client.update_container(container)

Parameters:	container – A `Container`. This `container` is used to indicate which container is to be updated. If `new_data` is None, the container is updated with the data from this `container`. new_data (`Container`, optional) – A `Container` containing metadata to update.

update_model_builder(model_builder, new_data=None)¶

Updates decision model metadata.

This is a direct mapping to REST API:

PUT /v2/decisions/{model_builder_name}

where {model_builder_name} is the model builder name.

Examples

Updates a model builder with new data using name:

>>> new = ModelBuilder()
>>> new.description = "new description"
>>> client.update_model_builder(decision_model_name, new)

Gets a model builder, then replaces description:

>>> model_builder = client.get_model_builder(id=guid)
>>> model_builder.description = "new description"
>>> client.update_model_builder(model_builder)

Gets a model builder by name, then replaces description:

>>> model_builder = client.get_model_builder(name='decision model name')
>>> model_builder.description = "new description"
>>> client.update_model_builder(model_builder)

Parameters:	model_builder – A `ModelBuilder` or a name as string. This `model_builder` is used to indicate which model builder is to be updated. If `new_data` is None, the model builder is updated with the data from this `model_builder`. new_data (`ModelBuilder`, optional) – A `ModelBuilder` containing metadata to update.

update_table_type(container, name, new_value=None)¶

Updates table type.

This is a direct mapping to REST API:

PUT /dd-scenario-api/v2/containers/{container_name}/tables/{tableName}/type

Parameters:	container – A `Container` or a container name as string. This `container` is used to indicate which container is to be updated. name – the name of the table. new_value (`TableType`) – A `TableType` containing metadata to update.

wait_for_completion(container)¶

Waits for the solve operation specified container to complete.

Returns:	The last `SolveStatus`