Home: Cortex Fabric Documentation

Cortex Python Reference

This reference guide describes the base API client library to integrate with Cortex Fabric. Refer to the Cortex Fabric documentation for more info about how to use the library.

Cortex Client

class cortex.client.Client(url: str, token: Optional[_Token] = None, config: Optional[dict] = None, project: Optional[str] = None, version: int = 4, verify_ssl_cert: bool = False)

API client used to access Connections, Managed Content, Experiments, Secrets, Models, Sessions, Skills and Types in a Fabric cluster. Experiments also have a local client (cortex.experiment.local.LocalExperiment) for data scientists to work without access to a Fabric cluster.

Create an instance of the Cortex Fabric client. There are a few different ways in which you can instantiate a Client

If the user has the Cortex CLI installed and configured to a Fabric environment, AND a default project is set, they can do the following:

>>> from cortex import Cortex; client = Cortex.client()

If the user has the Cortex CLI installed and configured, but a default project is not set:

>>> from cortex import Cortex; client = Cortex.client(project="some-project")

If the user does not have the Cortex CLI installed, or is using the cortex-python package from within a Skill (Daemon) running inside a Fabric cluster, they can simply extract the required parameters from the request object and create a Cortex client like below:

from cortex import Cortex

@app.post('/invoke')
def start(req: dict):
    payload = req['payload']
    client = Cortex.client(api_endpoint=req["apiEndpoint"], project=req["projectId"], token=req["token"])
    client.experiments.list_experiments()
    ....

If the user does not have the Cortex CLI installed, or is using the cortex-python package from within a Skill(Job) running inside a Fabric cluster, they can simply pass the params object passed into the Job script and create a Cortex client:

# contents of main.py for a Skill (job)
from cortex import Cortex

def main(params):
    client = Cortex.from_message(params)

if __name__ == "__main__":
    if len(sys.argv)<2:
        print("Message/payload argument is required")
        exit(1)
    # The last argument in sys.argv is the payload from cortex
    main(json.loads(sys.argv[-1]))

Parameters

url – Cortex fabric url
token – (optional) Use JWT token to authenticate requests, will default to settings in ~/.cortex/config if not provided to generate JWT tokens
project – (optional) Project name, must specify project for each request
version – (optional) Fabric API version (default: 4)

property connections: ConnectionClient

Returns a pre-initialised ConnectionClient whose project has been set to the project configured for the Cortex.client.

If you want to access connections for a project that is different from the one configured with Cortex.client, please use cortex.client.Client.connections_client() instead

## use default .connections client helper
from cortex import Cortex
client = Cortex.client()
client.connections.save_connection
client.connections.get_connection

Refer to the documentation of cortex.connection.ConnectionClient to learn more about the methods available on the ConnectionClient

Returns: An instance of this helper class that enables access to the Fabric Connections API.
Return type: cortex.connection.ConnectionClient

connections_client(project: Optional[str] = None) → ConnectionClient

Helper method to create a new cortex.connection.ConnectionClient instance that is configured to talk to another project than the default cortex.client.Client._project

>>> connc = client.connections_client(project="another-project")

Parameters: project (str, optional) – Project for which a connections client is to be created, defaults to (the project configured with cortex.client.Client)
Returns: A connection client
Return type: cortex.connection.ConnectionClient

property content: ManagedContentClient

Returns a pre-initialised ManagedContentClient whose project has been set to the project configured for the Cortex.client.

If you want to access managed content for a project that is different from the one configured with Cortex.client, please use cortex.client.Client.content_client() instead

## use default .content client helper
from cortex import Cortex
client = Cortex.client()
client.content.list
client.content.upload
client.content.exists
.....

Refer to the documentation of cortex.content.ManagedContentClient to learn more about the methods available on the ManagedContentClient

Returns: An instance of this helper class that enables access to the Fabric Managed Content API.
Return type: cortex.content.ManagedContentClient

content_client(project: Optional[str] = None) → ManagedContentClient

Helper method to create a new cortex.connection.ManagedContentClient instance that is configured to talk to another project than the default cortex.client.Client._project

>>> contentc = client.content_client(project="another-project")

Parameters: project (str, optional) – Project for which a managed content client is to be created, defaults to (the project configured with cortex.client.Client)
Returns: A managed content client
Return type: cortex.connection.ManagedContentClient

property experiments: ExperimentClient

Returns a pre-initialised ExperimentClient whose project has been set to the project configured for the Cortex.client.

If you want to access experiments for a project that is different from the one configured with Cortex.client, please use cortex.client.Client.experiments_client() instead

## use default .experiments client helper
from cortex import Cortex
client = Cortex.client()
client.experiments.list_experiments()
client.experiments.save_experiment()
client.experiments.list_runs()
client.experiments.delete_runs()

Refer to the documentation of cortex.experiment.ExperimentClient to learn more about the methods available on the ExperimentClient

Returns: An instance of this helper class that enables access to the Fabric Experiments API.
Return type: cortex.experiment.ExperimentClient

experiments_client(project: Optional[str] = None) → ExperimentClient

Helper method to create a new cortex.experiment.ExperimentClient instance that is configured to talk to another project than the default cortex.client.Client._project

>>> expc = client.experiments_client(project="another-project")

Parameters: project (str, optional) – Project for which an experiments client is to be created, defaults to (the project configured with cortex.client.Client)
Returns: An experiment client
Return type: cortex.experiment.ExperimentClient

