SK-3075: Document the new Detect methods for the skyvault and flowvault SDKs

flowvault/README.md

@@ -837,7 +837,7 @@ Upload one or more files to file columns. The SDK **orchestrates** this in two s
 
 **Note:**
 
-- `records` is required and must be a non-empty list of `UploadFilesRequestRecord`; each needs a `table_name` and a non-empty `columns` list.
+- `records` is required and must be a non-empty list of `UploadFilesRequestRecord`; each needs a `table_name` and a non-empty `columns` list. A column can appear only once in a record; a repeated column name fails validation.
 - Each `UploadFilesRequestColumn` needs a `column` name and **exactly one** file source — `file_path`, `base64`, or `file_object`. `base64` additionally requires `file_name`. The upload's content type is inferred from the file name.
 - Omit `skyflow_id` to create a new record (CREATE permission); set it to upload into an existing record (UPDATE permission).
 - `file_name` is derived from `file_path`/`file_object` when omitted; if still unset, the server generates one.
@@ -893,7 +893,7 @@ Delete files from file columns of existing records — and remove the stored obj
 
 **Note:**
 
-- `records` is required and must be a non-empty list of `DeleteFilesRequestRecord`; each needs a `table_name` and a non-empty `columns` list of file-column names.
+- `records` is required and must be a non-empty list of `DeleteFilesRequestRecord`; each needs a `table_name` and a non-empty `columns` list of file-column names. A column name can appear only once in a record; a repeated name fails validation.
 - Each record sets **exactly one** of `skyflow_id` or `unique_values` — both, or neither, fails validation.
 - `unique_values` takes the same shape as in [Get](#get): a list of dicts, each holding the unique column-name/value pairs that identify a record; each may resolve to more than one record.
 
@@ -1005,7 +1005,7 @@ detect = skyflow_client.detect()
 - **Role.** The service account needs the Detect Invoker, Detect Manager or Vault Owner role on the vault. Detect Invoker can de-identify data and write vault tokens into the vault; Detect Manager adds the ability to create, update and delete Detect configurations. Re-identifying values stored as `VAULT_TOKEN` is governed like detokenization: the caller also needs a policy granting the Detokenization action on the destination, unless it is a Vault Owner.
 - **Configuration.** Pass `configuration_id` (the id of a stored Detect configuration) or an inline `configuration` (a `DetectConfiguration`). Both are optional: with neither set the SDK sends only the vault id and the run uses the vault's default Detect settings; sending both is rejected by the API with HTTP 400. Create and manage stored configurations — and copy their ids — in Studio (vault → **Detect**) or through the management API; the SDK does not create them.
 - **Destination for vault tokens.** An entity de-identified with `VAULT_TOKEN` stores its value in the token group named by `destination`. That token group must already exist in the vault; Detect writes into it but does not create it. Create token groups, and the named redaction patterns that re-identification applies, in the vault schema in Studio.
-- **API reference.** Every Detect request, response and configuration class is listed in the [API Reference](../docs/api_reference.md).
+- **API reference.** Every Detect request, response and configuration class is listed in the [API Reference](../docs/api_reference.md). That reference is written for skyvault; its [Detect helper classes](../docs/api_reference.md#detect-helper-classes) section lists where flowvault differs.
 
 ## deidentify_string
 
@@ -1060,9 +1060,9 @@ Returns a `DeidentifyStringResponse` with `processed_text`, `entities` (each a `
 | Class | Fields | Notes |
 |-------|--------|-------|
 | `Detect` | `entities`, `object_entities`, `restrict`, `skip`, `custom_types`, `return_entities` | `restrict` / `skip` are regexes always / never treated as sensitive. `return_entities` is `EXCLUDE_SENSITIVE_DATA` (server default), `ALL` or `NONE`. |
-| `Entity` | `entity_type`, `deidentification_type`, `destination`, `transformation`, `include_prefix`, `prefix_override` | `entity_type` defaults to `ALL`. `deidentification_type` is `ENTITY_UNIQUE_COUNTER` (server default), `ENTITY_ONLY`, `MASK` or `VAULT_TOKEN`. `destination` (a token group name) is used only with `VAULT_TOKEN`. `include_prefix` (`IncludePrefix.YES` / `IncludePrefix.NO`) and `prefix_override` also apply only to `VAULT_TOKEN`: `include_prefix=IncludePrefix.NO` stores a raw token that **cannot be re-identified** (a data-loss trap), and `prefix_override` replaces the entity-type label in the token with a custom one. |
+| `Entity` | `entity_type`, `deidentification_type`, `destination`, `transformation`, `include_prefix`, `prefix_override` | `entity_type` defaults to `ALL`. `deidentification_type` is `ENTITY_UNIQUE_COUNTER` (server default), `ENTITY_ONLY`, `MASK` or `VAULT_TOKEN`. `destination` (a token group name) is used only with `VAULT_TOKEN`. `include_prefix` and `prefix_override` are described below the table. |
 | `Transformation` / `ShiftDates` | `shift_dates`; `min_days`, `max_days` | Shifts detected dates by a random number of days within the range. |
-| `CustomType` | `label`, `match`, `deidentification_type`, `destination`, `include_prefix`, `prefix_override` | A regex-defined entity type; `label` is reported as the entity type of its matches. `deidentification_type`, `destination`, `include_prefix` and `prefix_override` behave exactly as on `Entity`. |
+| `CustomType` | `label`, `match`, `deidentification_type`, `destination`, `include_prefix`, `prefix_override` | A regex-defined entity type; `label` is reported as the entity type of its matches. The other fields work as they do on `Entity`. |
 | `ObjectEntity` | `entity_type`, `deidentification_type` | Visual objects in images: `FACE`, `LICENSE_PLATE`, `LOGO`, `SIGNATURE` or `ALL`, handled with `REDACT` or `UNREDACT`. File inputs only. |
 | `FileMapping` | `source`, `destination`, `output_file_name_suffix`, `entities_destination`, `object_entities_destination` | Where the processed file and entity files are written. File inputs only. |
 | `Media` | `audio`, `document`, `image` | Media-type options. File inputs only. |
@@ -1104,14 +1104,33 @@ configuration = DetectConfiguration(
 )
 ```
 
+**Token prefixes.** With `VAULT_TOKEN`, a generated token starts by default with the entity type, for example `[NAME_<token>]`. To change this, set `include_prefix` and `prefix_override` on an `Entity` or `CustomType`:
+
+- `prefix_override='NAAM'` produces `[NAAM_<token>]`.
+- `include_prefix=IncludePrefix.NO` returns the raw vault token. A token without its prefix can't be re-identified later, so use it only when you won't need the original value back.
+
+You can't combine `prefix_override` with `include_prefix=IncludePrefix.NO`. When you set neither, the server default applies. Import `IncludePrefix` from `skyflow.utils.enums`.
+
+```python
+from skyflow.vault.detect import Entity
+from skyflow.utils.enums import EntityType, DeidentificationType
+
+Entity(
+    entity_type=EntityType.NAME,
+    deidentification_type=DeidentificationType.VAULT_TOKEN,
+    destination='<TOKEN_GROUP_NAME>',
+    prefix_override='NAAM',
+)
+```
+
 ## deidentify_file
 
 De-identifies a file. The API is asynchronous: the submit call returns a run id and the result is retrieved from the run. Build the request with `DeidentifyFileRequest`.
 
-Supply the file in exactly one of three ways: `file_path`, `file`, or `value` plus a `DeidentifySourceType` `data_source` (`BASE64` or `PRESIGNED_URL`). flowvault does **not** support a Skyflow ID as a file source — its `DeidentifySourceType` has only `BASE64` and `PRESIGNED_URL`. A local `file` / `file_path` is read when the request is sent, base64-encoded, and its `data_format` inferred from the extension. Passing more than one of them, or none, fails client-side validation before any network call. `configuration_id` / `configuration` follow the same rules as for strings (see [Before you start](#before-you-start)).
+Supply the file in exactly one of three ways: `file_path`, `file`, or `value` plus a `DeidentifySourceType` `data_source` (`BASE64` or `PRESIGNED_URL`; flowvault doesn't accept a Skyflow ID as the source). A local `file` / `file_path` is read when the request is sent, base64-encoded, and its `data_format` inferred from the extension. Passing more than one of them, or none, fails client-side validation before any network call. `configuration_id` / `configuration` follow the same rules as for strings (see [Before you start](#before-you-start)).
 
 - **Submit only** (default): one call, returns `run_id`. `status` is `None` and nothing is written to disk — retrieve the result later with [`get_run`](#get_run).
-- **Submit and poll**: pass `poll_options`. The SDK polls with exponential backoff (1, 2, 4, 8, 16, then 32 seconds) until the run is `SUCCESS`, `FAILED` or `UNKNOWN`, or until `wait_time` (default 60 s, max 300) or `max_attempts` (default and max 23) is used up. If the budget runs out the response carries the run id with `IN_PROGRESS` or `QUEUED`, so you can resume with `get_run`. `output_directory` is valid only with `poll_options`; setting it without them fails client-side validation.
+- **Submit and poll**: pass `poll_options`. The SDK polls with exponential backoff (1, 2, 4, 8, 16, then 32 seconds) until the run is `SUCCESS`, `FAILED` or `UNKNOWN`, or until `wait_time` (default 60 s, max 300) or `max_attempts` (default and max 23) is used up. `wait_time` caps the combined sleep between status checks, not the elapsed time, so polling can run longer than `wait_time`. If the budget runs out the response carries the run id with `IN_PROGRESS` or `QUEUED`, so you can resume with `get_run`. `output_directory` is valid only with `poll_options`; setting it without them fails client-side validation.
 
 ```python
 from skyflow.vault.detect import DeidentifyFileRequest, PollOptions
@@ -1149,7 +1168,7 @@ else:                            # IN_PROGRESS or QUEUED: budget ran out, resume
 - `/data/processed/processed-entities-patient-notes.json` — the detected entities
 - `/data/processed/processed-object-entities-patient-notes.json` — object entities, when the run produced them
 
-`output_directory` is created if it does not exist. **If you poll a local file and omit `output_directory`, these files are written to the current working directory** — often your project root or a server's working directory — so set `output_directory` explicitly. A request built from a `PRESIGNED_URL` value has no local name to derive from, and presigned-URL outputs are not fetched, so in that case read `response.output` and write the files yourself.
+`output_directory` is created if it does not exist. **If you poll a local file and omit `output_directory`, these files are written to the current working directory** — often your project root or a server's working directory — so set `output_directory` explicitly. A request built from `data_source` and `value` has no local file name to derive from, and the SDK doesn't fetch presigned-URL outputs. In those cases, read `response.output` and write the files yourself.
 
 **Supported formats and limits.** `data_format` accepts every `DeidentifyFileDataFormat`: `bmp`, `csv`, `dcm`, `doc`, `docx`, `gif`, `jpeg`, `jpg`, `json`, `jsonl`, `mp3`, `pdf`, `png`, `ppt`, `pptx`, `tif`, `tiff`, `txt`, `wav`, `xls`, `xlsx`, `xml`, `zip`. The `VAULT_TOKEN` de-identification type is supported only for `txt`, `csv`, `json`, `jsonl`, `xml`, `docx`, `xlsx` and `pptx`.