Truefoundry.Ml

​

module TrueFoundry.ml

​

Global Variables

• TRACKING_HOST_GLOBAL

​

function get_client

• disable_analytics (bool, optional): To turn off usage analytics collection, pass True. By default, this is set to False.

• MLFoundry: Instance of MLFoundry class which represents a run.

• Get client

import truefoundry.ml as tfm

client = tfm.get_client()

​

class MlFoundry

​

function create_data_directory

• ml_repo (str): Name of the ML Repo in which you want to create data_directory
• name (str): Name of the DataDirectory to be created.
• description (str): Description of the Datset
• metadata (Dict <str>: Any): Metadata about the data_directory in Dictionary form.

• DataDirectory: An instance of DataDirectory class

import truefoundry.ml as tfm

client = tfm.get_client()
data_directory = client.create_data_directory(name="<data_directory-name>", ml_repo="<repo-name>")
print(data_directory.fqn)

​

function create_ml_repo

• name (str, optional): The name of the Repository you want to create. if not given, it creates a name by itself.
• storage_integration_fqn (str): The storage integration FQN to use for the experiment for saving artifacts.

• Create Repository

import truefoundry.ml as tfm

client = tfm.get_client()

ml_repo = client.create_ml_repo(name="my-repo", storage_integration_fqn="truefoundry:example:name:blob-storage:blob")

​

function create_run

• ml_repo (str): The name of the project under which the run will be created. ml_repo should only contain alphanumerics (a-z,A-Z,0-9) or hyphen (-). The user must have ADMIN or WRITE access to this project.
• run_name (Optional[str], optional): The name of the run. If not passed, a randomly generated name is assigned to the run. Under a project, all runs should have a unique name. If the passed run_name is already used under a project, the run_name will be de-duplicated by adding a suffix. run name should only contain alphanumerics (a-z,A-Z,0-9) or hyphen (-).
• tags (Optional[Dict[str, Any]], optional): Optional tags to attach with this run. Tags are key-value pairs.

• MlFoundryRun: An instance of MlFoundryRun class which represents a run

• Create a run under current user.

import truefoundry.ml as tfm

client = tfm.get_client()

tags = {"model_type": "svm"}
run = client.create_run(
     ml_repo="my-classification-project", run_name="svm-with-rbf-kernel", tags=tags
)

run.end()

• Creating a run using context manager.

import truefoundry.ml as tfm

client = tfm.get_client()
with client.create_run(
     ml_repo="my-classification-project", run_name="svm-with-rbf-kernel"
) as run:
     # ...
     # Model training code
     ...
# `run` will be automatically marked as `FINISHED` or `FAILED`.

• Create a run in a project owned by a different user.

import truefoundry.ml as tfm

client = tfm.get_client()

tags = {"model_type": "svm"}
run = client.create_run(
     ml_repo="my-classification-project",
     run_name="svm-with-rbf-kernel",
     tags=tags,
)
run.end()

​

function get_all_runs

• ml_repo (str): Name of the project.

• pd.DataFrame: dataframe with two columns- run_id and run_name

• get all the runs from a ml_repo

import truefoundry.ml as tfm

client = tfm.get_client()

run = client.get_all_runs(ml_repo='my-repo')

​

function get_artifact_version

• ml_repo (str): ML Repo to which artifact is logged
• artifact_name (str): Artifact Name
• artifact_type (str): The type of artifact to fetch (acceptable values: “artifact”, “model”, “plot”, “image”)
• version (str | int): Artifact Version to fetch (default is the latest version)

• ArtifactVersion: An ArtifactVersion instance of the artifact

import tempfile
import truefoundry.ml as tfm

client = tfm.get_client()
model_version = client.get_artifact_version(ml_repo="ml-repo-name", name="artifact-name", version=1)

# load the model into memory
clf = model_version.load()

# download the model to disk
temp = tempfile.TemporaryDirectory()
download_info = model_version.download(path=temp.name)
print(download_info)

​

function get_artifact_version_by_fqn

• fqn (str): Fully qualified name of the artifact version.

