convert2md.py 技術ドキュメント

プログラムの動作

convert2md.py は、指定されたドキュメントファイル（PDF, DOCX, PPTX）や画像ファイル（JPG）を解析し、その内容をMarkdown形式のテキストに変換するPythonプログラムです。

主な機能は以下の通りです。

多様なファイル形式のサポート: markitdown ライブラリを利用して、PDF、Word (DOCX)、PowerPoint (PPTX) ファイルからテキストコンテンツを抽出し、Markdownに変換します。
画像ファイルの解析と説明: 入力ファイルがJPG形式の場合、OpenAIのVisionモデル（gpt-4o-mini）を利用して画像の内容を分析し、その説明文をMarkdownとして生成します。この機能は、.env ファイルに OPENAI_API_KEY が設定されている場合に有効になります。
環境変数からのAPIキー読み込み: OpenAI APIを利用する際に必要なAPIキーは、プログラムと同じディレクトリ、または親ディレクトリに配置された .env ファイルから自動的に読み込まれます。
Markdownファイルとして保存: 変換されたMarkdownテキストは、入力ファイルと同じディレクトリに、入力ファイル名と同じ名前で .md 拡張子を持つファイルとして保存されます。

このプログラムは、異なる形式のコンテンツを統一されたMarkdown形式に変換することで、コンテンツの再利用、編集、管理を効率化することを目的としています。特に、画像の内容をAIが自動で説明する機能は、アクセシビリティの向上やコンテンツ作成プロセスの自動化に貢献します。

原理

convert2md.py は、主に以下のライブラリと技術を利用して動作します。

markitdown ライブラリ: このプログラムの中核となるライブラリです。PDF、DOCX、PPTXといった様々なドキュメント形式からテキストコンテンツを抽出し、Markdown形式に変換する機能を提供します。markitdown は、各ファイル形式に対応するパーサーやレンダラーを内部的に使用しており、ファイルの内容を構造化されたMarkdownに変換します。
OpenAI API (Vision モデル): 入力ファイルがJPG形式の場合に利用されます。markitdown ライブラリの mlm_client および mlm_model パラメータを通じてOpenAIのAPIが呼び出されます。具体的には、OpenAIのVisionモデル（例: gpt-4o-mini）が画像を解析し、mlm_prompt で指定されたプロンプト（例: 「画像について説明してください。」）に基づいて画像の内容を自然言語で説明します。この説明文がMarkdownテキストの一部として出力されます。この機能により、視覚情報がテキスト情報に変換され、画像のコンテンツをMarkdownドキュメントに含めることが可能になります。
dotenv ライブラリ: このライブラリは、環境変数ファイル .env から環境変数（例: OPENAI_API_KEY）を読み込むために使用されます。これにより、APIキーのような機密情報をプログラムコードに直接記述することを避け、セキュリティを高め、異なる環境での設定変更を容易にします。プログラムの実行時に .env ファイルが検索され、そこに記述された変数がシステムの環境変数としてロードされます。

これらの技術の組み合わせにより、convert2md.py は多様な入力から一貫したMarkdown出力を生成する柔軟なツールとして機能します。

必要な非標準ライブラリとインストール方法

convert2md.py の実行には、以下の非標準Pythonライブラリが必要です。pip コマンドを使用してインストールできます。

python-dotenv: .env ファイルから環境変数を読み込むために必要です。
```
pip install python-dotenv
```
markitdown: ドキュメント（PDF, DOCX, PPTX）や画像（JPG）をMarkdownに変換する主要なライブラリです。特定のファイル形式をサポートするためには、追加の依存関係をインストールする必要があります。
```
pip install markitdown
pip install markitdown[docx] # DOCXファイルの変換が必要な場合
pip install markitdown[pptx] # PPTXファイルの変換が必要な場合
pip install markitdown[pdf]  # PDFファイルの変換が必要な場合
```
上記コマンドにより、Word、PowerPoint、PDFファイルの変換機能が追加されます。
openai: OpenAI APIと連携し、JPG画像の解析を行うために必要です。
```
pip install openai
```

必要な入力ファイル

プログラムが正しく動作するためには、以下の種類の入力ファイルが必要です。

