### BioLM Python SDK Quickstart Example

Source: https://docs.biolm.ai/latest/sdk/overview

Demonstrates how to use the BioLM Python SDK for common tasks like encoding sequences, predicting protein structures, and generating new sequences. It shows the basic function call structure with different entities and actions.

```python
from biolmai import biolm

# Encode a sequence (e.g. ESM2-8M)
result = biolm(entity="esm2-8m", action="encode", type="sequence", items="MSILVTRPSPAGEEL")

# Predict structure (e.g. ESMFold)
result = biolm(entity="esmfold", action="predict", type="sequence", items=["MDNELE", "MENDEL"])

# Generate sequences (e.g. ProGen2-OAS)
result = biolm(
    entity="progen2-oas",
    action="generate",
    type="context",
    items="M",
    params={"temperature": 0.7, "num_samples": 2, "max_length": 17}
)

```

--------------------------------

### Generate BioLM Model SDK Examples via CLI

Source: https://docs.biolm.ai/latest/cli/model

This command generates example code snippets for using BioLM models with the SDK. It can target specific models and actions, and output the examples to a file. Requires the BioLM CLI.

```bash
biolmai model example
biolmai model example esm2-8m
biolmai model example esm2-8m --action encode
biolmai model example esm2-8m --output example.py
```

--------------------------------

### Install BioLM AI from source

Source: https://docs.biolm.ai/latest/getting-started/installation

Installs BioLM AI after downloading the source code, either by cloning the repository or downloading a tarball. This command should be run from the root of the source directory.

```bash
python setup.py install

```

--------------------------------

### Install BioLM AI Package

Source: https://docs.biolm.ai/latest/getting-started/quickstart

Installs the BioLM AI Python package using pip. This is the first step to using the BioLM AI SDK.

```bash
pip install biolmai

```

--------------------------------

### BioLM Simple Sync Interface Example (Python)

Source: https://docs.biolm.ai/latest/getting-started/concepts

Demonstrates the simplest synchronous interface for making single or batch calls to BioLM. It requires no setup and directly returns results as a dictionary for single items or a list of dictionaries for batch calls. This interface uses an asynchronous backend for performance.

```python
from biolmai import biolm

# Single item: returns a dict
result = biolm(entity="esmfold", action="predict", items="MDNELE")
print(result["mean_plddt"])

# Batch: returns a list of dicts
result = biolm(entity="esmfold", action="predict", items=["MDNELE", "MENDEL"])

```

--------------------------------

### Async Context Manager Usage Example

Source: https://docs.biolm.ai/latest/sdk/usage/async-sync

Provides a practical example of using BioLMApiClient with an asynchronous context manager to perform a prediction.

```python
async with BioLMApiClient("esmfold") as model:
    result = await model.predict(items=[{"sequence": "MDNELE"}])
```

--------------------------------

### BioLM AI Quickstart: Basic Usage (biolm function)

Source: https://docs.biolm.ai/latest/getting-started/quickstart

Demonstrates basic, synchronous usage of the `biolm()` function for encoding sequences, predicting with models like esmfold, and writing results to disk. It also shows how to handle errors when `raise_httpx` is set to `False`.

```python
from biolmai import biolm

# Encode a single sequence
result = biolm(entity="esm2-8m", action="encode", type="sequence", items="MSILVTRPSPAGEEL")

# Predict a batch of sequences
result = biolm(entity="esmfold", action="predict", type="sequence", items=["SEQ1", "SEQ2"])

# Write results to disk
biolm(entity="esmfold", action="predict", type="sequence", items=["SEQ1", "SEQ2"], output='disk', file_path="results.jsonl")

# Check for errors when not raising (raise_httpx=False)
result = biolm(entity="esmfold", action="predict", type="sequence", items=["SEQ1", "BADSEQ"], raise_httpx=False)
for r in result:
    if isinstance(r, dict) and "error" in r:
        print("Error:", r["error"])
    else:
        print("OK")

```

--------------------------------

### Start Local OAuth Callback Server

Source: https://docs.biolm.ai/latest/_modules/biolmai/core/auth

Starts a simple HTTP server on a specified port to listen for OAuth 2.0 callback requests. It parses the callback URL to extract authorization codes or error information.