message(payload: dict, properties: Optional[dict] = None) → Message: Constructs a Message from payload and properties if given. This is useful for testing skills, as this the message passed when skills are invoked :param payload: The payload to include in the Message. :param properties: The properties to include in the Message. :return: A Message object.

property models: ModelClient

Returns a pre-initialised ModelClient whose project has been set to the project configured for the Cortex.client.

If you want to access models for a project that is different from the one configured with Cortex.client, please use cortex.client.Client.models_client() instead

## use default .models client helper
from cortex import Cortex
client = Cortex.client()
client.models.list_models()
client.models.get_model()
client.models.save_model()
.....

Refer to the documentation of cortex.model.ModelClient to learn more about the methods available on the ModelClient

Returns: An instance of this helper class that enables access to the Fabric Models API.
Return type: cortex.model.ModelClient

models_client(project: Optional[str] = None) → ModelClient

Helper method to create a new cortex.model.ModelClient instance that is configured to talk to another project than the default cortex.client.Client._project

>>> modelc = client.models_client(project="another-project")

Parameters: project (str, optional) – Project for which a models client is to be created, defaults to (the project configured with cortex.client.Client)
Returns: A models client
Return type: cortex.model.ModelClient

property secrets: SecretsClient

Returns a pre-initialised SecretsClient whose project has been set to the project configured for the Cortex.client.

Important

Note that, as of Fabric 6.3.3 and Fabric 6.4.0., you can only call cortex.secrets.SecretsClient.get_secret() from within a skill running inside the Fabric cluster (won’t work locally)

If you want to access secrets for a project that is different from the one configured with Cortex.client, please use cortex.client.Client.secrets_client() instead

## use default .secrets client helper
from cortex import Cortex
client = Cortex.client()
client.models.get_secret()
client.models.post_secret()
.....

Refer to the documentation of cortex.secrets.SecretsClient to learn more about the methods available on the SecretsClient

Returns: An instance of this helper class that enables access to the Fabric Secrets API.
Return type: cortex.secrets.SecretsClient

secrets_client(project: Optional[str] = None) → SecretsClient

Helper method to create a new cortex.secrets.SecretsClient instance that is configured to talk to another project than the default cortex.client.Client._project

>>> secretsc = client.secrets_client(project="another-project")

Parameters: project (str, optional) – Project for which a secrets client is to be created, defaults to (the project configured with cortex.client.Client)
Returns: A secrets client
Return type: cortex.secrets.SecretsClient

property sessions: SessionClient

Returns a pre-initialised SessionClient whose project has been set to the project configured for the Cortex.client.Client

If you want to access Sessions for a project that is different from the one configured with Cortex.client, please use cortex.client.Client.sessions_client() instead

## use default .sessions client helper
from cortex import Cortex
client = Cortex.client()
client.sessions.start_session()
client.sessions.get_session_data()
client.sessions.put_session_data()
client.sessions.delete_session()
.....

Refer to the documentation of cortex.session.SessionClient to learn more about the methods available on the SessionClient

Returns: An instance of this helper class that enables access to the Fabric Sessions API.
Return type: cortex.session.SessionClient

sessions_client(project: Optional[str] = None) → SessionClient

Helper method to create a new cortex.session.SessionClient instance that is configured to talk to another project than the default cortex.client.Client._project

>>> sessionsc = client.sessions_client(project="another-project")

Parameters: project (str, optional) – Project for which a Sessions client is to be created, defaults to (the project configured with cortex.client.Client)
Returns: A Sessions client
Return type: cortex.session.SessionClient

property skills: SkillClient

Returns a pre-initialised SkillClient whose project has been set to the project configured for the Cortex.client.Client

If you want to access Skills for a project that is different from the one configured with Cortex.client, please use cortex.client.Client.skills_client() instead

## use default .skills client helper
from cortex import Cortex
client = Cortex.client()
client.skills.get_skill()
client.skills.save_skill()
client.skills.delete_skill()
client.skills.get_logs()
client.skills.deploy()
client.skills.undeploy()
.....

Refer to the documentation of cortex.skill.SkillClient to learn more about the methods available on the SkillClient

Returns: An instance of this helper class that enables access to the Fabric SKills API.
Return type: cortex.skill.SkillClient

skills_client(project: Optional[str] = None) → SkillClient

Helper method to create a new cortex.skill.SkillClient instance that is configured to talk to another project than the default cortex.client.Client._project

>>> skillsc = client.skills_client(project="another-project")

Parameters: project (str, optional) – Project for which a Skill client is to be created, defaults to (the project configured with cortex.client.Client)
Returns: A Skills client
Return type: cortex.skill.SkillClient

property types: TypeClient

Returns a pre-initialised TypeClient whose project has been set to the project configured for the Cortex.client.Client

If you want to access Types for a project that is different from the one configured with Cortex.client, please use cortex.client.Client.types_client() instead

## use default .types client helper
from cortex import Cortex
client = Cortex.client()
client.types.get_type()
client.types.save_type()
.....

Refer to the documentation of cortex.types.TypeClient to learn more about the methods available on the TypeClient

Returns: An instance of this helper class that enables access to the Fabric Types API.
Return type: cortex.types.TypeClient

types_client(project: Optional[str] = None) → TypeClient

Helper method to create a new cortex.types.TypeClient instance that is configured to talk to another project than the default cortex.client.Client._project

>>> typesc = client.types_client(project="another-project")

Parameters: project (str, optional) – Project for which a Types client is to be created, defaults to (the project configured with cortex.client.Client)
Returns: A Types client
Return type: cortex.types.TypeClient

