C3 AI Documentation Home

Making a Runtime

A runtime is an execution context that lists all the required libraries (and their versions) and defines a context in which some application logic can be run. Runtimes provide flexibility to add or remove any specific library.

For more details, read about conda environments and node packages.

Motivation

A C3 AI Type System method can be implemented in multiple languages (the C3 Agentic AI Platform supports JavaScript, and Python) and may need third-party libraries - for example, to use the scikit-learn Python library for training a logistic regression model.

The C3 Agentic AI Platform supports the concept of a Language Runtime to make it possible for developers to specify the implementation language and required libraries. A method's runtime is declared by a method claim.

Important terminology and Types

Each language supported by the Type System is represented by a Type, for example:

The ImplLanguage Type declares the common interface that each subtype implements.

Runtime

A runtime logically specifies:

  • An ImplLanguage such as Python or JavaScript
  • The version of the ImplLanguage
  • A list of libraries (including their versions)
  • A list of repositories from which to install libraries (for example, conda-forge)
  • A list of parent runtimes, from which this child runtime inherits all libraries and repositories.

See ImplLanguage.Runtime for more details.

Library

A library represents a language-specific module or package necessary for executing an action.

For Python, a library can be a conda package or a pip package. For Node.js, a library is an npm module.

A library follows the naming convention:

  • {{package manager}} {{package name}} {{installation url}}. The installation url is optional, and the package version, if specified, is included in the package name. For example, conda numpy=1 would represent library numpy version 1 installed from conda.

See ImplLanguage.Library for more details.

Create and seed a runtime

For more information on creating a runtime in the Jupyter UI, see the Creating a runtime from the Jupyter UI section in the Working with Runtimes topic.

To seed a new runtime in the C3 Agentic AI Platform using Python, you must:

Create an instance of ImplLanguage.Runtime and specify all the necessary details:

Python
runtime = c3.ImplLanguage.Runtime(
  name="py-pandas", 
  languageVersion="3.9", 
  libraries=["conda pandas=1.2.4"]
)

Call upsertRuntime (If the runtime is python, this requires the platform to be running in a Linux environment).

Python
c3.Py.upsertRuntime(runtime)

Calling upsertRuntime can resolve and then seed both the resolved and the unresolved runtime.

The following is an example of a seeded resolved runtime:

JSON
    {
  "name":"py-pandas-server-py4j",
  "languageVersion":"3.9",
  "libraries":[
    "conda _libgcc_mutex=0.1=main",
    "conda _openmp_mutex=4.5=1_gnu",
    "conda blas=1.0=mkl",
    "conda ca-certificates=2021.7.5=h06a4308_1",
    "conda certifi=2021.5.30=py39h06a4308_0",
    "conda intel-openmp=2021.3.0=h06a4308_3350",
    "conda ld_impl_linux-64=2.35.1=h7274673_9",
    "conda libffi=3.3=he6710b0_2",
    "conda libgcc-ng=9.3.0=h5101ec6_17",
    "conda libgomp=9.3.0=h5101ec6_17",
    "conda libstdcxx-ng=9.3.0=hd4cf53a_17",
    "conda mkl=2021.3.0=h06a4308_520",
    "conda mkl-service=2.4.0=py39h7f8727e_0",
    "conda mkl_fft=1.3.0=py39h42c9631_2",
    "conda mkl_random=1.2.2=py39h51133e4_0",
    "conda ncurses=6.2=he6710b0_1",
    "conda numpy=1.20.2=py39h2d18471_0",
    "conda numpy-base=1.20.2=py39hfae3a4d_0",
    "conda openssl=1.1.1k=h27cfd23_0",
    "conda pandas=1.2.3=py39ha9443f7_0",
    "conda pip=21.1.3=py39h06a4308_0",
    "conda python=3.9.5=h12debd9_4",
    "conda python-dateutil=2.8.2=pyhd3eb1b0_0",
    "conda pytz=2021.1=pyhd3eb1b0_0",
    "conda readline=8.1=h27cfd23_0",
    "conda setuptools=52.0.0=py39h06a4308_0",
    "conda six=1.16.0=pyhd3eb1b0_0",
    "conda sqlite=3.36.0=hc218d9a_0",
    "conda tk=8.6.10=hbc83047_0",
    "conda tzdata=2021a=h52ac0ba_0",
    "conda wheel=0.36.2=pyhd3eb1b0_0",
    "conda xz=5.2.5=h7b6447c_0",
    "conda zlib=1.2.11=h7b6447c_3",
    "pip py4j==0.10.9.2"
  ]
}

To understand why you need to resolve a runtime, see the section below on Runtime Resolution.

Naming convention for runtimes

A runtime follows the following naming convention:

  • {{language}}-{{suffix}}. For example, py-deeplearning means that it is a Python runtime and includes various deep learning libraries like TensorFlow and Keras. Note that the suffix can contain -. For instance, js-ide-vscode is a valid runtime name.

Each runtime name is unique and must always start with the language abbreviation for the ImplLanguage used.

Note: The runtime name is case-sensitive and must be all lowercase. If the name contains a camel-case or is not all lowercase the runtime does not resolve correctly.

Runtime resolution

The runtimes that you create specify the required libraries for executing an action. These runtimes need only specify libraries directly used by your method. The versions of these libraries may be as loose or strict as you feel appropriate.

From a single runtime, the C3 Agentic AI Platform creates several resolved runtimes. These resolved runtimes can have all the libraries in the runtime. These resolved runtimes can also contain libraries required by the C3 AI SDK for the runtime's language. All (nested) dependent libraries of these libraries are also contained in a resolved runtime. All libraries in a resolved runtime have their versions pinned to the most specific granularity possible.

Why resolve a runtime

You want to freeze runtimes to avoid unexpected changes in production deployments. As the libraries referred to by runtimes publish new versions, the library versions specified in runtime may no longer be desirable.

For example, suppose your method uses the following runtime:

JSON
{
  "name": "py-foo", 
  "languageVersion":"3.9",
  "libraries":[
    "conda numpy>=1"
    ]
}

At the time that you created py-foo, numpy version 1.23.4 would be installed, and your method would work fine. After numpy publishes version 2.0.0, this new version gets installed. This new version contains breaking changes, and your method stops working.

To address this pain point, runtimes should always be frozen at development time, and the frozen (resolved) runtimes should be committed as metadata. This resolved runtime can be installed to execute code in the C3 Agentic AI Platform.

To understand how a runtime is resolved, see resolving a runtime.

Related content

Was this page helpful?