Metadata-Version: 2.4
Name: cite_master
Version: 0.2.0
Summary: A tool to automatically generate formatted citations from paper titles
Author-email: Mehmood Ul Haq <mehmooulhaq1040@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/mehmoodulhaq570/CiteMaster
Project-URL: Documentation, https://github.com/mehmoodulhaq570/CiteMaster#readme
Project-URL: Source, https://github.com/mehmoodulhaq570/CiteMaster
Project-URL: Bug Tracker, https://github.com/mehmoodulhaq570/CiteMaster/issues
Project-URL: Changelog, https://github.com/mehmoodulhaq570/CiteMaster/blob/main/CHANGELOG.md
Keywords: citation,bibtex,doi,crossref,apa,mla,ieee
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.1
Requires-Dist: tqdm>=4.59.0
Requires-Dist: bibtexparser<2,>=1.4
Provides-Extra: test
Requires-Dist: pytest>=7.4.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: pytest-mock>=3.11.0; extra == "test"
Dynamic: license-file

[![PyPI](https://img.shields.io/pypi/v/cite_master)](https://pypi.org/project/cite_master/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Issues](https://img.shields.io/github/issues/mehmoodulhaq570/CiteMaster)](https://github.com/mehmoodulhaq570/CiteMaster/issues)
[![Repo size](https://img.shields.io/github/repo-size/mehmoodulhaq570/CiteMaster.svg)](https://github.com/mehmoodulhaq570/CiteMaster)

# CiteMaster

**CiteMaster** turns research paper titles into formatted citations. It looks up each
title on [CrossRef](https://www.crossref.org/), resolves the DOI, fetches the BibTeX entry
and formats it in **APA**, **MLA** or **IEEE** style.

## Features

- Title to DOI lookup via the CrossRef API, with a title-similarity check so unrelated
  results are rejected
- BibTeX retrieval for each DOI
- APA, MLA and IEEE formatting
- Single titles or batches from `.txt` / `.csv` files, processed concurrently
- Command-line interface (`cite-master`) and an interactive mode (`python -m cite_master`)
- Automatic retries for network errors and rate limits
- On-disk cache of lookups, so repeated runs do not hit the API again
- Titles that could not be resolved are written to `failed_titles.txt`

## Installation

Requires **Python 3.9 or newer**.

```bash
pip install cite_master
```

From source:

```bash
git clone https://github.com/mehmoodulhaq570/CiteMaster.git
cd CiteMaster
pip install .
```

## Command-line usage

```bash
# Cite a single title (APA by default)
cite-master "Attention Is All You Need"

# Cite every title in a file in IEEE style and also save BibTeX
cite-master examples/papers.txt --style ieee --bibtex

# Write output files to a specific directory, using 8 worker threads
cite-master papers.txt --style mla -o results/ --workers 8

# Skip the cache and use a specific config file
cite-master papers.txt --no-cache --config my_config.json
```

Options:

| Option | Description |
| --- | --- |
| `--style {apa,mla,ieee}` | Citation style |
| `--bibtex` | Also output the BibTeX entries |
| `-o`, `--output-dir DIR` | Directory for output files |
| `--config PATH` | Path to a JSON config file |
| `--workers N` | Number of concurrent lookups for batch input |
| `--no-cache` | Do not read or write the lookup cache |
| `--quiet` / `--verbose` | Less or more console output |
| `--version` | Print the version and exit |

Run `cite-master --help` for the full list.

Exit codes: `0` every title was cited, `1` at least one title failed, `2` usage or
file error (for example a missing input file).

### Interactive mode

```bash
python -m cite_master
```

You are prompted for a title or file path, a citation style, and whether to include and
save BibTeX.

## Library usage

```python
from cite_master import cite_title

result = cite_title("Attention Is All You Need", style="apa")
if result.ok:
    print(result.citation)
else:
    print(result.status, result.error)  # e.g. "doi_not_found"
```

`cite_title` returns a `CitationResult` with `title`, `doi`, `bibtex`, `citation`,
`status` and `error`; it does not print or prompt. `from cite_master import main` runs the
interactive program.

`cite_titles` (concurrent, results in input order) and `read_titles` handle lists of
titles and title files. The lower-level helpers `get_doi_from_title`, `fetch_bibtex_from_doi` and
`format_citation` are also exported from `cite_master`.

The package logs to the `cite_master` logger and does not configure logging itself when
used as a library.

## Input formats

- **.txt**: one title per line (blank lines are ignored)
- **.csv**: titles in the first column

See [`examples/papers.txt`](examples/papers.txt) for a sample.

## Output files

Written to the output directory (default `outputs/`):

- `citations_output.txt`: formatted citations
- `bibtex_output.txt`: BibTeX entries (when requested)
- `failed_titles.txt`: titles that could not be cited (no DOI, no BibTeX, or an error),
  one per line, so the file can be fed back in to retry them

Existing files are not overwritten; a numbered name is used instead.

The CLI writes its log to `citemaster.log`.

## Configuration

Settings are read from the first config file found:

1. the path passed with `--config`
2. `./config.json` in the current directory
3. `~/.config/citemaster/config.json`

Create a file with all defaults:

```bash
python -c "from cite_master.config import Config; Config.create_default_config_file()"
```

Common keys:

| Key | Default | Meaning |
| --- | --- | --- |
| `output_dir` | `"outputs"` | Directory for output files |
| `citations_filename` | `"citations_output.txt"` | Citations file name |
| `bibtex_filename` | `"bibtex_output.txt"` | BibTeX file name |
| `failed_filename` | `"failed_titles.txt"` | File listing titles that could not be cited |
| `api_timeout` | `30` | Request timeout in seconds |
| `api_retry_attempts` | `3` | Attempts per request for network errors, 429 and 5xx (other 4xx fail at once) |
| `api_retry_delay` | `1` | Initial retry delay in seconds (backs off exponentially) |
| `api_rate_limit` | `50` | Maximum requests per minute |
| `max_workers` | `4` | Concurrent lookups for batch input |
| `cache_enabled` | `true` | Use the lookup cache |
| `cache_expiry_days` | `30` | Days before a cached entry is refreshed |
| `cache_dir` | `null` | Cache directory (default `~/.cache/citemaster/`) |
| `crossref_mailto` | `""` | Your email, sent to CrossRef for its "polite" pool |
| `title_match_threshold` | `0.9` | Minimum title similarity (0-1) to accept a CrossRef match |
| `verbose` / `quiet` | `false` | Console verbosity |

Command-line options override values from the config file.

CiteMaster also follows the limits CrossRef reports in its response headers. Without
`crossref_mailto` that is currently one request at a time and one per second, so
`--workers` mostly speeds up cached lookups. Setting `crossref_mailto` puts you in
CrossRef's "polite" pool, which allows more, and is recommended for large batches. See
[readme_docs/CONFIGURATION.md](readme_docs/CONFIGURATION.md) for details.

### Cache

DOI and BibTeX lookups are cached under `~/.cache/citemaster/`. Entries expire after
`cache_expiry_days`. Use `--no-cache` (or `"cache_enabled": false`) to bypass it, or
delete the directory to clear it.

## Upgrading from 0.1.x

- Python 3.9 or newer is required.
- The log file is now `citemaster.log` (was `errors.log`).
- `process_file` returns a list of `(title, doi)` tuples instead of a dict, so duplicate
  titles are kept and order is preserved. It no longer prints.
- `process_multiple_titles` returns a list of `CitationResult` instead of a dict. New code
  should use `cite_titles` directly.
- The citations file holds only successful citations; failed titles go to
  `failed_titles.txt`.

## Development

```bash
pip install -e ".[test]"
pytest                    # offline unit tests
pytest -m integration     # live CrossRef tests (needs network)
```

See [readme_docs/TESTING.md](readme_docs/TESTING.md).

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## Uninstalling

```bash
pip uninstall cite_master
```

## License

MIT. See [LICENSE](LICENSE).

## Contributing

Issues and pull requests are welcome at
<https://github.com/mehmoodulhaq570/CiteMaster>.

## Acknowledgments

- [CrossRef API](https://www.crossref.org/)
- [BibTeX](https://www.bibtex.org/)
