python-color-math 0.2.2__tar.gz → 0.2.13__tar.gz

{python_color_math-0.2.2/python_color_math.egg-info → python_color_math-0.2.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-color-math
-Version: 0.2.2
+Version: 0.2.13
 Summary: A fast, local semantic LaTeX colorizer for Markdown, Jupyter, and LaTeX math equations.
 Author: Aditya
 License: MIT License
@@ -53,6 +53,13 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: tutorial
+Requires-Dist: rich>=13.0.0; extra == "tutorial"
+Requires-Dist: questionary>=2.0.0; extra == "tutorial"
+Provides-Extra: all
+Requires-Dist: mcp>=1.0.0; extra == "all"
+Requires-Dist: rich>=13.0.0; extra == "all"
+Requires-Dist: questionary>=2.0.0; extra == "all"
 Dynamic: license-file
 
 # 🎨 Python Color Math
@@ -83,26 +90,36 @@ $$ \frac{d}{dx}\textcolor{#7aa2f7}{f(g(y))} \textcolor{white}{=} \textcolor{#bb9
 
 ```bash
 pip install python-color-math
+
+# Or with interactive arrow-key tutorial & rich panels:
+pip install "python-color-math[tutorial]"
+
+# Or with native AI Model Context Protocol (MCP) server support:
+pip install "python-color-math[mcp]"
+
+# Or everything:
+pip install "python-color-math[all]"
 ```
 
-*(Or locally from cloned source: `pip install -e .`)*
+*(Or locally from cloned source: `pip install -e .` or `pip install -e ".[tutorial]"`, `pip install -e ".[all]"`)*
 
 > [!TIP]
 > **Commands & PATH**:
-> - Registers both the short **`color-math`** and full **`python-color-math`** commands.
+> - Registers **`color-math`**, **`python-color-math`**, and the dedicated MCP server binary **`color-math-mcp`**.
 > - If Python's `Scripts/` folder is not on your `PATH`, run directly via Python without touching environment variables:
->   `python -m color_math [options]` *(or `python -m python_color_math`)*.
+>   `python -m color_math [options]` *(or `python -m color_math.mcp`)*.
 > - *Linux users*: Python's standard GUI library is available via `sudo apt install python3-tk`.
 
 ---
 
-## ⚡ Three Ways to Use
+## ⚡ Four Ways to Use
 
 ### 1. 🎓 Interactive Terminal Tutorial
 New to Color Math? Take the 2-minute paced CLI tour with live examples:
 ```bash
 color-math --tutorial
 ```
+*(Runs out of the box with zero dependencies. Install `python-color-math[tutorial]` to unlock arrow-key menus, Rich panels, an interactive LaTeX sandbox, and live theme inspection!)*
 
 ### 2. 🖥️ Graphical Pop-up Window (GUI)
 Prefer visual controls? Launch the native High-DPI pop-up window:
@@ -137,6 +154,15 @@ cat note.md | color-math -
 color-math note.md --diff
 ```
 
+### 4. 🤖 AI Agent Model Context Protocol (MCP)
+Empower local AI assistants (Claude Desktop, Cursor, Antigravity) to semantically format and inspect LaTeX equations:
+```bash
+# Run stdio MCP server directly:
+color-math-mcp
+# or:
+color-math --mcp
+```
+
 ---
 
 ## 📋 Cheat Sheet (Command Reference)
@@ -155,6 +181,7 @@ color-math note.md --diff
 | **Curated Themes** | `color-math note.md --theme catppuccin -w` | Select `default`, `catppuccin`, `nord`, or `light` |
 | **Feature Preset** | `color-math note.md --preset minimal -w` | Presets: `all` (default), `minimal` |
 | **Custom Colors** | `color-math note.md -c unit=#73daca -w` | Override any of 12 individual color roles |
+| **AI MCP Server** | `color-math-mcp` *(or `--mcp`)* | Launch Model Context Protocol server over stdio |
 | **Reset Palette** | `color-math --reset-colors` | Restore factory Tokyo Night palette |
 | **Inspect Colors** | `color-math --show-colors` | Display palette, descriptions, & terminal swatches |
 | **Undo / Strip** | `color-math note.md --undo -w` | Strip color wrappers back to plain LaTeX |
@@ -166,6 +193,9 @@ color-math note.md --diff
 
 Control recognition features with `--preset {all,minimal}` (default: `all`) or individual flags:
 
+- **Piecewise Environments (`\begin{cases}`)**: Full structural recognition of cases with multi-branch alignment (`&`), inequalities, and relations (`\ge`, `\le`, `\ne`, `<`, `>`).
+- **Inline & Display Math**: Accurately colors both display blocks (`$$...$$`) and inline expressions (`$...$`) while strictly protecting code fences and raw backticks.
+- **Half-Colored Auto-Completion**: Partially colored equations are automatically cleaned and re-colorized end-to-end rather than skipped.
 - **Calculus Differentials (`--differentials`)**: Disambiguates `dx`, `dt`, `d\theta`, and derivatives (`\frac{d}{dx}`, `\frac{\partial \psi}{\partial t}`) while leaving standalone distance variables `$d$` untouched.
 - **Physical Units (`--units`)**: Recognizes metric prefixes and unit compounds (`\mu m`, `m/s`, `kg`, `nm`).
 - **Rainbow Delimiters (`--rainbow-delimiters`)**: Recursively colors nested brackets `()`, `[]`, `{}` by depth to eliminate delimiter blindness.
@@ -225,6 +255,75 @@ Add-Content $PROFILE "`ncolor-math --generate-completion powershell | Out-String
 
 ---
 
+## 🤖 Model Context Protocol (MCP) Server
+
+`python-color-math` includes a native Model Context Protocol (MCP) server that empowers AI assistants (**Claude Desktop**, **Cursor**, **Antigravity**, and any MCP client) to format, inspect, colorize, and uncolor LaTeX documents.
+
+### Install MCP Extra
+```bash
+pip install "python-color-math[mcp]"
+```
+
+### Direct Execution
+```bash
+# Default stdio transport
+color-math-mcp
+
+# Or via the main CLI / module:
+color-math --mcp
+python -m color_math.mcp
+```
+
+### Client Configuration
+
+Add to your assistant's MCP configuration:
+
+#### Claude Desktop (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "color-math": {
+      "command": "color-math-mcp"
+    }
+  }
+}
+```
+
+#### Cursor (`.cursor/mcp.json`)
+```json
+{
+  "mcpServers": {
+    "color-math": {
+      "command": "color-math-mcp"
+    }
+  }
+}
+```
+
+#### Antigravity / Gemini CLI (`mcp_config.json`)
+```json
+{
+  "mcpServers": {
+    "python-color-math": {
+      "command": "python",
+      "args": ["-m", "color_math.mcp"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+| Tool | Description |
+| :--- | :--- |
+| `colorize_math_expression` | Colorizes an individual LaTeX string (e.g. `\frac{d}{dx}f(x) = f'(x)`). |
+| `colorize_text` | Parses and colorizes all equations (`$...$` and `$$...$$`) inside a Markdown, LaTeX, or Jupyter document. |
+| `uncolor_text` | Losslessly removes color tags, restoring clean plain LaTeX. |
+| `process_file` | Colorizes or uncolors files on disk in-place (`in_place=True`) or performs a safe dry-run returning a diff. |
+| `scan_vault` | Recursively scans an entire folder/vault to report math blocks and batch-colorize/uncolor notes. |
+| `list_themes_and_config` | Discovers available themes (Tokyo Night, Catppuccin, Nord, Light) and semantic color mappings. |
+
+---
+
 ## 🪝 Pre-commit Integration
 
 Integrate `color-math` into your git workflow using [pre-commit](https://pre-commit.com):

{python_color_math-0.2.2 → python_color_math-0.2.13}/README.md

@@ -26,26 +26,36 @@ $$ \frac{d}{dx}\textcolor{#7aa2f7}{f(g(y))} \textcolor{white}{=} \textcolor{#bb9
 
 ```bash
 pip install python-color-math
+
+# Or with interactive arrow-key tutorial & rich panels:
+pip install "python-color-math[tutorial]"
+
+# Or with native AI Model Context Protocol (MCP) server support:
+pip install "python-color-math[mcp]"
+
+# Or everything:
+pip install "python-color-math[all]"
 ```
 
-*(Or locally from cloned source: `pip install -e .`)*
+*(Or locally from cloned source: `pip install -e .` or `pip install -e ".[tutorial]"`, `pip install -e ".[all]"`)*
 
 > [!TIP]
 > **Commands & PATH**:
-> - Registers both the short **`color-math`** and full **`python-color-math`** commands.
+> - Registers **`color-math`**, **`python-color-math`**, and the dedicated MCP server binary **`color-math-mcp`**.
 > - If Python's `Scripts/` folder is not on your `PATH`, run directly via Python without touching environment variables:
->   `python -m color_math [options]` *(or `python -m python_color_math`)*.
+>   `python -m color_math [options]` *(or `python -m color_math.mcp`)*.
 > - *Linux users*: Python's standard GUI library is available via `sudo apt install python3-tk`.
 
 ---
 
-## ⚡ Three Ways to Use
+## ⚡ Four Ways to Use
 
 ### 1. 🎓 Interactive Terminal Tutorial
 New to Color Math? Take the 2-minute paced CLI tour with live examples:
 ```bash
 color-math --tutorial
 ```
+*(Runs out of the box with zero dependencies. Install `python-color-math[tutorial]` to unlock arrow-key menus, Rich panels, an interactive LaTeX sandbox, and live theme inspection!)*
 
 ### 2. 🖥️ Graphical Pop-up Window (GUI)
 Prefer visual controls? Launch the native High-DPI pop-up window:
@@ -80,6 +90,15 @@ cat note.md | color-math -
 color-math note.md --diff
 ```
 
+### 4. 🤖 AI Agent Model Context Protocol (MCP)
+Empower local AI assistants (Claude Desktop, Cursor, Antigravity) to semantically format and inspect LaTeX equations:
+```bash
+# Run stdio MCP server directly:
+color-math-mcp
+# or:
+color-math --mcp
+```
+
 ---
 
 ## 📋 Cheat Sheet (Command Reference)
@@ -98,6 +117,7 @@ color-math note.md --diff
 | **Curated Themes** | `color-math note.md --theme catppuccin -w` | Select `default`, `catppuccin`, `nord`, or `light` |
 | **Feature Preset** | `color-math note.md --preset minimal -w` | Presets: `all` (default), `minimal` |
 | **Custom Colors** | `color-math note.md -c unit=#73daca -w` | Override any of 12 individual color roles |
+| **AI MCP Server** | `color-math-mcp` *(or `--mcp`)* | Launch Model Context Protocol server over stdio |
 | **Reset Palette** | `color-math --reset-colors` | Restore factory Tokyo Night palette |
 | **Inspect Colors** | `color-math --show-colors` | Display palette, descriptions, & terminal swatches |
 | **Undo / Strip** | `color-math note.md --undo -w` | Strip color wrappers back to plain LaTeX |
@@ -109,6 +129,9 @@ color-math note.md --diff
 
 Control recognition features with `--preset {all,minimal}` (default: `all`) or individual flags:
 
+- **Piecewise Environments (`\begin{cases}`)**: Full structural recognition of cases with multi-branch alignment (`&`), inequalities, and relations (`\ge`, `\le`, `\ne`, `<`, `>`).
+- **Inline & Display Math**: Accurately colors both display blocks (`$$...$$`) and inline expressions (`$...$`) while strictly protecting code fences and raw backticks.
+- **Half-Colored Auto-Completion**: Partially colored equations are automatically cleaned and re-colorized end-to-end rather than skipped.
 - **Calculus Differentials (`--differentials`)**: Disambiguates `dx`, `dt`, `d\theta`, and derivatives (`\frac{d}{dx}`, `\frac{\partial \psi}{\partial t}`) while leaving standalone distance variables `$d$` untouched.
 - **Physical Units (`--units`)**: Recognizes metric prefixes and unit compounds (`\mu m`, `m/s`, `kg`, `nm`).
 - **Rainbow Delimiters (`--rainbow-delimiters`)**: Recursively colors nested brackets `()`, `[]`, `{}` by depth to eliminate delimiter blindness.
@@ -168,6 +191,75 @@ Add-Content $PROFILE "`ncolor-math --generate-completion powershell | Out-String
 
 ---
 
+## 🤖 Model Context Protocol (MCP) Server
+
+`python-color-math` includes a native Model Context Protocol (MCP) server that empowers AI assistants (**Claude Desktop**, **Cursor**, **Antigravity**, and any MCP client) to format, inspect, colorize, and uncolor LaTeX documents.
+
+### Install MCP Extra
+```bash
+pip install "python-color-math[mcp]"
+```
+
+### Direct Execution
+```bash
+# Default stdio transport
+color-math-mcp
+
+# Or via the main CLI / module:
+color-math --mcp
+python -m color_math.mcp
+```
+
+### Client Configuration
+
+Add to your assistant's MCP configuration:
+
+#### Claude Desktop (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "color-math": {
+      "command": "color-math-mcp"
+    }
+  }
+}
+```
+
+#### Cursor (`.cursor/mcp.json`)
+```json
+{
+  "mcpServers": {
+    "color-math": {
+      "command": "color-math-mcp"
+    }
+  }
+}
+```
+
+#### Antigravity / Gemini CLI (`mcp_config.json`)
+```json
+{
+  "mcpServers": {
+    "python-color-math": {
+      "command": "python",
+      "args": ["-m", "color_math.mcp"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+| Tool | Description |
+| :--- | :--- |
+| `colorize_math_expression` | Colorizes an individual LaTeX string (e.g. `\frac{d}{dx}f(x) = f'(x)`). |
+| `colorize_text` | Parses and colorizes all equations (`$...$` and `$$...$$`) inside a Markdown, LaTeX, or Jupyter document. |
+| `uncolor_text` | Losslessly removes color tags, restoring clean plain LaTeX. |
+| `process_file` | Colorizes or uncolors files on disk in-place (`in_place=True`) or performs a safe dry-run returning a diff. |
+| `scan_vault` | Recursively scans an entire folder/vault to report math blocks and batch-colorize/uncolor notes. |
+| `list_themes_and_config` | Discovers available themes (Tokyo Night, Catppuccin, Nord, Light) and semantic color mappings. |
+
+---
+
 ## 🪝 Pre-commit Integration
 
 Integrate `color-math` into your git workflow using [pre-commit](https://pre-commit.com):

{python_color_math-0.2.2 → python_color_math-0.2.13}/color_math/__init__.py

@@ -5,13 +5,19 @@ from .config import ColorMathOptions
 from .converters.block import convert_text
 from .undo import uncolor_text
 
-__version__ = "0.2.2"
+from .ipython import ColorMath, colormath, load_ipython_extension, unload_ipython_extension
+
+__version__ = "0.2.13"
 
 __all__ = [
     "__version__",
+    "ColorMath",
     "ColorMathOptions",
+    "colormath",
     "convert_text",
     "detect_format",
+    "load_ipython_extension",
     "transform_document",
     "uncolor_text",
+    "unload_ipython_extension",
 ]

{python_color_math-0.2.2 → python_color_math-0.2.13}/color_math/adapters.py

@@ -2,12 +2,14 @@
 
 from __future__ import annotations
 
+import copy
 import json
 import re
 from pathlib import Path
 
 from .config import ColorMathOptions
 from .converters.block import convert_math_block, convert_text
+from .parsers.frontmatter import detect_note_field
 from .undo import uncolor_fragment, uncolor_text
 from .utils.latex_helpers import read_comment_end, read_verb_end
 
@@ -50,6 +52,19 @@ def detect_format(path: Path | None, requested: str = "auto") -> str:
     return "markdown"
 
 
+def has_potential_math(text: str, format_name: str = "auto") -> bool:
+    """Ultra-fast probe to bypass documents that cannot possibly contain math."""
+    if "$" in text:
+        return True
+    if r"\[" in text or r"\(" in text:
+        return True
+    if format_name in ("tex", "auto") and r"\begin{" in text:
+        return True
+    if format_name in ("anki", "auto") and ("[$]" in text or "[$$]" in text):
+        return True
+    return False
+
+
 def transform_document(
     text: str,
     format_name: str,
@@ -57,10 +72,28 @@ def transform_document(
     palette: dict[str, str] | None = None,
     options: ColorMathOptions | None = None,
 ) -> str:
-    if format_name == "markdown":
-        return uncolor_text(text) if undo else convert_text(text, palette=palette, options=options)
     if format_name == "jupyter":
         return _transform_notebook(text, undo, palette=palette, options=options)
+
+    if undo:
+        if r"\textcolor" not in text:
+            return text
+    elif not has_potential_math(text, format_name):
+        return text
+
+    if format_name == "markdown":
+        if undo:
+            return uncolor_text(text)
+        opts = options
+        detection = detect_note_field(text)
+        if detection.is_quantum:
+            if opts is None:
+                opts = ColorMathOptions(color_quantum_operators=True, field="quantum")
+            else:
+                opts = copy.copy(opts)
+                opts.color_quantum_operators = True
+                opts.field = "quantum"
+        return convert_text(text, palette=palette, options=opts)
     if format_name == "anki":
         return _transform_delimited(text, ANKI_DELIMITERS, undo, palette=palette, options=options)
     if format_name == "tex":

python_color_math-0.2.13/color_math/colormath.default.json

@@ -0,0 +1,57 @@
+{
+  "_comment": "Python Color Math factory default configuration. This file serves as an immutable reference. To customize settings, edit '.colormath.json'. If '.colormath.json' has syntax errors or missing keys, Color Math safely falls back to these defaults.",
+  "theme": "default",
+  "colors": {
+    "main": "#7aa2f7",
+    "orange": "#e0af68",
+    "dot": "white",
+    "derivative": "#bb9af7",
+    "chain": "#9ece6a",
+    "upper": "#bb9af7",
+    "relation": "white",
+    "arrow": "#f7768e",
+    "set": "#bb9af7",
+    "spacing": "white",
+    "parameter": "#bb9af7",
+    "unit": "#73daca"
+  },
+  "options": {
+    "enable_taxonomy": true,
+    "rainbow_delimiters": true,
+    "variable_data_flow": false,
+    "color_units": true,
+    "color_differentials": true,
+    "color_braket": true,
+    "color_dimensionless": true,
+    "rainbow_bare_braces": false,
+    "highlight_unmatched_braces": false
+  },
+  "unicode": {
+    "greek_style": "plane1",
+    "convert_definite_integrals": false,
+    "convert_bounded_operators": false,
+    "convert_prose_to_unicode": false,
+    "convert_prose_to_latex": false
+  },
+  "_role_descriptions": {
+    "main": "Primary functions, terms, and outermost operations (e.g. f(x))",
+    "derivative": "Derivative marks and differentiated functions (e.g. f'(x))",
+    "chain": "Chain rule factors, inner differential stages (e.g. g'(x), y')",
+    "orange": "Big operators, sums, integrals, and limits (e.g. \\sum, \\int, \\lim)",
+    "dot": "Multiplication symbols, dots, and cross products (e.g. \\cdot, \\times)",
+    "relation": "Equals, inequalities, and comparison symbols (e.g. =, <, \\le)",
+    "arrow": "Implication and mapping arrows (e.g. \\to, \\implies)",
+    "set": "Set theory relations and operators (e.g. \\in, \\subset)",
+    "spacing": "LaTeX spacing and alignment commands (e.g. \\quad, \\,)",
+    "upper": "Matrix exponents, transposes, and top indices (e.g. A^T, M^{-1})",
+    "parameter": "Inner function parameters and indexed variables",
+    "unit": "Physical units and dimensions (e.g. m/s, \\mu m, ^\\circ C)"
+  },
+  "_unicode_descriptions": {
+    "greek_style": "Greek letter typography: 'plane1' (Mathematical Italic: 𝝍, 𝝰) or 'standard' (ψ, α)",
+    "convert_definite_integrals": "Convert bounded integrals like \\int_a^b to ∫_a^b (default: false to preserve vertical TeX limits)",
+    "convert_bounded_operators": "Convert bounded summations/products like \\sum_{i=1}^n to ∑_{i=1}^n (default: false)",
+    "convert_prose_to_unicode": "Convert LaTeX commands like \\psi to 𝜓 in regular prose outside math blocks (default: false to protect prose)",
+    "convert_prose_to_latex": "Convert Unicode symbols like 𝝍 back to \\psi in regular prose outside math blocks (default: false)"
+  }
+}