Skip to content

TrackingClient API Docs

TrackingClient is a lightweight wrapper around MLflow that standardizes how we create and manage experiments and runs, and how we log metrics, parameters, and tags programmatically. All tracked data is surfaced in OICM Platform -> Tracking for centralized visibility, monitoring, and analysis.

Core Concepts

  • Experiment: container for runs inside a workspace.
  • Run: single execution instance that holds params, metrics, tags, artifacts (if applicable).

Quickstart

from oip_tracking_client.v2.tracking import TrackingClient

tc = TrackingClient(
    api_host="OICM-SERVER-URL/api/tracking",
    api_key="***",
)

tc.set_experiment(
    experiment_name="my-first-experiment",
    workspace_id="YOUR_WORKSPACE_ID",
)

with tc.start_run(run_name="smoke_test"):
    tc.log_param("model", "xgboost")
    tc.log_metric("auc", 0.91)

Confirm on OICM (UI)

After running the code above, you should be able to see the experiment and run in the OICM UI.

  1. Open the target Workspace in OICM.
  2. In the left navigation, go to Tracking.
  3. Under Experiments, confirm the experiment my-first-experiment is listed.

Note: it can take a few seconds to appear. Refresh if needed.

  1. Open my-first-experiment to view its runs.
  2. In the Runs list, confirm a run named smoke_test is present.
  3. Open smoke_test to view run details.

On the run page, you should see:

  • Parameters and Tags you logged, shown as key/value metadata.
  • Metrics visualized as charts/time-series.
  • System metrics, for example cpu_utilization, captured alongside your custom metrics.

Usage Guidelines

One client instance per process: Create a single TrackingClient instance per program/process and reuse it. The client maintains process-level tracking context, for example workspace/experiment configuration via shared state such as environment variables. Multiple instances can conflict and lead to mixed or unexpected context.

Recommended call order:

  1. TrackingClient(...)
  2. set_experiment(...)
  3. start_run(...)
  4. Log params/metrics/tags
  5. End run via context manager exit or end_run()

APIs

TrackingClient.init

Summary

Initializes a tracking client for communicating with the tracking backend and configuring online/offline behavior.

Signature

TrackingClient(api_host: str | None = ..., api_key: str | None = ..., path_to_storage: str | None = ..., offline_mode: Optional[bool] = ...) -> None

Parameters

Parameter Type Required Default Description Notes / Constraints
api_host str | None Yes (whenoffline_mode=False) - Tracking API base URL. Must end with/api/tracking. Example: https://oicm.develop.openinnovation.ai/api/tracking
api_key str | None Yes (whenoffline_mode=False) - API key used to authenticate requests. In OICM: top-right user menu ->API Keys -> Generate API key
path_to_storage str | None Yes (whenoffline_mode=True) - Local storage path used for offline logging. Must be a writable directory. Offline runs are stored under<path_to_storage>/ml_runs/.
offline_mode bool | None No False Enables offline behavior whenTrue. WhenTrue, metrics/params are not sent to OICM; they are written to local storage (ml_runs).

TrackingClient.set_experiment

Summary

Sets the active workspace and experiment context used for subsequent run creation and logging. All runs created after this call will appear under the selected workspace and experiment in OICM -> Tracking.

Signature

set_experiment(experiment_name: str, workspace_id: str | None = ...) -> mlflow.entities.Experiment

Parameters

Parameter Type Required Description
experiment_name str Yes Name of the experiment to use, for example"my-first-experiment".
workspace_id str | None Yes Workspace identifier in OICM under which the experiment will be created/selected.

Returns

None

Notes

  • Call this once at startup before calling start_run() or logging metrics/params.
  • set_experiment(...) can be called multiple times within the same process to switch the active experiment context. Any runs started after the call will be created under the newly selected experiment.
  • Recommended: switch experiments only when there is no active run. End the current run or exit the with block before calling set_experiment(...) again to avoid mixed/ambiguous context.
  • If active run present before calling set_experiment, exception will be raised with warning.

Example - switching experiments in the same script

tc.set_experiment("exp_a", workspace_id)

with tc.start_run(run_name="run_in_a"):
    tc.log_metric("m1", 1.0)

tc.set_experiment("exp_b", workspace_id)

with tc.start_run(run_name="run_in_b"):
    tc.log_metric("m1", 2.0)

TrackingClient.start_run

Summary