```python
import http.server
import queue
import urllib.parse

def _start_local_callback_server(expected_state: str, port: int = 8765, timeout: int = 180) -> queue.Queue:
    """Start a local HTTP server to receive OAuth callback.
    
    Args:
        expected_state: Expected OAuth state parameter for CSRF protection
        port: Port to bind to (default 8765, must match OAUTH_REDIRECT_URI)
        timeout: Timeout in seconds to wait for callback
    
    Returns:
        Queue that will receive the authorization code
    """
    received = queue.Queue()

    class CallbackHandler(http.server.BaseHTTPRequestHandler):
        def do_GET(self):
            parsed = urllib.parse.urlparse(self.path)
            if parsed.path != "/callback":
                self.send_response(404)
                self.end_headers()
                return
            
            params = dict(urllib.parse.parse_qsl(parsed.query))
            code = params.get("code")
            state = params.get("state")
            error = params.get("error")
            error_description = params.get("error_description")
            
            if error:
                self.send_response(400)
                self.send_header("Content-Type", "text/html")
                self.end_headers()
                error_msg = error_description or error
                error_html = f"""<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Authorization Error - BioLM</title>
    <style>
        body {{ font-family: system-ui, sans-serif; background: #f8fafc; min-height: 100vh; display: flex; align-items: center; justify-content: center; padding: 1rem; }}
        .container {{ background: white; border-radius: 0.75rem; """
                # ... (rest of the HTML for error message)
                self.wfile.write(error_html.encode("utf-8"))
                return

            if code and state == expected_state:
                self.send_response(200)
                self.send_header("Content-Type", "text/html")
                self.end_headers()
                success_html = """<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Authorization Successful - BioLM</title>
    <style>
        body {{ font-family: system-ui, sans-serif; background: #f8fafc; min-height: 100vh; display: flex; align-items: center; justify-content: center; padding: 1rem; }}
        .container {{ background: white; border-radius: 0.75rem; """
                # ... (rest of the HTML for success message)
                self.wfile.write(success_html.encode("utf-8"))
                received.put(code)
            else:
                self.send_response(400)
                self.send_header("Content-Type", "text/html")
                self.end_headers()
                # ... (HTML for invalid state or missing code)

    server = http.server.HTTPServer(("127.0.0.1", port), CallbackHandler)
    # ... (thread execution and timeout handling)
    return received
```

--------------------------------

### CLI Authentication with biolmai login

Source: https://docs.biolm.ai/latest/getting-started/authentication

This example shows the command-line interface command `biolmai login` used for authentication. It initiates an OAuth 2.0 flow, potentially opening a browser for user authorization, and saves credentials locally.

```bash
$ biolmai login

Starting OAuth login...
A browser window will open for authorization.
Opened browser for authorization...
Waiting for authorization...

Login succeeded! Credentials saved to ~/.biolmai/credentials

```

--------------------------------

### Full Workflow: Load, Predict, Export (Python)

Source: https://docs.biolm.ai/latest/sdk/usage/io

A complete workflow example showing sequence loading from FASTA, structure prediction using a Model, and exporting the predicted structures to CSV. Requires `load_fasta`, `to_csv` from `biolmai.io`, and the `Model` class from `biolmai`.

```python
from biolmai.io import load_fasta, to_csv
from biolmai import Model

# 1. Load input sequences
sequences = load_fasta("input.fasta")

# 2. Process with model
model = Model("esmfold")
structures = model.predict(items=sequences)

# 3. Export results
to_csv(structures, "output.csv")
```

--------------------------------

### Download BioLM AI source tarball

Source: https://docs.biolm.ai/latest/getting-started/installation

Downloads the production tarball of the BioLM AI source code from GitHub. This is an alternative method for installing from source. Requires curl to be installed.

```bash
curl -OJL https://github.com/BioLM/py-biolm/tarball/production

```

--------------------------------

### Configure BioLM AI Client Rate Limiting and Concurrency

Source: https://docs.biolm.ai/latest/sdk/usage/rate_limiting

Demonstrates how to initialize the BioLM AI client with default, custom rate limits, and custom concurrency limits. It shows examples of setting requests per second/minute and using semaphores for controlling concurrent requests.

```python
from biolmai.core.http import BioLMApi, BioLMApiClient

# Use API's default throttle rate (recommended)
model = BioLMApi("esmfold")

# Custom rate limit: 1000 requests per second
model = BioLMApi("esmfold", rate_limit="1000/second")

# Custom rate limit: 60 requests per minute
model = BioLMApi("esmfold", rate_limit="60/minute")

# Custom concurrency limit: at most 5 requests at once
model = BioLMApiClient("esmfold", semaphore=5)

# Or use your own semaphore
import asyncio
sem = asyncio.Semaphore(5)
model = BioLMApiClient("esmfold", semaphore=sem)

# Disable default semaphore (no concurrency limit)
model = BioLMApiClient("esmfold", semaphore=None)

# Both: at most 5 concurrent, and at most 1000 per second
model = BioLMApiClient("esmfold", semaphore=sem, rate_limit="1000/second")

```

--------------------------------

### Response Mapping Example in YAML

Source: https://docs.biolm.ai/latest/protocols/output

Demonstrates how to configure response mapping for model tasks using YAML. It shows how to extract specific fields from an API response, such as a list of PDB structures, using a string expression.

```yaml
- id: predict
  slug: esmfold
  action: predict
  request_body:
    items: "{{ inputs.sequences }}"
  response_mapping: "{{ response.results[*].pdb }}"

```

--------------------------------

### Clone BioLM AI from GitHub

Source: https://docs.biolm.ai/latest/getting-started/installation

Clones the BioLM AI public repository from GitHub to install from source. This allows for development or using the latest unreleased features. Requires Git to be installed.

```bash
git clone git://github.com/BioLM/py-biolm

```

--------------------------------

### Minimal Protocol Definition Example

Source: https://docs.biolm.ai/latest/protocols/about

A basic example of a BioLM AI protocol definition in YAML format. It specifies the protocol name, input parameters, and a single task for prediction using the 'esmfold' model.

```yaml
name: my-protocol
inputs:
  sequences:
    type: list_of_str
    label: Sequences
    required: true
tasks:
  - slug: esmfold
    action: predict
    request_body:
      items: "{{ inputs.sequences }}"

```

--------------------------------

### BioLM AI Quickstart: Class-based Usage (Model class)

Source: https://docs.biolm.ai/latest/getting-started/quickstart

