feat(documents): add samples

samples/document-understanding-agent/.agent/REQUIRED_STRUCTURE.md

@@ -0,0 +1,64 @@
+## Required Agent Structure
+
+**IMPORTANT**: All UiPath coded agents MUST follow this standard structure unless explicitly specified otherwise by the user.
+
+### Required Components
+
+Every agent implementation MUST include these two Pydantic models:
+
+```python
+from pydantic import BaseModel
+
+class Input(BaseModel):
+    """Define input fields that the agent accepts"""
+    # Add your input fields here
+    pass
+
+class Output(BaseModel):
+    """Define output fields that the agent returns"""
+    # Add your output fields here
+    pass
+```
+
+### SDK Initialization
+
+```python
+from uipath.platform import UiPath
+
+# Initialize with environment variables
+uipath = UiPath()
+
+# With explicit credentials
+uipath = UiPath(base_url="https://cloud.uipath.com/...", secret="your_token")
+
+# Or with client_id and client_secret
+uipath = UiPath(
+    client_id=UIPATH_CLIENT_ID,
+    client_secret=UIPATH_CLIENT_SECRET,
+    scope=UIPATH_SCOPE,
+    base_url=UIPATH_URL
+)
+```
+
+### Standard Agent Template
+
+Every agent should follow this basic structure:
+
+```python
+from uipath.platform import UiPath
+from pydantic import BaseModel
+
+# 1. Define Input, and Output models
+class Input(BaseModel):
+    field: str
+
+class Output(BaseModel):
+    result: str
+
+# 2. Initialize with environment variables
+uipath = UiPath()
+
+# 3. Define the main function (the main function can be named "main", "run" or "execute")
+def main(input_data: Input) -> Output:
+     pass
+```

samples/document-understanding-agent/AGENTS.md

@@ -0,0 +1,21 @@
+# Agent Code Patterns Reference
+
+This document provides practical code patterns for building UiPath coded agents using the UiPath Python SDK.
+
+---
+
+## Documentation Structure
+
+This documentation is split into multiple files for efficient context loading. Load only the files you need:
+
+1. **@.agent/REQUIRED_STRUCTURE.md** - Agent structure patterns and templates
+   - **When to load:** Creating a new agent or understanding required patterns
+   - **Contains:** Required Pydantic models (Input, Output), SDK initialization patterns, standard agent template
+
+2. **@.agent/SDK_REFERENCE.md** - Complete SDK API reference
+   - **When to load:** Calling UiPath SDK methods, working with services (actions, assets, jobs, etc.)
+   - **Contains:** All SDK services and methods with full signatures and type annotations
+
+3. **@.agent/CLI_REFERENCE.md** - CLI commands documentation
+   - **When to load:** Working with `uipath init`, `uipath run`, or `uipath eval` commands
+   - **Contains:** Command syntax, options, usage examples, and workflows

samples/document-understanding-agent/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

samples/document-understanding-agent/README.md