Starts or resumes a run under the currently active experiment context. You can create a new run, optionally named; continue an existing run by run name; or attach to an existing run by run id.

Signature

start_run(run_id: Optional[str] = ..., run_name: Optional[str] = ..., tags: Optional[list[str]] = ...) -> mlflow.ActiveRun

Parameters

Parameter Type Required Default Description Notes / Constraints
run_id str | None No None Attach to an existing run by ID. If the run does not exist, an exception is raised.
run_name str | None No None Name of the run to create or resume. If a run with the same name already exists in the active experiment, the client continues that run. Otherwise a new run is created with this name.
tags list[str] | None No None Tag names to apply when the run starts. Tags are visible in the run metadata inOICM -> Tracking. If the call attaches to an existing run via run_id or run_name, any tags provided are merged into the run: only tags not already present are added.

Returns

mlflow.ActiveRun

Notes

  • If run_id and run_name are both omitted, a new run is created with an auto-generated name of the form run-<8-char-hash>.
  • If run_name is provided and a run with that name already exists in the currently active experiment, the client continues that run.
  • If run_name is provided and no run with that name exists in the currently active experiment, a new run is created with the provided name.
  • If run_name matches multiple existing runs in the active experiment, a warning is emitted and the client selects the first run from the list of matching runs.
  • If run_id is provided and the run ID exists, the client continues/attaches to that run.
  • If run_id is provided and the run ID does not exist, an exception is raised.
  • If both run_id and run_name are provided, run_id takes precedence. run_name is ignored and a warning is emitted.
  • If tags are provided, they are associated with the selected run and are visible in OICM -> Tracking.
  • If start_run continues an existing run via run_id or run_name and tags are provided, the client merges the tags: any tag that is not already present on the run is added, and tags that already exist are ignored with no duplicates.
  • Note: set_experiment(...) should be called before start_run(...) to ensure runs are created/located in the intended workspace + experiment.

TrackingClient.set_experiment_tags

Summary

Adds one or more tag names to the active experiment. Experiment tags are visible in OICM -> Tracking under the experiment's metadata and help categorize/group experiments.

Signature

TrackingClient.set_experiment_tags(tag_names: list[str]) -> None

Parameters

Parameter Type Required Description Notes / Constraints
tag_names list[str] Yes List of tag names to associate with the active experiment. Requires an active experiment context. Callset_experiment(...) first. Tags are visible in the UI. New tags are added; existing tags are kept with no duplicates.

Notes

  • If no experiment set, exception raised with warning.

TrackingClient.set_run_tags

Summary

Applies one or more tag names to the active run. Tags appear in the run metadata in OICM -> Tracking.

Parameters

Parameter Type Required Description Notes / Constraints
tag_names list[str] Yes List of tag names to associate with the active run. Requires an active run. Use withinwith tc.start_run(...):. New tags are added; existing tags are kept with no duplicates.

Returns

None

Notes

  • If no active runs, exception raised with warning.

TrackingClient.log_param

Summary

Logs a single parameter (key/value) to the active run. Parameters are visible in OICM -> Tracking under the run details.

Signature

TrackingClient.log_param(key: str, value: Any) -> None

Passthrough to mlflow.log_param.

Parameters

Parameter Type Required Description Notes / Constraints
key str Yes Parameter name. Must be a stable identifier, for examplemodel_name or learning_rate.
value Any Yes Parameter value. Values are stored as string-like metadata. Parameter values can be any Python type. Internally, values are persisted as string metadata, which means the value is stored using its string representation.

Returns

None

Notes

  • Requires an active run. Recommended usage is inside with tc.start_run(...):.
  • Parameters show up as key/value metadata in the UI.

TrackingClient.log_params

Summary

Logs multiple parameters to the active run in a single call. This is a convenience method equivalent to calling log_param repeatedly.

Signature

TrackingClient.log_params(params: dict[str, Any]) -> None

Parameters

Parameter Type Required Description Notes / Constraints
params dict[str, Any] Yes Mapping of parameter names to values. Values are stored as string-like metadata. Parameter values can be any Python type. Internally, values are persisted as string metadata, which means the value is stored using its string representation.

TrackingClient.log_metric

Summary

Logs a metric to the active run. Metrics are visualized as charts/time-series in OICM -> Tracking.

Signature

TrackingClient.log_metric(key: str, value: float, step: int | None = ..., timestamp: int | None = ...) -> None

