promptflow package#

class promptflow.PFClient(**kwargs)#

Bases: object

A client class to interact with prompt flow entities.

property connections: ConnectionOperations#

Connection operations that can manage connections.

property flows: FlowOperations#

Operations on the flow that can manage flows.

get_details(run: Union[str, Run], max_results: int = 100, all_results: bool = False) DataFrame#

Get the details from the run including inputs and outputs.

Note

If all_results is set to True, max_results will be overwritten to sys.maxsize.

Parameters:
  • run (Union[str, Run]) – The run name or run object

  • max_results (int) – The max number of runs to return, defaults to 100

  • all_results (bool) – Whether to return all results, defaults to False

Raises:

RunOperationParameterError – If max_results is not a positive integer.

Returns:

The details data frame.

Return type:

pandas.DataFrame

get_metrics(run: Union[str, Run]) Dict[str, Any]#

Get run metrics.

Parameters:

run (Union[str, Run]) – Run object or name of the run.

Returns:

Run metrics.

Return type:

Dict[str, Any]

run(flow: Union[str, PathLike], *, data: Optional[Union[str, PathLike]] = None, run: Optional[Union[str, Run]] = None, column_mapping: Optional[dict] = None, variant: Optional[str] = None, connections: Optional[dict] = None, environment_variables: Optional[dict] = None, name: Optional[str] = None, display_name: Optional[str] = None, tags: Optional[Dict[str, str]] = None, **kwargs) Run#

Run flow against provided data or run.

Note

At least one of the data or run parameters must be provided.

Column_mapping

Column mapping is a mapping from flow input name to specified values. If specified, the flow will be executed with provided value for specified inputs. The value can be:

  • from data:
    • data.col1

  • from run:
    • run.inputs.col1: if need reference run’s inputs

    • run.output.col1: if need reference run’s outputs

  • Example:
    • {"ground_truth": "${data.answer}", "prediction": "${run.outputs.answer}"}

Parameters:
  • flow (Union[str, PathLike]) – Path to the flow directory to run evaluation.

  • data (Union[str, PathLike]) – Pointer to the test data (of variant bulk runs) for eval runs.

  • run (Union[str, Run]) – Flow run ID or flow run. This parameter helps keep lineage between the current run and variant runs. Batch outputs can be referenced as ${run.outputs.col_name} in inputs_mapping.

  • column_mapping (Dict[str, str]) – Define a data flow logic to map input data.

  • variant (str) – Node & variant name in the format of ${node_name.variant_name}. The default variant will be used if not specified.

  • connections (Dict[str, Dict[str, str]]) – Overwrite node level connections with provided values. Example: {"node1": {"connection": "new_connection", "deployment_name": "gpt-35-turbo"}}

  • environment_variables (Dict[str, str]) – Environment variables to set by specifying a property path and value. Example: {"key1": "${my_connection.api_key}", "key2"="value2"} The value reference to connection keys will be resolved to the actual value, and all environment variables specified will be set into os.environ.

  • name (str) – Name of the run.

  • display_name (str) – Display name of the run.

  • tags (Dict[str, str]) – Tags of the run.

Returns:

Flow run info.

Return type:

Run

property runs: RunOperations#

Run operations that can manage runs.

stream(run: Union[str, Run], raise_on_error: bool = True) Run#

Stream run logs to the console.

Parameters:
  • run (Union[str, Run]) – Run object or name of the run.

  • raise_on_error (bool) – Raises an exception if a run fails or canceled.

Returns:

flow run info.

Return type:

Run

test(flow: Union[str, PathLike], *, inputs: Optional[dict] = None, variant: Optional[str] = None, node: Optional[str] = None, environment_variables: Optional[dict] = None) dict#

Test flow or node.

Parameters:
  • flow (Union[str, PathLike]) – path to flow directory to test

  • inputs (dict) – Input data for the flow test

  • variant (str) – Node & variant name in format of ${node_name.variant_name}, will use default variant if not specified.

  • node (str) – If specified it will only test this node, else it will test the flow.

  • environment_variables (dict) – Environment variables to set by specifying a property path and value. Example: {“key1”: “${my_connection.api_key}”, “key2”=”value2”} The value reference to connection keys will be resolved to the actual value, and all environment variables specified will be set into os.environ.

Returns:

The result of flow or node

Return type:

dict

property tools: ToolOperations#

Tool operations that can manage tools.

visualize(runs: Union[List[str], List[Run]]) None#

Visualize run(s).

Parameters:

run (Union[str, Run]) – Run object or name of the run.

class promptflow.ToolProvider(*args, **kwargs)#

Bases: ABC

The base class of tool class.

classmethod get_initialize_inputs()#
classmethod get_required_initialize_inputs()#
promptflow.load_flow(source: Union[str, PathLike, IO], **kwargs) Flow#

Load flow from YAML file.

Parameters:

source (Union[PathLike, str]) – The local yaml source of a flow. Must be a path to a local file. If the source is a path, it will be open and read. An exception is raised if the file does not exist.

Returns:

A Flow object

Return type:

Flow

promptflow.load_run(source: Union[str, PathLike, IO], params_override: Optional[list] = None, **kwargs) Run#

Load run from YAML file.

