Metadata-Version: 2.4
Name: papersmith
Version: 0.1.4
Summary: Programmatic Word document generation with LaTeX equations, style presets, citations, charts, and MCP server
Project-URL: Homepage, https://github.com/imnb57/papersmith
Project-URL: Documentation, https://imnb57.github.io/papersmith
Project-URL: Repository, https://github.com/imnb57/papersmith
Project-URL: Issues, https://github.com/imnb57/papersmith/issues
Project-URL: Changelog, https://github.com/imnb57/papersmith/blob/main/CHANGELOG.md
Author: PaperSmith Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: academic,citations,document,docx,equations,latex,mcp,word
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.20
Requires-Dist: bibtexparser>=2.0.0b0
Requires-Dist: docx2pdf>=0.1
Requires-Dist: google-generativeai>=0.5
Requires-Dist: kaleido>=0.2
Requires-Dist: latex2mathml>=3.0
Requires-Dist: lxml>=4.9
Requires-Dist: matplotlib>=3.8
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: openai>=1.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: lxml-stubs>=0.5; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# 🔨 papersmith

> **Wrap python-docx in a premium fluent API** with native LaTeX equations, citation management, charts, and built-in MCP server for LLMs.

[![CI](https://github.com/imnb57/papersmith/actions/workflows/ci.yml/badge.svg)](https://github.com/imnb57/papersmith/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/papersmith.svg)](https://pypi.org/project/papersmith/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Typed](https://img.shields.io/badge/typed-yes-blue.svg)](https://peps.python.org/pep-0561/)

---

## 🌟 Key Features

*   **📝 Fluent Document API** — Chainable methods to construct clean, professional documents.
*   **📐 Math & Equations** — Convert inline `$E=mc^2$` or block `$$\int x dx$$` into native Office Math (OMML) editable directly inside MS Word.
*   **🎨 Style Presets** — Apply pre-defined layouts (`academic`, `modern`, `report`, `minimal`, `formal`) or construct your own custom design systems.
*   **📚 Citation Manager** — Full APA, IEEE, Harvard, MLA, and Chicago format engines, featuring BibTeX file imports and clickable cross-references.
*   **📊 Integrated Charting** — Auto-embed matplotlib bar, line, pie, or scatter plots directly into document blocks.
*   **💬 Review & Comments** — Easily attach comments, insert tracked changes, and handle footnotes.
*   **🛡️ Metadata Scrubbing** — Auto-clean author names, edit times, and system metrics to keep documents pristine.
*   **🤖 MCP Server** — Expose a secure Model Context Protocol (MCP) server containing 25+ tools for Claude Desktop, Cursor, and other LLMs to generate documents.

---

## ⚙️ Architecture

```mermaid
graph TD
    UserCode[Python API / Markdown CLI] --> PaperSmith[papersmith.SmithDocument]
    PaperSmith --> StylePresets[Style Presets / Layout]
    PaperSmith --> MathModule[LaTeX Equation Renderer]
    PaperSmith --> CitationModule[Citation Manager / BibTeX]
    PaperSmith --> ChartModule[Matplotlib Chart Embedder]
    PaperSmith --> docx[python-docx Engine]
    docx --> OutputDocx[Word Document .docx]
    OutputDocx --> OutputPdf[PDF Export .pdf]
```

---

## 🚀 Quick Start

### Installation

```bash
pip install papersmith
```

### 1. Document Creation with Math & Layouts

```python
from papersmith import SmithDocument

# Initialize with the 'academic' styling preset
doc = SmithDocument(preset="academic")

# Design a title/cover page
doc.add_cover_page(
    title="Asymptotic Complexity & Data Structures",
    subtitle="Analysis of Sorting Algorithms",
    author="Jane Smith",
    institution="Massachusetts Institute of Technology",
    date="October 2026"
)

# Add headers and formatted body text
doc.add_heading("1. Merge Sort Analysis", level=2)
doc.add_text("Merge sort is a divide-and-conquer algorithm with an asymptotic complexity of $O(n \\log n)$.")

# Insert native editable equations
doc.add_equation(r"T(n) = 2T\left(\frac{n}{2}\right) + \Theta(n)")

# Save the document
doc.save("merge_sort_analysis.docx")
```

### 2. Citations & Bibliography

```python
from papersmith import SmithDocument

doc = SmithDocument(preset="academic")
doc.citations.style = "ieee"  # Choose from apa, ieee, harvard, mla, chicago

# Import your BibTeX file directly
doc.citations.import_bibtex("references.bib")

# Or register inline sources manually
doc.citations.add_source(
    "knuth1997",
    author="Donald E. Knuth",
    title="The Art of Computer Programming",
    year=1997,
    publisher="Addison-Wesley",
)

doc.add_heading("2. Literature Review", level=2)
doc.add_text("Classic sorting models are comprehensively detailed in {cite:knuth1997}.")

# Automatically resolves keys and formats bibliography
doc.add_bibliography()
doc.save("citations_example.docx")
```

---

## 🤖 Model Context Protocol (MCP) Integration

`papersmith` contains a built-in MCP server that enables LLMs (like Claude or custom GPTs) to programmatically generate Word documents.

### Claude Desktop Setup
Add this to your `claude_desktop_config.json` (typically in `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "papersmith": {
      "command": "papersmith",
      "args": ["mcp-server", "--transport", "stdio"]
    }
  }
}
```

### Cursor Setup
1. Go to **Settings** -> **Features** -> **MCP**.
2. Click **+ Add New MCP Server**.
3. Name: `papersmith`
4. Type: `command`
5. Command: `papersmith mcp-server --transport stdio`

---

## 💻 Command Line Interface (CLI)

The package exposes a `papersmith` CLI entry point with command helpers:

```bash
# Convert a Markdown file directly to docx using a style preset
papersmith convert report.md -o report.docx --preset report

# Convert markdown with custom author details
papersmith generate notes.md -o output.docx --preset modern --author "Alice"

# Scrub metadata (Creator, total edit time, revisions) from a file
papersmith scrub output.docx --author "Public Author"

# View all available style presets
papersmith presets

# Launch the MCP server
papersmith mcp-server --transport stdio
```

---

## 🛠️ Development & Testing

```bash
# Clone the repository
git clone https://github.com/imnb57/papersmith.git
cd papersmith

# Install development dependencies
pip install -e ".[dev]"

# Run tests & verify coverage
pytest

# Format & Lint
ruff check src/ tests/ --fix
ruff format src/ tests/

# Run type checker
mypy src/papersmith/
```

---

## 🚀 PyPI Releases

To publish a new release:
1. Bump the version in `pyproject.toml`.
2. Tag the commit and push it:
   ```bash
   git tag v0.1.4
   git push origin v0.1.4
   ```
3. The GitHub Actions release workflow (`.github/workflows/release.yml`) will automatically publish the built assets to PyPI using OIDC Trusted Publishing.

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
