paddleocr-skills 1.0.0

package/templates/paddleocr-vl/scripts/paddleocr-vl/smoke_test.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Smoke Test for PaddleOCR-VL
+
+Verifies that VL_API_URL and VL_TOKEN are correctly configured
+and that the API is accessible.
+
+Usage:
+    python scripts/paddleocr-vl/smoke_test.py
+    python scripts/paddleocr-vl/smoke_test.py --test-url "URL"  # Optional custom test
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Add current directory to Python path
+script_dir = Path(__file__).parent
+sys.path.insert(0, str(script_dir))
+
+
+def main():
+    parser = argparse.ArgumentParser(description='PaddleOCR-VL smoke test')
+    parser.add_argument(
+        '--test-url',
+        help='Optional: Custom document URL for testing'
+    )
+    parser.add_argument(
+        '--skip-api-test',
+        action='store_true',
+        help='Skip API connectivity test, only check configuration'
+    )
+    args = parser.parse_args()
+
+    print("=" * 60)
+    print("PaddleOCR-VL - Smoke Test")
+    print("=" * 60)
+    print()
+
+    # Check configuration
+    print("\n[1/3] Checking configuration...")
+
+    from _lib import Config
+
+    try:
+        Config.load_env()
+
+        # Get config values
+        api_url = Config.get_vl_api_url()
+        token = Config.get_vl_token()
+        timeout_ms = Config.get_timeout_ms()
+        max_retry = Config.get_max_retry()
+        cache_ttl = Config.get_cache_ttl_sec()
+
+        print(f"+ VL_API_URL: {api_url}")
+
+        # Mask token for display
+        if len(token) > 12:
+            masked_token = token[:8] + "..." + token[-4:]
+        else:
+            masked_token = "***"
+        print(f"+ VL_TOKEN: {masked_token}")
+        print(f"+ Timeout: {timeout_ms}ms")
+        print(f"+ Max Retry: {max_retry}")
+        print(f"+ Cache TTL: {cache_ttl}s")
+        print()
+
+    except Exception as e:
+        print(f"\nConfiguration error: {e}")
+        return 1
+
+    # Check imports and dependencies
+    print("[2/3] Checking dependencies...")
+    print()
+
+    try:
+        import httpx
+        print(f"+ httpx: {httpx.__version__}")
+
+        from dotenv import load_dotenv
+        print("+ python-dotenv: installed")
+
+        from _lib import VLClient, QualityEvaluator, SimpleCache
+        print("+ VLClient: OK")
+        print("+ QualityEvaluator: OK")
+        print("+ SimpleCache: OK")
+        print()
+
+    except ImportError as e:
+        print(f"X Dependency error: {e}")
+        print()
+        print("Please install dependencies:")
+        print("  pip install -r scripts/paddleocr-vl/requirements.txt")
+        print()
+        return 1
+
+    # Test API connectivity
+    if args.skip_api_test:
+        print("[3/3] Skipping API connectivity test (--skip-api-test)")
+        print()
+        print("=" * 60)
+        print("Configuration Check Complete!")
+        print("=" * 60)
+        print()
+        print("Your PaddleOCR-VL is configured correctly.")
+        print()
+        print("To test with a real document, run:")
+        print('  python scripts/paddleocr-vl/vl_caller.py --file-url "URL"')
+        print()
+        return 0
+
+    print("[3/3] Testing API connectivity...")
+    print()
+
+    # Use provided test URL or default
+    test_url = args.test_url or "https://paddleocr.bj.bcebos.com/dataset/document_layout_sample.png"
+
+    print(f"Test document: {test_url}")
+    print("Calling PaddleOCR-VL API...")
+    print()
+
+    from _lib import make_api_request, QualityEvaluator
+
+    try:
+        result = make_api_request(
+            file_url=test_url,
+            timeout_ms=timeout_ms,
+            use_cache=False  # Force fresh request for testing
+        )
+
+        if not result.get("ok", False):
+            error = result.get("error", {})
+            print(f"X API call failed: {error.get('message', 'Unknown error')}")
+            print(f"   Error code: {error.get('code', 'UNKNOWN')}")
+            print()
+            return 1
+
+        print("+ API call successful!")
+        print()
+
+        # Evaluate quality
+        quality = QualityEvaluator.evaluate(result)
+
+        print("Response Quality:")
+        print(f"  - Overall Confidence: {quality['overall_confidence']:.2f} / 1.00")
+        print(f"  - Quality Level: {quality['quality_level']}")
+
+        if quality.get('region_stats'):
+            stats = quality['region_stats']
+            print(f"  - Regions Detected: {stats.get('total_regions', 0)}")
+
+            if stats.get('by_type'):
+                print("  - Region Types:")
+                for region_type, count in sorted(stats['by_type'].items()):
+                    print(f"      {region_type}: {count}")
+
+        if quality.get('warnings'):
+            print("\n  Warnings:")
+            for warning in quality['warnings']:
+                print(f"    ! {warning}")
+
+        print()
+
+        # Show sample content
+        result_data = result.get("result", {})
+        full_text = result_data.get("full_text", "")
+
+        if full_text:
+            preview_length = min(200, len(full_text))
+            print(f"Content Preview ({preview_length} chars):")
+            print(f"  {full_text[:preview_length]}...")
+            print()
+
+    except Exception as e:
+        print(f"X API call failed: {e}")
+        print()
+        return 1
+
+    # Success
+    print("=" * 60)
+    print("All Tests Passed!")
+    print("=" * 60)
+    print()
+    print("Your PaddleOCR-VL setup is working correctly.")
+    print()
+    print("Next steps:")
+    print('  - Parse documents: python scripts/paddleocr-vl/vl_caller.py --file-url "URL"')
+    print('  - Show quality info: Add --show-quality flag')
+    print('  - Pretty JSON: Add --pretty flag')
+    print()
+
+    return 0
+
+
+if __name__ == '__main__':
+    exit_code = main()
+    sys.exit(exit_code)

