biolm package

Subpackages

Submodules

biolm.client module

BioLM convenience client and HTTP client re-exports.

class biolm.client.AsyncRateLimiter(max_calls: int, period: float)

Bases: object

limit()

class biolm.client.BioLM(*, entity: str, action: str, type: str | None = None, items: Any | List[Any], params: dict | None = None, api_key: str | None = None, **kwargs)

Bases: object

Universal client for BioLM API.

This is a convenience wrapper that creates a client, makes the request, and returns the result. For long-running operations or when making multiple requests, consider using BioLMApiClient (async) or BioLMApi (sync) directly with proper cleanup via context managers or shutdown().

Args:

entity (str): The entity name (model, database, calculation, etc). action (str): The action to perform (e.g., ‘generate’, ‘encode’, ‘predict’, ‘search’, ‘finetune’). type (str): The type of item (e.g., ‘sequence’, ‘pdb’, ‘fasta_str’). item (Union[Any, List[Any]]): The item(s) to process. params (Optional[dict]): Optional parameters for the action. raise_httpx (bool): Whether to raise HTTPX errors. stop_on_error (bool): Stop on first error if True. output (str): ‘memory’ or ‘disk’. file_path (Optional[str]): Output file path if output=’disk’. api_key (Optional[str]): API key for authentication. compress_requests (bool): Enable gzip compression for POST requests. Default: True. compress_threshold (int): Minimum payload size in bytes to trigger compression. Default: 256.

run() → Any

Run the specified action on the entity with the given item(s).

biolm.client.BioLMApi

alias of BlockingBioLMApi

class biolm.client.BioLMApiClient(model_name: str, api_key: str | None = None, base_url: str | None = None, timeout: Timeout = Timeout(connect=10.0, read=1200, write=1200, pool=1200), raise_httpx: bool = False, unwrap_single: bool = True, semaphore: int | Semaphore | None = 16, rate_limit: str | None = None, retry_error_batches: bool = True, compress_requests: bool = True, compress_threshold: int = 256, concurrent_batches: bool = True, http2: bool = True)

Bases: object

async call(func: str, items: List[dict], params: dict | None = None, raw: bool = False)

encode(*, items: List[dict], params: dict | None = None, stop_on_error: bool = False, output: str = 'memory', file_path: str | None = None, overwrite: bool = True, progress_callback: Callable[[int, int], None] | None = None)

static extract_max_items(schema: dict) → int | None

Extracts the ‘maxItems’ value for the ‘items’ key from the schema. Returns the integer value if found, else None.

generate(*, items: List[dict], params: dict | None = None, stop_on_error: bool = False, output: str = 'memory', file_path: str | None = None, overwrite: bool = True, progress_callback: Callable[[int, int], None] | None = None)

async lookup(query: dict | List[dict], *, raw: bool = False, output: str = 'memory', file_path: str | None = None)

predict(*, items: List[dict], params: dict | None = None, stop_on_error: bool = False, output: str = 'memory', file_path: str | None = None, overwrite: bool = True, progress_callback: Callable[[int, int], None] | None = None)

async schema(model: str, action: str) → dict | None

Fetch the JSON schema for a given model and action, with caching. Returns the schema dict if successful, else None. Uses a module-level cache keyed by (model, action) so it is safe to use from any event loop (sync wrapper, async tests, pytest-xdist workers).

Schema is always fetched from the hosted platform API without credentials. Hub gateways and custom model API hosts may not expose /schema/, and sending API tokens to the public schema endpoint can return 401.

score(*, items: List[dict], params: dict | None = None, stop_on_error: bool = False, output: str = 'memory', file_path: str | None = None, overwrite: bool = True)

search(*, items: List[dict], params: dict | None = None, stop_on_error: bool = False, output: str = 'memory', file_path: str | None = None, overwrite: bool = True)

async shutdown()

class biolm.client.CredentialsProvider

Bases: object

static get_auth_headers(api_key: str | None = None) → Dict[str, str]

biolm.client.batch_iterable(iterable, batch_size)

biolm.client.is_list_of_lists(items, check_n=10)

biolm.client.parse_rate_limit(rate: str)

biolm.finetune module

Programmatic finetuning client for BioLM.

