Metadata-Version: 2.4
Name: beaker-sdk
Version: 0.4.0
Summary: Beaker prompt-optimization SDK and CLI by BeakerAI.
Author: BeakerAI
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: pyyaml>=6
Requires-Dist: pydantic-ai>=1.74 ; extra == 'pydantic-ai'
Requires-Dist: opentelemetry-api>=1.30,<2 ; extra == 'pydantic-ai'
Requires-Dist: opentelemetry-sdk>=1.30,<2 ; extra == 'pydantic-ai'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30,<2 ; extra == 'pydantic-ai'
Requires-Dist: opentelemetry-api>=1.30,<2 ; extra == 'tracing'
Requires-Dist: opentelemetry-sdk>=1.30,<2 ; extra == 'tracing'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30,<2 ; extra == 'tracing'
Requires-Dist: opentelemetry-proto>=1.30,<2 ; extra == 'tracing'
Requires-Python: >=3.12
Provides-Extra: pydantic-ai
Provides-Extra: tracing
Description-Content-Type: text/markdown

# beaker

Beaker SDK and CLI package.

`beaker` gives developers the tools to define optimization specs,
validate them locally, upload datasets, configure hosted run environments,
launch optimization runs, and inspect results from code or the CLI.

Customer specs import contract types directly from `beaker`:

```python
from beaker import Case, CaseDataLoader, CaseResult, CaseScore, Spec, spec
```

Hosted model-selection rollouts also expose a generic OpenAI-compatible target:

```python
from beaker import RolloutContext, inference_target


def build_eval_client(runtime: RolloutContext):
    target = inference_target(runtime)
    return YourFrameworkClient(
        base_url=target.base_url,
        api_key=target.api_key,
        model=target.model,
    )
```

Call `inference_target` only in the evaluation path when `runtime.model` is
set. Production application calls should retain the application's existing
model and client defaults. The structural `beaker run smoke` check does not
invoke this path.

## CLI run lifecycle

The CLI is intentionally noninteractive: choose the remote GitHub branch,
dataset, run type, and models before invoking it. `--ref` resolves a remote
GitHub ref, so unpushed local changes are not included.

```bash
# Discover launch inputs.
beaker github branches --repo owner/repository
beaker model list --available-only

# Ordinary prompt optimization.
beaker run trigger --ref feature/prompts --dataset invoices@production

# Optimize the production system without an initial benchmark.
beaker run trigger --ref feature/prompts --dataset invoices \
  --execution-mode optimize_only

# Benchmark and optimize selected models.
beaker run trigger --ref feature/prompts --dataset invoices \
  --optimization-model openai:gpt-4o \
  --optimization-model anthropic:claude-sonnet-4-5 \
  --execution-mode benchmark_and_optimize --benchmark-split TEST

# Discover, inspect, and cancel runs.
beaker run list
beaker run status RUN_ID
beaker run status RUN_ID --watch
beaker run cancel RUN_ID
```

Lifecycle commands support stable JSON for automation:

```bash
beaker model list --json
beaker github branches --repo owner/repository --json
beaker run trigger --ref feature/prompts --dataset invoices --json
beaker run list --json
beaker run status RUN_ID --json
beaker run cancel RUN_ID --json
```
