@verial-ai/sdk 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,176 @@
+# @verial-ai/sdk
+
+[![npm version](https://img.shields.io/npm/v/@verial-ai/sdk)](https://www.npmjs.com/package/@verial-ai/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+TypeScript SDK and CLI for [Verial](https://verial.ai), the healthcare agent simulation and testing platform.
+
+## Installation
+
+```bash
+npm install @verial-ai/sdk
+```
+
+## Requirements
+
+- Node.js 18+
+- ESM only (`"type": "module"` in your package.json)
+
+## Quick Start
+
+Create an environment, add a simulator, define a benchmark with evals, run it, and check results:
+
+```typescript
+import { Verial } from "@verial-ai/sdk";
+
+const verial = new Verial({ apiKey: process.env.VERIAL_API_KEY });
+
+// 1. Create an environment (a simulated health system)
+const env = await verial.environments.create({
+  name: "Cardiology Clinic",
+});
+
+// 2. Add a FHIR simulator to the environment
+const sim = await verial.simulators.create({
+  type: "FHIR",
+  name: "Primary EHR",
+});
+await verial.environments.addSimulator({
+  environmentId: env.id,
+  simulatorId: sim.id,
+});
+
+// 3. Create a benchmark with a task and eval
+const benchmark = await verial.benchmarks.create({
+  name: "Prior Auth Workflow",
+  environmentId: env.id,
+});
+
+const task = await verial.tasks.create({
+  benchmarkId: benchmark.id,
+  name: "Submit prior auth for MRI",
+  instruction: "Submit a prior authorization request for a brain MRI",
+});
+
+await verial.evals.create({
+  taskId: task.id,
+  label: "Prior auth submitted",
+  assert: "A prior authorization request was successfully submitted for the MRI",
+});
+
+// 4. Run the benchmark
+const run = await verial.runs.create({ benchmarkId: benchmark.id });
+
+// 5. Check results
+const result = await verial.runs.get({ id: run.id });
+console.log(result.verdict, result.score);
+```
+
+## Authentication
+
+Get your API key from the [Verial dashboard](https://app.verial.ai), then pass it to the client:
+
+```typescript
+const verial = new Verial({ apiKey: "your-api-key" });
+```
+
+Or set it via the CLI:
+
+```bash
+verial auth set-key your-api-key
+```
+
+## Common Use Cases
+
+### Run a benchmark
+
+```typescript
+const run = await verial.runs.create({ benchmarkId: "bench_abc123" });
+const result = await verial.runs.get({ id: run.id });
+
+// Inspect individual task results
+const { data: taskRuns } = await verial.taskRuns.list({ runId: run.id });
+for (const tr of taskRuns) {
+  const { data: evalRuns } = await verial.evalRuns.list({ taskRunId: tr.id });
+  console.log(tr.name, evalRuns.map((e) => e.verdict));
+}
+```
+
+### Create a playground for manual testing
+
+```typescript
+const playground = await verial.playgrounds.create({
+  environmentId: "env_abc123",
+});
+
+// Access provisioned sandboxes (FHIR stores, voice lines, etc.)
+const pg = await verial.playgrounds.get({ id: playground.id });
+console.log(pg.sandboxes);
+
+// Clean up when done
+await verial.playgrounds.teardown({ id: playground.id });
+```
+
+### Generate synthetic data
+
+```typescript
+const dataset = await verial.datasets.create({ name: "Diabetic cohort" });
+await verial.datasets.generate({
+  id: dataset.id,
+  prompt: "10 patients with Type 2 diabetes, ages 45-70",
+});
+```
+
+## Error Handling
+
+All API errors throw `VerialApiError` with structured fields:
+
+```typescript
+import { Verial, VerialApiError } from "@verial-ai/sdk";
+
+try {
+  await verial.environments.get({ id: "nonexistent" });
+} catch (err) {
+  if (err instanceof VerialApiError) {
+    console.error(err.status);  // 404
+    console.error(err.code);    // "NOT_FOUND"
+    console.error(err.message); // "Environment not found"
+  }
+}
+```
+
+## CLI
+
+The package includes a CLI for managing resources from the terminal.
+
+```bash
+# Install globally
+npm install -g @verial-ai/sdk
+
+# Authenticate
+verial auth set-key your-api-key
+
+# Manage resources
+verial environments list
+verial benchmarks list
+verial runs create --benchmark-id bench_abc123
+verial runs get run_abc123
+verial playgrounds create --environment-id env_abc123
+```
+
+Run `verial --help` or `verial <command> --help` for all available commands.
+
+## Configuration
+
+| Option    | Default                  | Description       |
+| --------- | ------------------------ | ----------------- |
+| `apiKey`  | (required)               | Your Verial API key |
+| `baseUrl` | `https://api.verial.ai`  | API base URL      |
+
+## Documentation
+
+For complete API reference and guides, visit [docs.verial.ai](https://docs.verial.ai).
+
+## License
+
+MIT