dyno-phi

Python SDK and CLI for the Phi protein design API. The phi package exposes synchronous (PhiClient) and asynchronous (AsyncPhiClient) clients; the CLI ships behind the [cli] extra so the SDK stays light. It is published to PyPI from clients/phi in dynotx/phi-api.

Install

The CLI as an isolated tool on your PATH:

uv tool install "dyno-phi[cli]"

uv tool provisions its own Python, which covers the client's Python 3.12+ requirement on stock macOS, where the system Python is 3.9. Re-run with --upgrade to upgrade. pip install "dyno-phi[cli]" into a Python 3.12+ of your own does the same. From a phi-api checkout, just install-cli runs the first form and just install-cli-dev installs the working tree.

The SDK inside an existing project, without the CLI's dependencies:

uv add dyno-phi        # or: pip install dyno-phi

Check the install with phi --version. dyno-phi 0.2.x was an earlier, unrelated client of a retired API; if phi --version prints 0.2.x, that client is first on your PATH (which -a phi lists every match) and pip install --upgrade "dyno-phi[cli]" in the Python that owns it replaces it. Coming from 0.2.x: the key is PHI_API_KEY (or PHI_KEY) and the base URL PHI_API, the commands are phi <group> <command> as listed under CLI, and Python 3.12+ is required; see CHANGELOG.md.

If uv's tool directory is behind another phi on PATH, sourcing uv's shell shim is not enough to move it: the shim prepends the directory only when PATH does not already contain it, and on macOS path_helper appends inherited entries behind /etc/paths.d, so in a shell that inherits a PATH naming the directory it stays last. Pin the order at the end of ~/.zshrc:

typeset -U path PATH
path=("$HOME/.local/bin" $path)

Authentication

Both the SDK and the CLI read connection settings from the environment, falling back to ~/.config/phi/config.toml:

export PHI_API=https://phi-api-staging-917387676927.us-central1.run.app
export PHI_KEY=...     # static staging key
export PHI_ORG=dynotx  # literal static tenant, not the Clerk org

With a Clerk key (ak_...) the tenant comes from the key, so PHI_ORG is ignored; it is required only for a static key.

Pass base_url=, api_key=, and org= to the client constructor to override the environment.

60-second quickstart

phi quickstart

Creates the quickstart project, folds the Trp-cage mini-protein with ESMFOLD, waits, and downloads the results. The manual equivalent is:

phi jobs submit ESMFOLD --input sequences=@sequence.fasta --wait --out quickstart-output

SDK usage

Submit a job and wait for it, closing the client on exit:

from phi import PhiClient

with PhiClient() as client:
    submitted = client.jobs.submit("ESMFOLD", inputs={"sequences": ["NLYIQWLKDGGPSSGRPPPS"]})
    job = client.jobs.wait(submitted.job_id)
    print(job.status, job.outputs)

AsyncPhiClient mirrors the same surface for concurrent work:

import asyncio

from phi import AsyncPhiClient


async def fold(sequences: list[str]) -> list[str]:
    async with AsyncPhiClient() as client:
        submitted = await asyncio.gather(
            *(client.jobs.submit("ESMFOLD", inputs={"sequences": [seq]}) for seq in sequences)
        )
        jobs = await asyncio.gather(*(client.jobs.wait(job.job_id) for job in submitted))
    return [job.status for job in jobs]


asyncio.run(fold(["NLYIQWLKDGGPSSGRPPPS", "GSHMKELVLALYDYQEKSPRE"]))

Runnable end-to-end scripts live in examples/: single fold job, named pipeline, ad-hoc DAG, artifact download, and concurrent async submission.

Job types and local validation

client.job_types lists the job types the API advertises and the JSON Schema for each one's params and inputs. Schemas are cached on disk per host for 24 hours; pass refresh=True to refetch.

client.job_types.validate_params("PROTEINMPNN", {"num_seq_per_target": 8})

validate_params and validate_inputs raise PhiValidationError on a bad key, type, enum value, or numeric range. They are a shallow pre-flight check: top-level keys only, with no descent into nested objects or array items. The server validates fully, so a clean pass locally is not a guarantee the request will be accepted.

Knowledge documents

client.documents and AsyncPhiClient.documents list, read, search, write, and review tenant-scoped Markdown documents. Use iter_documents() and iter_versions() to follow cursor pages. Updates take the active digest as if_digest; a stale value raises PhiConflictError. propose() creates a draft that remains outside active reads and search until a document writer calls activate().

CLI

Every command reads the same environment and accepts --json for scripting.

phi docs sync <dir> --dry-run safely plans publication from a clean knowledge checkout. Without --dry-run it publishes only Git-tracked files in the authored Markdown layer after the checkout's deny-list guard passes, defaults platform documents to internal access, and skips unchanged content and access. It does not delete remote-only documents.

Full reference

See docs/sdk-and-cli.md for environment and profile resolution, sync/async parity, the complete CLI reference, the error taxonomy and how a release is cut.