Illustrates using the class-based `Model` for repeated operations with a specific model, such as encoding sequences or predicting with esmfold. This approach is suitable when working extensively with one model.

```python
from biolmai import Model

model = Model("esm2-8m")
result = model.encode(type="sequence", items="MSILVTRPSPAGEEL")

model = Model("esmfold")
result = model.predict(type="sequence", items=["SEQ1", "SEQ2"])

```

--------------------------------

### BioLM Python Client: Auto-Batching Example

Source: https://docs.biolm.ai/latest/sdk/usage/batching

Illustrates the auto-batching mechanism of the BioLM Python client. The client automatically splits input into batches based on the model's maximum batch size, ensuring efficient processing without manual intervention.

```python
# If the model's max batch size is 8, this will be split into 2 requests:
items = ["SEQ" + str(i) for i in range(12)]
result = biolm(entity="esm2-8m", action="encode", type="sequence", items=items)
# result is a list of 12 results, in order
```

--------------------------------

### BioLMApiClient Async Interface Example (Python)

Source: https://docs.biolm.ai/latest/getting-started/concepts

Shows how to use the asynchronous BioLMApiClient for high throughput and async applications. This client's methods are coroutines and must be awaited, typically used within an async function or with asyncio.run(). It requires importing BioLMApiClient and asyncio.

```python
from biolmai.core.http import BioLMApiClient
import asyncio

async def main():
    model = BioLMApiClient("esmfold")
    result = await model.predict(items=[{"sequence": "MDNELE"}])
    print(result)

asyncio.run(main())

```

--------------------------------

### Predict with Manual Batching and Error Handling

Source: https://docs.biolm.ai/latest/sdk/usage/batching

This example demonstrates manual batching for prediction tasks using a list of lists, where each inner list represents a batch. It also shows how to configure the client to stop on the first error or process all batches and collect errors using `stop_on_error=False`.

```python
batches = [
    [{"sequence": "SEQ1"}, {"sequence": "BADSEQ"}],  # batch 1
    [{"sequence": "SEQ3"}],                          # batch 2
]
result = biolm(entity="esmfold", action="predict", items=batches, stop_on_error=False)
```

--------------------------------

### CLI Login with Custom Scope

Source: https://docs.biolm.ai/latest/getting-started/authentication

This example shows how to specify a custom scope for the `biolmai login` command. Supported scopes include 'read', 'write', and 'introspection', allowing fine-grained control over API access.

```bash
# Specify custom scope (supported: read, write, introspection)
$ biolmai login --scope "read write"
```

--------------------------------

### OAuth 2.0 Browser Login with PKCE

Source: https://docs.biolm.ai/latest/_modules/biolmai/core/auth

This endpoint facilitates the OAuth 2.0 authorization code flow with PKCE, commonly used for CLI applications. It starts a local server to handle the redirect, opens a browser for user authentication, and exchanges the authorization code for an access token.