package/templates/paddleocr-vl/scripts/paddleocr-vl/vl_caller.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""
+PaddleOCR-VL Document Parser
+
+High-quality document parsing with layout analysis.
+Returns complete API response without filtering.
+
+Usage:
+    python scripts/paddleocr-vl/vl_caller.py --file-url "URL"
+    python scripts/paddleocr-vl/vl_caller.py --file-path "document.pdf"
+    python scripts/paddleocr-vl/vl_caller.py --file-path "doc.pdf" --pretty --show-quality
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Add current directory to Python path for imports
+script_dir = Path(__file__).parent
+sys.path.insert(0, str(script_dir))
+
+from _lib import (
+    Config,
+    make_api_request,
+    format_error_output,
+    wrap_success_output,
+    QualityEvaluator,
+    setup_logging,
+    ERROR_CONFIG,
+    ERROR_AUTH,
+    ERROR_QUOTA,
+    ERROR_TIMEOUT,
+    ERROR_OVERLOADED,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='PaddleOCR-VL - High-quality document parsing with layout analysis',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Parse document from URL
+  python scripts/paddleocr-vl/vl_caller.py --file-url "https://example.com/document.pdf"
+
+  # Parse local file
+  python scripts/paddleocr-vl/vl_caller.py --file-path "./invoice.pdf"
+
+  # Pretty print JSON output with quality metrics
+  python scripts/paddleocr-vl/vl_caller.py --file-path "doc.pdf" --pretty --show-quality
+
+  # Disable cache for fresh processing
+  python scripts/paddleocr-vl/vl_caller.py --file-url "URL" --no-cache
+
+Notes:
+  - This script returns COMPLETE API response (all content)
+  - Claude will extract what the user needs from the full data
+  - No content is filtered or removed at script level
+  - Results are cached for 10 minutes by default
+        """
+    )
+
+    # Input file (mutually exclusive)
+    input_group = parser.add_mutually_exclusive_group(required=True)
+    input_group.add_argument(
+        '--file-url',
+        help='URL to document (PDF, PNG, JPG, etc.)'
+    )
+    input_group.add_argument(
+        '--file-path',
+        help='Local file path'
+    )
+
+    # Output options
+    parser.add_argument(
+        '--pretty',
+        action='store_true',
+        help='Pretty print JSON output'
+    )
+
+    parser.add_argument(
+        '--output', '-o',
+        metavar='FILE',
+        help='Save result to JSON file (absolute or relative path)'
+    )
+
+    parser.add_argument(
+        '--show-quality',
+        action='store_true',
+        help='Show quality assessment and confidence scores'
+    )
+
+    parser.add_argument(
+        '--no-cache',
+        action='store_true',
+        help='Disable cache, force fresh API call'
+    )
+
+    # Advanced options
+    parser.add_argument(
+        '--timeout',
+        type=int,
+        default=30000,
+        help='Request timeout in milliseconds (default: 30000)'
+    )
+
+    parser.add_argument(
+        '--log-level',
+        choices=['DEBUG', 'INFO', 'WARNING', 'ERROR'],
+        default='INFO',
+        help='Set logging level (default: INFO)'
+    )
+
+    args = parser.parse_args()
+
+    # Setup logging
+    setup_logging(args.log_level)
+
+    # Load config from .env file
+    try:
+        api_url = Config.get_vl_api_url()
+        token = Config.get_vl_token()
+        timeout_ms = Config.get_timeout_ms()
+        max_retry = Config.get_max_retry()
+        cache_ttl_sec = Config.get_cache_ttl_sec()
+    except ValueError as e:
+        print(f"\nConfiguration error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    # Call API
+    try:
+        result = make_api_request(
+            file_path=args.file_path,
+            file_url=args.file_url,
+            timeout_ms=args.timeout,
+            use_cache=not args.no_cache
+        )
+
+        # Show quality assessment if requested
+        if args.show_quality and result.get("ok", False):
+            quality = QualityEvaluator.evaluate(result)
+
+            print("=" * 60)
+            print("QUALITY ASSESSMENT")
+            print("=" * 60)
+            print(f"Overall Confidence: {quality['overall_confidence']:.2f} / 1.00")
+            print(f"Quality Level: {quality['quality_level']}")
+
+            if quality.get('region_stats'):
+                stats = quality['region_stats']
+                print(f"\nRegions Detected: {stats.get('total_regions', 0)}")
+                if stats.get('by_type'):
+                    print("Region Types:")
+                    for region_type, count in stats['by_type'].items():
+                        print(f"  - {region_type}: {count}")
+
+                if stats.get('low_confidence_count', 0) > 0:
+                    print(f"\nWarning: {stats['low_confidence_count']} regions have low confidence")
+
+            if quality.get('warnings'):
+                print("\nWarnings:")
+                for warning in quality['warnings']:
+                    print(f"  ⚠ {warning}")
+
+            print("=" * 60)
+            print()
+
+        # Ensure result is wrapped in standard format
+        output = wrap_success_output(result)
+
+        # Prepare JSON output
+        indent = 2 if args.pretty else None
+        json_output = json.dumps(output, indent=indent, ensure_ascii=False)
+
+        # Save to file if --output specified
+        if args.output:
+            try:
+                output_path = Path(args.output).resolve()
+
+                # Create directory if not exists
+                output_path.parent.mkdir(parents=True, exist_ok=True)
+
+                # Write file
+                with open(output_path, 'w', encoding='utf-8') as f:
+                    f.write(json_output)
+
+                # Print success message to stderr (so it doesn't mix with JSON output)
+                print(f"Result saved to: {output_path}", file=sys.stderr)
+
+            except PermissionError:
+                print(f"Error: Permission denied to write to {output_path}", file=sys.stderr)
+                sys.exit(5)
+            except OSError as e:
+                print(f"Error: Cannot write to {output_path}: {e}", file=sys.stderr)
+                sys.exit(5)
+        else:
+            # No --output: print to stdout (original behavior)
+            print(json_output)
+
+        # Determine exit code based on result
+        if not result.get("ok", False):
+            error_code = result.get("error", {}).get("code", "UNKNOWN")
+
+            # Map error codes to exit codes (aligned with ppocrv5)
+            if error_code == ERROR_CONFIG:
+                sys.exit(1)  # Configuration error
+            elif error_code in [ERROR_AUTH, ERROR_QUOTA]:
+                sys.exit(2)  # Authentication or quota error
+            elif error_code in [ERROR_TIMEOUT, ERROR_OVERLOADED]:
+                sys.exit(3)  # Timeout or service overload
+            else:
+                sys.exit(4)  # Other errors
+
+        # Success
+        sys.exit(0)
+
+    except ValueError as e:
+        # Configuration errors
+        output = format_error_output(e, ERROR_CONFIG)
+        print(json.dumps(output, indent=2, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)
+
+    except Exception as e:
+        # Unexpected errors
+        output = format_error_output(e)
+        print(json.dumps(output, indent=2, ensure_ascii=False), file=sys.stderr)
+        sys.exit(4)
+
+
+if __name__ == '__main__':
+    main()