### Install py-biolm SDK

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/quickstart.rst

Installs the py-biolm package using pip. This is the first step to using the SDK.

```bash
pip install biolmai
```

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

### Download and Install BioLM AI from Tarball

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/installation.rst

Downloads the BioLM AI project as a tarball from GitHub and installs it. This method is an alternative to cloning the repository. Requires curl to download and then setup.py to install.

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

```console
python setup.py install
```

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

### Clone BioLM AI Repository from GitHub

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/installation.rst

Clones the BioLM AI project repository directly from GitHub. This method allows access to the latest development version. Requires Git to be installed.

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

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

### Install Development Dependencies

Source: https://github.com/biolm/py-biolm/blob/main/README.md

Installs the necessary development dependencies for the BioLM Python SDK from the 'requirements_dev.txt' file using pip. This command ensures all required libraries are available for development.

```shell
pip install -r requirements_dev.txt
```

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

### Setup Python Environment with pyenv

Source: https://github.com/biolm/py-biolm/blob/main/README.md

Installs Python 3.11.5, creates a virtual environment named 'py-biolm', and activates it using pyenv. This ensures a consistent Python environment for development.

```shell
pyenv install 3.11.5
pyenv virtualenv 3.11.5 py-biolm
pyenv activate py-biolm
```

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

### Set up Local Development Environment (Shell)

Source: https://github.com/biolm/py-biolm/blob/main/CONTRIBUTING.rst

These commands set up a virtual environment for local development and install the py-biolm package in development mode. It assumes you have virtualenvwrapper installed.

```shell
mkvirtualenv biolmai
cd biolmai/
python setup.py develop
```

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

### BioLMApi Client Class Examples

Source: https://context7.com/biolm/py-biolm/llms.txt

Illustrates direct client interactions for advanced API control, including initialization with configuration, single and batch predictions, sequence encoding, large-scale disk-based processing, and manual batching.

```python
from biolmai.client import BioLMApi
import asyncio

# Initialize client with configuration
client = BioLMApi(
    model_name="esmfold",
    api_key="your_api_token",  # Or set BIOLMAI_TOKEN env var
    base_url="https://biolm.ai/api/v3",
    raise_httpx=False,
    unwrap_single=True,
    semaphore=5,  # Limit to 5 concurrent requests
    rate_limit="1000/second",  # Max 1000 requests per second
    retry_error_batches=True  # Retry failed batches individually
)

# Single prediction
result = client.predict(items=[{"sequence": "MDNELE"}])
print(result[0]["mean_plddt"])

# Batch encoding
items = [
    {"sequence": "MSILVTRPSPAGE"},
    {"sequence": "ACDEFGHIKLMNP"},
    {"sequence": "QWERTYUIOPASDFGH"}
]
embeddings = client.encode(items=items, params={"output_hidden_states": True})
for emb in embeddings:
    print(emb["embeddings"][:5])  # First 5 dimensions

# Large-scale disk-based processing
async def process_large_dataset():
    async with BioLMApi("esm2-8m", semaphore=10) as client:
        sequences = [{"sequence": f"M{'A'*i}L"} for i in range(1000)]
        await client.encode(
            items=sequences,
            output='disk',
            file_path='embeddings.jsonl',
            stop_on_error=False
        )

asyncio.run(process_large_dataset())

# Manual batching with list-of-lists
batches = [
    [{"sequence": "MDNELE"}, {"sequence": "MENDEL"}],  # Batch 1
    [{"sequence": "ISOTYPE"}, {"sequence": "ANTIBODY"}],  # Batch 2
]
results = client.predict(items=batches, stop_on_error=False)
print(f"Processed {len(results)} sequences")

# Context manager for automatic cleanup
with BioLMApi("esmfold") as client:
    result = client.predict(items=[{"sequence": "MKQHKAMIVALIVICITAVVAALVTRKD"}])
    print(result[0]["pdb"])
```

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

### Basic Usage of py-biolm SDK

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/quickstart.rst

Demonstrates fundamental operations of the py-biolm SDK, including encoding a single sequence, predicting a batch of sequences, and saving predictions to a file. Requires the 'biolm' module to be imported.

```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")
```

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

### Verify BioLM API Token with 'status' command

Source: https://github.com/biolm/py-biolm/blob/main/README.md

Verifies that the BIOLMAI_TOKEN environment variable is set correctly by running the 'biolmai status' command. This command confirms the authentication setup for the BioLM API.

```shell
biolmai status
```

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

### High-Level BioLM Interface Examples

Source: https://context7.com/biolm/py-biolm/llms.txt

