{"id":7808,"library":"truss-transfer","title":"Truss Transfer: Baseten Pointer Resolution Utility","description":"Truss-transfer is a Python-optional download utility library for resolving Baseten Pointers (bptr), designed to speed up file transfers within the Baseten ecosystem. It is primarily used internally by the `truss` CLI for serving AI/ML models in production. The current stable version is 0.0.41, with frequent releases often coinciding with updates to the main `truss` library.","status":"active","version":"0.0.41","language":"en","source_language":"en","source_url":"https://github.com/basetenlabs/truss.git","tags":["mlops","baseten","file-transfer","ai-models","model-serving","utility"],"install":[{"cmd":"pip install truss-transfer","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"truss_transfer","correct":"import truss_transfer"},{"note":"Used for defining model repositories for Baseten Pointers.","symbol":"PyModelRepo","correct":"from truss_transfer import PyModelRepo"}],"quickstart":{"code":"import truss_transfer\nimport os\n\n# Example: Define a Hugging Face model repository using PyModelRepo\n# For actual use, 'hf_access_token' would be an environment variable or Baseten secret.\n# Replace 'your-hf-model' with an actual model ID and 'main' with a valid revision.\nhf_model_repo = truss_transfer.PyModelRepo(\n    repo_id=os.environ.get('HF_MODEL_ID', 'microsoft/DialoGPT-medium'),\n    revision=os.environ.get('HF_MODEL_REVISION', 'main'),\n    volume_folder='dialogpt_model_cache',\n    runtime_secret_name='hf_access_token'\n)\n\nprint(f\"Defined Hugging Face model repository: {hf_model_repo.repo_id}\")\n\n# Example: Define a GCS model repository\n# 'gcs-service-account-jsn' would be a Baseten secret containing GCS service account JSON.\ngcs_model_repo = truss_transfer.PyModelRepo(\n    repo_id=os.environ.get('GCS_BUCKET_PATH', 'gs://my-bucket/my-model/'),\n    revision='',\n    volume_folder='gcs_model_cache',\n    runtime_secret_name='gcs-service-account-jsn',\n    kind='gcs'\n)\n\nprint(f\"Defined GCS model repository: {gcs_model_repo.repo_id}\")\n\n# In a typical Truss deployment, these PyModelRepo objects are often used\n# within a `config.yaml` or a `model.py` for model loading and data transfer.\n# This example primarily shows how to instantiate the objects.\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `import truss_transfer` in Python code after `pip install truss-transfer`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"breaking","affected_versions":"0.0.x series"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change the import statement to use an underscore: `import 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.","error":"ModuleNotFoundError: No module named 'truss-transfer'"},{"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.","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.","error":"TypeError: PyModelRepo.__init__() got an unexpected keyword argument 'unsupported_arg'"},{"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.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'bptr://...' when deploying a Truss model"}]}