Parameters

Parameter Type Required Description Notes / Constraints
key str Yes Metric name. Use stable names, for exampleloss, accuracy, or auc.
value float Yes Metric value. Metrics can be logged multiple times per run as a time-series.
step int | None No Training step / iteration index. Useful for plotting trends over training steps.
timestamp int | None No Timestamp for the metric point. If provided, should be an epoch timestamp. The implementation expects milliseconds. If omitted, current time is used.

Returns

None

Notes

  • Requires an active run. Recommended usage is inside with tc.start_run(...):.
  • Metrics are additive time-series; you can log the same metric key repeatedly across steps.
  • The latest metric value for each key will be displayed on Overview tab under given run on OICM.

TrackingClient.end_run

Summary

Ends the currently active run and finalizes it so it appears as completed in OICM -> Tracking.

Signature

TrackingClient.end_run(status: str | None = ...) -> None

Parameters

Parameter Type Required Default Description Notes / Constraints
status str No "FINISHED" Terminal status to set when ending the active run. Allowed values:FINISHED (default), FAILED, KILLED.

Returns

None

Notes

  • Ends the active run, if one exists, and updates its status to the value provided.
  • If no run is active, the call is effectively a no-op.
  • Prefer with tc.start_run(...): for automatic run cleanup. Use end_run(status=...) when you need to explicitly mark a run as FAILED or KILLED.

TrackingClient.active_run

Summary

Returns the currently active run if one exists; otherwise returns None.

Signature

TrackingClient.active_run() -> mlflow.ActiveRun | None

Parameters

None

Returns

mlflow.ActiveRun | None

TrackingClient.last_active_run

Summary

Returns the most recent active run in the current process context, if available.

Signature

TrackingClient.last_active_run() -> mlflow.ActiveRun | None

Parameters

None

Returns

mlflow.ActiveRun | None

TrackingClient.get_run

Summary

Fetches run details for a given run ID.

Signature

TrackingClient.get_run(run_id: str) -> mlflow.entities.Run

Passthrough to mlflow.get_run.

Parameters

Parameter Type Required Description Notes / Constraints
run_id str Yes Unique identifier of the run. Use to retrieve run metadata, params, metrics, and tags for an existing run.

Returns

mlflow.entities.Run

Notes

  • This is a read API: it does not start/attach to a run, it only fetches details.
  • If the run ID does not exist or is not accessible, an exception is raised.

TrackingClient.get_experiment_by_name

Summary

Fetches an experiment by its name. Returns the experiment metadata if found, otherwise returns None.

Signature

TrackingClient.get_experiment_by_name(name: str) -> Experiment | None

Parameters

Parameter Type Required Default Description Notes / Constraints
name str Yes - Experiment name to look up. Experiment names are case-sensitive. (MLflow)

Returns

Experiment | None (returns None if not found).

TrackingClient.create_experiment

Summary

Creates a new experiment under the specified workspace and optionally applies experiment tags at creation time. The created experiment is visible in OICM -> Tracking.

Signature

TrackingClient.create_experiment(experiment_name: str, workspace_id: str | None = None, tags: Optional[list[str]] = None) -> mlflow.entities.Experiment

Parameters

Parameter Type Required Default Description Notes / Constraints
experiment_name str Yes - Name of the experiment to create. Use a stable, human-readable name, for examplebaseline-v1 or artifact-tests.
workspace_id str Yes (online_mode) None Workspace in which the experiment will be created. If omitted in online mode (offline_mode=False), exception raised.
tags list[str] | None No None Tag names to apply to the experiment. Tags are visible on the experiment in the UI. Tag updates are additive; duplicates are ignored.

Returns

Experiment - the created experiment object, including its identifier and metadata.

Notes

  • Creates an experiment under the provided workspace_id.
  • If experiment with same name present under workspace, experiment returned.
  • If tags are provided, they are associated with the experiment and appear in OICM -> Tracking.
  • If workspace_id is not provided, the method relies on existing client context, if set.

TrackingClient.delete_experiment

Summary

Deletes an experiment from the backend store by marking it as deleted. The lifecycle stage becomes deleted.

Signature

TrackingClient.delete_experiment(experiment_id: str) -> None

Parameters

Parameter Type Required Default Description
experiment_id str Yes - ID of the experiment to delete.

Returns

None

Behavior

After deletion, the experiment's lifecycle stage is deleted.