Demonstrates the universal entry point for all BioLM API operations, including protein folding, sequence embedding, protein generation, and error handling without exceptions.

```python
from biolmai import BioLM

# Single sequence protein folding
result = BioLM(
    entity="esmfold",
    action="predict",
    type="sequence",
    items="MSILVTRPSPAGEELVSRLRTLGQVAWHFPLIEFSPGQQLPQLADQLAALGESDLLFALSQH"
)
print(result["pdb"])
print(result["mean_plddt"])

# Batch processing multiple sequences
results = BioLM(
    entity="esmfold",
    action="predict",
    type="sequence",
    items=["MDNELE", "MENDEL", "ISOTYPE"]
)
for r in results:
    print(f"pLDDT: {r['mean_plddt']}, PDB length: {len(r['pdb'])}")

# Sequence embedding generation
embedding = BioLM(
    entity="esm2-8m",
    action="encode",
    type="sequence",
    items="MSILVTRPSPAGEEL"
)
print(embedding["embeddings"])

# Protein generation with parameters
sequences = BioLM(
    entity="progen2-oas",
    action="generate",
    type="context",
    items="M",
    params={"temperature": 0.7, "top_p": 0.6, "num_samples": 3, "max_length": 50}
)
for seq in sequences:
    print(seq["sequence"])

# Error handling without exceptions
result = BioLM(
    entity="esmfold",
    action="predict",
    type="sequence",
    items="INVALID::SEQUENCE",
    raise_httpx=False
)
if "error" in result:
    print(f"Error: {result['error']}, Status: {result['status_code']}")
```

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

### Install BioLM Package in Editable Mode

Source: https://github.com/biolm/py-biolm/blob/main/README.md

Installs the 'biolmai' package in editable mode using make. This allows changes in the package code to be reflected immediately without reinstallation, which is ideal for development.

```shell
make install
```

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

### Run Code Quality and Tests (Shell)

Source: https://github.com/biolm/py-biolm/blob/main/CONTRIBUTING.rst

These commands check your code quality with flake8 and run tests using setup.py or pytest. Tox is used to test against multiple Python versions. Ensure flake8 and tox are installed in your virtual environment.

```shell
flake8 biolmai tests
python setup.py test or pytest
tox
```

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

### Auto-Batching Example with BioLM Client

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/batching.rst

Provides an example of how the BioLM client's auto-batching works. When a list of items is provided, the client automatically splits it into batches based on the model's maximum batch size, ensuring efficient processing.

```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
```

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

### Run Automated Tests with a Specific Seed

Source: https://github.com/biolm/py-biolm/blob/main/README.md

Executes the automated tests for the BioLM Python SDK with a specified seed using the 'make test' command. The 'RS' environment variable ensures that random operations within the tests are reproducible.

```shell
RS=118 make test
```

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

### Advanced Manual Batching with BioLMApi (Python)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/api_client.rst

Provides an example of advanced manual batching using BioLMApi's `_batch_call_autoschema_or_manual` method. This allows for fine-grained control over how data is batched before being sent to the API, useful for optimizing performance or handling specific data structures.

```python
from biolmai.client import BioLMApi

# Advanced: manual batching
model = BioLMApi("esm2-8m") # Example model
batches = [[{"sequence": "SEQ1"}, {"sequence": "SEQ2"}], [{"sequence": "SEQ3"}]]
result = model._batch_call_autoschema_or_manual("encode", batches)
```

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

### Asynchronous Protein Structure Prediction

Source: https://github.com/biolm/py-biolm/blob/main/README.rst

Provides an example of asynchronous protein structure prediction using the `BioLMApiClient`. It demonstrates initializing the client for 'esmfold', making an asynchronous 'predict' call with a list of sequences, and printing the result.

```python
from biolmai.client import BioLMApiClient
import asyncio

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

asyncio.run(main())
```

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

### Set BIOLMAI_TOKEN Environment Variable

Source: https://github.com/biolm/py-biolm/blob/main/README.md

Sets the 'BIOLMAI_TOKEN' environment variable in the shell to authenticate requests to the BioLM API. The token is required for accessing API functionalities and can be obtained from the BioLM website.

```shell
export BIOLMAI_TOKEN=<your_token>
```

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

### Interoperability: Running Async Client from Sync Code

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/async_sync.rst

Provides an example of how to run the asynchronous BioLMApiClient from synchronous Python code. This is achieved by using `asyncio.run()` within a synchronous function, allowing integration of async capabilities into existing synchronous workflows.

```python
import asyncio
from biolmai.client import BioLMApiClient

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

result = run_sync()
```

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

### Manual Batching with Error Handling in BioLM

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/batching.rst