Parameters:
  • source (Union[PathLike, str]) – The local yaml source of a run. Must be a path to a local file. If the source is a path, it will be open and read. An exception is raised if the file does not exist.

  • params_override (List[Dict]) – Fields to overwrite on top of the yaml file. Format is [{“field1”: “value1”}, {“field2”: “value2”}]

Returns:

A Run object

Return type:

Run

promptflow.log_metric(key, value, variant_id=None)#

Log a metric for current promptflow run.

Parameters:
  • key (str) – Metric name.

  • value (float) – Metric value.

  • variant_id (str) – Variant id for the metric.

promptflow.start_trace(*, session: Optional[str] = None, **kwargs)#

Start a tracing session.

This will capture OpenAI and prompt flow related calls and persist traces; it will also provide a UI url for user to visualize traces details.

Note that this function is still under preview, and may change at any time.

promptflow.tool(func=None, *, name: Optional[str] = None, description: Optional[str] = None, type: Optional[str] = None, input_settings=None, streaming_option_parameter: Optional[str] = None, **kwargs) Callable#

Decorator for tool functions. The decorated function will be registered as a tool and can be used in a flow.

Parameters:
  • name (str) – The tool name.

  • description (str) – The tool description.

  • type (str) – The tool type.

  • input_settings (Dict[str, promptflow.entities.InputSetting]) – Dict of input setting.

Returns:

The decorated function.

Return type:

Callable

promptflow.trace(func: Optional[Callable] = None) Callable#

A decorator to add trace to a function.

When a function is wrapped by this decorator, the function name, inputs, outputs, start time, end time, and error (if any) will be recorded.

It can be used for both sync and async functions. For sync functions, it will return a sync function. For async functions, it will return an async function.

Parameters:

func (Callable) – The function to be traced.

Returns:

The wrapped function with trace enabled.

Return type:

Callable

Examples:

Synchronous function usage:

@trace
def greetings(user_id):
    name = get_name(user_id)
    return f"Hello, {name}"

Asynchronous function usage:

@trace
async def greetings_async(user_id):
    name = await get_name_async(user_id)
    return f"Hello, {name}"

Subpackages#

Submodules#

class promptflow.exceptions.ErrorCategory(value)#

Bases: str, Enum

An enumeration.

SYSTEM_ERROR = 'SystemError'#
UNKNOWN = 'Unknown'#
USER_ERROR = 'UserError'#
class promptflow.exceptions.ErrorTarget(value)#

Bases: str, Enum

The target of the error, indicates which part of the system the error occurs.

AZURE_RUN_STORAGE = 'AzureRunStorage'#
BATCH = 'Batch'#
CONTROL_PLANE_SDK = 'ControlPlaneSDK'#
EXECUTOR = 'Executor'#
FLOW_EXECUTOR = 'FlowExecutor'#
FLOW_INVOKER = 'FlowInvoker'#
FUNCTION_PATH = 'FunctionPath'#
NODE_EXECUTOR = 'NodeExecutor'#
RUNTIME = 'Runtime'#
RUN_STORAGE = 'RunStorage'#
RUN_TRACKER = 'RunTracker'#
SERVING_APP = 'ServingApp'#
TOOL = 'Tool'#
UNKNOWN = 'Unknown'#
exception promptflow.exceptions.PromptflowException(message='', message_format='', target: ErrorTarget = ErrorTarget.UNKNOWN, module=None, **kwargs)#

Bases: Exception

Base exception for all errors.

Parameters:
  • message (str) – A message describing the error. This is the error message the user will see.

  • target (ErrorTarget) – The name of the element that caused the exception to be thrown.

  • error (Exception) – The original exception if any.

property additional_info#

Return a dict of the additional info of the exception.

By default, this information could usually be empty.

However, we can still define additional info for some specific exception. i.e. For ToolExcutionError, we may add the tool’s line number, stacktrace to the additional info.

property error_codes#

Returns a list of the error codes for this exception.

The error codes is defined the same as the class inheritance. i.e. For ToolExcutionError which inherits from UserErrorException, The result would be [“UserErrorException”, “ToolExecutionError”].

get_arguments_from_message_format(message_format)#

Get the arguments from the message format.

property inner_exception#

Get the inner exception.

The inner exception can be set via either style:

  1. Set via the error parameter in the constructor.

    raise PromptflowException(“message”, error=inner_exception)

  2. Set via raise from statement.

    raise PromptflowException(“message”) from inner_exception

property message#

The error message.

property message_format#

The error message format.

property message_parameters#

The error message parameters.

property module#

The module of the error that occurs.

It is similar to target but is more specific. It is meant to store the Python module name of the code that raises the exception.

property reference_code#

The reference code of the error.

property serializable_message_parameters#

The serializable error message parameters.

property target#

The error target.

Returns:

The error target.

Return type:

ErrorTarget

exception promptflow.exceptions.SystemErrorException(message='', message_format='', target: ErrorTarget = ErrorTarget.UNKNOWN, module=None, **kwargs)#

Bases: PromptflowException

Exception raised when service error is triggered.

exception promptflow.exceptions.UserErrorException(message='', message_format='', target: ErrorTarget = ErrorTarget.UNKNOWN, module=None, **kwargs)#

Bases: PromptflowException

Exception raised when invalid or unsupported inputs are provided.

exception promptflow.exceptions.ValidationException(message='', message_format='', target: ErrorTarget = ErrorTarget.UNKNOWN, module=None, **kwargs)#

Bases: UserErrorException

Exception raised when validation fails.