Metadata-Version: 2.4
Name: academic-document-checker
Version: 0.4.1b2
Summary: Rule-based academic document checker with optional AI enhancement (coming in v1.5+)
Author: Academic Document Checker Team
License: MIT
Project-URL: Homepage, https://github.com/darmsc/Academic_Document_Checker
Project-URL: Documentation, https://github.com/darmsc/Academic_Document_Checker#readme
Project-URL: Repository, https://github.com/darmsc/Academic_Document_Checker
Project-URL: Issues, https://github.com/darmsc/Academic_Document_Checker/issues
Keywords: academic,document,checker,thesis,medical,journal,validation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: python-docx>=0.8.11
Requires-Dist: PyYAML>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: jinja2>=3.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: ai
Requires-Dist: openai>=1.0; extra == "ai"
Requires-Dist: anthropic>=0.20; extra == "ai"
Provides-Extra: medical
Requires-Dist: language-tool-python>=2.7; extra == "medical"
Requires-Dist: pyspellchecker>=0.7.0; extra == "medical"
Provides-Extra: all
Requires-Dist: academic-document-checker[ai,dev,medical]; extra == "all"
Dynamic: license-file

# Academic Document Checker

> A Python CLI tool that automatically validates academic documents (Word, PDF, and more) with profile-based checking for PhD theses, medical journals, and more.

## What Does It Do?

The Academic Document Checker analyzes your Word documents and provides comprehensive feedback on:

- ✅ **Structure** - Required sections, heading hierarchy, organization
- ✅ **Formatting** - Word counts, figure limits, citation style
- ✅ **Citations** - Format validation, orphaned references, completeness
- ✅ **Grammar** - Academic tone, passive voice, sentence complexity
- ✅ **Style** - Writing quality, clarity, domain-specific requirements

## Why Use This Tool?

### For PhD Students
- Ensure your thesis meets institutional requirements before submission
- Catch structural and formatting issues early
- Validate citation completeness and consistency
- Get feedback on academic writing style

### For Medical Researchers
- Check compliance with journal-specific guidelines (Lancet, NEJM, BMJ)
- Validate CONSORT/STROBE/PRISMA checklist items
- Ensure proper medical terminology usage
- Meet strict word and reference limits

### For Academic Supervisors
- Standardize quality expectations across students
- Quickly identify common issues in student work
- Provide consistent, objective feedback
- Save time on structural reviews

## Quick Start

### Installation

```bash
pip install academic-document-checker
```

### Basic Usage

```bash
# Check a PhD thesis
doc-checker check thesis.docx --profile phd-thesis

# Check a medical journal manuscript
doc-checker check manuscript.docx --profile lancet

# Generate HTML report
doc-checker check thesis.docx --profile phd-thesis --format html --output report.html
```

### Example Output

```
📄 Checking: thesis.docx
📋 Profile: PhD Thesis

Structure Analysis:
  ✓ All required sections present
  ❌ Missing: "List of Abbreviations"
  ⚠️  Section order: "Discussion" should come before "Conclusion"

Formatting:
  ✓ Abstract: 287 words (limit: 500)
  ❌ Total words: 38,450 (minimum: 40,000)
  ✓ References: 67 (minimum: 50)

Citations:
  ⚠️  3 citations not found in references
  ⚠️  5 references never cited in text
  ✓ Citation format is consistent (APA)

Grammar & Style:
  ⚠️  Passive voice: 28% (recommended: <25%)
  ⚠️  12 sentences exceed 40 words
  💡 Consider more active voice in Discussion section

Summary: 2 errors, 7 warnings, 1 suggestion
```

## Profile System

The tool uses **profiles** to adapt checking rules for different document types:

### Available Profiles

| Profile | Best For | Key Features |
|---------|----------|--------------|
| **generic** | General academic papers | Basic structure, flexible formatting |
| **phd-thesis** | Doctoral dissertations | 15+ required sections, 40k+ words, comprehensive |
| **medical-journal** | Medical research papers | IMRAD structure, clinical guidelines, medical terms |
| **lancet** | The Lancet submissions | 3000 word limit, 30 references, strict formatting |
| **nejm** | NEJM submissions | 2700 word limit, 40 references, NEJM style |
| **bmj** | BMJ submissions | 4000 word limit, patient involvement, BMJ boxes |
| **grant-proposal** | Generic grant applications | Aims, budget, significance, innovation sections |
| **nih** | NIH grant applications | NIH-specific sections, page limits, review criteria |
| **nsf** | NSF grant applications | Broader impacts, intellectual merit requirements |

### Profile Inheritance

Profiles build on each other to avoid duplication:

```
Generic Publication
├── PhD Thesis
├── Medical Journal
│   ├── The Lancet
│   ├── NEJM
│   ├── BMJ
│   └── Custom Journals...
└── Grant Proposal
    ├── NIH
    ├── NSF
    └── Custom Grants...
```

## Features

### 1. Multi-Format Support
Works with Word documents (.docx), plain text (.txt), and Markdown (.md) out of the box.
PDF and LaTeX support is planned for a future release.

