promptflow.client module#

class promptflow.client.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: Optional[Union[str, PathLike, Callable]] = None, *, 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, resume_from: Optional[Union[str, Run]] = None, code: Optional[Union[str, PathLike]] = None, init: Optional[dict] = 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.

  • resume_from (str) – Create run resume from an existing run.

  • code (Union[str, PathLike]) – Path to the code directory to run.

  • init (dict) – Initialization parameters for flex flow, only supported when flow is callable class.

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[Union[dict, PathLike]] = None, variant: Optional[str] = None, node: Optional[str] = None, environment_variables: Optional[dict] = None, init: Optional[dict] = None) → dict#

Test flow or node.

Parameters:

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

  • inputs (Union[dict, PathLike]) – Input data or json file 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.

  • init (dict) – Initialization parameters for flex flow, only supported when flow is callable class.

Returns:

The result of flow or node

Return type:

dict

property tools: ToolOperations#

Tool operations that can manage tools.

property traces: TraceOperations#

Operations on the trace that can manage traces.

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

Visualize run(s).

Parameters:

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

promptflow.client.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.client.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