```APIDOC
## POST /oauth2/authorize

### Description
Initiates the OAuth 2.0 authorization code flow with PKCE. This endpoint is typically called by a client application to begin the user authentication process.

### Method
GET

### Endpoint
`/oauth2/authorize`

### Parameters
#### Query Parameters
- **response_type** (string) - Required - Must be 'code'.
- **client_id** (string) - Required - The client ID obtained from the authorization server.
- **redirect_uri** (string) - Required - The URI to which the user will be redirected after authorization.
- **scope** (string) - Required - The scope of the access request (e.g., 'openid profile email').
- **code_challenge** (string) - Required - The PKCE code challenge generated from the code verifier.
- **code_challenge_method** (string) - Required - The method used to generate the code challenge (typically 'S256').
- **state** (string) - Required - An opaque value used to maintain state between the request and callback, and to prevent CSRF attacks.

### Request Example
```
GET /oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:8765/callback&scope=openid%20profile&code_challenge=E9MelODU30_Y_j_r9J6O_d_4_5_7_8_9_0_A_B_C&code_challenge_method=S256&state=STATE_STRING
```

### Response
#### Success Response (200)
Upon successful authorization, the user's browser is redirected to the `redirect_uri` with an authorization `code` and the `state` parameter.

#### Response Example
```
http://localhost:8765/callback?code=AUTHORIZATION_CODE&state=STATE_STRING
```

## POST /oauth2/token

### Description
Exchanges an authorization `code` for an access token, refresh token, and ID token. This endpoint is used by the client after the user has authorized the application.

### Method
POST

### Endpoint
`/oauth2/token`

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be 'authorization_code'.
- **code** (string) - Required - The authorization code received from the authorization server.
- **redirect_uri** (string) - Required - The redirect URI used in the initial authorization request.
- **client_id** (string) - Required - The client ID.
- **client_secret** (string) - Optional - The client secret (for confidential clients).
- **code_verifier** (string) - Required - The original code verifier used to generate the code challenge.

### Request Example
```json
{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "http://localhost:8765/callback",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code_verifier": "CODE_VERIFIER_STRING"
}
```

### Response
#### Success Response (200)
Returns a JSON object containing the access token, refresh token, ID token, and other relevant information.

#### Response Example
```json
{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "id_token": "ID_TOKEN",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```
```

--------------------------------

### Define Protocol Inputs with InputSpec (YAML)

Source: https://docs.biolm.ai/latest/protocols/inputs

This snippet demonstrates how to define input specifications for a protocol using YAML. It shows examples of 'list_of_str' for sequences and 'float' for temperature, including various optional parameters like label, required, initial, min, and max.

```yaml
inputs:
  sequences:
    type: list_of_str
    label: Protein sequences
    required: true
  temperature:
    type: float
    label: Sampling temperature
    initial: 0.7
    min: 0
    max: 2

```

--------------------------------

### BioLM Python Client: Manual Batching with Error Handling

Source: https://docs.biolm.ai/latest/sdk/usage/batching

Shows an example of manual batching using a list of lists with the BioLM Python client, including the `stop_on_error=False` parameter. This allows for custom batching and continued processing even if some items within a batch cause errors.

```python
# Two batches: first has 2 items, second has 1
items = [
    [{"sequence": "SEQ1"}, {"sequence": "BADSEQ"}],  # batch 1
    [{"sequence": "SEQ3"}],                          # batch 2
]
result = biolm(entity="esmfold", action="predict", items=items, stop_on_error=False)
# result is a flat list: [result1, result2, result3]
```

--------------------------------

### YAML: BioLM AI Model Task Example

Source: https://docs.biolm.ai/latest/protocols/tasks

An example of a 'model task' in a BioLM AI protocol, demonstrating how to call a model for prediction. It specifies the model slug, action, request body with items and parameters.

```yaml
- id: predict
  slug: esmfold
  action: predict
  request_body:
    items: "{{ inputs.sequences }}"
    params: {}

```

--------------------------------

### YAML: BioLM AI Gather Task Example

Source: https://docs.biolm.ai/latest/protocols/tasks

An example of a 'gather task' in a BioLM AI protocol, showing how to collect specific fields from a previous task. It defines the task type, source task, and the fields to gather.

```yaml
- type: gather
  from: predict
  fields: [pdb, mean_plddt]

```

--------------------------------

### BioLMApiClient Shutdown and Context Manager

Source: https://docs.biolm.ai/latest/sdk/usage/async-sync

Shows how to properly shut down the BioLMApiClient or use it as a context manager for automatic cleanup.

```python
# Close the client when done
await model.shutdown()

# Or use a context manager (no explicit shutdown)
async with BioLMApiClient("model") as model:
    ...
```

--------------------------------

### Load and Write FASTA using File-like Objects (Python)

Source: https://docs.biolm.ai/latest/sdk/usage/io

Illustrates using `load_fasta` and `to_fasta` with file-like objects (StringIO) instead of file paths. This is useful for in-memory operations or when dealing with streams. Requires `io` module and functions from `biolmai.io`.

```python
import io
from biolmai.io import load_fasta, to_fasta

# Load from file-like object
file_obj = io.StringIO(">seq1\nACDEFGHIKLMNPQRSTVWY\n")
items = load_fasta(file_obj)

# Write to file-like object
output = io.StringIO()
to_fasta(items, output)
content = output.getvalue()
```

--------------------------------

### Get BioLM API Token

Source: https://docs.biolm.ai/latest/_modules/biolmai/core/auth

Retrieves an API token by making a POST request to the BioLM authentication endpoint. It uses username and password from environment variables.

```python
import json
import os
import requests

# Assuming BIOLMAI_BASE_DOMAIN is defined elsewhere
def get_api_token():
    """Get a BioLM API token to use with future API requests."""
    url = f"{BIOLMAI_BASE_DOMAIN}/api/auth/token/"

    payload = json.dumps(
        {
            "username": os.environ.get("BIOLM_USER"),
            "password": os.environ.get("BIOLM_PASSWORD"),
        }
    )
    headers = {"Content-Type": "application/json"}

    response = requests.request("POST", url, headers=headers, data=payload)
    response_json = response.json()

    return response_json
```

--------------------------------

### Get User Authorization Header

Source: https://docs.biolm.ai/latest/_modules/biolmai/core/auth

Constructs an Authorization header for API requests. It prioritizes environment variables BIOLMAI_TOKEN or BIOLM_TOKEN, falling back to reading a credentials file.

```python
import os

# Assuming ACCESS_TOK_PATH, parse_credentials_file, and BIOLMAI_BASE_DOMAIN are defined elsewhere
def get_user_auth_header():
    """Returns a dict with the appropriate Authorization header, either using
    an API token from BIOLMAI_TOKEN or BIOLM_TOKEN environment variable, or by
    reading the credentials file at ~/.biolmai/credentials next."""
    api_token = os.environ.get("BIOLMAI_TOKEN") or os.environ.get("BIOLM_TOKEN")
    if api_token:
        headers = {"Authorization": f"Token {api_token}"}
    elif os.path.exists(ACCESS_TOK_PATH):
        access_refresh_dict = parse_credentials_file(ACCESS_TOK_PATH)
        if access_refresh_dict is None:
            err = (
                f"Error reading credentials file {ACCESS_TOK_PATH}. "
                "The file may be corrupted or contain invalid data. "
                "Please run `biolmai login` to re-authenticate."
            )
            raise AssertionError(err)
        access = access_refresh_dict.get("access")
        refresh = access_refresh_dict.get("refresh")
        headers = {
            "Cookie": f"access={access};refresh={refresh}",
        }
    else:
        err = (
            f"No {BIOLMAI_BASE_DOMAIN} credentials found. Please run "
            "`biolmai status` to debug."
        )
        raise AssertionError(err)
    return headers
```

--------------------------------

### Perform OAuth 2.0 Login with PKCE in Biolm AI

Source: https://docs.biolm.ai/latest/_modules/biolmai/core/auth

Initiates an OAuth 2.0 login flow using the Proof Key for Code Exchange (PKCE) extension. It handles obtaining authorization codes, exchanging them for tokens, and persisting the tokens (access, refresh, and related details) to a local credentials file. This function supports customization of client ID, scope, and endpoint URLs.

```python
import time
from typing import Optional

# Assume these functions and constants are defined elsewhere
def _browser_login_with_pkce(client_id, scope, auth_url, token_url, redirect_uri, client_secret=None):
    # Placeholder for actual PKCE browser login implementation
    # This function should return a dictionary containing token information
    pass

# Mock constants for demonstration
class MockConst:
    BIOLMAI_OAUTH_CLIENT_SECRET = "mock_client_secret"
    BIOLMAI_PUBLIC_CLIENT_ID = "mock_public_client_id"
    OAUTH_AUTHORIZE_URL = "https://mock.biolmai.com/auth"
    OAUTH_TOKEN_URL = "https://mock.biolmai.com/token"
    OAUTH_REDIRECT_URI = "http://localhost:8080/callback"

const = MockConst()


def oauth_login(
    *,
    client_id: Optional[str] = None,
    scope: str = "read write",
    auth_url: Optional[str] = None,
    token_url: Optional[str] = None,
    redirect_uri: Optional[str] = None,
) -> dict:
    """Perform OAuth login using PKCE and persist tokens to ~/.biolmai/credentials.
    
    Args:
        client_id: OAuth client ID (defaults to BIOLMAI_PUBLIC_CLIENT_ID from const)
        scope: OAuth scope string
        auth_url: Authorization endpoint (defaults to OAUTH_AUTHORIZE_URL)
        token_url: Token endpoint (defaults to OAUTH_TOKEN_URL)
        redirect_uri: Redirect URI (defaults to OAUTH_REDIRECT_URI)
    
    Returns:
        Token response dict
    """
    
    client_id = client_id or const.BIOLMAI_PUBLIC_CLIENT_ID
    if not client_id:
        raise ValueError(
            "OAuth client ID required. Set BIOLMAI_OAUTH_CLIENT_ID environment variable "
            "or pass --client-id to login command."
        )
    
    # Get client_secret from environment (if provided)
    client_secret = const.BIOLMAI_OAUTH_CLIENT_SECRET
    
    auth_url = auth_url or const.OAUTH_AUTHORIZE_URL
    token_url = token_url or const.OAUTH_TOKEN_URL
    redirect_uri = redirect_uri or const.OAUTH_REDIRECT_URI
    
    # Perform browser/PKCE flow
    token_data = _browser_login_with_pkce(
        client_id, scope, auth_url, token_url, redirect_uri, client_secret=client_secret
    )
    
    # Extract tokens
    access_token = token_data.get("access_token") or token_data.get("access")
    refresh_token = token_data.get("refresh_token") or token_data.get("refresh")
    expires_in = token_data.get("expires_in", 3600)
    
    if not access_token:
        raise ValueError("No access token in OAuth response")
    
    # Prepare credentials dict
    creds = {
        "access": access_token,
        "refresh": refresh_token,
        "expires_in": expires_in,
        "expires_at": int(time.time()) + int(expires_in),
        "token_url": token_url,
        "client_id": client_id,
    }
    
    # Save client_secret if provided (for confidential clients)
    if client_secret:
        creds["client_secret"] = client_secret
    
    # Persist credentials
    # Assume a function like save_credentials(ACCESS_TOK_PATH, creds) exists
    # save_credentials(ACCESS_TOK_PATH, creds)
    
    return creds

```

--------------------------------

### Encode and Predict Sequences with BioLM Python SDK

Source: https://docs.biolm.ai/latest/sdk/models

Demonstrates how to use the BioLM Python SDK to encode a single sequence using the 'esm2-8m' model and predict structures for multiple sequences using the 'esmfold' model. This requires the 'biolmai' package to be installed.

```python
from biolmai import biolm

result = biolm(entity="esm2-8m", action="encode", type="sequence", items="MSILVTRPSPAGEEL")
result = biolm(entity="esmfold", action="predict", type="sequence", items=["SEQ1", "SEQ2"])

```

--------------------------------

### Extract Template Expression from Value (Python)

Source: https://docs.biolm.ai/latest/_modules/biolmai/core/expression_evaluator

Safely extracts a template expression string from a given value. It checks if the value is a string starting with '${{' and ending with '}}'. If it is, it returns True and the inner expression; otherwise, it returns False and an empty string.

```python
"""Extract template expression from a value if present.
    
    Args:
        value: Value that may contain a template expression
        
    Returns:
        Tuple of (is_template_expr, expression_string)
        - is_template_expr: True if value is a template expression
        - expression_string: The inner expression (without ${{ }} wrapper)
    """
    if isinstance(value, str) and value.startswith("${{") and value.endswith("}}"):
        # Extract inner expression
        inner = value[3:-2].strip()
        return True, inner
    return False, ""
```

--------------------------------

### Jupyter Notebook Async Usage

Source: https://docs.biolm.ai/latest/sdk/usage/async-sync

Illustrates how to leverage the asynchronous BioLMApiClient with top-level await for optimal performance in Jupyter notebooks.

```python
from biolmai.core.http import BioLMApiClient
model = BioLMApiClient("esmfold")
result = await model.predict(items=[{"sequence": "MDNELE"}, {"sequence": "MENDEL"}])
```

--------------------------------

### Default Rate Limiting with BioLMApi

Source: https://docs.biolm.ai/latest/getting-started/concepts

Demonstrates initializing the BioLMApi client with default rate limiting settings. This configuration utilizes the API schema's recommended throttle and a concurrency limit (semaphore) for efficient throughput without overloading the API.

```python
from biolmai.core.http import BioLMApi

# Default (recommended): uses API throttle + semaphore
model = BioLMApi("esmfold")
```

--------------------------------

### Get Max Batch Size from Schema

Source: https://docs.biolm.ai/latest/sdk/usage/batching

This snippet demonstrates how to retrieve the maximum batch size allowed by an API endpoint by inspecting its schema. It utilizes the BioLMApi client to fetch the schema and extract the relevant batch size information.

```python
from biolmai.core.http import BioLMApi
model = BioLMApi("esm2-8m")
schema = model.schema("esm2-8m", "encode")
max_batch = model.extract_max_items(schema)
print("Max batch size:", max_batch)
```

--------------------------------

### Sync/Async Interoperability with Thread Pool

Source: https://docs.biolm.ai/latest/sdk/usage/async-sync

Demonstrates how to run asynchronous BioLMApiClient methods from synchronous code using asyncio.run within a thread pool.

```python
import asyncio
from biolmai.core.http import BioLMApiClient

def run_sync():
    model = BioLMApiClient("esmfold")
    return asyncio.run(model.predict(items=[{"sequence": "MDNELE"}]))

result = run_sync()
```

--------------------------------

### BioLM AI SDK Overview

Source: https://docs.biolm.ai/latest/protocols/output

An overview of the BioLM AI Software Development Kit (SDK), including its core components and usage patterns.

```APIDOC
## BioLM AI SDK Overview

### Description
This section provides an introduction to the BioLM AI SDK, outlining its capabilities for programmatic access to BioLM AI features such as models, protocols, and workspaces. It covers essential aspects like I/O handling, batching, error handling, and asynchronous operations.

### Key Features

*   **Models**: Interface with various machine learning models.
*   **Protocols**: Define and execute computational protocols.
*   **Workspaces**: Manage your project environments.
*   **Volumes**: Handle data storage and access.
*   **I/O**: Support for various data formats including CSV, FASTA, JSON, and PDB.
*   **Usage**: Guidance on effective SDK utilization.
*   **Batching and Input Flexibility**: Process data in batches with flexible input options.
*   **Error Handling**: Strategies for managing and responding to errors.
*   **Async and Sync Usage**: Options for both asynchronous and synchronous operations.
*   **Rate Limiting and Throttling**: Information on API usage limits.
*   **Format I/O**: Specific details on handling FASTA, CSV, JSON, and PDB formats.
*   **FAQ**: Frequently asked questions about the SDK.
```

--------------------------------

### Basic BioLMApi Operations

Source: https://docs.biolm.ai/latest/sdk/usage/async-sync

Demonstrates the basic synchronous operations available through the BioLMApi interface, including encode, predict, generate, call, and schema.

```python
BioLMApi("model").encode(...)
BioLMApi("model").predict(...)
BioLMApi("model").generate(...)
BioLMApi("model").call(...)
BioLMApi("model").schema(...)
```

--------------------------------

### Get Authentication Status

Source: https://docs.biolm.ai/latest/_modules/biolmai/core/auth

Checks the current authentication status by looking for tokens in environment variables or a credentials file. If an environment variable token is found, it's validated. If a credentials file exists, it's parsed, and its contents are checked for OAuth token indicators.

```python
def get_auth_status():
    environ_token = os.environ.get("BIOLMAI_TOKEN") or os.environ.get("BIOLM_TOKEN")
    if environ_token:
        msg = "Environment variable BIOLMAI_TOKEN/BIOLM_TOKEN detected. Validating token..."
        click.echo(msg)
        validate_user_auth(api_token=environ_token)
    elif os.path.exists(ACCESS_TOK_PATH):
        msg = f"Credentials file found {ACCESS_TOK_PATH}. Validating token..."
        click.echo(msg)
        access_refresh_dict = parse_credentials_file(ACCESS_TOK_PATH)
        if access_refresh_dict is None:
            click.echo(f"Error reading credentials file {ACCESS_TOK_PATH}.")
            click.echo("The file may be corrupted or contain invalid data.")
            click.echo("Please login again by running `biolmai login`.")
            return
        access = access_refresh_dict.get("access")
        refresh = access_refresh_dict.get("refresh")
        
        # Check if these are OAuth tokens
        is_oauth = bool(access_refresh_dict.get("token_url") or access_refresh_dict.get("client_id"))
        
        if is_oauth:
```

--------------------------------

### Encode Sequences with List of Dicts

Source: https://docs.biolm.ai/latest/sdk/usage/batching

This example shows how to encode a batch of protein sequences using a list of dictionaries as input. Each dictionary should contain a 'sequence' key with the protein sequence string. This method leverages the biolm client's auto-batching capabilities.

```python
from biolmai import biolm

items = [{"sequence": "SEQ1"}, {"sequence": "SEQ2"}]
result = biolm(entity="esm2-8m", action="encode", items=items)
```

--------------------------------

### Generate PKCE Code Verifier and Challenge

Source: https://docs.biolm.ai/latest/_modules/biolmai/core/auth

Generates a cryptographically secure code verifier and its corresponding code challenge for OAuth 2.0 PKCE (Proof Key for Code Exchange).

```python
import base64
import hashlib
import secrets
from typing import Tuple

def _b64url(b: bytes) -> str:
    """Base64 URL-safe encoding without padding."""
    return base64.urlsafe_b64encode(b).decode("ascii").rstrip("=")

def _gen_pkce_pair() -> Tuple[str, str]:
    """Generate PKCE code verifier and challenge pair."""
    verifier = _b64url(secrets.token_bytes(64))
    challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
    return verifier, challenge
```

--------------------------------

### BioLM AI CLI: Dataset Management

Source: https://docs.biolm.ai/latest/cli/dataset

This snippet demonstrates the usage of the 'biolmai dataset' command for various dataset operations. It covers listing all datasets, showing details of a specific dataset by its ID, uploading a dataset from a local file path, and downloading a dataset to a specified output path. These commands are essential for managing data within the BioLM AI ecosystem.

```bash
biolmai dataset list
biolmai dataset show DATASET_ID
biolmai dataset upload DATASET_ID FILE_PATH
biolmai dataset download DATASET_ID OUTPUT_PATH
```

--------------------------------

### Load FASTA, Encode Sequences, Export Results (Python)

Source: https://docs.biolm.ai/latest/sdk/usage/io

Demonstrates loading sequences from a FASTA file, encoding them using a Model, and exporting the results to a CSV file. Requires `load_fasta`, `to_csv` from `biolmai.io`, and the `Model` class from `biolmai`.

```python
from biolmai.io import load_fasta, to_csv
from biolmai import Model

# Load sequences from FASTA
items = load_fasta("sequences.fasta")

# Use with model
model = Model("esm2-8m")
results = model.encode(items=items)

# Export results to CSV
to_csv(results, "results.csv")
```

--------------------------------

### Validate OAuth Token and Get User Info (Python)

Source: https://docs.biolm.ai/latest/_modules/biolmai/core/auth

This Python function validates an OAuth access token by making a request to an introspection endpoint. It parses the response to extract user information such as billing details, usage plan, and workspace budget. It returns True if the token is valid (status code 200) and False otherwise, with optional debug logging for exceptions.

```python
def _validate_oauth_token(access_token: str, client_id: str = None, client_secret: str = None) -> bool:
    """Validate OAuth access token using introspection endpoint.
    
    Args:
        access_token: OAuth access token to validate
        client_id: OAuth client ID (required for django-oauth-toolkit)
        client_secret: OAuth client secret (optional, for public clients can be empty)
    
    Returns:
        True if token is valid, False otherwise
    """
    from biolmai.core.const import BIOLMAI_OAUTH_CLIENT_SECRET, OAUTH_INTROSPECT_URL
    
    introspect_url = OAUTH_INTROSPECT_URL
    
    if not client_id:
        # Can't introspect without client_id for django-oauth-toolkit
        if os.environ.get("DEBUG"):
            click.echo("DEBUG: No client_id provided for introspection", err=True)
        return False
    
    if not access_token:
        if os.environ.get("DEBUG"):
            click.echo("DEBUG: No access_token provided for introspection", err=True)
        return False
    
    # Use client_secret from parameter or environment
    if client_secret is None:
        client_secret = BIOLMAI_OAUTH_CLIENT_SECRET
    
    try:
        if os.environ.get("DEBUG"):
            click.echo(f"DEBUG: Introspecting token at {introspect_url}", err=True)
        
        # For public clients (no secret), try different authentication methods
        # For confidential clients (with secret), use Basic Auth with client_id:client_secret
        methods_to_try = []
        
        if client_secret:
            # Confidential client: use Basic Auth with client_id:client_secret
            methods_to_try.append(("basic_auth_with_secret", client_secret))
        else:
            # Public client: try multiple methods
            # Method 1: Bearer token authentication (access token as Bearer)
            methods_to_try.append(("bearer_token", None))
            # Method 2: client_id in body, no auth header
            methods_to_try.append(("client_id_in_body", None))
            # Method 3: Basic Auth with client_id:"" (empty secret)
            methods_to_try.append(("basic_auth_empty_secret", ""))
        
        for method_name, secret_value in methods_to_try:
            if _is_debug():
                click.echo(f"DEBUG: Trying introspection method: {method_name}", err=True)
            
            headers = {
                "Content-Type": "application/x-www-form-urlencoded",
                "Accept": "application/json",
            }
            data = {
                "token": access_token,
            }
            
            if method_name == "basic_auth_with_secret":
                # Basic Auth with client_id:client_secret
                credentials = base64.b64encode(
                    f"{client_id}:{secret_value}".encode()
                ).decode()
                headers["Authorization"] = f"Basic {credentials}"
            elif method_name == "bearer_token":
                # Bearer token authentication (access token as Bearer)
                # Some OAuth servers allow introspection using the token itself
                headers["Authorization"] = f"Bearer {access_token}"
            elif method_name == "basic_auth_empty_secret":
                # Basic Auth with client_id:"" (empty secret)
                credentials = base64.b64encode(
                    f"{client_id}:".encode()
                ).decode()
                headers["Authorization"] = f"Basic {credentials}"
            elif method_name == "client_id_in_body":
                # No auth header, client_id in body
                data["client_id"] = client_id
            
            resp = requests.post(
                introspect_url,
                data=data,
                headers=headers,
                timeout=30
            )
            
            if _is_debug():
                click.echo(f"DEBUG: Method {method_name} - Response status: {resp.status_code}", err=True)
                if resp.status_code != 200:
                    # If token is invalid, try next method
                    continue
                
                # If token is valid, parse user info
                try:
                    user_data = resp.json()
                    fields_to_show = {
                        'month_dollars_billed': user_data.get('get_curr_month_dollars_billed'),
                        'usage_plan': user_data.get('usage_plan'),
                        'workspace_budget': user_data.get('workspace_budget'),
                    }
                    
                    click.echo("OAuth token is valid. User info:")
                    for key, value in fields_to_show.items():
                        if value is not None:
                            click.echo(f"  {key}: {value}")
                    return True # Token is valid and processed
                except Exception as e:
                    if _is_debug():
                        click.echo(f"DEBUG: Failed to parse user info: {e}", err=True)
                    return False # Token might be valid but response is malformed
            else:
                # Non-debug mode: only check status code
                if resp.status_code == 200:
                    return True
        
        # If no method succeeded
        return False
    except Exception as e:
        if os.environ.get("DEBUG"):
            click.echo(f"DEBUG: OAuth token API validation exception: {e}", err=True)
        return False
```

--------------------------------

### Error Handling for File Operations (Python)

Source: https://docs.biolm.ai/latest/sdk/usage/io

Demonstrates how to handle common file-related exceptions like `FileNotFoundError` and `ValueError` when using `load_fasta`. This promotes robust code by anticipating and managing potential issues.

```python
from biolmai.io import load_fasta

try:
    items = load_fasta("nonexistent.fasta")
except FileNotFoundError:
    print("File not found")

try:
    items = load_fasta("empty.fasta")
except ValueError as e:
    print(f"Invalid file: {e}")
```

--------------------------------

### Validate OAuth Token via API Call (Python)

Source: https://docs.biolm.ai/latest/_modules/biolmai/core/auth

This function validates an OAuth access token by making a GET request to a user info endpoint. It's useful for public clients where token introspection might not be available. The function returns `True` if the token is valid (status code 200) and `False` otherwise. It requires the `requests` library and access to `BIOLMAI_BASE_DOMAIN` and `BASE_API_URL` constants.

```python
import os
import click
import requests

def _validate_oauth_token_via_api(access_token: str) -> bool:
    """Validate OAuth token by making a lightweight API call to a user info endpoint.
    
    For public clients where introspection doesn't work, we can validate
    the token by making a simple API call to a user info endpoint that accepts OAuth Bearer tokens.
    
    Args:
        access_token: OAuth access token to validate
    
    Returns:
        True if token is valid, False otherwise
    """
    from biolmai.core.const import BASE_API_URL, BIOLMAI_BASE_DOMAIN
    
    try:
        # Use /api/users/me/ endpoint to validate the token
        # This endpoint requires authentication and returns user info if token is valid
        url = f"{BIOLMAI_BASE_DOMAIN}/api/users/me/"
        headers = {
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json",
        }
        
        if os.environ.get("DEBUG"):
            click.echo(f"DEBUG: Validating OAuth token via API call to {url}", err=True)
        
        resp = requests.get(url, headers=headers, timeout=10)
        
        if os.environ.get("DEBUG"):
            click.echo(f"DEBUG: OAuth token validation response status: {resp.status_code}", err=True)
        
        if resp.status_code == 200:
            try:
                user_data = resp.json()
                if _is_debug(): # Assuming _is_debug() is defined elsewhere
                    import pprint
                    click.echo("DEBUG: Token valid, user info:", err=True)
                    click.echo(pprint.pformat(user_data, indent=2), err=True)
                else:
                    # Show selected user info fields in a clean format
                    fields_to_show = {
                        'username': user_data.get('username'),
                        'email': user_data.get('email'),
                        'first_name': user_data.get('first_name'),
                        'api_use_count': user_data.get('api_use_count'),
                        'in_trial': user_data.get('in_trial'),
                        'in_metering': user_data.get('in_metering'),
                        'in_fixed_rate': user_data.get('in_fixed_rate'),
                        'payment_past_due_or_canceled': user_data.get('payment_past_due_or_canceled'),
                    }
                    # Further processing or display of fields_to_show would go here
            except Exception as e:
                click.echo(f"Error parsing user data: {e}", err=True)
                return False
            return True
        else:
            return False
    except requests.exceptions.RequestException as e:
        click.echo(f"Error during OAuth token validation API call: {e}", err=True)
        return False

```

--------------------------------

### BioLM Python Client: Manual Batching (List of Lists)

Source: https://docs.biolm.ai/latest/sdk/usage/batching

Demonstrates advanced manual batching using a list of lists of dictionaries with the BioLM Python client. Each inner list is treated as a distinct batch, allowing for custom batch size and composition control.

```python
batches = [
    [{"sequence": "SEQ1"}, {"sequence": "SEQ2"}],  # batch 1
    [{"sequence": "SEQ3"}],                        # batch 2
]
biolm(entity="esmfold", action="predict", items=batches)
```