Shows manual batching with the `stop_on_error` parameter in the BioLM client. This example uses a list of lists for batching and sets `stop_on_error=False` to continue processing even if some batches contain 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]
```

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

### BioLM: Encode Sequence with ESM2-8M

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/api_biolm.rst

Encodes a single biological sequence using the ESM2-8M model via the BioLM API. This function takes the model entity, action type, and sequence as input. It requires the 'biolm' library to be installed.

```python
result = biolm(entity="esm2-8m", action="encode", type="sequence", items="MSILVTRPSPAGEEL")
```

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

### Generate sequences using BioLMApi (Python)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/api_client.rst

Shows how to use the BioLMApi client for synchronous sequence generation, including parameters for controlling the generation process like temperature and top_p. Suitable for models like ProGen2-OAS.

```python
from biolmai.client import BioLMApi

# ProGen2-OAS: generate new sequences
model = BioLMApi("progen2-oas")
result = model.generate(
    items=[{"context": "M"}],
    params={"temperature": 0.7, "top_p": 0.6, "num_samples": 2, "max_length": 17}
)
```

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

### Lookup Operations: Single, Batch, and Raw Queries

Source: https://context7.com/biolm/py-biolm/llms.txt

Illustrates how to perform database and knowledge base queries using the BioLMApi client. Supports single lookups by specific identifiers, batch lookups for multiple queries, and accessing the raw HTTP response for detailed inspection.

```python
from biolmai.client import BioLMApi

client = BioLMApi("uniprot")

# Single lookup
result = client.lookup(query={"accession": "P12345"})
print(result)

# Batch lookup
queries = [
    {"accession": "P12345"},
    {"accession": "Q9Y6K9"},
    {"accession": "O15111"}
]
results = client.lookup(query=queries)
for r in results:
    print(r)

# Raw response access
result = client.lookup(query={"accession": "P12345"}, raw=True)
print(f"Data: {result.data}")
print(f"Status: {result.raw.status_code}")
print(f"Headers: {result.raw.headers}")
```

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

### Commit and Push Changes (Shell)

Source: https://github.com/biolm/py-biolm/blob/main/CONTRIBUTING.rst

These commands stage all your changes, commit them with a descriptive message, and push the branch to your GitHub repository. Replace 'Your detailed description of your changes.' with a summary of your modifications.

```shell
git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature
```

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

### Deploy to PyPI using bump2version (Shell)

Source: https://github.com/biolm/py-biolm/blob/main/CONTRIBUTING.rst

This command sequence is for maintainers to deploy new versions to PyPI. It involves committing changes, updating the version using bump2version, pushing to GitHub, and pushing tags. Travis CI automatically deploys to PyPI upon successful tests.

```shell
bump2version patch # possible: major / minor / patch
git push
git push --tags
```

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

### CLI Authentication Management for BioLM

Source: https://context7.com/biolm/py-biolm/llms.txt

Provides commands for managing authentication via the command-line interface. Includes checking status, logging in and out, setting API tokens via environment variables, and verifying the authentication status.

```bash
# Check authentication status
biolmai status

# Login with username/password
biolmai login

# Logout
biolmai logout

# Set API token via environment variable
export BIOLMAI_TOKEN=your_api_token_here

# Verify token is set
biolmai status
```

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

### Schema and Rate Limit Discovery with BioLMApiClient

Source: https://context7.com/biolm/py-biolm/llms.txt

Shows how to automatically fetch API constraints and validation rules for a given model and action. This includes retrieving the full schema for validation purposes and extracting specific parameters like the maximum batch size and throttle rate.

```python
import asyncio
from biolmai.client import BioLMApiClient

async def check_model_limits():
    client = BioLMApiClient("esmfold")

    # Fetch schema for validation
    schema = await client.schema("esmfold", "predict")
    print(f"Schema: {schema}")

    # Extract batch size limit
    max_batch = client.extract_max_items(schema)
    print(f"Maximum batch size: {max_batch}")

    # Check rate limiting
    if schema and "throttle_rate" in schema:
        print(f"Rate limit: {schema['throttle_rate']}")

    await client.shutdown()

asyncio.run(check_model_limits())
```

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

### Programmatic Authentication for BioLM Client

Source: https://context7.com/biolm/py-biolm/llms.txt

Demonstrates different methods for authenticating the BioLM Python client programmatically. Options include using environment variables, providing the API key directly during client instantiation, or relying on a credentials file configured via the CLI.

```python
# Programmatic authentication
import os
from biolmai.client import BioLMApi

# Option 1: Environment variable
os.environ["BIOLMAI_TOKEN"] = "your_token"
client = BioLMApi("esmfold")