Wraps the /api/finetune/ endpoints (the SDK-facing companion to the browser console finetuning UI) so callers can launch and track XGBoost and DSM finetuning runs from Python without a session cookie.

Auth follows the same rules as the rest of the SDK: pass api_key= or set BIOLM_TOKEN (see biolm.core.http.CredentialsProvider).

class biolm.finetune.Finetune

Bases: object

Launch and track BioLM finetuning runs.

All methods are classmethods returning plain dicts. *_data arguments accept a list of row dicts ([{"sequence": ..., "label": ...}, ...]) or a raw CSV string; they are sent inline as JSON.

classmethod cancel(run_id: str, **kwargs) → dict

Synchronous wrapper for cancel_async().

async classmethod cancel_async(run_id: str, *, api_key: str | None = None, base_url: str | None = None) → dict

Cancel an in-flight run.

classmethod dsm_rl(**kwargs) → dict

Synchronous wrapper for dsm_rl_async().

async classmethod dsm_rl_async(*, seed_sequences: List[str] | str, oracle_type: str = 'esmc', stability_objective: str = 'thermostability', training_mode: str = 'online', algorithm: str = 'ppo', num_episodes: int = 100, samples_per_episode: int = 64, learning_rate: float = 0.0003, batch_size: int = 8, mask_ratio: float = 0.3, mutation_rate: float = 0.1, run_name: str | None = None, environment_id: int | str | None = None, api_key: str | None = None, base_url: str | None = None) → dict

Launch DSM RL protein optimization against an oracle.

classmethod dsm_stage1(**kwargs) → dict

Synchronous wrapper for dsm_stage1_async().

async classmethod dsm_stage1_async(*, train_data: List[Dict[str, Any]] | str, test_data: List[Dict[str, Any]] | str | None = None, valid_data: List[Dict[str, Any]] | str | None = None, sequence_col: str = 'sequence', lr: float = 0.0001, batch_size: int = 8, grad_accum: int = 16, max_steps: int = 50000, max_length: int = 2048, save_every: int = 1000, fp16: bool = False, run_name: str | None = None, environment_id: int | str | None = None, api_key: str | None = None, base_url: str | None = None) → dict

Launch DSM Stage 1 (single-chain masked-LM finetune).

classmethod dsm_stage2(**kwargs) → dict

Synchronous wrapper for dsm_stage2_async().

async classmethod dsm_stage2_async(*, stage1_checkpoint: str, paired_data: List[Dict[str, Any]] | str, unpaired_data: List[Dict[str, Any]] | str | None = None, heavy_col: str = 'heavy', light_col: str = 'light', use_mixed_training: bool = False, fp16: bool = False, lr: float = 5e-05, batch_size: int = 4, unpaired_batch_size: int = 8, grad_accum: int = 16, max_steps: int = 25000, max_length: int = 300, unpaired_ratio: float = 2.0, run_name: str | None = None, environment_id: int | str | None = None, api_key: str | None = None, base_url: str | None = None) → dict

Launch DSM Stage 2 (paired multichain finetune from a Stage 1 checkpoint).

classmethod get_run(run_id: str, **kwargs) → dict

Synchronous wrapper for get_run_async().

async classmethod get_run_async(run_id: str, *, api_key: str | None = None, base_url: str | None = None) → dict

Fetch sanitized detail (status, results) for a single run.

classmethod list_runs(**kwargs) → dict

Synchronous wrapper for list_runs_async().

async classmethod list_runs_async(*, dag: str | None = None, status: str | None = None, page: int = 1, page_size: int = 20, api_key: str | None = None, base_url: str | None = None) → dict

List the caller’s finetune runs (paginated).

classmethod progress(run_id: str, **kwargs) → dict

Synchronous wrapper for progress_async().

async classmethod progress_async(run_id: str, *, api_key: str | None = None, base_url: str | None = None) → dict

Fetch lightweight status + telemetry channel id for a run.

classmethod wait(run_id: str, *, poll_interval: float = 15.0, timeout: float | None = None, api_key: str | None = None, base_url: str | None = None) → dict

Block until run_id reaches a terminal state, returning its detail.

classmethod xgboost(**kwargs) → dict

Synchronous wrapper for xgboost_async().