Cortex

class cortex.client.Cortex

Entry point to the Cortex API.

static client(api_endpoint: Optional[str] = None, api_version: int = 4, verify_ssl_cert=None, token: Optional[str] = None, config: Optional[dict] = None, project: Optional[str] = None, profile: Optional[str] = None) → Client

Gets a client with the provided parameters. All parameters are optional and default to environment variable values if not specified. Client creation can fail if you don’t have a default project set in your environment variables or the Cortex config file.

Important

You can also set a default project when configuring your Cortex CLI using cortex configure –project <your-project>.

This value will be updated into the $HOME/.cortex/config file. If your Cortex config file $HOME/.cortex/config does not contain a default project set for the profile being used as the default one, you will need to set the project key when instantiating a cortex.client.Client.

Example

>>> from cortex import Cortex
>>> cortex = Cortex.client(project='example-project')

Parameters

api_endpoint – The Cortex URL.
api_version – The version of the API to use with this client.
verify_ssl_cert – A boolean to enable/disable SSL validation, or path to a CA_BUNDLE file or directory with certificates of trusted CAs (default: True)
project – Cortex Project that you want to use.
token – (optional) Use JWT token for authenticating requests, will default to settings in ~/.cortex/config if not provided
config – (optional) Use Cortex personal access token config file to generate JWT tokens.

Returns

An instance of cortex.client.Client

Return type

cortex.client.Client

static from_message(msg, verify_ssl_cert=None) → Client

Creates a Cortex client from a skill’s input message, expects

{ api_endpoint:"..", token:"..", projectId:".."}

Parameters

msg – A message for constructing a Cortex Client.
verify_ssl_cert – A boolean to enable/disable SSL validation, or path to a CA_BUNDLE file or directory with certificates of trusted CAs (default: True)

Returns

A Cortex Client

Return type

cortex.client.Client

static local(basedir=None)

Create a Local Cortex implementation (mock)

Parameters: basedir (str, optional) – Root filesystem location, defaults to None
Returns: an instance of cortex.client.Local
Return type: cortex.client.Local

static login()

Login to Cortex6. The function prompts the caller for Cortex Personal Access Config.

Example

>>> Cortex.login()
Cortex Personal Access Config: Cortex Personal Access Config
Cortex Project: The project that you to start using you Cortex assets from. (Not required)

CortexEnv

class cortex.env.CortexEnv(api_endpoint: Optional[str] = None, token: Optional[str] = None, config: Optional[dict] = None, project: Optional[str] = None, profile: Optional[str] = None)

Sets environment variables for Cortex.

static get_cortex_profile(profile: Optional[str] = None): gets the configured cortex profile from the local machine

static get_cortex_token() → str: gets the cortex token from the local machine

static get_token(): gets the token from either the cortex_token env variable or the profile’s token. if cortex_token and both cortex_profile are falsey, then cortexToken will be None

Cortex Local Experiments

class cortex.experiment.local.LocalExperiment(name, basedir=None)

Runs experiment locally, not using Cortex services.

clean_dir(dir_to_clean: str) → None

Removes only the files from the given directory

Parameters: dir_to_clean (str) – Directory to remove files from
Return type: None

display(): Provides html output of the experiment. Useful in Jupyter notebooks

find_runs(filter_obj, sort, limit: int) → List[Run]

find_runs is not supported in local mode

Raises: NotImplementedError – _description_
Return type: List[Run]

get_artifact_path(run: Run, name: str, extension: str = 'pk') → str

Returns the fully qualified path to a particular artifact.

Parameters

run (Run) – The run that generated the artifact requested.
name (str) – The name of the artifact.
extension (str, optional) – An optional extension, defaults to “pk”

Returns

A local filesystem path to the artifact

Return type

str

get_run(run_id: str) → Run

Gets a particular run from the runs in this experiment.

Parameters: run_id (str) – Identifier of the run to be fetched
Return type: cortex.experiment.model.Run

last_run() → Run

Returns the most recent run of this experiment

Returns: _description_
Return type: Run

load_artifact(run: Run, name: str, extension: str = 'pk') → any

Returns a particular artifact created by the given run of the experiment.

Parameters

run (Run) – The run that generated the artifact requested.
name (str) – The name of the artifact.
extension (str, optional) – An optional extension, defaults to “pk”

Returns

Python objects loaded into memory from the artifact content

Return type

Any

property name: str

Name of the experiment.

Returns: Name of the experiment.
Return type: str

reset(): Resets the experiment, removing all associated configuration and runs.

runs() → List[Run]: Returns the runs associated with the experiment. :rtype: List[Run]

save_run(run: Run) → None

Saves a run.

Parameters: run (cortex.experiment.model.Run) – The run you want to save.
Return type: None

set_meta(prop: str, value: any) → None

Associates metadata properties with the experiment.

Parameters

prop (str) – The name of the metadata property to associate with the experiment.
value (any) – The value of the metadata property to associate with the experiment. Needs to be serializable to JSON

start_run() → Run: Creates a run for the experiment. :rtype: cortex.experiment.model.Run

Cortex Experiment

class cortex.experiment.Experiment(document: Dict, client: ExperimentClient)

Tracks runs, associated parameters, metrics, and artifacts of experiments.

display(): _summary_

find_runs(filter_obj: Optional[dict] = None, sort: Optional[dict] = None, limit: Optional[int] = None) → List[Run]

Alias to cortex.experiment.ExperimentClient.find_runs()