# Option 2: Direct API key
client = BioLMApi("esmfold", api_key="your_token")

# Option 3: Credentials file (set via CLI login)
# Automatically reads from ~/.biolmai/credentials
client = BioLMApi("esmfold")
```

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

### BioLMApi Synchronous Client Usage (Python)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/usage.rst

Illustrates advanced synchronous usage with the BioLMApi client, offering more control over batching, error handling, and schema access. Useful for complex workflows and integrations.

```python
from biolmai.client import BioLMApi

# Use BioLMApi for more control, e.g. batching, error handling, schema access
model = BioLMApi("esm2-8m", raise_httpx=False)

# Encode a batch
result = model.encode(items=[{"sequence": "SEQ1"}, {"sequence": "SEQ2"}])

# Generate with ProGen2-OAS
model = BioLMApi("progen2-oas")
result = model.generate(
    items=[{"context": "M"}],
    params={"temperature": 0.7, "top_p": 0.6, "num_samples": 2, "max_length": 17}
)

# Access the schema for a model/action
schema = model.schema("esm2-8m", "encode")
max_batch = model.extract_max_items(schema)

# Call the API directly (rarely needed)
resp = model.call("encode", [{"sequence": "SEQ1"}])

# Advanced: manual batching
batches = [[{"sequence": "SEQ1"}, {"sequence": "SEQ2"}], [{"sequence": "SEQ3"}]]
result = model._batch_call_autoschema_or_manual("encode", batches)
```

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

### Direct API Call with BioLMApi (Python)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/api_client.rst

Demonstrates how to make a direct, low-level call to the BioLM API using the BioLMApi client. This method bypasses some of the higher-level abstractions and is typically used for specific scenarios or debugging.

```python
from biolmai.client import BioLMApi

# Call the API directly (rarely needed)
model = BioLMApi("esm2-8m") # Example model
resp = model.call("encode", [{"sequence": "SEQ1"}])
```

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

### High-Level BioLM Interface

Source: https://context7.com/biolm/py-biolm/llms.txt

The universal entry point for all BioLM API operations. This interface simplifies common tasks like protein folding, sequence encoding, and generation with easy-to-use parameters.

```APIDOC
## High-Level BioLM Interface

### Description
Universal entry point for all BioLM API operations, simplifying tasks like protein folding, sequence encoding, and generation.

### Method
POST (implicitly through the BioLM class instantiation and method calls)

### Endpoint
Not directly exposed as a single endpoint, but interacts with various BioLM API endpoints based on `entity`, `action`, and `type`.

### Parameters

#### Request Body (Implicit)
- **entity** (string) - Required - The biological model entity to use (e.g., "esmfold", "esm2-8m", "progen2-oas", "esm1v-all").
- **action** (string) - Required - The action to perform (e.g., "predict", "encode", "generate").
- **type** (string) - Required - The type of input data (e.g., "sequence", "context").
- **items** (string or list of strings/objects) - Required - The input data for the action (e.g., protein sequences, contexts).
- **params** (object) - Optional - Additional parameters specific to the action and entity (e.g., temperature, top_p, num_samples, max_length for generation).
- **raise_httpx** (boolean) - Optional - If set to `False`, errors will be returned in the result dictionary instead of raising exceptions.

### Request Example
```json
{
  "entity": "esmfold",
  "action": "predict",
  "type": "sequence",
  "items": "MSILVTRPSPAGEELVSRLRTLGQVAWHFPLIEFSPGQQLPQLADQLAALGESDLLFALSQH"
}
```

### Response
#### Success Response (200)
- **pdb** (string) - PDB structure string (for prediction actions).
- **mean_plddt** (float) - Confidence score for the prediction.
- **embeddings** (list of floats) - List of embedding vectors (for encoding actions).
- **sequence** (string) - Generated protein sequence (for generation actions).
- **error** (string) - Error message if `raise_httpx` is `False` and an error occurs.
- **status_code** (integer) - HTTP status code if `raise_httpx` is `False` and an error occurs.

#### Response Example (Prediction)
```json
{
  "pdb": "ATOM      1  N   MET A   1  ...",
  "mean_plddt": 0.923
}
```

#### Response Example (Encoding)
```json
{
  "embeddings": [0.123, -0.456, ...]
}
```

#### Response Example (Generation)
```json
{
  "sequence": "MKTAYELLRQGFISLLDVVVV"
}
```