```bash
# Word document
doc-checker check thesis.docx --profile phd-thesis

# Markdown
doc-checker check thesis.md --profile phd-thesis

# Plain text
doc-checker check thesis.txt --profile phd-thesis

# Future formats (planned)
doc-checker check thesis.pdf --profile phd-thesis
```

### 2. Multi-Profile Support
Choose the right profile for your document type. Each profile has specific requirements and validation rules.

```bash
doc-checker profiles --list
doc-checker check document.docx --profile phd-thesis
```

### 3. Comprehensive Checking
- **Structure**: Required sections, heading hierarchy, numbering
- **Formatting**: Word limits, figure counts, spacing requirements
- **Citations**: Format detection, completeness, consistency
- **Grammar**: Academic tone, passive voice, sentence length
- **Style**: Writing quality, clarity, domain-specific standards

### 4. Multiple Output Formats
```bash
# Terminal output (default)
doc-checker check thesis.docx --profile phd-thesis

# HTML report
doc-checker check thesis.docx --profile phd-thesis --format html --output report.html

# JSON output (for automation)
doc-checker check thesis.docx --profile phd-thesis --format json --output results.json
```

### 5. Custom Profiles
Create profiles for your institution or specific needs:

```bash
# Create new profile
doc-checker profile create my-university --extends phd-thesis

# Validate custom profile
doc-checker profile validate my-profile.yaml
```

### 6. AI Enhancement (Roadmap)

⚠️ **Coming in Future Releases** - AI features are planned but not yet implemented.

The tool will support three AI options in future versions:

#### v1.5 (Target: Q3 2026) - Cloud AI
- **Providers**: OpenAI (ChatGPT), Anthropic (Claude)
- **Cost**: $0.10-$0.50 per document
- **Quality**: Excellent
- **Privacy**: Document sent to provider's servers
- **Use case**: Best for final review before submission

#### v2.0 (Target: Q4 2026) - Local AI  
- **Provider**: Ollama (runs on your computer)
- **Cost**: Free
- **Quality**: Good
- **Privacy**: Completely private, offline
- **Use case**: Budget-friendly, sensitive documents

#### v2.5 (Target: Q1 2027) - Fine-Tuned Models
- **Provider**: Custom models via Ollama/Hugging Face
- **Cost**: Free (after training)
- **Quality**: Excellent for specific domains
- **Privacy**: Completely private, offline
- **Use case**: Institution-specific requirements

**Current Version (v1.0)**: Rule-based checking only (no AI required)

See [`plans/UPDATED_PROJECT_PLAN_v2.0.md`](plans/UPDATED_PROJECT_PLAN_v2.0.md) for detailed AI strategy.

## Documentation

### Planning Documents
- **[Project Plan (v2.0)](plans/UPDATED_PROJECT_PLAN_v2.0.md)** - Consolidated project plan with all specifications
  - Technical architecture
  - Development roadmap
  - Testing strategy
  - AI enhancement strategy
  - ICMJE/COPE compliance
  - Profile specifications

### User Guides (Coming Soon)
- User Guide - How to use the tool effectively
- Creating Custom Profiles - Build your own profiles
- Medical Guidelines - Understanding clinical reporting standards
- Configuration Reference - All configuration options

## Command Reference

### Checking Documents

```bash
# Basic check
doc-checker check <file> --profile <profile-name>

# Multiple files
doc-checker check chapter*.docx --merge

# Custom configuration
doc-checker check <file> --config custom-rules.yaml

# Specify output
doc-checker check <file> --format html --output report.html

# Set severity threshold
doc-checker check <file> --severity error

# Ignore sections
doc-checker check <file> --ignore "Acknowledgements,Appendices"
```

### Managing Profiles

```bash
# List available profiles
doc-checker profiles --list

# Show profile details
doc-checker profile show phd-thesis

# Create custom profile
doc-checker profile create <name> --extends <parent-profile>

# Validate profile
doc-checker profile validate <profile-file>

# Compare profiles
doc-checker profile diff <profile1> <profile2>
```

### Configuration

```bash
# Initialize configuration
doc-checker init

# Show current configuration
doc-checker config --show

# Set default profile
doc-checker config set default-profile phd-thesis
```

## Configuration File

Create a `.doc-checker.yaml` file in your project:

```yaml
# Default profile to use
default_profile: "phd-thesis"

# Citation style preference
citation_style: "apa"

# Custom dictionary
custom_dictionary:
  - "bioinformatics"
  - "proteomics"
  - "metabolomics"

# Ignore patterns
ignore_sections:
  - "Acknowledgements"
  - "Dedication"

# Severity threshold
severity: "warning"  # Only show warnings and errors

# Output preferences
output:
  format: "html"
  include_suggestions: true
  show_line_numbers: true

# AI enhancement (optional)
ai:
  enabled: false
  provider: "openai"
  model: "gpt-4"
  api_key: "${OPENAI_API_KEY}"  # Use environment variable
```

## Requirements