Parameters

filter_obj (Dict) – A mongo style query object. For example. {“runId”: “run_01”}. Allowed fields which can be set as keys in this dictionary include [runId, _createdAt, startTime, endTime, took, experimentName]
sort (Dict, optional) – A mongo style sort object, defaults to None on the client. Server side default is {“_updatedAt”: -1}
limit (int, optional) – Limit the number of results to this number, defaults to 25

Returns

A list of cortex.experiment.Run instances that match the provided filter, sort and limit criteria

Return type

List[Run]

get_run(run_id: str) → Run

Alias to cortex.experiment.ExperimentClient.get_run()

Parameters: run_id (str) – The identifier for the run.
Returns: An instance of cortex.experiment.Run
Return type: Run

last_run() → Run

Returns the most recent Run available on this Experiment. Recency is computed using the endTime attribute of a Run

Raises: cortex.exceptions.APIException
Returns: _description_
Return type: Run

load_artifact(run: Run, name: str) → any

Downloads the given artifact with name name for the Run run using cortex.experiment.ExperimentClient.get_artifact() loads it using dill.loads()

Parameters

run (Run) – The run for which artifact is to be loaded from
name (str) – Name/key of the artifact belonging to this run

Returns

Unpickled object loaded into memory by dill

Return type

any

reset(filter_obj: Optional[dict] = None) → None

Deletes all runs associated with this Experiment with filter conditions applied via the optional filter_obj param.

Parameters: filter_obj (Dict) – A mongo style query object. For example. {“runId”: “run_01”}. Allowed fields which can be set as keys in this dictionary include [runId, _createdAt, startTime, endTime, took, experimentName], is optional

runs() → List[Run]

Alias to cortex.experiment.ExperimentClient.list_runs()

Returns: A list of RemoteRun instances that belong this experiment
Return type: List[Run]

save_run(run: Run) → None

Alias to cortex.experiment.ExperimentClient.update_run

Parameters: run (Run) – An instance of cortex.experiment.Run

set_meta(prop: str, value: any)

Sets a meta property along with value on an experiment

Parameters

prop (str) – The key of the meta attribute
value (any) – The value of the meta attribute. Needs to be serialisable to json

start_run() → Run

Starts a run for the experiment

Returns: A cortex.experiment.Run instance
Return type: Run

to_camel(camel: str = '1.0.0') → Dict

Converts the instance of this class to a valid CAMEL specification

Parameters: camel (str, optional) – Version of the CAMEL specification to use, defaults to “1.0.0”
Returns: A python dictionary containing the valid CAMEL specification of this cortex.experiment.Experiment instance
Return type: Dict

Cortex Experiment Run

class cortex.experiment.Run(experiment)

Captures the elapsed time of a run of an experiment and saves the metrics and parameters for the run.

property artifacts

The artifacts stored in this run.

Returns: The artifact object.

property end_time: The end time for the run.

static from_json(json: dict, experiment)

Creates a run from a json representation.

Parameters

json (dict) – The json representation of the run.
experiment (cortex.experiment.Experiment) – The experiment to associate with the run.

Returns

A run that has the values in the given json object with the given experiment.

Return type

cortex.experiment.model.Run

get_artifact(name)

Gets an artifact object by name.

Parameters: name – The key of the artifact.
Returns: The artifact object.

get_meta(meta): Gets metadata for the run.

get_metric(metric)

Gets a particular metric for the run.

Parameters: metric – metric to get

get_param(param)

Gets a particular parameter of the run.

Parameters: param – Parameter to get.

property id: The id for the run.

log_artifact(name: str, artifact): Logs a given artifact.

log_artifact_ref(name: str, ref): Logs a given artifact reference.

log_metric(name: str, metric): Logs a given metric.

log_param(name: str, param): Logs for a given parameter.

log_params(params): Logs a group of parameters.

property meta: Metadata for the run.

property metrics: The metrics for the run.

property params: Params of the run.

set_meta(name: str, val): Sets metadata for the run.

start(): Starts the timer.

property start_time: The start time for the run.

stop(): Stops the time and captures data about the run.

to_json(): A json representation of the run.

property took: The interval between the start and end of the run.

Cortex Experiment RemoteRun

class cortex.experiment.RemoteRun(experiment, client: ExperimentClient)

A run that is executed remotely, through a client.

static create(experiment: Experiment, experiment_client: ExperimentClient) → Run: Creates a remote run. :param experiment: The experiment to associate with this run. :type experiment: Experiment :param experiment_client: The client for the run. :type experiment_client: ExperimentClient :return: A run. :rtype: cortex.experiment.RemoteRun

static from_json(json: dict, experiment: Experiment): Builds a run from the given json. :param run_json: json that specifies the run; acceptable values are runId, startTime, endTime, took, a list of params, metrics, metadata, and artifacts :type run_json: Dict :param experiment: the parent experiment of the run :type experiment: cortex.experiment.Experiment :return: a run :rtype: cortex.experiment.RemoteRun

static get(experiment: Experiment, run_id: str, experiment_client: ExperimentClient) → Run

Gets a run.

Parameters

experiment (Experiment) – The parent experiment of the run.
run_id (str) – The identifier for the run.
experiment_client (ExperimentClient) – The client for the run.

Returns

A RemoteRun instance.

Return type

cortex.experiment.RemoteRun

get_artifact(name: str, deserializer=<function loads>) → bytes

Gets an artifact with the given name. Deserializes the artifact stream using dill by default. Deserialization can be disabled entirely or the deserializer function can be overridden.

