nano-pdf

nano-pdf

目的

このスキルは、PDF の処理に役立つツールを提供します。テキスト抽出、テキストマイニング、フォーム入力、加工、OCR との連携に対応し、ドキュメントのワークフローを効率的に処理できます。

使用する場面

スキャンしたドキュメントからの PDF データ抽出、レポート内のテキスト分析、フォーム送信の自動化、ファイルの結合や分割、テキストを含まない PDF への OCR 適用などのタスクに使用します。データパイプラインやドキュメント自動化スクリプトで活用するほか、非構造化データを扱う OCR サービスとの連携にも使用できます。

主な機能

• テキスト抽出：PDF からプレーンテキストや構造化データを抽出します。パスワードを使った暗号化ファイルにも対応し、画像ベースの PDF には Tesseract 連携による OCR を使用します。
• テキストマイニング：抽出したテキストを分析し、キーワード、感情、パターンを特定します。たとえば、ドキュメント内の語句の出現回数をカウントできます。
• フォーム入力：JSON データを使って PDF のインタラクティブフォームに値を入力できます。フォームを静的な PDF にフラット化することもできます。
• 加工：PDF の結合、分割、回転、透かしの追加に対応し、最大 500 ページのドキュメントも効率的に処理できます。
• OCR 連携：外部 API を使ってスキャンした PDF を検索可能なテキストに変換します。Tesseract などのエンジンを設定する必要があります。

使用パターン

簡単なスクリプトでは CLI から、サーバー側の連携では API から呼び出します。一括処理ではシェルスクリプト内でコマンドを連結し、Web アプリではループ内で API を呼び出します。入力パスと出力パスは必ず明示してください。基本的なパターンは、最初にテキストを抽出し、その後、必要に応じてマイニングや加工を行うことです。OCR を多用するタスクでは、PDF の操作前に画像を前処理してください。

主なコマンド／API

CLI コマンドでは nano-pdf バイナリを使用します。API エンドポイントは https://api.opencclaw.com/nano-pdf/ 配下にあります。認証には $NANO_PDF_API_KEY 環境変数が必要です。

• テキストを抽出：nano-pdf extract --file input.pdf --output text.txt --ocr true（テキストを選択できない場合に OCR を追加します）。
• テキストをマイニング：nano-pdf mine --input text.txt --keywords "AI,robot" --output results.json（キーワードの出現頻度を出力します）。
• フォームに入力：nano-pdf fill --template form.pdf --data '{"field1": "value"}' --output filled.pdf。
• PDF を加工：nano-pdf merge --files file1.pdf file2.pdf --output combined.pdf。
• 抽出用の API エンドポイント：POST /extract に本文 {"file": "base64encoded_content", "ocr": true} を指定し、ヘッダーに Authorization: Bearer $NANO_PDF_API_KEY を指定します。
• コードスニペット（Python）：

  import requests
  response = requests.post('https://api.opencclaw.com/nano-pdf/extract', headers={'Authorization': f'Bearer {os.environ["NANO_PDF_API_KEY"]}'}, json={'file': 'base64data'})
  print(response.json()['text'])
  

• 設定形式：API の本文には JSON を使用します。例：{"file": "path", "options": {"ocr_engine": "tesseract", "language": "en"}}。CLI では --config config.json のようなフラグベースの設定を使用します。

連携に関する注意事項

認証が必要なリクエストでは $NANO_PDF_API_KEY を設定してください。ローカルで使用する場合は、pip install nano-pdf でインストールし、モジュールとしてインポートします。他のツールと組み合わせる場合は、CLI の出力を NLP ライブラリにパイプしてマイニングしたり、HTTP リクエストを使って Node.js から利用したりできます。OCR を使用するには、Tesseract がインストールされ、環境パスで設定されていることを確認してください。API のレート制限（例：1 分あたり 100 リクエスト）を確認するため、サンドボックスで連携をテストしてください。

エラー処理

ファイルが見つからない場合（終了コード 404）、API キーが無効な場合（401）、OCR が失敗した場合（例：Tesseract がインストールされていない）など、よくあるエラーを確認してください。コードでは try-except を使用します。

try:
    result = nano_pdf.extract('input.pdf')
except FileNotFoundError:
    print("Error: File does not exist.")
except Exception as e:
    print(f"API Error: {e} - Check $NANO_PDF_API_KEY.")

CLI では stderr の出力を解析します。一時的なエラー（例：ネットワークの問題）は、指数バックオフを使って再試行してください。処理前に PDF が破損していないことを確認するなど、入力を必ず検証してください。

例 1：PDF からテキストを抽出してマイニングする

スキャンした請求書 PDF からテキストを抽出し、商品名をマイニングするには、次の手順に従います。

1. 実行します：nano-pdf extract --file invoice.pdf --output invoice_text.txt --ocr true
2. 続けて実行します：nano-pdf mine --input invoice_text.txt --keywords "product" --output analysis.json 後続の処理に使用できる、キーワードの出現回数を含む JSON が生成されます。

例 2：フォーム PDF の入力と操作

求人応募フォームに入力し、カバーレターと結合するには、次の手順を実行します。

1. JSON でデータを準備します：{"name": "John Doe", "position": "Engineer"}
2. 実行します：nano-pdf fill --template application.pdf --data application_data.json --output filled_app.pdf
3. 結合します：nano-pdf merge --files filled_app.pdf cover_letter.pdf --output final_packet.pdf 提出用の単一の PDF が出力されます。

グラフの関係

• 関連項目：「ocr-tool」（OCR 機能の強化用）、「document-parser」（より幅広いファイル形式への対応用）、「text-analyzer」（高度なマイニング連携用）。
• クラスター：「community」クラスターを介して、「data-extraction」や「automation-utils」などのスキルとつながっています。