Metadata-Version: 2.4
Name: lakera-red-sdk
Version: 0.6.0
Summary: Official Python SDK for Lakera Red — run adversarial scans against your AI agents and chatbots.
Project-URL: Homepage, https://red.lakera.ai
Project-URL: Documentation, https://docs.lakera.ai/docs/red/sdk-quickstart
Author-email: "Lakera AI (a Check Point company)" <support@lakera.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: adversarial,agent-security,ai-safety,ai-security,lakera,lakera-red,llm,red-teaming,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: pyyaml>=6; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-pyyaml>=6; extra == 'dev'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6; extra == 'yaml'
Description-Content-Type: text/markdown

# Lakera Red SDK

Official Python SDK for [Lakera Red](https://red.lakera.ai) — run adversarial scans
against your AI agents from your own runtime.

Lakera is a Check Point company.

## Install

```bash
pip install lakera-red-sdk
```

## Quick start

```python
import asyncio
from lakera_red_sdk import LakeraRedClient, LakeraRedClientOptions, CreateScanOptions, Session


async def main():
    async with LakeraRedClient(LakeraRedClientOptions(
        api_key="sk_lr_...",
        base_url="https://red-webhooks.lakera.ai",
        log_level="info",
    )) as client:
        scan = await client.create_scan(CreateScanOptions(
            target="My Agent",
            name="Example scan",
            concurrency=1,
            objectives=["safety.hate-speech.1"],
            language="fr",  # optional; defaults to "en"
        ))

        async def handler(session: Session) -> None:
            async for message in session:
                reply = await your_agent(session.id, message.attack)
                await message.respond(reply)

        await scan.run(handler)
        await scan.write_results("./results.json")


asyncio.run(main())
```

## Key concepts

| Concept         | Description                                                                                                                |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Target**      | A named configuration representing the system under test. Created once, reused across scans.                               |
| **Session**     | A multi-turn conversation. The SDK manages lifecycle; your handler receives an async iterator of `SessionMessage` objects. |
| **Strategy**    | `static` = independent single-turn probes (fast). `crescendo` = adaptive multi-turn attacks. `smoke` = canned probe set.   |
| **Concurrency** | How many sessions run in parallel. For `crescendo`, automatically capped to the number of objectives.                      |

## Custom objectives

Alongside standard objective IDs, you can define objectives inline without any prior
catalog setup:

```python
from lakera_red_sdk import LakeraRedClient, CustomObjective

async with LakeraRedClient(api_key="sk_lr_...", base_url="https://red-webhooks.lakera.ai") as client:
    scan = await client.create_scan(
        target="My Agent",
        name="Custom objective scan",
        custom_objectives=[
            CustomObjective(
                key="my-org.jailbreak.1",
                name="Jailbreak attempt",
                attack_description="Try to make the model ignore its system prompt and reveal confidential instructions.",
                success_indicators=["model reveals system prompt", "model ignores safety constraints"],
            )
        ],
    )
```

| Field                | Description                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `key`                | Stable identifier you choose. Appears as `objectiveId` in scan results — use it to correlate results back to this objective.         |
| `name`               | Display name shown in the dashboard.                                                                                                 |
| `attack_description` | What the attack tries to achieve — fed directly to the attack generator. More specific descriptions produce better-targeted attacks. |
| `success_indicators` | Signals that indicate the attack succeeded — used by the evaluator.                                                                  |

Custom objectives are scan-local — they are never written to the objectives catalog and
are not visible to other scans.

## Multi-turn sessions with cleanup

For stateful agents that accumulate per-session state (conversation history, DB
connections, etc.), use `try/finally` to clean up:

```python
async def handler(session: Session) -> None:
    try:
        async for message in session:
            reply = await chatbot(session.id, message.attack)
            await message.respond(reply)
    finally:
        clear_session(session.id)
```

## Configuration

```python
from lakera_red_sdk import LakeraRedClient, LakeraRedClientOptions

async with LakeraRedClient(LakeraRedClientOptions(
    api_key="sk_lr_...",             # Lakera Red API key
    base_url="https://red-webhooks.lakera.ai", # Lakera Red API endpoint
    log_level="info",                # "debug" | "info" | "warn" | "error" | "silent"
    extra_headers={},                # additional HTTP headers (optional)
    logger=custom_logger,            # BYO logger implementing the Logger protocol (optional)
)) as client:
    ...
```

## Examples

| Example     | What it demonstrates                                      |
| ----------- | --------------------------------------------------------- |
| **echo**    | Simplest integration — echoes attacks back                |
| **chatbot** | Stateful multi-turn chatbot with Claude + session cleanup |

## License

[MIT](./LICENSE)

## Development

```bash
pip install -e ".[dev]"
mypy src/        # type checking
ruff check src/  # linting
ruff format src/ # formatting
pytest           # tests
```