• ArtifactVersion: An ArtifactVersion instance of the artifact

import tempfile
import truefoundry.ml as tfm

client = tfm.get_client()
artifact_version = client.get_artifact_version_by_fqn(
     fqn="artifact:truefoundry/my-classification-project/sklearn-artifact:1"
)

# download the artifact to disk
temp = tempfile.TemporaryDirectory()
download_info = artifact_version.download(path=temp.name)
print(download_info)

​

function get_data_directory

• ml_repo (str): name of an the project of which the data-directory is part of.
• name (str): the name of the data-directory

• DataDirectory: An instance of DataDirectory class

import truefoundry.ml as tfm
client = tfm.get_client()
data_directory = client.get_data_directory(ml_repo='my-repo', name="<data-directory-name>")
with open("artifact.txt", "w") as f:
     f.write("hello-world")
data_directory.add_files(
     artifact_paths=[tfm.DataDirectoryPath('artifact.txt', 'a/b/')]
)
# print the path of files and folder in the data_directory
for file in data_directory.list_files():
     print(file.path)

​

function get_data_directory_by_fqn

• fqn (str): Fully qualified name of the artifact version.

• DataDirectory: An instance of DataDirectory class

import truefoundry.ml as tfm

client = tfm.get_client()
data_directory = client.get_data_directory_by_fqn(fqn="<data-dir-fqn>")
with open("artifact.txt", "w") as f:
     f.write("hello-world")

data_directory.add_files(
     artifact_paths=[tfm.DataDirectoryPath('artifact.txt', 'a/b/')]
)
# print the path of files and folder in the data_directory
for file in data_directory.list_files():
     print(file.path)

​

function get_data_directory_by_id

• id (uuid.UUID): Id of the data_directory.

• DataDirectory: An instance of DataDirectory class

import truefoundry.ml as tfm

client = tfm.get_client()
data_directory = client.get_data_directory_by_id(id="<data_directory-id>")
with open("artifact.txt", "w") as f:
     f.write("hello-world")

data_directory.add_files(
     artifact_paths=[tfm.DataDirectoryPath('artifact.txt', 'a/b/')]
)
# print the path of files and folder in the data_directory
for file in data_directory.list_files():
     print(file.path)

​

function get_model_version

• ml_repo (str): ML Repo to which model is logged
• name (str): Model Name
• version (str | int): Model Version to fetch (default is the latest version)

• ModelVersion: A ModelVersion instance of the model

• Sklearn

# See `truefoundry.ml.mlfoundry_api.MlFoundry.log_model` examples to understand model logging
import tempfile
import joblib
import truefoundry.ml as tfm

client = tfm.get_client()
model_version = client.get_model_version(
    ml_repo="my-classification-project",
    name="my-sklearn-model",
    version=1
)

# Download the model to disk
temp = tempfile.TemporaryDirectory()
download_info = model_version.download(path=temp.name)
print(download_info.model_dir, download_info.model_filename)

# Deserialize and Load
model = joblib.load(
    os.path.join(download_info.model_dir, download_info.model_filename)
)

• Huggingface Transformers

# See `truefoundry.ml.mlfoundry_api.MlFoundry.log_model` examples to understand model logging
import torch
from transformers import pipeline

import truefoundry.ml as tfm

client = tfm.get_client()
model_version = client.get_model_version(
    ml_repo="my-llm-project",
    name="my-transformers-model",
    version=1
)

# Download the model to disk
temp = tempfile.TemporaryDirectory()
download_info = model_version.download(path=temp.name)
print(download_info.model_dir)

# Deserialize and Load
pln = pipeline("text-generation", model=download_info.model_dir, torch_dtype=torch.float16)

​

function get_model_version_by_fqn

• fqn (str): Fully qualified name of the model version.

• ModelVersion: A ModelVersion instance of the model

• Sklearn

# See `truefoundry.ml.mlfoundry_api.MlFoundry.log_model` examples to understand model logging
import tempfile
import joblib
import truefoundry.ml as tfm

client = tfm.get_client()
model_version = client.get_model_version_by_fqn(
     fqn="model:truefoundry/my-classification-project/my-sklearn-model:1"
)