Parameters

name (str) – Name of the artifact to be fetched
deserializer (function, optional) – Function to be used as the deserializer, defaults to dill.loads

Returns

Bytes in memory containing the artifact’s file contents

Return type

bytes

get_keras_model(artifact_name='model'): Gets the keras model.

log_artifact(name: str, artifact): Updates the artifacts for the run.

log_artifact_file(name: str, file_path): Logs the artifact to the file given in the filepath.

log_artifact_stream(name: str, stream): Updates the artifact with the given stream.

log_keras_model(model, artifact_name='model'): Logs a keras model as an artifact.

log_metric(name: str, metric: any)

Updates the metric for the run.

Parameters

name (str) – Name of the metric to log and update
metric (any) – Value of the metric to log and update. This value needs to be JSON serializable

log_param(name: str, param: any) → None

Updates the params for the run.

Parameters

name (str) – Name of the parameter to log and update
param (any) – Value of the parameter to log and update. This value needs to be JSON serializable

set_meta(name: str, val: any)

Sets the metadata for the run.

Parameters

name (str) – Name of the meta attribute to set
val (any) – Value of the meta attribute to set. Needs to be JSON serializable

REST API Clients

AuthenticationClient

class cortex.auth.AuthenticationClient(*args, **kwargs)

Client authentication.

Parameters: _Client (_type_) – cortex.serviceconnector._Client
Returns: Instance of AuthenticationClient
Return type: AuthenticationClient

fetch_auth_token(config: Dict, validity=2) → str

Generates JWT token from the personal access token provided via the config parameter

Parameters

config (Dict) – A Personal access token provided by the Cortex Console,represented as a python dict
validity (float, optional) – The validity of the JWT token in minutes, defaults to 2 minutes

Returns

A JWT token in string form

Return type

str

ConnectionClient

class cortex.connection.ConnectionClient(*args, **kwargs)

A client used to manage connections on a Fabric server.

Parameters: _Client (_type_) – _description_
Returns: An instance of a ConnectionClient

get_connection(name: str) → dict

Fetch the specific connection in the name argument and return the details as a python dictionary

Parameters: name (str) – Name of the connection to be fetched from the Fabric API
Returns: A python dictionary containing the specified connection details
Return type: dict

save_connection(connection: dict) → dict

Saves the provided connection dictionary to the Fabric API server.

Parameters: connection (dict) – A Python dictionary containing specification for one of the supported Fabric connection types
Returns: A dictionary containing metadata about the saved connection
Return type: dict

ExperimentClient

class cortex.experiment.ExperimentClient(*args, **kwargs)

A client for the Cortex experiment and model management API. You can find a pre-created instance of this class on every cortex.client.Client instance via the Client.experiments attribute.

>>> from cortex import Cortex; client = Cortex.client();
>>> client.experiments.list_experiments() # list experiments from the default project configured for the user

create_run(experiment_name: str, **kwargs) → Dict

Creates a run for the specified experiment_name. Refer to the official CreateRun docs for information on other possible kwargs this method can accept

>>> from cortex import Cortex; cc=Cortex.client(project='test')
>>> cc.experiments.create_run('op-gc_dtree_exp')
{'_projectId': 'test', 'runId': 'ox00gu0', 'experimentName': 'op-gc_dtree_exp', '_id': '63f0f9e809c5267ccb9110ca', '_createdAt': '2023-02-18T16:16:40.405Z', '_updatedAt': '2023-02-18T16:16:40.405Z'}

Raises: requests.exceptions.HTTPError
Parameters: experiment_name (str) – The experiment to associate with this run.
Returns: A dictionary providing a JSON representation of the created run
Return type: Dict

delete_experiment(experiment_name: str) → bool

Delete an experiment specified by experiment_name

>>> from cortex import Cortex; cc=Cortex.client(project='test')
>>> cc.experiments.delete_experiment('another')
True

Parameters: experiment_name (str) – Name of the experiment to be deleted
Returns: A boolean value indicating the status of the delete operation
Return type: bool

delete_run(experiment_name: str, run_id: str) → bool

Deletes a run with identifier run_id from the experiment with name experiment_name

Parameters

experiment_name (str) – Name of the experiment to which this run belongs
run_id (str) – Identifier of the run to be deleted

Raises

cortex.exceptions.DeleteRunException

Returns

A boolean indicating the status of the delete operation

Return type

bool

delete_runs(experiment_name, filter_obj: Optional[Dict] = None) → str

Delete runs belonging to the specified experiment_name that match the optional filter_obj conditions

>>> from cortex import Cortex; cc=Cortex.client(project='test')
>>> cc.experiments.delete_runs('op-gc_dtree_exp')
'Runs deleted'

Parameters

experiment_name (str) – Name of the experiment whose runs are to be deleted
filter_obj (Dict) – A mongo style query object. For example. {“runId”: “run_01”}. Allowed fields which can be set as keys in this dictionary include [runId, _createdAt, startTime, endTime, took, experimentName]

Raises

requests.exceptions.HTTPError

Returns

A message indicating that runs were deleted

Return type

_type_

find_runs(experiment_name: str, filter_obj: Dict, sort: Optional[dict] = None, limit=25) → List[Dict]

Similar to cortex.experiment.ExperimentClient.list_runs(), but also allows you to filter with a mongo-style query dictionary passed in through filter_obj, along with sort and limit options