#### Response Example (Error Handling)
```json
{
  "error": "Invalid sequence format.",
  "status_code": 400
}
```
```

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

### Access Schema and Batch Size with BioLMApi (Python)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/api_client.rst

Illustrates how to retrieve the schema for a specific model and action using BioLMApi, and how to programmatically extract the maximum batch size from the schema. This is useful for understanding API capabilities and for advanced batching strategies.

```python
from biolmai.client import BioLMApi

# Access the schema for a model/action
model = BioLMApi("progen2-oas") # Example model
schema = model.schema("esm2-8m", "encode")
max_batch = model.extract_max_items(schema)
```

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

### Clone py-biolm Repository (Shell)

Source: https://github.com/biolm/py-biolm/blob/main/CONTRIBUTING.rst

This command clones your forked repository of py-biolm to your local machine. Ensure you replace 'your_name_here' with your actual GitHub username.

```shell
git clone git@github.com:your_name_here/biolmai.git
```

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

### Configure BioLMApi with Custom Timeout and Semaphore

Source: https://context7.com/biolm/py-biolm/llms.txt

This snippet shows how to instantiate BioLMApi with a custom httpx.Timeout object for granular control over request timings. It also demonstrates setting up an asyncio.Semaphore to limit concurrent requests when using multiple BioLMApiClient instances.

```python
from biolmai.client import BioLMApi
import asyncio
import httpx

# Custom timeout configuration
custom_timeout = httpx.Timeout(
    timeout=30.0,  # 30 seconds total timeout
    connect=5.0,   # 5 seconds connection timeout
    read=25.0,     # 25 seconds read timeout
    write=10.0     # 10 seconds write timeout
)

client = BioLMApi(
    model_name="esmfold",
    base_url="https://biolm.ai/api/v3",
    timeout=custom_timeout,
    raise_httpx=True,
    unwrap_single=False  # Always return lists
)

# Using shared semaphore across multiple clients
shared_semaphore = asyncio.Semaphore(10)  # 10 total concurrent requests

async def multi_model_processing():
    # Assuming BioLMApiClient is available or BioLMApi can be used with client instances
    # For demonstration, let's assume a BioLMApiClient class exists that takes a semaphore
    # If not, this part might need adjustment based on the actual SDK's client management
    class BioLMApiClient: # Placeholder for demonstration
        def __init__(self, model_name, semaphore):
            self.model_name = model_name
            self.semaphore = semaphore
            print(f"Initialized client for {model_name}")
        async def predict(self, items):
            async with self.semaphore:
                print(f"Predicting with {self.model_name}...")
                await asyncio.sleep(0.1) # Simulate API call
                return [{{'result': 'prediction_data'}} for _ in items]
        async def encode(self, items):
            async with self.semaphore:
                print(f"Encoding with {self.model_name}...")
                await asyncio.sleep(0.1) # Simulate API call
                return [{{'result': 'encoding_data'}} for _ in items]
        async def shutdown(self):
            print(f"Shutting down client for {self.model_name}")
            pass

    client1 = BioLMApiClient("esmfold", semaphore=shared_semaphore)
    client2 = BioLMApiClient("esm2-8m", semaphore=shared_semaphore)

    sequences = [{"sequence": "MDNELE"}] * 20

    # Both clients share the same concurrency limit
    results1 = await client1.predict(items=sequences)
    results2 = await client2.encode(items=sequences)

    await client1.shutdown()
    await client2.shutdown()

    return results1, results2

asyncio.run(multi_model_processing())

```

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

### Error Handling Strategies for Production Workflows

Source: https://context7.com/biolm/py-biolm/llms.txt

Details various strategies for robust error management in BioLM applications. Includes graceful degradation without exceptions, exception-based handling using try-except blocks, automatic retries on batch errors, and stopping execution upon encountering the first error.

```python
from biolmai import BioLM
from biolmai.client import BioLMApi
import httpx

# Strategy 1: Graceful degradation without exceptions
sequences = ["VALID", "INVALID::SEQ", "ANOTHER"]
results = BioLM(
    entity="esmfold",
    action="predict",
    type="sequence",
    items=sequences,
    raise_httpx=False,
    stop_on_error=False
)

for i, r in enumerate(results):
    if "error" in r:
        print(f"Sequence {i} failed: {r['error']}")
    else:
        print(f"Sequence {i} pLDDT: {r['mean_plddt']}")

# Strategy 2: Exception-based error handling
try:
    result = BioLM(
        entity="esmfold",
        action="predict",
        type="sequence",
        items="BAD::SEQUENCE",
        raise_httpx=True
    )
except httpx.HTTPStatusError as e:
    print(f"HTTP error: {e.response.status_code}")
    print(f"Response: {e.response.text}")

