Truss Transfer: Baseten Pointer Resolution Utility

Common errors

• ModuleNotFoundError: No module named 'truss-transfer'

  cause The Python import statement uses a hyphen, which is invalid for module names. The PyPI package name `truss-transfer` is installed, but the corresponding importable module uses an underscore.
  fix Change the import statement to use an underscore: `import truss_transfer`.

• TypeError: PyModelRepo.__init__() got an unexpected keyword argument 'unsupported_arg'

  cause The `PyModelRepo` class constructor arguments have changed or an unrecognized argument is being passed. This often happens with minor version updates due to the library's active development.
  fix Consult the latest `truss-transfer` or Baseten `truss` documentation (specifically `PyModelRepo` usage) for the correct set of parameters. Remove or update the offending keyword argument.

• FileNotFoundError: [Errno 2] No such file or directory: 'bptr://...' when deploying a Truss model

  cause The Baseten Pointer (bptr) specified in the `PyModelRepo` or `config.yaml` cannot be resolved or accessed by `truss-transfer`. This can be due to incorrect `repo_id`, missing credentials (e.g., `runtime_secret_name` not configured on Baseten), or network issues.
  fix Verify the `repo_id` is correct and accessible from the Baseten environment. Ensure that any specified `runtime_secret_name` (e.g., `hf_access_token`, `gcs-service-account-jsn`) is correctly configured and available within your Baseten workspace. Check network connectivity if deploying to a custom environment.

Warnings

• gotcha Direct standalone usage of `truss-transfer` is uncommon for end-users. It is primarily an internal dependency and utility for the `truss` CLI and Baseten platform. Attempting to use it outside this context without a clear understanding of Baseten Pointers (bptr) and `truss` deployment mechanisms may not yield expected results.
  Fix: Focus on using the main `truss` CLI for model deployment. `truss-transfer`'s functionality is integrated into `truss`'s model serving and data transfer processes. Consult Baseten's official `truss` documentation for model deployment workflows.
• gotcha The package name on PyPI is `truss-transfer`, but the primary import is `truss_transfer` (with an underscore). Mismatched naming conventions between PyPI and import statements are a common source of `ModuleNotFoundError`.
  Fix: Always use `import truss_transfer` in Python code after `pip install truss-transfer`.
• breaking Since `truss-transfer` is frequently updated and tightly coupled with the `truss` library and Baseten platform, new versions might introduce subtle changes in `PyModelRepo` parameters or expected behavior without explicit major version bumps. This is particularly relevant when `truss-transfer` is bundled with `truss`.
  Fix: When `truss-transfer` is a direct dependency in a `truss` project, ensure `truss` and `truss-transfer` versions are compatible. Refer to the Baseten `truss` documentation and release notes for any specific version requirements or migration guides. Regularly update both `truss` and `truss-transfer` to their latest stable versions.

Install

• pip install truss-transfer Install stable version

Imports

• truss_transfer

  import truss_transfer

• PyModelRepo

  from truss_transfer import PyModelRepo

  Used for defining model repositories for Baseten Pointers.

Quickstart

This quickstart demonstrates how to define `PyModelRepo` objects, which are central to `truss-transfer`'s functionality. These objects specify how to fetch model artifacts from sources like Hugging Face or Google Cloud Storage, often managed as Baseten Pointers (bptr) for deployment with the main `truss` library.

import truss_transfer
import os

# Example: Define a Hugging Face model repository using PyModelRepo
# For actual use, 'hf_access_token' would be an environment variable or Baseten secret.
# Replace 'your-hf-model' with an actual model ID and 'main' with a valid revision.
hf_model_repo = truss_transfer.PyModelRepo(
    repo_id=os.environ.get('HF_MODEL_ID', 'microsoft/DialoGPT-medium'),
    revision=os.environ.get('HF_MODEL_REVISION', 'main'),
    volume_folder='dialogpt_model_cache',
    runtime_secret_name='hf_access_token'
)

print(f"Defined Hugging Face model repository: {hf_model_repo.repo_id}")

# Example: Define a GCS model repository
# 'gcs-service-account-jsn' would be a Baseten secret containing GCS service account JSON.
gcs_model_repo = truss_transfer.PyModelRepo(
    repo_id=os.environ.get('GCS_BUCKET_PATH', 'gs://my-bucket/my-model/'),
    revision='',
    volume_folder='gcs_model_cache',
    runtime_secret_name='gcs-service-account-jsn',
    kind='gcs'
)

print(f"Defined GCS model repository: {gcs_model_repo.repo_id}")

# In a typical Truss deployment, these PyModelRepo objects are often used
# within a `config.yaml` or a `model.py` for model loading and data transfer.
# This example primarily shows how to instantiate the objects.