>>> from cortex import Cortex; cc=Cortex.client()
>>> cc.experiments.find_runs('op-gc_dtree_exp', filter_obj={"runId": "run_01"})
[{'_id': '63cfb10ffe65fb07bf8a94b9', '_projectId': 'test', 'runId': 'run_01', 'experimentName': 'op-gc_dtree_exp', 'params': {'category': 'Decision Tree', 'version': 1, 'SourceData': 'Upstream Server Data'}, 'metrics': {'accuracy': 0.68}, 'meta': {'algo': 'DecisionTreeClassifier'}, '_createdAt': '2023-01-24T10:21:03.120Z', '_updatedAt': '2023-01-24T10:21:04.497Z', 'artifacts': {'model': 'experiments/op-gc_dtree_exp/run_01/artifacts/model'}}]

Parameters

experiment_name (str) – Name of the experiment whose runs are to be filtered
filter_obj (Dict) – A mongo style query object. For example. {“runId”: “run_01”}. Allowed fields which can be set as keys in this dictionary include [runId, _createdAt, startTime, endTime, took, experimentName]
sort (Dict, optional) – A mongo style sort object, defaults to None on the client. Server side default is {“_updatedAt”: -1}
limit (int, optional) – Limit the number of results to this number, defaults to 25

Returns

A list of JSON objects (dictionaries), with each dictionary encoding the information available for a run that matches the provided filter criteria

Return type

List[Dict]

get_artifact(experiment_name: str, run_id: str, artifact: str) → bytes

Retrieve the artifact with key artifact from run run_id belonging to experiment experiment_name

Parameters

experiment_name (str) – Experiment name
run_id (str) – Identifier of the run whose param attribute is to be updated
artifact (str) – Name or Key of the artifact to be stored. This will be used to store the stream data in Managed Content

Returns

A Python bytes object containing the data corresponding to the artifact key in managed content

Return type

bytes

get_experiment(experiment_name: str) → Dict

Retrieve all data for the experiment with name experiment_name

>>> from cortex import Cortex; cc=Cortex.client()
>>> cc.experiments.get_experiment('ddgc_dtree_exp')
{'_version': 1, 'name': 'ddgc_dtree_exp', 'title': 'Decision Tree model', 'description': 'Decision Tree model', 'tags': [], '_projectId': 'test', 'modelId': 'german-credit-model'}

Parameters: experiment_name (str) – Name of the experiment to retrieve data from
Returns: A dictionary with all metadata about the experiment
Return type: Dict

get_run(experiment_name: str, run_id: str) → Dict

Get all details available for a run_id belonging to an experiment_name

>>> from cortex import Cortex; cc=Cortex.client(project='test')
>>> cc.experiments.get_run('op-gc_dtree_exp', 'ox00gu0')
{'_id': '63f0f9e809c5267ccb9110ca', '_projectId': 'test', 'runId': 'ox00gu0', 'experimentName': 'op-gc_dtree_exp', '_createdAt': '2023-02-18T16:16:40.405Z', '_updatedAt': '2023-02-18T16:16:40.405Z'}

Raises

requests.exceptions.HTTPError

Parameters

experiment_name (str) – Name of the experiment whose run is to be retrieved
run_id (str) – ID of the Run to be retrieved

Returns

A dictionary providing a JSON representation of the specified run

Return type

Dict

list_experiments() → List[Dict]

Returns a list of experiments available on the project configured for the experiment client.

>>> from cortex import Cortex; cc=Cortex.client()
>>> cc.experiments.list_experiments()
[{'_version': 2, 'name': 'op-gc_dtree_exp', 'title': 'Decision Tree model', 'description': 'Decision Tree model', 'meta': None, 'tags': [], 'modelId': 'op-german-credit', 'updatedAt': '2023-01-24T10:21:01.347Z', 'createdAt': '2023-01-24T10:11:16.445Z'}]

Returns: A list containing multiple dictionaries, each corresponding to an experiment and all associated metadata
Return type: List[Dict]

list_runs(experiment_name: str) → List[Dict]

List all the runs that belong to the specified experiment_name

>>> from cortex import Cortex; cc=Cortex.client()
>>> cc.experiments.list_runs('op-gc_dtree_exp')
[{'_id': '63cfb10ffe65fb07bf8a94b9', '_projectId': 'test', 'runId': 'run_01', 'experimentName': 'op-gc_dtree_exp', 'params': {'category': 'Decision Tree', 'version': 1, 'SourceData': 'Upstream Server Data'}, 'metrics': {'accuracy': 0.68}, 'meta': {'algo': 'DecisionTreeClassifier'}, '_createdAt': '2023-01-24T10:21:03.120Z', '_updatedAt': '2023-01-24T10:21:04.497Z', 'artifacts': {'model': 'experiments/op-gc_dtree_exp/run_01/artifacts/model'}}]

Parameters: experiment_name (str) – Experiment name whose runs are to be listed
Returns: A List of dictionaries that contain the information available for each run of that experiment
Return type: List[Dict]

save_experiment(experiment_name: str, model_id=None, **kwargs) → Dict

Save an experiment with the provided experiment_name, and modelId. All the fields specified in the API reference for Cortex Experiments (except name and modelId) can be passed in as keyword args to this method

>>> from cortex import Cortex; cc=Cortex.client()
>>> cc.experiments.save_experiment('exp-name', 'juhf')
{'_version': 1, 'name': 'exp-name', 'tags': [], '_projectId': 'exp-test', 'modelId': 'juhf'}

Parameters

