> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Training tasks and verifiers in TypeScript

> Generate, test and review tasks and compiled verifiers through the existing Training workflow

Use a full Arga credential with the `training` resource in v0.2.0+. Upload-only trace keys cannot read collections, generate tasks, approve them or prepare environments. Begin with [SDK evidence](https://docs.argalabs.com/sdks/typescript/tracing.md) or [Braintrust sync](https://docs.argalabs.com/sdks/typescript/braintrust.md).

## Generate a draft

```typescript theme={null}
import { Arga } from 'arga-sdk';

const client = new Arga({ apiKey: process.env.ARGA_API_KEY!, timeout: 300000 });
const dataset = await client.training.get('DATASET_UUID');
let task = await client.training.generateTask(dataset.id, {
  traceId: dataset.traces[0].id,
});
console.log(task.id, task.status, task.revision);
```

Use the collection UUID from an upload receipt or Training URL. Generation can take up to several minutes. The draft includes the task, starting state, evidence, assumptions, scoring rules and a compiled Python snapshot verifier. Incomplete coverage and missing objectives or starting state block generation; omitted state remains unknown.

Expected outcomes follow the objective and operating policy. For a $49 duplicate payment with a prior $12 refund, the task should preserve the original payment, start with the prior refund, and require $49 total refunded. It should exclude the recorded attempt's newly created $37 refund from starting state.

## Inspect and test the verifier

The remaining examples share `client`, `dataset` and `task`:

```typescript theme={null}
import { writeFile, readFile } from 'node:fs/promises';
import { createHash } from 'node:crypto';

const bundle = await client.training.getGrader(dataset.id, task.id);
const artifact = bundle.grader;
if (createHash('sha256').update(artifact.source).digest('hex') !== artifact.source_hash) {
  throw new Error('Verifier hash mismatch');
}
await writeFile('grader.py', artifact.source);
```

The verifier is compiled from the proposed rules, rather than model-written executable code. It supports existence, absence, equality, substring, count and unchanged-state predicates. Generated verifiers remain Python artifacts even when called from TypeScript.

Capture normalized before/after snapshots containing every collection, record and field the rules require. Each collection is `{ "complete": true, "records": [...] }`, nested under provider and resource names. Keep provider keys such as `payment_intents` in snake\_case and use task-consistent IDs. See the shared [snapshot contract](https://docs.argalabs.com/sdks/python/training.md#test-normalized-snapshots).

```typescript theme={null}
const snapshots = JSON.parse(await readFile('snapshots.json', 'utf8'));
const result = await client.training.testGrader(dataset.id, task.id, {
  revision: task.revision,
  before: snapshots.before,
  after: snapshots.after,
});
console.log(result.outcome);
```

You can also run the downloaded verifier locally:

```bash theme={null}
python3 grader.py snapshots.json
```

| Outcome | Meaning | Local exit code |
| - | - | - |
| `pass` | Required predicates hold | 0 |
| `fail` | A required outcome is missing or incorrect | 1 |
| `unsafe` | A forbidden-state guard is violated | 2 |
| `error` | Evidence is missing, incomplete or invalid | 3 |

Snapshots are limited to 2 MB, 5,000 records per collection and 30 rules. Declare empty collections explicitly. The SDK does not capture these snapshots automatically; the `example` in a grader bundle is illustrative. Snapshot verifiers do not judge writing quality, run your agent or detect transient actions undone between captures.

## Edit and rebuild

```typescript theme={null}
const spec = structuredClone(task.spec);
spec.name = 'Duplicate-payment correction';
task = await client.training.updateTask(dataset.id, task.id, {
  revision: task.revision, spec,
});
task = await client.training.prepareGrader(dataset.id, task.id, {
  revision: task.revision,
});
```

Submit the full specification and keep its objective, starting state, provenance and rules consistent. Edits invalidate earlier approval. Use the returned revision for later tests and review; stale revisions return HTTP 409.

## Review and approve

Open the collection in [Training](https://app.argalabs.com/training). Review its task, starting state, scoring, source evidence, assumptions and compiled grader. After that review:

```typescript theme={null}
const approved = await client.training.reviewTask(dataset.id, task.id, {
  revision: task.revision,
  decision: 'approved',
  acknowledgeAssumptions: true,
  acknowledgeGrader: true,
});
console.log(approved.scenarioId);
```

Do not automate the acknowledgements without inspecting the actual revision. Approval saves a reusable Scenario. Rejected or unreviewed tasks cannot be exported as approved tasks or used to prepare environments.

```typescript theme={null}
const environment = await client.training.createEnvironment(dataset.id, task.id);
const jsonl = await client.training.exportJsonl(dataset.id);
await writeFile('approved-tasks.jsonl', jsonl);
```

If you edit or rebuild a task, review its current revision again before preparing an environment. These methods prepare data and service environments; they do not run customer agents or train a model. Collections remain private to their owner within the existing Training storage lifecycle. Requested generation sends selected evidence to Arga's configured model provider; v1 adds no automatic expiry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.