# Preclinical Python SDK

Python SDK for the [Preclinical](https://preclinical.co) healthcare AI safety testing platform.

## Installation

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

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

## Quick Start

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

```python
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.):

```python
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](https://docs.preclinical.co)
