discountchubbs/james-grammar-8B

Autocorrect Daemon Architecture

This project is a fully private, locally-hosted AI grammar, syntax, and style correction daemon for macOS. Rather than functioning as an open-ended conversational LLM, this system constrains a 4-bit quantized foundation model (Meta-Llama-3-8B-Instruct) into a dedicated, single-task neural copyediting utility.

All conversational generation, chat persona, and open-ended generative behaviors are eliminated. The model operates under deterministic greedy decoding ($T=0.0$) solely to map imperfect drafts to the author's exact academic writing style, vocabulary, and APA syntax.

Privacy & Security:

Unlike cloud-based LLMs that transmit highlighted text over the internet, this local language model executes 100% locally on Apple Unified Memory via Apple MLX. The daemon operates with zero outbound network requests and zero persistent disk logging—highlighted text is processed ephemerally in RAM and immediately discarded. This design helps guarantee complete protection for Personally Identifiable Information (PII) and information security.

---

How It Works

[Highlight Text in any App] ──> [Ctrl + Space Hotkey]
                                         │
                                         ▼
                 [James Autocorrect Daemon.app (macOS Native App)]
                 • Captures global hotkey via CGEventTap.
                 • Native Menu Bar item (✍️) running the James-grammar-8B model locally.
                 • Direct In-Memory MLX Inference (<300ms, zero network latency).
                                         │
                                         ▼
                     [Instant In-Place Text Replacement Using only James's Voice and Style.]
                 • Corrects the highlighted text for spelling and grammatical style while maintaining the author's exact voice.

---

Quickstart Setup

One-Click macOS Setup (Automated)

./setup_macos.sh

Creates the virtual environment with uv, installs all dependencies, compiles the native .app, registers auto-start on login, and launches the Menu Bar daemon.

---

---

1. Data Pipeline

1. Extract Sentences from Documents:

   source .venv/bin/activate
   python pipeline/extract_docs.py
   

   Scans your documents for .docx files, extracts and cleans text, and saves deduplicated sentences to data/dataset_raw.txt.

2. Generate Comprehensive Grammar & Syntax Dataset:

   source .venv/bin/activate
   python pipeline/generate_dataset.py
   

   Generates data/train.jsonl and data/valid.jsonl covering 16 grammatical dimensions:

   • Formal Contraction Expansion: Expanding informal and unpunctuated contractions ("don't" / "dont" $\rightarrow$ "do not", "can't" / "cant" $\rightarrow$ "cannot", "won't" / "wont" $\rightarrow$ "will not").
   • Punctuation & Comma Precision: Enforcing introductory clause commas, Oxford commas, and conjunctive adverbs (", for example,", ", however,"), while stripping compound-predicate commas and erroneous subordinating commas (", because," $\rightarrow$ "because").
   • Run-Ons & Comma Splices: Reconstructing comma-spliced clauses and loose coordinate chains into clean sentence boundaries.
   • Word-Order & Syntax Inversions: Inverted modifiers and swapped words ("example an" $\rightarrow$ "an example", "software my" $\rightarrow$ "my software").
   • Subject-Verb Agreement: Singular/plural agreement ("he have" $\rightarrow$ "he has", "they was" $\rightarrow$ "they were").
   • Verb Tenses & Participles: Modal auxiliaries and irregular forms ("should of went" $\rightarrow$ "should have gone", "had saw" $\rightarrow$ "had seen").
   • Pronoun Case & Reference: Subjective vs. objective compound cases ("me and him went" $\rightarrow$ "he and I went", "who" $\leftrightarrow$ "whom").
   • Relative Clauses: Precision with restrictive that vs. non-restrictive which.
   • Articles & Prepositions: Missing, misplaced, or swapped articles (a/an/the) and prepositions (in/on/at/for/to).
   • Double Negatives: Eliminating informal double negatives ("don't need no" $\rightarrow$ "do not need any").
   • Quantifiers & Determiners: Proper count vs. non-count quantifiers ("too much people" $\rightarrow$ "too many people", "less participants" $\rightarrow$ "fewer participants").
   • Comparatives & Superlatives: Standard academic comparatives ("different than" $\rightarrow$ "different from", "more better" $\rightarrow$ "better").
   • Logical Connectors: Removing redundant connectors ("Although ..., but ..." $\rightarrow$ "Although ...,").
   • Sentence-Initial Capitalization: Restoring leading uppercase on uncapitalized sentence starts.
   • Spelling & Homophones: Character-level mutations and phonetic typos (recieve $\rightarrow$ receive, their/there/they're, affect/effect).

---

2. Model Training & Fusion

1. Fine-Tune with LoRA:

   ./model/train_lora.sh
   

   Runs Low-Rank Adaptation (LoRA) directly on james-grammar-8B using Apple Silicon MLX GPU acceleration. Checkpoints are saved to model/adapters/.

2. Fuse Adapters into Standalone Model:

   ./model/fuse_model.sh
   

   Permanently fuses the trained adapter weights directly into james-grammar-8B.

---

3. Running the Standalone System

Step 1: Build & Launch the Daemon App

./service/build_hotkey.sh

Compiles and installs the native macOS background app to ~/Applications/James Autocorrect Daemon.app. The daemon directly embeds MLX and james-grammar-8B in-process for zero-latency in-memory inference without needing an external web server.

Step 2: Grant Accessibility Permissions

• Open macOS System Settings > Privacy & Security > Accessibility.
• Ensure James Autocorrect Daemon is toggled ON.

Step 3: Menu Bar Icon & Controls

• Look at your top macOS Menu Bar (next to WiFi / Battery) for the ✍️ icon.
• Click the icon to view status or select Quit Autocorrect (⌘Q) to unload the model from memory.

Step 4: Auto-Start on Login (Optional)

To automatically launch the daemon in the background every time you boot or log in to your Mac:

osascript -e 'tell application "System Events" to make login item at end with properties {path:"'"$HOME"'/Applications/James Autocorrect Daemon.app", hidden:true}'

Step 5: System-Wide Usage

• Highlight any text across any macOS application (Chrome, IDE, Word, Slack, Notes, Terminal, etc.).
• Press Ctrl + Space.
• The daemon instantly replaces the highlighted text with grammatically corrected text in James's voice.

---

License & Academic Citation

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0) with strict Educational & Academic Research restrictions.

You are free to use, study, and modify this software, datasets, and model weights EXCLUSIVELY for non-commercial educational instruction, student learning, and academic scientific research. Any academic paper, thesis, dissertation, or derivative software utilizing this work must cite the author in the publication's appropriate citation style:

APA 7th Edition:

Vecellio-Grant, J. (2026). Autocorrect daemon (Version 1.0) [Computer software]. Hugging Face. https://huggingface.co/discountchubbs/james-grammar-8B

BibTeX (LaTeX / Computer Science / IEEE):

@software{vecellio_grant_2026_autocorrect,
  author = {Vecellio-Grant, James},
  title = {Autocorrect Daemon},
  year = {2026},
  version = {1.0},
  publisher = {Hugging Face},
  url = {https://huggingface.co/discountchubbs/james-grammar-8B}
}

Commercial, corporate, or for-profit usage is strictly prohibited without prior explicit written permission from the author. See LICENSE for complete terms.