experiment_name (str) – Name to use for the new experiment which is to be saved
model_id (str, optional) – _description_, defaults to None

Returns

A dictionary with metadata about the saved experiment

Return type

Dict

update_artifact(experiment_name: str, run_id: str, artifact: str, stream)

Update the bytes or file content corresponding to experiment’s run artifact with name provided in the artifact param. stream should be a valid Python I/O stream. Use this field to store trained models, large model weights and training data corresponding to an experiment run.

Parameters

experiment_name (str) – Experiment name
run_id (str) – Identifier of the run whose param attribute is to be updated
artifact (str) – Name or Key of the artifact to be stored. This will be used to store the stream data in Managed Content
stream (Python I/O stream) – A Python I/O stream which will be written to managed content with filename provided in the artifact param

Raises

cortex.exceptions.UpdateRunException

Returns

A boolean indicating the status of the update operation

Return type

bool

update_meta(experiment_name: str, run_id: str, meta: str, val: any) → bool

Update the value of a meta attribute of an experiment’s run. The value val needs to be serializable to json. The meta attributes should be used to store metadata about a particular run of an experiment. It can contain information about the class of model being trained, usecases, problem specification and more.

Parameters

experiment_name (str) – Experiment name
run_id (str) – Identifier of the run whose meta attribute is to be updated
meta (str) – Identifier of the meta attribute
val (any) – Value to be updated for the provided meta attribute

Raises

cortex.exceptions.UpdateRunException

Returns

A boolean indicating the status of the update operation

Return type

bool

update_metric(experiment_name: str, run_id: str, metric: str, val: any)

Update the value of a metric attribute of an experiment’s run. The value val needs to be serializable to json. Metrics should be used to store data pertaining to a run’s performance, and other dimensions

Parameters

experiment_name (str) – Experiment name
run_id (str) – Identifier of the run whose param attribute is to be updated
metric (str) – Identifier of the param attribute
val (any) – Value to be updated for the provided metric attribute

Raises

cortex.exceptions.UpdateRunException

Returns

A boolean indicating the status of the update operation

Return type

bool

update_param(experiment_name: str, run_id: str, param: str, val: any) → bool

Update the value of a param attribute of an experiment’s run. The value val needs to be serializable to json. Params should be used to store information about a model’s runtime or train-time characteristics. For example, hyper-parameters of a models should be stored in this object

Parameters

experiment_name (str) – Experiment name
run_id (str) – Identifier of the run whose param attribute is to be updated
param (str) – Identifier of the param attribute
val (any) – Value to be updated for the provided param attribute

Raises

cortex.exceptions.UpdateRunException

Returns

A boolean indicating the status of the update operation

Return type

bool

update_run(experiment_name: str, run_id: str, **kwargs) → bool

Updates a run and returns the boolean status of the operation. Refer to the official UpdateRun docs for information on other possible kwargs this method can accept

Parameters

experiment_name (str) – Name of the experiment whose run is to be updated
run_id (str) – ID of the run to be updated

Raises

cortex.exceptions.UpdateRunException

Returns

Boolean indicating the status of the operation

Return type

bool

ManagedContentClient

class cortex.content.ManagedContentClient(*args, **kwargs)

A client used to access the Cortex managed content service (blob store). You can find a pre-created instance of this class on every cortex.client.Client instance via the Client.content attribute.

>>> from cortex import Cortex; client = Cortex.client();
>>> client.content.list() # list content from the default project configured for the user

delete(key: str) → dict

Delete a file from managed content (S3)

Parameters: key (str) – The path of the file to delete
Returns: A boolean indicating whether the file exists or not.
Return type: dict

download(key: str, retries: int = 1) → HTTPResponse

Download a file from managed content (S3 like blob store).

Parameters

key (str) – The path of the file to retrieve.
retries (int, optional) – Number of times to retry a failed request from a response., defaults to 1

Returns

A HTTPResponse object

Return type

urllib3.response.HTTPResponse

exists(key: str) → bool

Check that a file from managed content (S3) exists.

Parameters: key (str) – The path of the file to check.
Returns: A boolean indicating whether the file exists or not.
Return type: bool

list(prefix: Optional[str] = None, limit: int = -1, skip: int = -1) → List[dict]

List objects in a project’s managed content store

Parameters

prefix (str, optional) – The key prefix to filter objects with, defaults to None
limit (int, optional) – Limit the number of results returned, defaults to -1
skip (int, optional) – Skip number of records. Use along with limit to paginate results, defaults to -1

Returns

List of dictionaries with each dictionary holding metadata about individual files in the project’s managed content store

Return type

List[dict]

upload(key: str, stream_name: str, stream: Union[BytesIO, StringIO, FileIO], content_type: str, retries: int = 1) → dict

Store stream file in Managed Content (S3).

Parameters

key (str) – The path where the file will be stored in managed content
stream_name (str) – The name under which to save the stream.
stream (Union[BytesIO, StringIO, FileIO]) – The file object.
content_type (str) – the type of the file to store (e.g., text/csv).
retries (int, optional) – Number of times to retry a failed request from a retryable response, defaults to 1

Returns

a dict with the response to request upload.

Return type

dict

upload_directory(source: str, destination: str, retries: int = 1) → dict

Walk source directory and store in Managed Content

Parameters

source (str) – The path to the local directory.
destination (str) – Prefix to add to resulting saved directory.
retries (int, optional) – Number of times to retry a failed request from a retryable response, defaults to 1

Returns

A dict with the response to request upload.

Return type

dict