# Download the model to disk
temp = tempfile.TemporaryDirectory()
download_info = model_version.download(path=temp.name)
print(download_info.model_dir, download_info.model_filename)

# Deserialize and Load
model = joblib.load(
     os.path.join(download_info.model_dir, download_info.model_filename)
)

• Huggingface Transformers

# See `mlfoundry.mlfoundry_api.MlFoundry.log_model` examples to understand model logging
import torch
from transformers import pipeline

import truefoundry.ml as tfm

client = tfm.get_client()
model_version = client.get_model_version_by_fqn(
     fqn="model:truefoundry/my-llm-project/my-transformers-model:1"
)
# Download the model to disk
temp = tempfile.TemporaryDirectory()
download_info = model_version.download(path=temp.name)
print(download_info.model_dir)

# Deserialize and Load
pln = pipeline("text-generation", model=download_info.model_dir, torch_dtype=torch.float16)

​

function get_run_by_fqn

• run_fqn (str): fqn of an existing run.

• MlFoundryRun: An instance of MlFoundryRun class which represents a run

• get run by run fqn

import truefoundry.ml as tfm

client = tfm.get_client()

run = client.get_run_by_fqn(run_fqn='truefoundry/my-repo/svm')

​

function get_run_by_id

• run_id (str): run_id or fqn of an existing run.

• MlFoundryRun: An instance of MlFoundryRun class which represents a run

• Get run by the run id

import truefoundry.ml as tfm

client = tfm.get_client()

run = client.get_run_by_id(run_id='a8f6dafd70aa4baf9437a33c52d7ee90')

​

function get_run_by_name

• ml_repo (str): name of the ml_repo of which the run is part of.
• run_name (str): the name of the run required

• MlFoundryRun: An instance of MlFoundryRun class which represents a run

• get run by name

import truefoundry.ml as tfm

client = tfm.get_client()

run = client.get_run_by_name(run_name='svm', ml_repo='my-repo')

​

function get_tracking_uri

import tempfile
import truefoundry.ml as tfm

client = tfm.get_client()
tracking_uri = client.get_tracking_uri()
print("Current tracking uri: {}".format(tracking_uri))

​

function list_artifact_versions

• ml_repo (str): Repository in which the model is stored.
• name (str): Name of the artifact whose version is required
• artifact_type (ArtifactType): Type of artifact you want for example model, image, etc.

• Iterator[ArtifactVersion]: An iterator that yields non-deleted artifact versions of an artifact under a given ml_repo, sorted in reverse by version number

import truefoundry.ml as tfm

client = tfm.get_client()
artifact_versions = client.list_artifact_versions(ml_repo="my-repo", name="artifact-name")

for artifact_version in artifact_versions:
     print(artifact_version)

​

function list_artifact_versions_by_fqn

• artifact_fqn: FQN of the Artifact to list versions for.
• An artifact_fqn looks like {artifact_type}`: {org}/{user}/{project}/{artifact_name}`
• or {artifact_type}`: {user}/{project}/{artifact_name}`

• Iterator[ArtifactVersion]: An iterator that yields non-deleted artifact versions under the given artifact_fqn, sorted in reverse by version number

• ArtifactVersion: An instance of mlfoundry.ArtifactVersion

import truefoundry.ml as tfm