変換対象のファイル:
- ドキュメントファイル: .pdf, .docx (Microsoft Word), .pptx (Microsoft PowerPoint) などのファイル形式がサポートされています。これらのファイルは markitdown ライブラリによって処理可能な内容である必要があります。
- 画像ファイル: .jpg (または .jpeg) ファイルがサポートされています。JPGファイルの場合、OpenAI APIのVisionモデルによる画像解析が試みられます。
.env ファイル (OpenAI APIを使用する場合): OpenAI APIを利用してJPG画像を解析する場合、プログラムと同じディレクトリ、またはその親ディレクトリに .env ファイルを配置し、OPENAI_API_KEY を設定する必要があります。

.env ファイルの内容例:
```
OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```
sk-xxxxxxxx... の部分は、ご自身のOpenAI APIキーに置き換えてください。

生成される出力ファイル

convert2md.py は、入力ファイルに基づいて以下の形式のファイルを出力します。

ファイル名: 入力ファイルと同じディレクトリに、入力ファイルのベース名と同じ名前で、拡張子が .md となったファイルが生成されます。
- 例1: 入力ファイルが document.pdf の場合、出力ファイルは document.md となります。
- 例2: 入力ファイルが image.jpg の場合、出力ファイルは image.md となります。
ファイルの内容:
- ドキュメントファイル (PDF, DOCX, PPTX) の場合: 入力ファイルのテキストコンテンツがMarkdown形式に変換されて記述されます。見出し、リスト、段落などが可能な限り元のドキュメントの構造を保持してMarkdownに変換されます。
- 画像ファイル (JPG) の場合: OpenAI APIのVisionモデルが画像を解析し、その内容を説明した自然言語のテキストがMarkdown形式で記述されます。

コマンドラインでの使用例 (Usage)

convert2md.py は、コマンドラインから以下の形式で実行します。

python convert2md.py <input_file>

<input_file>: Markdownに変換する対象の入力ファイルへのパスを指定します。絶対パスでも相対パスでも構いません。

コマンドラインでの具体的な使用例

ここでは、いくつかの具体的なシナリオでの使用例と、その実行結果を説明します。

PDFファイルをMarkdownに変換する例
- 前提: report.pdf というPDFファイルが convert2md.py と同じディレクトリに存在すると仮定します。
- コマンド:
```
python convert2md.py report.pdf
```
- 実行結果: プログラムは report.pdf を解析し、report.md というMarkdownファイルが同じディレクトリに生成されます。report.md には report.pdf のテキストコンテンツがMarkdown形式で記述されます。
```
Convert document file to markdown file
infile: report.pdf
outfile: report.md
... (変換されたMarkdownテキストが標準出力に表示される) ...
Save to report.md

USAGE:
  python script.py <input_file>
  <input_file>: The path to the input file to be converted to markdown.
```

JPG画像をMarkdownに変換する例 (OpenAI APIを使用)

前提:
- landscape.jpg という画像ファイルが convert2md.py と同じディレクトリに存在すると仮定します。
- プログラムと同じディレクトリに .env ファイルが存在し、OPENAI_API_KEY が適切に設定されていると仮定します。
```
OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```
コマンド:
```
python convert2md.py landscape.jpg
```

実行結果: プログラムは landscape.jpg をOpenAI APIに送信して解析させ、その説明文を基に landscape.md というMarkdownファイルが同じディレクトリに生成されます。 landscape.md の内容例:

これは広大な緑の丘陵地帯の風景写真です。空は明るく、いくつかの白い雲が浮かんでいます。手前には芝生が広がり、遠くにはなだらかな丘が続いています。自然の美しさと静けさを感じさせる一枚です。

標準出力には以下のようなメッセージが表示されます。

Convert document file to markdown file
infile: landscape.jpg
outfile: landscape.md
Analyze image file landscape.jpg
... (変換されたMarkdownテキストが標準出力に表示される) ...
Save to landscape.md

USAGE:
  python script.py <input_file>
  <input_file>: The path to the input file to be converted to markdown.

存在しないファイルを指定した場合の例

コマンド:

python convert2md.py non_existent_file.pdf

実行結果: ファイルが存在しないため、エラーメッセージが表示され、プログラムが終了します。

Error: ファイル non_existent_file.pdf が存在しません。

USAGE:
  python script.py <input_file>
  <input_file>: The path to the input file to be converted to markdown.