Total Perspective Vortex

3.2.1 verified Fri May 01 auth: no python

A library for routing entities (jobs, users or groups) to destinations in Galaxy. Current version is 3.2.1, released in April 2025. Release cadence is irregular with multiple minor releases per year.

pip install total-perspective-vortex

Common errors

error ModuleNotFoundError: No module named 'total_perspective_vortex' ↓

cause Running Python environment without the package installed, or using wrong Python interpreter.

fix

Run pip install total-perspective-vortex in the same environment. Check with python -c "import total_perspective_vortex; print(total_perspective_vortex.__version__)".

error pydantic.error_wrappers.ValidationError: 1 validation error for TPVConfig config -> destinations -> ... ↓

cause Configuration YAML has invalid structure or type mismatch (e.g., string instead of integer for memory).

fix

Validate config with tpv validate --config path/to/config.yml and fix errors according to schema.

error KeyError: 'destination_id' ↓

cause Route returned a destination with a missing or incorrectly spelled key in the entity or routing rules.

fix

Check that destination IDs in your config match those referenced in routing rules. Use tpv dry-run --explain to trace decision.

Warnings

breaking Version 3.0.0 changed the TPV shared database URL. Old short links point to db-v1 which is frozen. Use https://gxy.io/tpv/db-v2.yml for latest v2 database or fork your own. ↓

fix Update config to use new database URL: https://gxy.io/tpv/db-v2.yml

deprecated Pydantic v1-style class Config is deprecated since v3.2.1. Replace with ConfigDict (Pydantic v2). ↓

fix Replace `class Config` with `model_config = ConfigDict(...)` in your custom models.

gotcha The entity 'tool_type' tag is automatically set for special tool types (e.g., 'data_source'). This can override user-set tool_type attributes unexpectedly. ↓

fix Check if tool is being automatically tagged; manually set tool_type in config after loading.

gotcha Jinja2 templates in configuration are evaluated at load time; syntax errors or missing variables cause silent failures or unexpected defaults. ↓

fix Test templates separately and use tpv validate command to catch errors early.

Imports

TPVConfigLoader
wrong
```
from tpv.config import TPVConfigLoader
```
correct
```
from total_perspective_vortex.config import TPVConfigLoader
```
Package name uses underscores, not hyphens, but tpv is not importable directly.

Quickstart

Basic usage: create an entity, load a router, and route to a destination.

from total_perspective_vortex.entities import Entity
from total_perspective_vortex.routing import Router

# Define an entity (e.g., a job)
entity = Entity(
    id="job-123",
    tool_id="toolshed.g2.bx.psu.edu/repos/devteam/fastqc/fastqc/0.11.9",
    user="alice"
)

# Initialize router with config path
router = Router(config_path="tpv_config.yml")

# Route entity to destination
destination = router.route(entity)
print(destination)