# Zotomatic

Zotomatic は、研究論文の PDF から Zotero の書誌情報や本文抽出結果をもとに、
ユーザー定義テンプレートに従った Markdown 形式の研究ノートを自動生成する CLI ツールです。

---

## クイックスタート
[スタートガイド](docs/ja/getting-started.md)

### インストール

```bash
pip install zotomatic
zotomatic init --pdf-dir ./papers  # PDF を保存するディレクトリ
```

### PDFファイルからノートを生成する
任意のディレクトリにある PDF ファイルを指定して、Markdown ノートを生成します。  
設定値`pdf-dir`は不要です。

```bash
zotomatic scan --path ./papers/sample.pdf
```

### 設定したDFディレクトリ内のPDFをまとめて処理する
設定したPDFディレクトリ内の PDF を一括で処理し、ノートを生成します。  
設定値`pdf-dir`は必須です。

```bash
zotomatic scan --once
```

### 設定したPDFディレクトリを監視する
設定したPDFディレクトリに PDF が追加されるたびに、自動でノートを生成します。  
設定値`pdf-dir`は必須です。

```bash
zotomatic scan --watch
```

---

## 概要

Zotomatic は、研究論文の PDF を起点に、書誌情報や本文の抽出結果をもとにして、ユーザー定義のテンプレートに従って Markdown ノートを自動生成する CLI ツールです。

Zotero で管理されている論文 PDF からは、著者・タイトル・アブストラクトなどのメタデータを取得して文献情報が反映されたノートを生成できます。一方で、Zotero 管理外の PDF に対しても、最低限の情報を用いたノート生成が可能です。

さらに Zotomatic は LLM と任意で連携し、論文内容の要約やタグ生成を指定言語で行い、その結果をノートに挿入できます。
※ 言語ごとの出力品質や正確性は、利用する LLM に依存します。

生成されるノートは単なる Markdown ファイルであり、テンプレートは完全にユーザーが自由に定義できます。そのため、Obsidian をはじめとする任意のエディタやナレッジ管理ツールで利用できます。

---

## 主な特徴

- **研究論文 PDF から Markdown ノートを自動生成**  
  手作業でのノート作成を不要にし、再利用しやすい Markdown 形式で研究ノートを出力します。

- **Zotero 管理下の PDF から書誌情報を自動取得**  
  著者・タイトル・アブストラクトなどのメタデータを Zotero から取得し、ノートに反映します。

- **Zotero 管理外の PDF にも対応**  
  Zotero に登録されていない PDF でも、最低限の構造化されたノートを自動生成できます。

- **メタデータ欠損時もベストエフォートで自動補完**  
  Zotero に書誌情報が正しく読み込まれていない場合でも、PDF 本文を解析し、可能な範囲で自動補完します。
  ※ 補完処理はZotero管理下のPDFのみに対して実行されます。

- **ユーザー定義テンプレートによる柔軟なノート構成**  
  研究分野や用途に応じて、見出し構成や項目を自由にカスタマイズできます。

- **LLM 連携による要約・タグ生成（任意・言語指定可）**  
  要約やタグ付けを LLM によって自動生成できます。使用の有無や生成言語は設定で制御可能です（デフォルトは日本語で、その他英語や中国語などが指定できます）。

- **複数実行モード対応**  
  ノート生成を行う scan コマンドは、ディレクトリ監視による watch モード、一括処理を行う once モード、個別の PDF ファイルを指定する path モードを備えており、用途に応じたノート生成が可能です。

---

## ユースケース

- **ブラウザから１クリックで PDF を自動でノート化**  
  Zotero Connector で論文 PDF を保存し、`scan --watch` でリアルタイムにノート生成。
- **既存ライブラリの一括ノート化**  
  `scan --once` で `pdf_dir` 配下を一度だけ走査し、まとめてノート作成。
- **Zotero 管理外の PDF をスポット処理**  
  `scan --path` で指定した PDF だけを素早くノート化。
- **LLM 連携で要約・タグを自動挿入（任意）**  
  API キーを設定すると、要約やタグを指定言語で自動生成。現在は OpenAI API のみ対応しています(今後他サービスにも対応予定)。

Zotero 連携でメタデータを取得したい場合は、Zotero デスクトップアプリのを起動しておくのが基本です。

具体的な手順は `docs/ja/getting-started.md` を参照してください。

---

## ドキュメント

- [インデックス](docs/ja/index.md)
- [スタートガイド](docs/ja/getting-started.md)
- [設定リファレンス](docs/ja/configuration.md)
- [CLI リファレンス](docs/ja/cli.md)

---

## 今後の予定（Roadmap）

- OpenAI 以外の LLM プロバイダ対応（例: Gemini など）

※ 上記は予定であり、実装時期や内容は変更される可能性があります。

---

## 注意事項

- zotomatic は研究支援ツールであり、生成される要約やタグの正確性を保証するものではありません
- 論文の理解や引用にあたっては、必ず原文を確認してください

---

## ライセンス

MIT License

---

## サポート・フィードバック

バグ報告は GitHub Issues にて受け付けています。

本プロジェクトは個人開発のため、すべての Issue や Pull Request に対応できない場合があります。現時点では、Pull Request の受け付けは行っていません。