# Strategy 3: Automatic retry on batch errors
client = BioLMApi("esmfold", retry_error_batches=True, raise_httpx=False)
mixed_batches = [
    [{"sequence": "GOOD"}, {"sequence": "ALSO::BAD"}],
    [{"sequence": "ANOTHER"}]
]
results = client.predict(items=mixed_batches)
# Failed batches are automatically retried individually
print(f"Total results: {len(results)}")

# Strategy 4: Stop on first error
results = BioLM(
    entity="esmfold",
    action="predict",
    type="sequence",
    items=["VALID1", "BAD::SEQ", "VALID2"],
    stop_on_error=True,
    raise_httpx=False
)
print(f"Processed before error: {len(results)}")
```

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

### Encode using BioLMApi (Python)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/api_client.rst

Demonstrates how to use the BioLMApi client for synchronous encoding of items, specifying the model and input data. This is useful for processing sequences with models like ESM2-8M.

```python
from biolmai.client import BioLMApi

# ESM2-8M: encode a batch
model = BioLMApi("esm2-8m")
result = model.encode(items=[{"sequence": "SEQ1"}, {"sequence": "SEQ2"}])
```

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

### Batch Encode Sequences with BioLM Client

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/batching.rst

Shows how to use the BioLM client to encode a batch of sequences. Input is provided as a list of strings, and the `type` parameter must be specified. The client automatically handles batching if `items` is a list.

```python
biolm(entity="esm2-8m", action="encode", type="sequence", items=["SEQ1", "SEQ2"])
```

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

### Configure BioLM API Client with Rate Limiting and Concurrency

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/rate_limiting.rst

This snippet demonstrates how to initialize the BioLM API client with different rate limiting and concurrency configurations. It covers using the API's default throttle, custom requests per second/minute limits, and custom concurrency limits using asyncio Semaphores. It also shows how to combine both custom rate limiting and concurrency.

```python
from biolm.api import BioLMApi
import asyncio

# 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
sem = asyncio.Semaphore(5)
model = BioLMApiClient("esmfold", semaphore=sem)

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

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

### Predict with Structured Batch Input using BioLM Client

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/batching.rst

Illustrates using the BioLM client for predictions with a batch of structured items, where each item is a dictionary. The `type` parameter is inferred from the dictionary keys, simplifying input specification for structured data.

```python
biolm(entity="esmfold", action="predict", items=[{"sequence": "SEQ1"}, {"sequence": "SEQ2"}])
```

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

### Inspect BioLM Model Schema and Max Batch Size

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/batching.rst

Demonstrates how to inspect the BioLM API schema to determine the maximum batch size (`maxItems`) for a given model and action. This involves importing `BioLMApi`, instantiating a model, fetching the schema, and extracting the `maxItems` value.

```python
from biolmai.client 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)
```

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

### BioLMApi Client Class

Source: https://context7.com/biolm/py-biolm/llms.txt

Provides direct client access for advanced control over BioLM API interactions, including configuration for API keys, base URLs, concurrency, rate limiting, and retry mechanisms.

```APIDOC
## BioLMApi Client Class

### Description
Direct client for advanced control over API interactions, allowing configuration of API keys, base URLs, concurrency, rate limiting, and retry policies.

### Method
Multiple methods available on the client instance, such as `predict`, `encode`, `generate`.

### Endpoint
Interacts with the BioLM API endpoints specified by the `base_url` and the client's method calls.

### Parameters

#### Initialization Parameters
- **model_name** (string) - Required - The name of the BioLM model to use (e.g., "esmfold", "esm2-8m").
- **api_key** (string) - Optional - Your BioLM API key. Can also be set via the `BIOLMAI_TOKEN` environment variable.
- **base_url** (string) - Optional - The base URL for the BioLM API. Defaults to "https://biolm.ai/api/v3".
- **raise_httpx** (boolean) - Optional - If `True` (default), raises exceptions for HTTP errors. If `False`, returns error information in the response.
- **unwrap_single** (boolean) - Optional - If `True` (default), unwraps single-item responses. If `False`, responses are always lists.
- **semaphore** (integer) - Optional - The maximum number of concurrent requests allowed.
- **rate_limit** (string) - Optional - The rate limit for API requests (e.g., "1000/second").
- **retry_error_batches** (boolean) - Optional - If `True`, failed batches will be retried individually.

#### Method Parameters (Example: `predict`)
- **items** (list of objects or list of lists of objects) - Required - Input data for the prediction. Each object should contain a "sequence" key.
- **params** (object) - Optional - Additional parameters for the prediction.
- **stop_on_error** (boolean) - Optional - If `True`, processing stops upon the first error.
- **output** (string) - Optional - Specifies the output format, e.g., 'disk' to write to a file.
- **file_path** (string) - Required if `output` is 'disk' - The path to the output file.

### Request Example (Initialization)
```python
from biolmai.client import BioLMApi