@@ -0,0 +1,72 @@
+# Document Understanding Sample
+
+This sample demonstrates how to use UiPath Document Understanding capabilities with the UiPath Python SDK to classify, extract and validate data from documents.
+
+## Overview
+
+Document Understanding enables automated processing of documents through:
+
+- **Classification**: Identify document types
+- **Extraction**: Extract data from classified documents
+- **Validation**: Create human-in-the-loop validation actions for review
+
+This sample includes three Document Understanding approaches:
+
+- **IXP (Intelligent Xtraction and Processing)** (`samples/ixp.py`) - [IXP documentation](https://docs.uipath.com/ixp/automation-cloud/latest/overview/introduction)
+- **Modern Projects** (`samples/du_modern.py`) - [Modern DU documentation](https://docs.uipath.com/document-understanding/automation-cloud/latest/user-guide/about-document-understanding)
+- **Pretrained Models** (`samples/pretrained.py`) - [Pretrained models documentation](https://docs.uipath.com/document-understanding/automation-cloud/latest/user-guide/out-of-the-box-pre-trained-ml-packages)
+
+## Prerequisites
+
+- UiPath Automation Suite or Automation Cloud tenant
+- Document Understanding projects deployed with appropriate tags ( [DU Modern publish documentation](https://docs.uipath.com/document-understanding/automation-cloud/latest/user-guide/publish) / [IXP model deployment documentation](https://docs.uipath.com/document-understanding/automation-cloud/latest/user-guide/publish) )
+- Action catalog configured for validation actions ( [Actions documentation](https://docs.uipath.com/action-center/automation-cloud/latest/user-guide/about-actions) )
+- Storage bucket for validation data ( [Storage buckets documentation](https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/about-storage-buckets) )
+
+## Setup
+
+1. **Install dependencies**:
+
+   ```bash
+   uv sync
+   ```
+
+2. **Configure UiPath credentials and initialize project**:
+
+   ```bash
+   uv run uipath auth
+   uv run uipath init
+   ```
+
+3. **Update sample parameters**:
+
+   Edit the sample files to match your environment:
+   - Project names and tags
+   - Document type names
+   - Action catalog and folder names
+   - Storage bucket configuration
+
+## Usage
+
+Run the complete sample workflow:
+
+```bash
+uv run uipath run main
+```
+
+Or run individual samples:
+
+```python
+from samples import ixp, du_modern, pretrained
+
+# IXP extraction and validation
+ixp.extract_validate()
+
+# Modern project
+du_modern.extract_validate()
+du_modern.classify_extract_validate()
+
+# Pretrained model
+pretrained.extract_validate()
+pretrained.classify_extract_validate()
+```

samples/document-understanding-agent/bindings.json

@@ -0,0 +1,4 @@
+{
+    "version": "2.0",
+    "resources": []
+}

samples/document-understanding-agent/entry-points.json

@@ -0,0 +1,5 @@
+{
+    "$schema": "https://cloud.uipath.com/draft/2024-12/entry-point",
+    "$id": "entry-points.json",
+    "entryPoints": []
+}

samples/document-understanding-agent/main.py

@@ -0,0 +1,10 @@
+from src import ixp, du_modern, pretrained
+
+def main():
+    ixp.extract_validate()
+
+    du_modern.extract_validate()
+    du_modern.classify_extract_validate()
+
+    pretrained.extract_validate()
+    pretrained.classify_extract_validate()

samples/document-understanding-agent/pyproject.toml

@@ -0,0 +1,10 @@
+[project]
+name = "document-understanding-agent"
+version = "0.1.0"
+authors = [{ name = "John Doe" }]
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "uipath>=2.2.14, <2.3.0",
+]

samples/document-understanding-agent/src/du_modern.py

@@ -0,0 +1,81 @@
+from uipath.platform import UiPath
+from uipath.platform.documents import ProjectType, ActionPriority
+
+TAG = "Production"
+PROJECT_NAME = "TestModernProject"
+DOCUMENT_TYPE_NAME = "TestDocumentType"
+FILE_PATH = "test.pdf"
+ACTION_TITLE = "Test Validation Action"
+ACTION_PRIORITY = ActionPriority.MEDIUM
+ACTION_CATALOG = "default_du_actions"
+ACTION_FOLDER = "Shared"
+STORAGE_BUCKET_NAME = "du_storage_bucket"
+STORAGE_BUCKET_DIRECTORY_PATH = "TestDirectory"
+
+def extract_validate():
+    uipath = UiPath()
+
+    extraction_response = uipath.documents.extract(
+        tag=TAG,
+        project_name=PROJECT_NAME,
+        project_type=ProjectType.MODERN,
+        document_type_name=DOCUMENT_TYPE_NAME,
+        file_path=FILE_PATH,
+    )
+
+    validation_action = uipath.documents.create_validate_extraction_action(
+        action_title=ACTION_TITLE,
+        action_priority=ACTION_PRIORITY,
+        action_catalog=ACTION_CATALOG,
+        action_folder=ACTION_FOLDER,
+        storage_bucket_name=STORAGE_BUCKET_NAME,
+        storage_bucket_directory_path=STORAGE_BUCKET_DIRECTORY_PATH,
+        extraction_response=extraction_response,
+    )
+
+    uipath.documents.get_validate_extraction_result(
+        validation_action=validation_action
+    )
+
+def classify_extract_validate():
+    uipath = UiPath()
+
+    classification_results = uipath.documents.classify(
+        tag=TAG,
+        project_name=PROJECT_NAME,
+        project_type=ProjectType.MODERN,
+        file_path=FILE_PATH,
+    )
+
+    validation_action = uipath.documents.create_validate_classification_action(
+        action_title=ACTION_TITLE,
+        action_priority=ACTION_PRIORITY,
+        action_catalog=ACTION_CATALOG,
+        action_folder=ACTION_FOLDER,
+        storage_bucket_name=STORAGE_BUCKET_NAME,
+        storage_bucket_directory_path=STORAGE_BUCKET_DIRECTORY_PATH,
+        classification_results=classification_results,
+    )
+
+    validated_classification_results = uipath.documents.get_validate_classification_result(
+        validation_action=validation_action
+    )
+
+    best_confidence_result = max(validated_classification_results, key=lambda result: result.confidence)
+
+    extraction_response = uipath.documents.extract(classification_result=best_confidence_result)
+
+    validation_action = uipath.documents.create_validate_extraction_action(
+        action_title=ACTION_CATALOG,
+        action_priority=ACTION_PRIORITY,
+        action_catalog=ACTION_CATALOG,
+        action_folder=ACTION_FOLDER,
+        storage_bucket_name=STORAGE_BUCKET_NAME,
+        storage_bucket_directory_path=STORAGE_BUCKET_DIRECTORY_PATH,
+        extraction_response=extraction_response,
+    )
+
+    uipath.documents.get_validate_extraction_result(
+        validation_action=validation_action
+    )
+

samples/document-understanding-agent/src/ixp.py

@@ -0,0 +1,37 @@
+from uipath.platform import UiPath
+from uipath.platform.documents import ProjectType, ActionPriority
+
+PROJECT_NAME = "TestIxpProject"
+TAG = "live"
+FILE_PATH = "test.pdf"
+ACTION_TITLE = "Test IXP Validation Action"
+ACTION_CATALOG = "default_du_actions"
+ACTION_FOLDER = "Shared"
+ACTION_PRIORITY = ActionPriority.MEDIUM
+STORAGE_BUCKET_NAME = "du_storage_bucket"
+STORAGE_BUCKET_DIRECTORY_PATH = "TestDirectory"
+
+
+def extract_validate():
+    uipath = UiPath()
+
+    extraction_response = uipath.documents.extract(
+        tag=TAG,
+        project_name=PROJECT_NAME,
+        project_type=ProjectType.IXP,
+        file_path=FILE_PATH,
+    )
+
+    validation_action = uipath.documents.create_validate_extraction_action(
+        action_title=ACTION_TITLE,
+        action_priority=ACTION_PRIORITY,
+        action_catalog=ACTION_CATALOG,
+        action_folder=ACTION_FOLDER,
+        storage_bucket_name=STORAGE_BUCKET_NAME,
+        storage_bucket_directory_path=STORAGE_BUCKET_DIRECTORY_PATH,
+        extraction_response=extraction_response,
+    )
+
+    uipath.documents.get_validate_extraction_result(
+        validation_action=validation_action
+    )

samples/document-understanding-agent/src/pretrained.py

@@ -0,0 +1,61 @@
+from uipath.platform import UiPath
+from uipath.platform.documents import ProjectType, ActionPriority
+
+DOCUMENT_TYPE_NAME = "invoices"
+FILE_PATH = "test.pdf"
+ACTION_TITLE = "Test Validation Action"
+ACTION_PRIORITY = ActionPriority.MEDIUM
+ACTION_CATALOG = "default_du_actions"
+ACTION_FOLDER = "Shared"
+STORAGE_BUCKET_NAME = "du_storage_bucket"
+STORAGE_BUCKET_DIRECTORY_PATH = "TestDirectory"
+
+def extract_validate():
+    uipath = UiPath()
+
+    extraction_response = uipath.documents.extract(
+        project_type=ProjectType.PRETRAINED,
+        document_type_name=DOCUMENT_TYPE_NAME,
+        file_path=FILE_PATH,
+    )
+
+    extraction_action = uipath.documents.create_validate_extraction_action(
+        action_title=ACTION_TITLE,
+        action_priority=ACTION_PRIORITY,
+        action_catalog=ACTION_CATALOG,
+        action_folder=ACTION_FOLDER,
+        storage_bucket_name=STORAGE_BUCKET_NAME,
+        storage_bucket_directory_path=STORAGE_BUCKET_DIRECTORY_PATH,
+        extraction_response=extraction_response,
+    )
+
+    uipath.documents.get_validate_extraction_result(
+        validation_action=extraction_action
+    )
+
+def classify_extract_validate():
+    uipath = UiPath()
+
+    classification_results = uipath.documents.classify(
+        project_type=ProjectType.PRETRAINED, file_path=FILE_PATH
+    )
+
+    best_confidence_result = max(classification_results, key=lambda result: result.confidence)
+
+    extraction_response = uipath.documents.extract(
+        classification_result=best_confidence_result
+    )
+
+    extraction_action = uipath.documents.create_validate_extraction_action(
+        action_title=ACTION_TITLE,
+        action_priority=ACTION_PRIORITY,
+        action_catalog=ACTION_CATALOG,
+        action_folder=ACTION_FOLDER,
+        storage_bucket_name=STORAGE_BUCKET_NAME,
+        storage_bucket_directory_path=STORAGE_BUCKET_DIRECTORY_PATH,
+        extraction_response=extraction_response,
+    )
+
+    uipath.documents.get_validate_extraction_result(
+        validation_action=extraction_action
+    )

samples/document-understanding-agent/uipath.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://cloud.uipath.com/draft/2024-12/uipath",
+  "runtimeOptions": {
+    "isConversational": false
+  },
+  "packOptions": {
+    "fileExtensionsIncluded": [],
+    "filesIncluded": [],
+    "filesExcluded": [],
+    "directoriesExcluded": [],
+    "includeUvLock": true
+  },
+  "functions": {"main": "main.py:main"}
+}