- Python 3.8 or higher
- Supported document formats: `.docx` (Word), `.md` (Markdown), `.txt` (plain text)
- Internet connection only required for optional AI features (planned for v1.5+)
- Future format support planned: PDF, LaTeX, RTF

## Development Status & Release Plan

### Current Status
🚀 **v0.4.1-beta** — Bug fixes, improved citation handling, and integration tests complete
📅 **Next Milestone**: v1.0.0 Public Release (Target: Q2 2026)

### Release Roadmap

#### v1.0 - Rule-Based Core (Target: Q2 2026) 🎯 CURRENT FOCUS
**Status**: Final Polish & Documentation

**Completed**:
- ✅ Phase 1: Foundation & Core Architecture
- ✅ Phase 2: Core Analyzers (Structure, Formatting, Citations)
- ✅ Phase 3: Medical & PhD Profiles (ICMJE/COPE Compliance)
- ✅ Phase 3b: Grant Proposal Profiles (NIH, NSF)
- ✅ MVP Stage 1: Verification & Testing Foundation (70%+ coverage)
- ✅ MVP Stage 2: Sample Documents Creation (4 complete datasets)
- ✅ MVP Stage 3: Integration Testing & Bug Fixes (135 tests, 0 failures)

**In Progress**:
- 🔄 Phase 4: User Documentation

**Features**:
- Complete rule-based document checking
- Structure, formatting, citations, grammar analysis
- ICMJE/COPE compliance validation
- HTML, JSON, Terminal, JUnit reports
- Multiple profiles (PhD thesis, medical journals, generic)
- CI/CD integration support
- Comprehensive documentation

**No AI required** - Fast, free, works offline

---

#### v1.5 - Cloud AI Integration (Target: Q3 2026)
**Status**: Planned for 8 weeks after v1.0 release

**Scope**:
- ⏳ Phase 5: Cloud AI Integration (Weeks 16-23)

**New Features**:
- Optional `--ai-enhance` flag
- OpenAI (GPT-4) integration
- Anthropic (Claude) integration
- Cost estimation and tracking
- AI-powered content quality analysis
- Semantic citation validation
- Context-aware writing suggestions

**Requires**: User-provided API key, internet connection

---

#### v2.0 - Local AI Support (Target: Q4 2026)
**Status**: Planned for 6 weeks after v1.5 release

**Scope**:
- ⏳ Phase 6: Local AI Support (Weeks 24-29)

**New Features**:
- Ollama integration
- Local LLM support (Llama 3, Mistral, etc.)
- `--ai-provider local` option
- Model management CLI (`doc-checker ai models`)
- Completely offline AI analysis
- Zero API costs

**Requires**: Ollama installed, 8GB+ RAM, 5-10GB disk space

---

#### v2.5 - Fine-Tuned Models (Target: Q1 2027)
**Status**: Planned for 12+ weeks after v2.0 release

**Scope**:
- ⏳ Phase 7: Fine-Tuned Models (Weeks 30-41+)

**New Features**:
- Pre-trained domain-specific models:
  - `medical-v1` - Medical journal manuscripts
  - `phd-thesis-v1` - PhD dissertations
  - `generic-academic-v1` - General academic papers
- Hugging Face model distribution
- Custom model fine-tuning scripts
- Institution-specific model support
- Fine-tuning documentation and guides

**Requires**: Same as v2.0

---

#### v3.0+ - Future Enhancements
- PDF document support
- Markdown and LaTeX support
- Multi-language support
- Collaborative checking
- Web interface
- **Profile Governance & Accreditation System** (see [`plans/profile-governance-strategy.md`](plans/profile-governance-strategy.md))

---

See [`plans/UPDATED_PROJECT_PLAN_v2.0.md`](plans/UPDATED_PROJECT_PLAN_v2.0.md) for detailed roadmap.

## Contributing

Contributions are welcome! Here's how you can help:

- **Add profiles** - Create profiles for specific journals or institutions
- **Improve analyzers** - Enhance existing checks or add new ones
- **Write documentation** - Improve guides and examples
- **Report bugs** - Open issues for problems you encounter
- **Suggest features** - Share ideas for improvements

## Technology Stack

- **Python 3.8+** - Core language
- **Click/Typer** - CLI framework
- **python-docx** - Word document parsing
- **LanguageTool** - Grammar checking
- **Rich** - Terminal output
- **Jinja2** - Report generation
- **pytest** - Testing
- **Future**: PyPDF2/pdfplumber (PDF), python-markdown (Markdown), pylatex (LaTeX)

## License

[MIT](LICENSE)

## Support

- **Issues**: [GitHub Issues](https://github.com/darmsc/Academic_Document_Checker/issues)
- **Discussions**: [GitHub Discussions](https://github.com/darmsc/Academic_Document_Checker/discussions)
- **Documentation**: [Full documentation](https://github.com/darmsc/Academic_Document_Checker/docs)

## Acknowledgements

This tool is designed to help academic writers produce high-quality documents. It complements, but does not replace, human review and editorial judgment.

---

**Status**: Active Development - Phase 4 | **Current Version**: 0.4.1-beta | **Target v1.0**: Q2 2026 | **Last Updated**: April 2026