tfm.login(tracking_uri=https://your.truefoundry.site.com")
client = tfm.get_client()
artifact_fqn = "artifact:org/my-project/my-artifact"
for av in client.list_artifact_versions(artifact_fqn=artifact_fqn):
     print(av.name, av.version, av.description)

​

function list_data_directories

• ml_repo (str): Name of the ML Repository
• max_results (int): Maximum number of Data Directory to list
• offset (int): Skip these number of instance of DataDirectory and then give the result from these number onwards

• Iterator[DataDirectory]: An iterator that yields DataDirectory instances

import truefoundry.ml as tfm

client = tfm.get_client()
data_directories = client.list_data_directories(ml_repo="<ml-repo-nam>")

for data_directory in data_directories:
     print(data_directory.name)

​

function list_ml_repos

• List[str]: A list of names of ML Repos

​

function list_model_versions

• ml_repo (str): Repository in which the model is stored.
• name (str): Name of the model whose version is required

• Iterator[ModelVersion]: An iterator that yields non-deleted model versions of a model under a given ml_repo, sorted in reverse by version number

import truefoundry.ml as tfm

client = tfm.get_client()
model_versions = client.list_model_version(ml_repo="my-repo", name="svm")

for model_version in model_versions:
     print(model_version)

​

function list_model_versions_by_fqn

• model_fqn: FQN of the Model to list versions for.
• A model_fqn looks like model`: {org}/{user}/{project}/{artifact_name}`
• or model`: {user}/{project}/{artifact_name}`

• Iterator[ModelVersion]: An iterator that yields non-deleted model versions under the given model_fqn, sorted in reverse by version number

• ModelVersion: An instance of mlfoundry.ModelVersion

import truefoundry.ml as tfm

mlfoundry.login(tracking_uri="https://your.truefoundry.site.com")
client = tfm.get_client()
model_fqn = "model:org/my-project/my-model"
for mv in client.list_model_versions(model_fqn=model_fqn):
     print(mv.name, mv.version, mv.description)

​

function log_artifact

• ml_repo (str): Name of the ML Repo to which an artifact is to be logged.
• name (str): Name of the Artifact. If an artifact with this name already exists under the current ml_repo, the logged artifact will be added as a new version under that name. If no artifact exist with the given name, the given artifact will be logged as version 1.
• artifact_paths (List[truefoundry.ml.ArtifactPath], optional): A list of pairs of (source path, destination path) to add files and folders to the artifact version contents. The first member of the pair should be a file or directory path and the second member should be the path inside the artifact contents to upload to.

         E.g. >>> client.log_artifact(
              ...     ml_repo="sample-repo",
              ...     name="xyz",
              ...     artifact_paths=[
                         tfm.ArtifactPath("foo.txt", "foo/bar/foo.txt"),
                         tfm.ArtifactPath("tokenizer/", "foo/tokenizer/"),
                         tfm.ArtifactPath('bar.text'),
                         ('bar.txt', ),
                         ('foo.txt', 'a/foo.txt')
                      ]
              ... )
         would result in
         .
         └── foo/
             ├── bar/
             │   └── foo.txt
             └── tokenizer/
                 └── # contents of tokenizer/ directory will be uploaded here

• description (Optional[str], optional): arbitrary text upto 1024 characters to store as description. This field can be updated at any time after logging. Defaults to None
• metadata (Optional[Dict[str, Any]], optional): arbitrary json serializable dictionary to store metadata. For example, you can use this to store metrics, params, notes. This field can be updated at any time after logging. Defaults to None

• truefoundry.ml.ArtifactVersion: an instance of ArtifactVersion that can be used to download the files, or update attributes like description, metadata.

import os
import truefoundry.ml as tfm

with open("artifact.txt", "w") as f:
     f.write("hello-world")

client = tfm.get_client()
ml_repo = "sample-repo"

client.create_ml_repo(ml_repo=ml_repo)
client.log_artifact(
     ml_repo=ml_repo,
     name="hello-world-file",
     artifact_paths=[tfm.ArtifactPath('artifact.txt', 'a/b/')]
)

​

function log_model

• ml_repo (str): Name of the ML Repo to which an artifact is to be logged.
• name (str): Name of the model. If a model with this name already exists under the current ML Repo, the logged model will be added as a new version under that name. If no models exist with the given name, the given model will be logged as version 1.
• model_file_or_folder (str): Path to either a single file or a folder containing model files. This folder is usually created using serialization methods of libraries or frameworks e.g. joblib.dump, model.save_pretrained(...), torch.save(...), model.save(...)
• framework (Union[enums.ModelFramework, str]): Model Framework. Ex:- pytorch, sklearn, tensorflow etc. The full list of supported frameworks can be found in mlfoundry.enums.ModelFramework. Can also be None when model is None.
• description (Optional[str], optional): arbitrary text upto 1024 characters to store as description. This field can be updated at any time after logging. Defaults to None
• metadata (Optional[Dict[str, Any]], optional): arbitrary json serializable dictionary to store metadata. For example, you can use this to store metrics, params, notes. This field can be updated at any time after logging. Defaults to None

• truefoundry.ml.ModelVersion: an instance of ModelVersion that can be used to download the files, load the model, or update attributes like description, metadata, schema.

• Sklearn

import truefoundry.ml as tfm
from truefoundry.ml import ModelFramework

import joblib
import numpy as np
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.svm import SVC

X = np.array([[-1, -1], [-2, -1], [1, 1], [2, 1]])
y = np.array([1, 1, 2, 2])
clf = make_pipeline(StandardScaler(), SVC(gamma='auto'))
clf.fit(X, y)
joblib.dump(clf, "sklearn-pipeline.joblib")

client = tfm.get_client()
client.create_ml_repo(  # This is only required once
     ml_repo="my-classification-project",
     # This controls which bucket is used.
     # You can get this from Integrations > Blob Storage. `None` picks the default
     storage_integration_fqn=None
)
model_version = client.log_model(
     ml_repo="my-classification-project",
     name="my-sklearn-model",
     model_file_or_folder="sklearn-pipeline.joblib",
     framework=ModelFramework.SKLEARN,
     metadata={"accuracy": 0.99, "f1": 0.80},
     step=1,  # step number, useful when using iterative algorithms like SGD
)
print(model_version.fqn)

• Huggingface Transformers

import truefoundry.ml as tfm
from truefoundry.ml import ModelFramework

import torch
from transformers import AutoTokenizer, AutoConfig, pipeline, AutoModelForCausalLM
pln = pipeline(
     "text-generation",
     model_file_or_folder="EleutherAI/pythia-70m",
     tokenizer="EleutherAI/pythia-70m",
     torch_dtype=torch.float16
)
pln.model.save_pretrained("my-transformers-model")
pln.tokenizer.save_pretrained("my-transformers-model")

client = tfm.get_client()
client.create_ml_repo(  # This is only required once
     ml_repo="my-llm-project",
     # This controls which bucket is used.
     # You can get this from Integrations > Blob Storage. `None` picks the default
     storage_integration_fqn=None
)
model_version = client.log_model(
     ml_repo="my-llm-project",
     name="my-transformers-model",
     model_file_or_folder="my-transformers-model/",
     framework=ModelFramework.TRANSFORMERS
)
print(model_version.fqn)

​

class ArtifactVersion

​

Properties

• fqn (str): Fully qualified name of the artifact version
• name (str): Name of the artifact
• version (int): Version number of the artifact
• description (str): Description of the artifact version
• metadata (Dict[str, Any]): Metadata associated with the artifact version
• created_at (datetime): Timestamp when the artifact version was created
• updated_at (datetime): Timestamp when the artifact version was last updated

​

Methods

• download(path: str) -> DownloadInfo: Download the artifact to a local path
• load() -> Any: Load the artifact into memory (for supported types)

​

class ModelVersion

​

Properties

• fqn (str): Fully qualified name of the model version
• name (str): Name of the model
• version (int): Version number of the model
• description (str): Description of the model version
• metadata (Dict[str, Any]): Metadata associated with the model version
• framework (str): Framework used for the model (e.g., sklearn, pytorch)
• created_at (datetime): Timestamp when the model version was created
• updated_at (datetime): Timestamp when the model version was last updated

​

Methods

• download(path: str) -> DownloadInfo: Download the model to a local path
• load() -> Any: Load the model into memory (for supported frameworks)

​

class DataDirectory

​

Properties

• fqn (str): Fully qualified name of the data directory
• name (str): Name of the data directory
• description (str): Description of the data directory
• metadata (Dict[str, Any]): Metadata associated with the data directory
• created_at (datetime): Timestamp when the data directory was created
• updated_at (datetime): Timestamp when the data directory was last updated

​

Methods

• add_files(artifact_paths: List[DataDirectoryPath]): Add files to the data directory
• list_files() -> Iterator[DataDirectoryFile]: List all files in the data directory
• download(path: str) -> DownloadInfo: Download the data directory to a local path

​

class MlFoundryRun

​

Properties

• fqn (str): Fully qualified name of the run
• name (str): Name of the run
• run_id (str): Unique identifier for the run
• status (str): Current status of the run (RUNNING, FINISHED, FAILED)
• start_time (datetime): Timestamp when the run started
• end_time (datetime): Timestamp when the run ended (if finished)
• tags (Dict[str, Any]): Tags associated with the run

​

Methods

• log_metrics(metric_dict: Dict[str, float]): Log metrics for the run
• log_params(params_dict: Dict[str, Any]): Log parameters for the run
• log_artifact(name: str, artifact_paths: List[ArtifactPath]): Log an artifact
• log_model(name: str, model_file_or_folder: str, framework: str): Log a model
• end(): Mark the run as finished

​

function search_runs

• ml_repo (str): Name of the project. filter_string (str, optional): Filter query string, defaults to searching all runs. Identifier required in the LHS of a search expression.
• Signifies an entity to compare against. An identifier has two parts separated by a period: the type of the entity and the name of the entity. The type of the entity is metrics, params, attributes, or tags. The entity name can contain alphanumeric characters and special characters.
• You can search using two run attributes : status and artifact_uri. Both attributes have string values. When a metric, parameter, or tag name contains a special character like hyphen, space, period, and so on, enclose the entity name in double quotes or backticks, params.”model-type” or params.model-type
• run_view_type (str, optional): one of the following values “ACTIVE_ONLY”, “DELETED_ONLY”, or “ALL” runs. order_by (List[str], optional): List of columns to order by (e.g., “metrics.rmse”). Currently supported values are metric.key, parameter.key, tag.key, attribute.key. The order_by column can contain an optional DESC or ASC value. The default is ASC. The default ordering is to sort by start_time DESC.
• job_run_name (str): Name of the job which are associated with the runs to get that runs
• max_results (int): max_results on the total numbers of run yielded through filter

• Iterator[MlFoundryRun]: An iterator that yields MLFoundryRun instances matching the search query

import truefoundry.ml as tfm

client = tfm.get_client()
with client.create_run(ml_repo="my-project", run_name="run-1") as run1:
     run1.log_metrics(metric_dict={"accuracy": 0.74, "loss": 0.6})
     run1.log_params({"model": "LogisticRegression", "lambda": "0.001"})

with client.create_run(ml_repo="my-project", run_name="run-2") as run2:
     run2.log_metrics(metric_dict={"accuracy": 0.8, "loss": 0.4})
     run2.log_params({"model": "SVM"})

# Search for the subset of runs with logged accuracy metric greater than 0.75
filter_string = "metrics.accuracy > 0.75"
runs = client.search_runs(ml_repo="my-project", filter_string=filter_string)

# Search for the subset of runs with logged accuracy metric greater than 0.7
filter_string = "metrics.accuracy > 0.7"
runs = client.search_runs(ml_repo="my-project", filter_string=filter_string)

# Search for the subset of runs with logged accuracy metric greater than 0.7 and model="LogisticRegression"
filter_string = "metrics.accuracy > 0.7 and params.model = 'LogisticRegression'"
runs = client.search_runs(ml_repo="my-project", filter_string=filter_string)

# Search for the subset of runs with logged accuracy metric greater than 0.7 and
# order by accuracy in Descending order
filter_string = "metrics.accuracy > 0.7"
order_by = ["metric.accuracy DESC"]
runs = client.search_runs(
     ml_repo="my-project", filter_string=filter_string, order_by=order_by
)

filter_string = "metrics.accuracy > 0.7"
runs = client.search_runs(
     ml_repo="transformers", order_by=order_by ,job_run_name='job_run_name', filter_string=filter_string
)

order_by = ["metric.accuracy DESC"]
runs = client.search_runs(
     ml_repo="my-project", filter_string=filter_string, order_by=order_by, max_results=10
)