upload_streaming(key: str, stream: object, content_type: str = 'application/octet-stream', retries: int = 1) → dict

Store stream file in Managed Content. Use this method to upload large files to Managed Content

Parameters

key (str) – The path where the file will be stored.
stream (object) – The file object.
content_type (str, optional) – The type of the file to store (e.g., text/csv), defaults to “application/octet-stream”
retries (int, optional) – Number of times to retry a failed request from a retryable response., defaults to 1

Returns

A dict with the response to request upload.

Return type

dict

SessionClient

class cortex.session.SessionClient(*args, **kwargs)

A client for the Cortex Sessions API.

delete_session(session_id)

Deletes a session.

Parameters: session_id – The ID of the session to delete.
Returns: status

get_session_data(session_id, key=None) → Dict[str, object]

Gets data for a specific session.

Parameters

session_id – The ID of the session to query.
key – An optional key in the session memory; the entire session memory is returned if a key is not specified.

Returns

A dict containing the requested session data

put_session_data(session_id, data: Dict)

Adds data to an existing session.

Parameters

session_id – The ID of the session to modify.
data – Dict containing the new session keys to set.

Returns

status

start_session(ttl=None, description='No description given') → str

Starts a new session.

Parameters

ttl – Resets sessions expiration; default is 15 minutes.
description – An optional human-readable description for this sessions instance

Returns

The ID of the new Session.

SecretsClient

class cortex.secrets.SecretsClient(*args, **kwargs)

A client for the Cortex Secrets API.

get_secret(name: str)

Fetches a secret to work with.

Parameters: name – The name of the Secret to retrieve.
Returns: A Secret object.

post_secret(name: str, value: object): Posts the secret information. :param name: Secret name :param value: Secret value :return: status

SkillClient

class cortex.skill.SkillClient(*args, **kwargs)

A client used to interact with skills.

delete_skill(skill_name): Delete a skill by name :param skill_name: Skill name :return: status

deploy(skill_name): Deploy a skill :param skill_name: Skill name :return: status

get_logs(skill_name, action_name): Get logs by skill name and action name :param skill_name: Skill name :param action_name: Action name :return: Logs

get_skill(skill_name): Get a skill by name :param skill_name: Skill name :return: skill json

invoke(skill_name: str, input_name: str, payload: object, properties: object, sync: bool = False) → dict

Invoke a skill on a specified input_name with the specified payload and properties. Use sync=True if you want to access the Skill invocation results without polling.

Parameters

skill_name (str) – Skill name
input_name (str) – Input name of the Skill
payload (object) – Skill payload
properties (object) – Skill properties
sync (bool,) – Set this to True if you want synchronous skill invokes

Returns

The activation details of the invocation if sync=False, and the full Skill response if sync=True

Return type

dict

list_skills(): Retrieve List of skills for specified project :return: list of skills

property project: AnyStr

_summary_

Returns:: _type_: _description_

save_skill(skill_obj): Create or Update skill :param skill_obj: Skill object to save :return: response json

send_message(activation: str, channel: str, output_name: str, message: object): Send a payload to a specific output, this can be called more than one and will replace the stdout/stderr as payload for jobs :param activation: ActivationId provided in resources :param channel: ChannelId provided in the parameters :param output_name: Output name provided in the parameters or another skill output connected from this skill :param message: dict - payload to be sent to the agent :return: success or failure message

undeploy(skill_name): Undeploy a skill :param skill_name: Skill name :return: status

Messages

class cortex.message.Message(params: Optional[Dict] = None)

Wraps a set of parameters or a payload when invoking an action, skill, or agent.

The following keys are valid in the params dictionary

{
    "activationId": "Request ID for the current execution",
    "agentName": "Name of the agent invoking the skill, will be empty for skill invokes",
    "apiEndpoint": "URI of the API server to use when making requests to platform services in processing of this message.",
    "channelId": "ID of the channel (wire) this message was sent on",
    "outputName": "Output name defined in the agent definition, can be overridden",
    "payload": "JSON payload passed to the skill",
    "projectId": "Project to which this skill belongs to",
    "properties": "Properties merged from Skill definition, Skill reference, and Agent definition.",
    "sessionId": "The ID of the session associated with this message, this will be the activationId unless provided externally",
    "skillName": "The name of the skill being invoked.",
    "timestamp": "Timestamp of the invoke",
    "token": " The JWT token to be used for making authenticated requests to APIs needed to process this message."
}

static from_env(**kwargs)

Creates an instance of cortex.message.Message by reading from existing environment and cortex profile

Returns: cortex.message.Message pre-populated with params loaded from pre-existing Cortex environment variables or Cortex profile
Return type: cortex.message.Message

to_params() → Dict: Gets the parameters in the message.

Exceptions

class cortex.exceptions.CortexException: Base exception type.

class cortex.exceptions.AuthenticationException: Cortex authentication exception.

class cortex.exceptions.BadTokenException: Cortex token invalid exception.

class cortex.exceptions.ConfigurationException: Cortex configuration exception.

class cortex.exceptions.APIException: Cortex API exception.

Cortex Python Reference

Cortex Client

Cortex

CortexEnv

Cortex Local Experiments

Cortex Experiment

Cortex Experiment Run

Cortex Experiment RemoteRun

REST API Clients

AuthenticationClient

ConnectionClient

ExperimentClient

ManagedContentClient

SessionClient

SecretsClient

SkillClient

Messages

Exceptions

Related Projects

Cortex Fabric

Cortex Python Builders

Cortex Python Profiles