Documentation

# kortical.api.model_instance

This object represents a model instance on Kortical. A model instance is a deployment of a model version; they may be found within an environment of a Kortical project.

The ModelInstance class includes the following attributes:

  • id - The ID assigned to the instance upon creation.
  • name - The name of the instance.
  • version - The version of the model that has been deployed.
  • type - Either "app" or "model". Components are displayed in a single list, so use type to identify models.
  • status - Current status (e.g creating, pending, running, terminating).
  • created_by - User that created the model instance.
  • created - The time of creation.
  • environment - The environment which the component belongs to, represented as a Environment object.
  • project - The project which the component belongs to, represented as a Project object.

In the Kortical CLI, you can view this by running:

# Within a selected project/environment...
>>> kortical component list

Components for environment [Integration] in project [Document Tagging]:
+----+------------------+-----------------+-------+---------+----------------------------+---------------------+------------------------------+----------------------------------+
| id |       name       |     version     | type  | status  |         created_by         |       created       |         environment          |             project              |
+====+==================+=================+=======+=========+============================+=====================+==============================+==================================+
| 51 | document_tagging | id [16] v[4]    | model | Pending | owen.saldanha@kortical.com | 2023/06/06 15:41:52 | id [128], name [Integration] | id [42], name [Document Tagging] |
+----+------------------+-----------------+-------+---------+----------------------------+---------------------+------------------------------+----------------------------------+
| 50 | web_app          | id [17] v[None] | app   | Running | owen.saldanha@kortical.com | 2023/06/06 15:41:18 | id [128], name [Integration] | id [42], name [Document Tagging] |
+----+------------------+-----------------+-------+---------+----------------------------+---------------------+------------------------------+----------------------------------+

Run kortical component -h for further help.

# Model Instances

#

# list

This function lists the model instances within the specified project/environment.

Inputs

  • project - A Project object.
  • environment - An Environment object.
  • include_created_by (= False) - Use this to see which user created the model.
  • include_deleted (= False) - Include model instances that are no longer live.

Returns

  • [ModelInstance, ...] - A list of ModelInstance objects.
from kortical.api.project import Project
from kortical.api.model_instance import ModelInstance

# Get project + environment
doc_project = Project.get_project('document_tagging')
integration = doc_project.get_environment('Integration')

# List model instances
model_instances = ModelInstance.list(doc_project, integration)

#

# get_model_instance

This function gets a model instance from the specified project/environment.

Inputs

  • project - A Project object.
  • environment - An Environment object.
  • model_name_or_instance_id - The name or ID of the model instance you want.

Returns

  • ModelInstance - A ModelInstance object.
from kortical.api.project import Project
from kortical.api.model_instance import ModelInstance

# Get project + environment
doc_project = Project.get_project('document_tagging')
integration = doc_project.get_environment('Integration')

# Get model instance
model_instance = ModelInstance.get_model_instance(doc_project, integration, 'nlp_classifier')

#

# create_model_instance

This function creates a new model instance in the specified environment.

Inputs

  • project - A Project object.
  • environment - An Environment object.
  • model_name_or_version_id - Version ID used to specify the component + version you want to add. If a model name is passed in, uses the default version ID (you can view this in kortical model list).
  • wait_for_ready (= False) - wait for the model instance to reach a running state.

Returns

  • ModelInstance - a ModelInstance object.
from kortical.api.project import Project
from kortical.api.model_instance import ModelInstance

# Get project + environment
doc_project = Project.get_project('document_tagging')
integration = doc_project.get_environment('Integration')

# Deploy model to the Integration environment
new_app_instance = ModelInstance.create_model_instance(doc_project, integration, 'nlp_classifier')

#

# wait_for_status

This function waits for a model instance to enter a specified state; this is useful if you are deploying/removing items.

Inputs

  • component_instance_state - state to wait for; examine ComponentInstanceState for a list of valid states.
  • timeout_seconds (= 180) - time in seconds to wait.
  • poll_frequency (= 0.25) - how often in seconds to make a status request.

Returns

  • None
