feat: Make Discovery accessible from CLI and SDK (#228) (#232)

* > Add discovery CLI command and SDK operations for automated schema generation

* > Add discovery SDK/CLI with local and stack-connected modes, remove S3 upload dependency

* > docs: add discovery CLI command and SDK operations documentation

* > Add Discovery module documentation to README files

* > Add batch ground truth matching and flexible output modes to discovery CLI

* > Add stdout output for discover command in batch mode when no output file specified

---------

Co-authored-by: Bob Strahan <strahans@amazon.com>

Author: rstrahan

CHANGELOG.md

@@ -5,6 +5,10 @@ SPDX-License-Identifier: MIT-0
 
 ## [Unreleased]
 
+### Added
+
+- **Discovery accessible from CLI and SDK** — Discovery can now be run programmatically via the IDP SDK (`client.discovery.run()`) and CLI (`idp-cli discover`), enabling users with many document classes to automate schema generation without the Web UI. Supports both modes: without ground truth (exploratory) and with ground truth (optimized). ([#228](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/issues/228))
+
 ### Changed
 
 - **Sync to BDA no longer auto-activates the config version** — Previously, performing "Sync to BDA" would automatically set the current config version as active. Since each config version now has its own BDA project, auto-activation is unnecessary. Users can manually choose which version to activate via the Versions table. The "Sync to BDA" confirmation modal text has been updated accordingly.

config.yaml

@@ -0,0 +1 @@
+key: value

docs/idp-cli.md

@@ -1995,6 +1995,55 @@ This uses the same mechanism as the Web UI configuration management system.
 
 ---
 
+### `discover`
+
+Discover document class schemas from sample documents using Amazon Bedrock.
+
+**Two modes:**
+- **Stack-connected** (`--stack-name`): Uses stack's discovery config and saves schema to DynamoDB configuration
+- **Local** (no `--stack-name`): Uses system default Bedrock settings, prints schema to stdout without saving
+
+**Ground truth matching:** Ground truth files (`-g`) are auto-matched to documents (`-d`) by filename stem. For example, `invoice.pdf` matches `invoice.json`. Unmatched documents run without ground truth.
+
+**Output behavior:**
+- Single document: `-o` writes the schema to the specified file
+- Batch + `-o` is a directory (or has no extension): writes one `{class_name}.json` per schema
+- Batch + `-o` is a file: writes all schemas as a JSON array
+
+```bash
+# Single document (local mode — no stack needed)
+idp-cli discover -d ./invoice.pdf
+
+# With ground truth (matched by filename stem)
+idp-cli discover -d ./invoice.pdf -g ./invoice.json
+
+# Save schema to file
+idp-cli discover -d ./form.pdf -o ./form-schema.json
+
+# Batch with auto-matched ground truth
+idp-cli discover -d ./invoice.pdf -d ./w2.pdf -g ./invoice.json -g ./w2.json
+
+# Batch output to directory (one file per schema)
+idp-cli discover -d ./invoice.pdf -d ./w2.pdf -o ./schemas/
+
+# Batch output to single file (JSON array)
+idp-cli discover -d ./invoice.pdf -d ./w2.pdf -o ./all-schemas.json
+
+# Stack mode (saves to config)
+idp-cli discover --stack-name my-stack -d ./invoice.pdf --config-version v2
+```
+
+| Option | Description |
+|--------|-------------|
+| `--stack-name` | CloudFormation stack name (optional — omit for local mode) |
+| `-d, --document` | Path to document file (required, repeatable for batch) |
+| `-g, --ground-truth` | Path to JSON ground truth file(s) (repeatable, auto-matched by filename stem) |
+| `--config-version` | Config version to save to (stack mode only) |
+| `-o, --output` | Output path: file (single/JSON array) or directory (one file per schema) |
+| `--region` | AWS region |
+
+---
+
 ## Troubleshooting
 
 ### Stack Not Found

docs/idp-sdk.md

@@ -944,6 +944,80 @@ else:
 
 ---
 
+## Discovery Operations
+
+Discover document class schemas from sample documents using Amazon Bedrock.
+
+**Two modes:**
+- **Stack-connected** (with `stack_name`): Uses the stack's discovery config from DynamoDB, saves discovered schema to config
+- **Local** (without `stack_name`): Uses system default Bedrock settings, returns schema without saving
+
+### discovery.run()
+
+Analyze a document to generate a JSON Schema definition for a document class.
+
+```python
+# Local mode — no stack needed
+client = IDPClient()
+result = client.discovery.run("./invoice.pdf")
+print(json.dumps(result.json_schema, indent=2))
+
+# Stack mode — uses stack config, saves schema
+client = IDPClient(stack_name="my-stack")
+result = client.discovery.run("./w2-form.pdf")
+
+# With ground truth for better accuracy
+result = client.discovery.run(
+    "./invoice.pdf",
+    ground_truth_path="./invoice-expected.json"
+)
+
+# Save to specific config version
+result = client.discovery.run(
+    "./form.pdf",
+    config_version="v2"
+)
+```
+
+**Parameters:**
+- `document_path` (str, required): Local path to document file (PDF, PNG, JPG, TIFF)
+- `ground_truth_path` (str, optional): Path to JSON ground truth file
+- `config_version` (str, optional): Config version to save to (stack mode only)
+- `stack_name` (str, optional): Stack name override
+
+**Returns:** `DiscoveryResult` with `status`, `document_class`, `json_schema`, `config_version`, `document_path`, `error`
+
+### discovery.run_batch()
+
+Run discovery on multiple documents sequentially. Ground truth paths are
+auto-matched to documents by filename stem.
+
+```python
+# Batch without ground truth
+result = client.discovery.run_batch([
+    "./invoice.pdf",
+    "./w2-form.pdf",
+    "./paystub.png",
+])
+print(f"Succeeded: {result.succeeded}/{result.total}")
+
+# Batch with selective ground truth (matched by position)
+result = client.discovery.run_batch(
+    ["./invoice.pdf", "./w2.pdf"],
+    ground_truth_paths=[None, "./w2.json"],
+)
+```
+
+**Parameters:**
+- `document_paths` (list, required): List of local file paths
+- `ground_truth_paths` (list, optional): Parallel list of ground truth paths (use None for docs without GT)
+- `config_version` (str, optional): Config version to save to
+- `stack_name` (str, optional): Stack name override
+
+**Returns:** `DiscoveryBatchResult` with `total`, `succeeded`, `failed`, `results`
+
+---
+
 ## Manifest Operations
 
 Operations for manifest generation and validation.