# uip ixp documents & labellings

> Syntax and options for `uip ixp documents` and `uip ixp labellings`, which manage training documents and review/confirm the model's predictions on them.

`uip ixp documents` manages a project's raw training documents (upload/download/delete/list). `uip ixp labellings` reviews and confirms the model's predictions on those documents — the human-in-the-loop step that produces ground truth for retraining. See [Concepts](./uip-ixp.md#concepts) on the parent page for how this fits into the training loop.

## Synopsis

```text
uip ixp documents list <project-name> [-l, --limit <n>] [--offset <n>]
uip ixp documents download <project-name> <document-id> [-o, --output <path>]
uip ixp documents upload <project-name> <file>
uip ixp documents delete <project-name> <document-id> -y

uip ixp labellings confirm <project-name> [document-id] [-f, --fields <ids>] [-c, --corrections <json>] [--group <name>] [--occurrence <n>] [--updates <json>] [-m, --model-version <n>]
uip ixp labellings unconfirm <project-name> <document-id> [-f, --fields <ids>] [--group <name>] [--occurrence <n>] [--updates <json>]
uip ixp labellings mark-missing <project-name> <document-id> -f, --fields <ids>
uip ixp labellings get-predictions <project-name> [document-id]
```

## uip ixp documents

Read IXP document content.

### uip ixp documents list

List all documents in a project.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-name>` | yes | Project name. |

#### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-l` | `--limit <number>` | 1-10000 | 50 | Number of items to return. |
| — | `--offset <number>` | 0-1000000 | 0 | Number of items to skip. |

#### Examples

```bash
uip ixp documents list my-invoices
```

```bash
uip ixp documents list my-invoices --limit 100 --offset 100
```

#### Data shape (--output json)

```json
{
  "Code": "IxpDocumentsList",
  "Data": {
    "Documents": [
      { "DocumentId": "5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21", "AttachmentRef": "c1a7e9d3-8b2f-4e60-9a15-7d3c6f0b4e28", "Filename": "invoice-001.pdf" }
    ],
    "Total": 120,
    "Offset": 0,
    "Limit": 50
  }
}
```

### uip ixp documents download

Download the original document file (PDF/PNG/JPG/etc.) for viewing. The file's extension is auto-corrected to match the real content type the server reports — it doesn't trust `--output`'s extension.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-name>` | yes | Project name. |
| `<document-id>` | yes | Document ID. |

#### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-o` | `--output <path>` | path | a generated tmpdir path | Output file path. Extension is auto-corrected (e.g. `.jpeg`/`.tiff` are accepted as equivalent to `.jpg`/`.tif`, otherwise a mismatched or missing extension is replaced/appended). |

#### Example

```bash
uip ixp documents download my-invoices 5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21 -o ./doc
```

#### Data shape (--output json)

```json
{
  "Code": "IxpDocumentsDownload",
  "Data": { "Path": "./doc.pdf", "ContentType": "application/pdf", "SizeBytes": 102400 }
}
```

### uip ixp documents upload

Upload a document file to an existing project. Rejects unsupported file extensions client-side before any network call.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-name>` | yes | Project name. |
| `<file>` | yes | Path to the document file to upload. |

#### Example

```bash
uip ixp documents upload my-invoices ./invoice.pdf
```

#### Data shape (--output json)

```json
{
  "Code": "IxpDocumentsUpload",
  "Data": {
    "ProjectName": "my-invoices",
    "Filename": "invoice.pdf",
    "AttachmentRef": "c1a7e9d3-8b2f-4e60-9a15-7d3c6f0b4e28",
    "DocumentId": "5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21"
  }
}
```

### uip ixp documents delete

Delete a document from a project.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-name>` | yes | Project name. |
| `<document-id>` | yes | Document ID. |

#### Options

| Short | Long | Required | Description |
|---|---|---|---|
| `-y` | `--yes` | **yes** | Confirm this irreversible operation. |

#### Example

```bash
uip ixp documents delete my-invoices 5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21
```

#### Data shape (--output json)

```json
{ "Code": "IxpDocumentsDelete", "Data": { "Status": "ok" } }
```

## uip ixp labellings

Manage IXP labellings and predictions — the human review step that turns model predictions into confirmed ground truth.

:::note
`confirm` and `get-predictions` accept an **optional** `[document-id]` — omitting it applies the operation across every document in the project. **This project-wide form is deprecated and will be removed in a future release**; a `[WARN]` line is written to stderr when you omit it (stdout stays parseable for `--output json` scripting). Pass a document id, found via `uip ixp documents list`.
:::

### Repeatable field groups: targeting occurrences

For a repeatable field group (e.g. "Line Items" with one occurrence per invoice line), `confirm` and `unconfirm` share a common targeting model via `--group`:

| Flags | Effect |
|---|---|
| `--group <name>` alone | Targets every occurrence of the group. |
| `--group <name> --occurrence <n>` | Targets exactly one occurrence (0-based index) — the single-line ergonomic form. Requires `--group` and a document id. |
| `--group <name> --updates <json>` | Targets several specific occurrences in **one atomic call**: `[{"occurrence":<n>,"fields"?:[...],"corrections"?:{...}}]` (confirm) or `[{"occurrence":<n>,"fields"?:[...]}]` (unconfirm). `--updates` is the superset — `--occurrence <n>` is equivalent to a single-entry `--updates`. Mutually exclusive with `--occurrence`, `--fields`, and (for `confirm`) `--corrections`. |

`--group` must be the **full label path** exactly as shown in the `Name` field of `get-predictions` output (e.g. `"Invoice > Line Items"`), not just the leaf name.

### uip ixp labellings confirm

Confirm IXP-generated predictions as ground truth for one document.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-name>` | yes | Project name. |
| `[document-id]` | no | Document ID. Omitting it confirms every document in the project — **deprecated**. |

#### Options

| Short | Long | Value | Description |
|---|---|---|---|
| `-f` | `--fields <field-ids>` | comma-separated | Field IDs to confirm. Omit to confirm all predicted fields. Without `--group`, confirms each field ID across every occurrence it appears in; with `--group --occurrence`, confirms only within that occurrence. |
| `-c` | `--corrections <json>` | JSON array | Override predicted values while keeping references: `[{"field_id":"...","value":"corrected"}]`. Applies across every occurrence the field appears in (or the targeted occurrence). Mutually exclusive with `--updates`. |
| — | `--group <name>` | string | Target field group — see targeting table above. |
| — | `--occurrence <index>` | integer | Single-occurrence index within `--group`. See targeting table above. |
| — | `--updates <json>` | JSON array | Batched multi-occurrence form. See targeting table above. |
| `-m` | `--model-version <version>` | non-negative integer | Optimistic-concurrency guard: the model version (from `get-predictions`' `ModelVersion`) the predictions were reviewed against. If a retrain produced a newer version since, the confirm is **rejected** rather than stamping drifted values as ground truth. Omit to skip the check. |

#### Examples

```bash
# Confirm a single document with a field filter and a correction
uip ixp labellings confirm my-invoices 5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21 \
  -f a7c3e9105f2b4d86,b2f8a01c7d3e6940 -c '[{"field_id":"a7c3e9105f2b4d86","value":"INV-7654321"}]'
```

```bash
# Confirm all predicted fields on a document as-is
uip ixp labellings confirm my-invoices 5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21
```

```bash
# Confirm every occurrence of a repeatable group
uip ixp labellings confirm my-invoices 5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21 --group "Line Items"
```

```bash
# Single occurrence
uip ixp labellings confirm my-invoices 5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21 \
  --group "Line Items" --occurrence 2
```

```bash
# Batched: confirm one field in two specific occurrences, in one atomic call
uip ixp labellings confirm my-invoices 5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21 \
  --group "Loan and Property" --updates '[{"occurrence":0,"fields":["e9b1746c0a2f5d83"]},{"occurrence":2,"fields":["e9b1746c0a2f5d83"]}]'
```

#### Data shape (--output json)

```json
{
  "Code": "IxpLabellingsConfirm",
  "Data": { "ProjectName": "my-invoices", "TotalDocuments": 1, "PredictionsConfirmed": 1 }
}
```

`TotalDocuments`/`PredictionsConfirmed` count **documents**, not fields (`PredictionsConfirmed` is 0 or 1 per document — this preserves the legacy CLI's per-document contract even though the underlying field count may be higher).

### uip ixp labellings unconfirm

Remove confirmations from a document — the targeted fields go back to un-annotated. Use to roll back a mistaken `confirm`/`mark-missing`. Every other annotation on the document is carried forward. Shares `confirm`'s `--group`/`--occurrence`/`--updates` targeting model (see table above), minus `--corrections`/`--model-version`.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-name>` | yes | Project name. |
| `<document-id>` | yes | Document ID. |

#### Options

| Short | Long | Value | Description |
|---|---|---|---|
| `-f` | `--fields <field-ids>` | comma-separated | Field IDs to unconfirm. |
| — | `--group <name>` | string | Target field group. |
| — | `--occurrence <index>` | integer | Single-occurrence index. |
| — | `--updates <json>` | JSON array | Batched multi-occurrence form: `[{"occurrence":<n>,"fields"?:[...]}]`. |

At least one of `--fields`/`--group` is required — unconfirming an entire document implicitly is not allowed.

#### Examples

```bash
uip ixp labellings unconfirm my-invoices 5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21 \
  -f a7c3e9105f2b4d86,b2f8a01c7d3e6940
```

```bash
uip ixp labellings unconfirm my-invoices 5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21 --group "Line Items"
```

#### Data shape (--output json)

```json
{
  "Code": "IxpLabellingsUnconfirm",
  "Data": {
    "ProjectName": "my-invoices",
    "DocumentId": "5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21",
    "FieldsUnconfirmed": 2,
    "Unmatched": []
  }
}
```

### uip ixp labellings mark-missing

Mark fields as missing in a document — annotated as having no value and no location. Use when the field is genuinely absent.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-name>` | yes | Project name. |
| `<document-id>` | yes | Document ID. |

#### Options

| Short | Long | Value | Required | Description |
|---|---|---|---|---|
| `-f` | `--fields <field-ids>` | comma-separated | **yes** | Field IDs to mark as missing. |

#### Example

```bash
uip ixp labellings mark-missing my-invoices 5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21 \
  -f a7c3e9105f2b4d86,b2f8a01c7d3e6940
```

#### Data shape (--output json)

```json
{
  "Code": "IxpLabellingsMarkMissing",
  "Data": {
    "ProjectName": "my-invoices",
    "DocumentId": "5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21",
    "FieldsMarked": 2,
    "Unmatched": []
  }
}
```

### uip ixp labellings get-predictions

Get IXP model predictions for documents in a project — predicted labels and field values, plus the `ModelVersion` that produced them (`null` when a document has no predictions yet).

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<project-name>` | yes | Project name. |
| `[document-id]` | no | Document ID. Omitting it fans out across every document in the project — **deprecated**. |

#### Examples

```bash
uip ixp labellings get-predictions my-invoices 5f3a9c21-7e4b-4d8a-9f12-6c0b8e3d2a14.7f3c8a21
```

#### Data shape (--output json)

```json
{
  "Code": "IxpLabellingsGetPredictions",
  "Data": { "ProjectName": "my-invoices", "TotalDocuments": 1, "DocumentsWithPredictions": 1, "Predictions": [] }
}
```

`Predictions` entries preserve the API's native PascalCase, including a per-label `Occurrence` index for repeatable groups.

## Related

- [uip ixp](./uip-ixp.md) — concepts and the full resource directory.
- [uip ixp projects](./uip-ixp-projects.md) — `get-metrics` to check labelling quality; `publish` to ship a retrained model.
- [uip ixp taxonomy](./uip-ixp-taxonomy.md) — the fields/groups predictions here are scored against.

## See also

- [IXP tool overview](./uip-ixp.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)