async classmethod xgboost_async(*, train_data: List[Dict[str, Any]] | str, embedding_models: List[str], task_type: str = 'classification', target_column: str = 'label', text_column: str = 'sequence', test_data: List[Dict[str, Any]] | str | None = None, validation_data: List[Dict[str, Any]] | str | None = None, n_estimators: int = 100, max_depth: int = 6, learning_rate: float = 0.1, n_splits: int = 5, seed: int = 42, hyperopt: bool = False, hyperopt_n_trials: int | None = None, antibody_mode: bool = False, heavy_column: str = 'heavy', light_column: str = 'light', modality: str = 'protein', run_name: str | None = None, environment_id: int | str | None = None, api_key: str | None = None, base_url: str | None = None) → dict

Launch an XGBoost finetune (optionally with Ray Tune hyperopt).

biolm.platform module

Platform management client for BioLM console APIs.

Talks to {BIOLM_BASE_DOMAIN}/console/api/ with a persistent httpx.Client so Django session cookies survive account-context switches. A workspace is an account + environment pair.

exception biolm.platform.AmbiguousOrganizationError(message: str, status_code: int | None = None, response: Any | None = None)

Bases: PlatformError

More than one organization matched the requested identifier.

exception biolm.platform.AmbiguousWorkspaceError(message: str, status_code: int | None = None, response: Any | None = None)

Bases: PlatformError

More than one workspace matched the requested path.

exception biolm.platform.OrganizationNotFoundError(message: str, status_code: int | None = None, response: Any | None = None)

Bases: PlatformError

No organization matched the requested identifier.

class biolm.platform.PlatformClient(api_key: str | None = None, base_url: str | None = None, timeout: float = 30.0, transport: BaseTransport | None = None, client: Client | None = None)

Bases: object

Sync client for BioLM platform (orgs, environments, budgets, workspaces).

Instances retain session cookies and active account context. They are stateful, session-scoped, and not safe for concurrent use across threads.

close() → None

create_api_key(account: str | None = None) → Dict[str, str]

Create an API key and return its one-time secret.

The key is owned by the active server-side account context. Pass account (an org slug or the personal label) to create the key under a different account; the switch and creation happen in this one session so organization ownership cannot silently fall back to personal. The original context is restored afterward. The returned token is shown only once and is not stored by the SDK.

create_environment(name: str) → Dict[str, Any]

create_organization(name: str, slug: str) → Dict[str, Any]

create_workspace(name: str, account: str | None = None) → Workspace

current_workspace() → Workspace

delete_api_key(token_or_prefix: str) → None

Revoke an API key by full token or eight-character prefix.

get_budget() → Dict[str, Any]

get_context() → Dict[str, Any]

get_current_user() → Dict[str, Any]

get_organization(identifier: int | str) → Dict[str, Any]

get_usage_summary(year: int | None = None, month: int | None = None, environment_id: int | None = None, account: str | None = None) → Dict[str, Any]

Return monthly usage for the current or named account.

get_workspace(path: str) → Workspace

Resolve and return the workspace matching an exact path.

invite_to_organization(identifier: int | str, email: str, role: str = 'member') → Dict[str, Any]

list_environments() → List[Dict[str, Any]]

list_organizations() → List[Dict[str, Any]]

list_workspaces() → List[Workspace]

List personal and organization workspaces, restoring prior context.

The environments endpoint is session-scoped, so enumeration must switch the backend account context for each account. Those switches may cause the backend to ensure or select a default environment; there is no context-free environment listing endpoint available.

set_budget(workspace_budget: float) → Dict[str, Any]

set_context(account_type: str, account_id: int | None = None, environment_id: int | None = None) → Dict[str, Any]

switch_workspace(workspace_or_path: Workspace | str) → Workspace

exception biolm.platform.PlatformError(message: str, status_code: int | None = None, response: Any | None = None)

Bases: Exception

Raised when a console API request fails or returns an error status.

class biolm.platform.Workspace(account_type: str, account_id: int, environment_id: int, account: str, environment: str)

Bases: object

Immutable account + environment pair.

account / environment are path segments (org slug or personal label, and environment slug from the API name field). IDs remain authoritative.

account: str

account_id: int

account_type: str

environment: str

environment_id: int

property path: str