Python SDK

The Biolevate Python SDK (biolevate) is a high-level async client for the Biolevate API. It provides typed models, structured error handling, and a clean interface for all API resources.

Installation

pip

pip install biolevate

uv

uv add biolevate

Poetry

poetry add biolevate

Client Initialization

BiolevateClient is the main entry point. It takes your API domain and Personal Access Token (PAT).

from biolevate import BiolevateClient

client = BiolevateClient(
    base_url="https://<api-domain>",
    token="<your-pat>",
)

Using as an async context manager

The recommended pattern is to use BiolevateClient as an async context manager. This ensures the underlying HTTP connections are properly closed when your code finishes.

import asyncio
from biolevate import BiolevateClient

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        page = await client.providers.list()
        for provider in page.data:
            print(provider.name)

asyncio.run(main())

Error Handling

The SDK raises typed exceptions for all error cases. Import them from the biolevate package:

from biolevate import (
    BiolevateClient,
    BiolevateError,
    NotFoundError,
    AuthenticationError,
    APIError,
)

Exception hierarchy

Exception	When it is raised
BiolevateError	Base class — catches any SDK error
NotFoundError	The requested resource does not exist (404)
AuthenticationError	Invalid or expired PAT, or insufficient permissions (401 / 403)
APIError	Any other unexpected API error — exposes status_code and message

Example

from biolevate import BiolevateClient, NotFoundError, AuthenticationError, APIError

async def main():
    async with BiolevateClient(
        base_url="https://<api-domain>",
        token="<your-pat>",
    ) as client:
        try:
            provider = await client.providers.get("invalid-uuid")
        except NotFoundError:
            print("Provider not found")
        except AuthenticationError:
            print("Invalid token or access denied")
        except APIError as e:
            print(f"API error {e.status_code}: {e.message}")

asyncio.run(main())

Available Resources

Resource	SDK attribute	Guide
Providers	client.providers	Providers
Provider Items	client.items	Provider Items
Files	client.files	Files
Collections	client.collections	Collections
QA Jobs	client.qa	Question Answering
Extraction	client.extraction	Extraction

Next Steps

• Providers — list and retrieve storage providers
• Provider Items — browse, upload, download, rename, and delete files and folders
• Files — create EliseFiles, trigger indexation, retrieve ontologies
• Collections — organise indexed files into collections
• Question Answering — run AI question answering jobs on documents
• Extraction — run AI metadata extraction jobs on documents