from kortical.api.project import Project
from kortical.api.component_instance import ComponentInstanceState

# Get model instance
doc_project = Project.get_project('document_tagging')
integration = doc_project.get_environment('Integration')
model_instance = integration.get_component_instance('nlp_classifier')

# Wait
model_instance.wait_for_status(ComponentInstanceState.RUNNING)

#

# get_url

This function returns the URL for a component instance. You can also view this in the CLI by running kortical status.

No Inputs

Returns

  • component_url - URL for the component.
from kortical.api.project import Project

# Get model instance
doc_project = Project.get_project('document_tagging')
integration = doc_project.get_environment('Integration')
model_instance = integration.get_component_instance('nlp_classifier')

# Get URL
url = model_instance.get_url()

>>> print(url)
'https://platform.kortical.com/<company>/<system>/api/v1/projects/document_tagging/environments/integration/models/nlp_classifier'

#

# predict

This function sends a dataframe to a model instance, receiving the predictions in a dataframe containing a new column.

Inputs

  • df - the dataframe for which you want predictions; most commonly a test set.

Returns

  • df - dataframe containing the predictions.
import pandas as pd
from kortical.api.project import Project

# Get model instance
doc_project = Project.get_project('document_tagging')
integration = doc_project.get_environment('Integration')
model_instance = integration.get_component_instance('nlp_document_classifier')

# Get logs
df_train = pd.read_csv('<path-to-csv>')
df_out = model_instance.predict(df_train)

# Kortical Config (Component Level)

Kortical Config allows you to configure various settings (i.e worker group, replicas) at a project/environment/component level, including:

  • Replicas - this is the number of pods each component will have when deployed to this environment. Applies to both apps and models.
  • Worker Group - this is the worker group on which this environment will be hosted.
  • Low-latency mode - for models only. This will reduce prediction request times, but at the expense of less logging.

For example, if we assign 3 replicas to an environment, then all the components inside that environment will run on 3 replicas.

#

# get_kortical_config

This function returns the Kortical config for the component instance.

No Inputs

Returns

  • (config, inherited_config) - Two dictionaries. The first dictionary contains any component level settings you have made, the second one shows you what has been inherited from a higher level (i.e company/project/environment level Kortical Config).
from kortical.api.project import Project

# Get component instance
doc_project = Project.get_project('document_tagging')
integration = doc_project.get_environment('Integration')
model_instance = integration.get_model_instance('nlp_classifier')

# Get Kortical Config
kortical_config, inherited_config = model_instance.get_kortical_config()

>>> print(kortical_config, inherited_config)
{} {'replicas': 2, 'worker_group': 'default', 'low_latency_mode': False}

In this example, we have not set any config for this environment (i.e everything inherits).

#

# set_kortical_config

This function sets the Kortical config for the component instance.

Inputs

  • kortical_config - A dictionary of settings you want to configure for the environment. Valid keys are replicas, worker_group and low_latency_mode.

Returns

  • (config, inherited_config) - Two dictionaries. The first dictionary contains any component level settings you have made, the second one shows you what has been inherited from a higher setting (i.e company/project/environment level Kortical Config).
from kortical.api.project import Project

# Get component instance
doc_project = Project.get_project('document_tagging')
integration = doc_project.get_environment('Integration')
model_instance = integration.get_model_instance('nlp_classifier')
kortical_config, inherited_config = model_instance.get_kortical_config()

# Set Kortical Config
kortical_config, inherited_config = model_instance.set_kortical_config({'replicas': 3})

>>> print(kortical_config, inherited_config)
{'replicas': 3} {'replicas': 2, 'worker_group': 'default', 'low_latency_mode': False}

To undo, simply set the key to a None value:

kortical_config, inherited_config = model_instance.set_kortical_config({'replicas': None})

>>> print(kortical_config, inherited_config)
{} {'replicas': 2, 'worker_group': 'default', 'low_latency_mode': False}

WARNING

Note that the inherited config dictionary does not include what you have set at the component level! If you want a simplified view, you could run the following:

full_component_kortical_config = inherited_config.update(kortical_config)

← kortical.api.app →