API#

ICortex tries to inherit from IPython as much as possible and tries to adhere already established standards.

Kernel#

class ICortexKernel(**kwargs: Any)#

Bases: IPythonKernel

Class that implements the ICortex kernel. It is basically ipykernel.ipkernel.IPythonKernel with magic commands and logic for handling code generation.

class ICortexShell(**kwargs: Any)#

Bases: InteractiveShell

bake(line: str)#

Bake notebook into a Python script

eval_var(line: str)#

Evaluate var magic

export(line: str)#

Export notebook to a file

run_cell(raw_cell, store_history=False, silent=False, shell_futures=True, cell_id=None, input_type=InputType.CODE)#

Run a complete IPython cell.

Parameters
  • raw_cell (str) – The code (including IPython code such as %magic functions) to run.

  • store_history (bool) – If True, the raw and translated cell will be stored in IPython’s history. For user code calling back into IPython’s machinery, this should be set to False.

  • silent (bool) – If True, avoid side-effects, such as implicit displayhooks and and logging. silent=True forces store_history=False.

  • shell_futures (bool) – If True, the code will share future statements with the interactive shell. It will both be affected by previous __future__ imports, and any __future__ imports in the code will affect the shell. If False, __future__ imports are not shared in either direction.

Returns

result

Return type

ExecutionResult

class InputType(value)#

Bases: Enum

Enum for input cell type.

get_icortex()#

Get the global overloaded InteractiveShell instance.

Returns None if no InteractiveShell instance is registered or ICortex has not been initialized yet.

Services#

This sections explains how to add or extend new code generation services.

class ServiceBase(**kwargs: Dict[str, Any])#

Bases: ABC

Abstract base class for interfacing a code generation service. Its main purpose is to provide a flexible API for connecting user prompts with whatever logic the service provider might choose to implement. User prompts adhere to POSIX argument syntax and are parsed with argparse.

To create a new service:

Check out icortex.services.textcortex.TextCortexService as a reference implementation.

variables#

A dict that maps variable names to ServiceVariable s.

Type

Dict[str, ServiceVariable]

name#

A unique name.

Type

str

description#

Description string.

Type

str

prompt_parser#

Parser to parse the prompts.

Type

argparse.ArgumentParser

abstract classmethod generate(prompt: str, args, context: Optional[ICortexContext] = None) GenerationResult#

Implement the logic that generates code from user prompts here.

Parameters
  • prompt (str) – The prompt that describes what the generated code should perform

  • context (Dict[str, Any], optional) – A dict containing the current notebook context, that is in the Jupyter notebook format. See icortex.context.ICortexHistory for more details.

Returns

A list that contains code generation results. Should ideally be valid Python code.

Return type

List[Dict[Any, Any]]

abstract classmethod get_outputs_from_result(generation_result: GenerationResult) List[str]#

Given a GenerationResult, return a dict that contains the response.

Parameters

generation_result (GenerationResult) – The result of the generation

Returns

The response dict

Return type

Dict[str, Any]

get_variable(var_name: str) ServiceVariable#

Get a variable by its name

Parameters

var_name (str) – Name of the variable

Returns

Requested variable

Return type

ServiceVariable

get_variable_names() List[str]#

Get a list of variable names.

Returns

List of variable names

Return type

List[str]

class ServiceVariable(type_: type, default: Optional[Any] = None, help: str = '', secret: bool = False, argparse_args: List = [], argparse_kwargs: Dict = {}, require_arg: bool = False)#

Bases: object

A variable for a code generation service

Parameters
  • type (Any) – Variable type.

  • default (Any, optional) – Default value, should match type_.

  • help (str, optional) – Help string for the variable. Defaults to “”.

  • secret (bool, optional) – When set to True, the variable is omitted from caches and the context. Defaults to False.

  • argparse_args (List, optional) – Args to be given to ArgumentParser.add_argument(). Defaults to [].

  • argparse_kwargs (Dict, optional) – Keywords args to be given to ArgumentParser.add_argument(). Defaults to {}.

  • require_arg (bool, optional) – When set to true, the prompt parser will raise an error if the variable is not specified. Defaults to False.

AVAILABLE_SERVICES: Dict[str, str] = {'echo': 'icortex.services.echo.EchoService', 'huggingface': 'icortex.services.huggingface.HuggingFaceAutoService', 'openai': 'icortex.services.openai.OpenAIService', 'textcortex': 'icortex.services.textcortex.TextCortexService'}#

A dictionary that maps unique service names to corresponding classes that derive from icortex.services.service_base.ServiceBase. Extend this to add new code generation services to ICortex.

get_service(name: str) Type[ServiceBase]#

Get the class corresponding a service name

Parameters

name (str) – Name of the service in AVAILABLE_SERVICES

Returns

A class that derives from ServiceBase

Return type

Type[ServiceBase]

class TextCortexService(**kwargs: Dict)#

Interface to TextCortex’s code generation service

get_outputs_from_result(generation_result: GenerationResult) List[str]#

Given a GenerationResult, return a dict that contains the response.

Parameters

generation_result (GenerationResult) – The result of the generation

Returns

The response dict

Return type

Dict[str, Any]

Context#

class Cell(execution_result: Optional[ExecutionResult] = None)#

Bases: ABC

class CodeCell(code: str, outputs: List[Any], execution_result: Optional[ExecutionResult] = None)#

Bases: Cell

class ICortexContext(scope: Optional[Dict[str, Any]] = None)#

Bases: object

Interface to construct a history variable in globals for storing notebook context. The constructed dict maps to JSON, and the schema is compatible with the Jupyter notebook format:

bake(dest_path: str, format=True)#

Bake the notebook to a Python script

get_code(argparsify=False)#

Aggregates the code for the notebook

run(notebook_args: List[str])#

Run the notebook with the given arguments

property vars#

Returns a list of all variables defined in the notebook

class PromptCell(prompt: str, outputs: List[Any], service_interaction: ServiceInteraction, execution_result: Optional[ExecutionResult] = None)#

Bases: Cell

class VarCell(var_line: str, var: Var, code: str, outputs: List[Any], execution_result: Optional[ExecutionResult] = None)#

Bases: Cell