client = BioLMApi(
    model_name="esmfold",
    api_key="your_api_token",
    semaphore=5,
    rate_limit="1000/second"
)
```

### Request Example (Prediction)
```python
result = client.predict(items=[{"sequence": "MDNELE"}])
print(result[0]["mean_plddt"])
```

### Response
#### Success Response (200)
- **(Varies by method)** - The structure of the response depends on the method called (e.g., `predict`, `encode`). Generally returns a list of results, where each result corresponds to an input item.

#### Response Example (Prediction)
```json
[
  {
    "pdb": "ATOM      1  N   MET A   1  ...",
    "mean_plddt": 0.915
  }
]
```

#### Response Example (Encoding)
```json
[
  {
    "embeddings": [0.1, -0.2, 0.3, ...]
  }
]
```
```

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

### BioLM High-Level Synchronous API Usage (Python)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/usage.rst

Demonstrates synchronous usage of the BioLM high-level API for encoding sequences, predicting structures, and generating new sequences. This API is suitable for quick scripts and general use.

```python
from biolmai import biolm

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

# ESM2-8M: encode a batch of sequences
result = biolm(entity="esm2-8m", action="encode", type="sequence", items=["SEQ1", "SEQ2"])

# ESMFold: predict structure for a batch
result = biolm(entity="esmfold", action="predict", type="sequence", items=["MDNELE", "MENDEL"])

# ProGen2-OAS: generate new sequences from a context
result = biolm(
    entity="progen2-oas",
    action="generate",
    type="context",
    items="M",
    params={"temperature": 0.7, "top_p": 0.6, "num_samples": 2, "max_length": 17}
)
# result is a list of dicts with "sequence" keys

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

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

### Create and Switch to a New Branch (Shell)

Source: https://github.com/biolm/py-biolm/blob/main/CONTRIBUTING.rst

This command creates a new branch for your bug fix or feature development. Replace 'name-of-your-bugfix-or-feature' with a descriptive name for your branch.

```shell
git checkout -b name-of-your-bugfix-or-feature
```

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

### Encode Sequence with BioLM Client

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/batching.rst

Demonstrates how to use the BioLM client to encode a single sequence. It requires specifying the entity, action, type, and the sequence item. This is a basic usage pattern for single item input.

```python
biolm(entity="esm2-8m", action="encode", type="sequence", items="MSILVTRPSPAGEEL")
```

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

### CLI Authentication with biolmai login (Shell)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/authentication.rst

This shell snippet illustrates the process of logging in using the 'biolmai login' command. This method saves access and refresh tokens, which expire after a period of inactivity. It is not compatible with social logins.

```shell
$ biolmai login

# Username:
# Password:
# Login succeeded!
#
# Saving new access and refresh token.
# { 'user': { 'api_use_count': 13000,
#             'email': 'support@biolm.ai',
#             'get_curr_month_api_use_count': 100,
#             'in_trial': False,
#             'institute': 1,
#             'username': ''}}
```

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

### Predict Batch of Protein Sequences

Source: https://github.com/biolm/py-biolm/blob/main/README.rst

Illustrates using the BioLM constructor to predict structures for a batch of protein sequences using the 'esmfold' entity. It shows how to pass a list of sequences for batch processing.

```python
from biolmai import biolm

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

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

### Advanced Manual Batching with List of Lists in BioLM

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/batching.rst

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

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

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

### BioLM Disk Output with Error Handling (Python)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/disk_output.rst

Demonstrates writing BioLM results to disk in JSONL format. Supports continuing processing on errors or stopping immediately upon encountering the first error.

```python
from biolmai.client import BioLMApi

# Write all results to disk, continue on errors
biolm(entity="esmfold", action="predict", type="sequence", items=["SEQ1", "BADSEQ"], output='disk', file_path="results.jsonl", stop_on_error=False)

# Write to disk, stop on first error
biolm(entity="esmfold", action="predict", type="sequence", items=["SEQ1", "BADSEQ"], output='disk', file_path="results.jsonl", stop_on_error=True)

# Advanced: retry failed batches as single items (BioLMApi only)
model = BioLMApi("esm2-8m", retry_error_batches=True)
model.encode(items=[{"sequence": "SEQ1"}, {"sequence": "BADSEQ"}], output='disk', file_path="out.jsonl")
```

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

### Synchronous Prediction with BioLM

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/async_sync.rst

