preclinical 0.2.0

Python SDK for the Preclinical healthcare AI safety testing platform

Preclinical Python SDK

Python SDK for the Preclinical healthcare AI safety testing platform.

Installation

The package is not yet published to PyPI. Install from source:

pip install /path/to/preclinical/sdk/python

Quick Start

from preclinical import Preclinical, CreateTestParams

# Pass api_key directly, or set the PRECLINICAL_API_KEY environment variable
client = Preclinical(api_key="sk_live_...")

# Start a test
test = client.tests.run_and_wait(
    CreateTestParams(agent_id="your-agent-id", test_mode="demo")
)

print(f"Status: {test.status}")
print(f"Pass rate: {test.pass_rate}%")

# Get detailed results
results = client.tests.results(test.id)
for r in results.data:
    status = "PASS" if r.passed else "FAIL"
    print(f"[{status}] {r.scenario_name}")

Usage

from preclinical import Preclinical, CreateAgentParams, CreateTestParams

# Initialize (context manager closes the HTTP client)
with Preclinical(api_key="sk_live_...") as client:

    # Agents
    agents = client.agents.list()
    agent = client.agents.create(CreateAgentParams(
        name="My Agent",
        provider="openai",
        config={"api_key": "sk-...", "base_url": "https://api.openai.com/v1", "target_model": "gpt-4o"},
    ))
    client.agents.validate(agent.id)

    # Tests
    created = client.tests.create(CreateTestParams(agent_id=agent.id))
    test = client.tests.get(created.id)
    results = client.tests.results(created.id)

    # Scenario runs (with transcript)
    run = client.scenario_runs.get(results.data[0].id)
    for entry in run.transcript:
        print(f"[{entry['role']}]: {entry['content']}")

    # Scenarios
    scenarios = client.scenarios.list()

    # Webhooks
    webhooks = client.webhooks.list()

Async Usage

An AsyncPreclinical client is available for async applications (FastAPI, etc.):

from preclinical import AsyncPreclinical, CreateTestParams

async def run_test():
    async with AsyncPreclinical(api_key="sk_live_...") as client:
        test = await client.tests.run_and_wait(
            CreateTestParams(agent_id="your-agent-id", test_mode="demo")
        )
        print(f"Pass rate: {test.pass_rate}%")

The async client mirrors the sync API exactly -- all methods are async and the client supports async with.

Documentation

Full API docs at docs.preclinical.co