Metadata-Version: 2.4
Name: zotomatic
Version: 0.2.0
Summary: A CLI tool for generating Markdown notes from academic PDF papers using customizable templates, Zotero metadata, and LLM-powered summaries.
Project-URL: Source, https://github.com/glyphcat/zotomatic
Project-URL: Issues, https://github.com/glyphcat/zotomatic/issues
Project-URL: Documentation, https://github.com/glyphcat/zotomatic/tree/main/docs
Author: glyphcat
License: MIT License
        
        Copyright (c) 2025 glyphcat
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: academic,cli,llm,markdown,metadata,note,paper,pdf,research,summarization,tagging,template,zotero
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.1
Requires-Dist: pdfminer-six>=20240706
Requires-Dist: pymupdf>=1.26.7
Requires-Dist: pyzotero>=1.6.16
Requires-Dist: watchfiles>=1.1.0
Description-Content-Type: text/markdown

# Zotomatic

Zotomatic is a CLI tool that generates Markdown research notes from PDFs using user-defined templates, Zotero metadata, and extracted text.  

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

---

## Quick Start

[Start Guide](docs/en/getting-started.md)

### Install

```bash
pip install zotomatic
zotomatic init --pdf-dir ./papers  # Directory for PDFs
```

### Generate notes from a PDF file

Generate a Markdown note from a specific PDF in any directory.  
`pdf_dir` is not required.

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

### Batch process PDFs under the configured directory

Process all PDFs under the configured directory.  
`pdf_dir` is required.

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

### Watch the configured directory for new PDFs

Watch the configured directory and generate notes whenever a PDF is added.  
`pdf_dir` is required.

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

---

## Overview

Zotomatic is a CLI tool that starts from research PDFs, uses bibliographic information and extracted text, and generates Markdown notes based on user-defined templates.

For PDFs managed in Zotero, Zotomatic can fetch metadata such as authors, title, and abstract to produce notes enriched with bibliographic details. It can also generate minimal notes for PDFs outside Zotero.

Zotomatic can optionally integrate with an LLM to generate summaries and tags in a specified language and insert the results into notes.  
Note: Output quality and accuracy depend on the LLM.

Notes are plain Markdown files, and templates are fully user-defined. You can use them with any editor or knowledge tool, including Obsidian.

---

## Key Features

- **Automatic Markdown note generation from research PDFs**  
  Avoid manual note taking and output reusable research notes in Markdown.

- **Automatic metadata retrieval from Zotero-managed PDFs**  
  Pull authors, title, abstract, and other bibliographic data from Zotero and insert them into notes.

- **Support for PDFs outside Zotero**  
  Generate minimal, structured notes even when PDFs are not registered in Zotero.

- **Best-effort completion for missing metadata**  
  If Zotero metadata is incomplete, Zotomatic attempts to fill missing fields from PDF text.  
  Note: Completion runs only for Zotero-managed PDFs.

- **Flexible, user-defined templates**  
  Customize headings and sections to match your workflow.

- **Optional LLM summaries and tags (language-selectable)**  
  Generate summaries and tags via LLM when enabled (default output is Japanese with other languages available).

- **Multiple scan modes**  
  Use watch, once, or path mode to fit your workflow.

---

## Installation

```bash
pip install zotomatic
```

---

## Use Cases

- **Auto-generate notes from PDFs saved in the browser**  
  Save a PDF via Zotero Connector and run `scan --watch` for real-time note creation.
- **Batch-generate notes for an existing library**  
  Run `scan --once` to process everything under `pdf_dir`.
- **Spot-process PDFs outside Zotero**  
  Use `scan --path` for quick, file-specific note generation.
- **Auto-insert summaries and tags (optional)**  
  With an API key, generate summaries and tags in a chosen language (ChatGPT and Gemini supported).

If you want Zotero metadata, keep the Zotero desktop app running.

See `docs/en/getting-started.md` for step-by-step instructions.

---

## Documentation

- [Index](docs/en/index.md)
- [Start Guide](docs/en/getting-started.md)
- [Configuration Reference](docs/en/configuration.md)
- [CLI Reference](docs/en/cli.md)

---

## Roadmap

- Support additional LLM providers

Note: Roadmap items and timelines may change.

---

## Notes

- Zotomatic is a research support tool and does not guarantee the accuracy of generated summaries or tags.
- Always verify results against the original paper before citing.

---

## License

MIT License

---

## Support and Feedback

Please use GitHub Issues for bug reports.

This is a personal project, so not all issues or pull requests can be addressed. Pull requests are not accepted at this time.