Demonstrates the basic synchronous usage of the BioLM library for making predictions. This method is straightforward and suitable for simple scripts or Jupyter notebooks. It directly returns the result without requiring an event loop.

```python
from biolmai import biolm
result = biolm(entity="esmfold", action="predict", items="MDNELE")
```

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

### Write Prediction Results to Disk

Source: https://github.com/biolm/py-biolm/blob/main/README.rst

Shows how to save the results of a protein sequence prediction task to a JSONL file. This is achieved by specifying the 'output' parameter as 'disk' and providing a 'file_path'.

```python
from biolmai import biolm

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

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

### Run a Subset of Tests with Pytest (Shell)

Source: https://github.com/biolm/py-biolm/blob/main/CONTRIBUTING.rst

This command allows you to run a specific subset of tests using pytest. Replace 'tests.test_biolmai' with the relevant test module or function you wish to execute.

```shell
pytest tests.test_biolmai
```

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

### Async Client Operations: Parallel Processing and Streaming

Source: https://context7.com/biolm/py-biolm/llms.txt

Demonstrates high-performance asynchronous API access using BioLMApiClient. Supports parallel processing of multiple models and concurrent actions, as well as generator-based streaming for large datasets to disk, managing concurrency with semaphores and rate limits.

```python
import asyncio
from biolmai.client import BioLMApiClient

async def parallel_processing():
    # Create async client
    client = BioLMApiClient(
        model_name="esmfold",
        semaphore=20,  # 20 concurrent requests
        rate_limit="500/second"
    )

    # Process multiple models in parallel
    sequences = [{"sequence": "MDNELE"}, {"sequence": "ISOTYPE"}]

    # Run different actions concurrently
    fold_task = client.predict(items=sequences)
    embed_task = client.encode(items=sequences)

    folds, embeddings = await asyncio.gather(fold_task, embed_task)

    print(f"Folds: {len(folds)}, Embeddings: {len(embeddings)}")

    await client.shutdown()

asyncio.run(parallel_processing())

# Generator-based streaming for large datasets
async def stream_process():
    async with BioLMApiClient("esm2-8m", rate_limit="100/second") as client:
        # Generate sequences on-the-fly
        def sequence_generator():
            for i in range(10000):
                yield {"sequence": f"MKKL{'A'*i}END"}

        results = await client.encode(
            items=sequence_generator(),
            output='disk',
            file_path='large_embeddings.jsonl'
        )

asyncio.run(stream_process())
```

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

### Asynchronous Batch Prediction with BioLMApiClient

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/async_sync.rst

Demonstrates performing batch predictions asynchronously using BioLMApiClient. This method allows for concurrent processing of multiple items, leveraging Python's asyncio capabilities for efficiency in high-throughput scenarios. It returns a list of results.

```python
import asyncio
from biolmai.client import BioLMApiClient

async def main():
    model = BioLMApiClient("esmfold")
    # Batch: returns a list of dicts
    result = await model.predict(items=[{"sequence": "MDNELE"}, {"sequence": "MENDEL"}])
    print(result[0]["mean_plddt"], result[1]["mean_plddt"])

asyncio.run(main())
```

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

### Set BIOLMAI_TOKEN Environment Variable (Python)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/authentication.rst

This Python snippet shows how to set the BIOLMAI_TOKEN environment variable programmatically using the `os` module. This is useful for applications that need to authenticate API requests without manual shell configuration.

```python
import os
os.environ['BIOLMAI_TOKEN'] = '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'
```

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

### Asynchronous Prediction with BioLMApiClient

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/async_sync.rst

Illustrates the asynchronous usage of the BioLMApiClient for predictions. This approach is designed for high-throughput applications and integrates with Python's asyncio framework. It requires defining an async function and running it within an event loop.

```python
from biolmai.client import BioLMApiClient
import asyncio

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

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

### Encode Sequences with List of Dicts (Python)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/batching.rst

Encodes a batch of items, where each item is a dictionary, using the biolm library. This is a common use case for structured input. It requires the 'esm2-8m' entity and the 'encode' action.

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

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

### Continuing on Errors with Error Dictionaries (Python)

Source: https://github.com/biolm/py-biolm/blob/main/docs/python-client/error_handling.rst

Shows how to set raise_httpx to False and stop_on_error to False, allowing the client to continue processing all items even if some fail. Errors are returned as dictionaries within the results list, containing 'error' and 'status_code' keys.

```python
result = biolm(entity="esmfold", action="predict", items=["GOODSEQ", "BADSEQ"], raise_httpx=False, stop_on_error=False)
# result[0] is a normal result, result[1] is a dict with "error" and "status_code"
```