# TikZ Extractor CLI
A Python package for extracting TikZ picture environments from codebases and generating AI context files. This tool recursively scans directories, extracts TikZ blocks from various file types, saves them as individual `.tex` files, and creates a consolidated context file for AI model consumption.
## Features
- 🔍 **Recursive Directory Scanning**: Automatically finds TikZ blocks in specified file types
- 📄 **Multiple File Format Support**: Works with `.tex`, `.md`, `.py`, and other text files
- 🎯 **Smart Extraction**: Uses robust regex patterns to extract complete TikZ picture environments
- 📁 **Organized Output**: Saves each TikZ block as a separate `.tex` file with descriptive names
- 🤖 **AI Context Generation**: Creates a consolidated file with all extracted blocks for LLM consumption
- 🖥️ **CLI Interface**: Easy-to-use command-line interface with flexible options
- 📦 **Python Module**: Importable package for programmatic usage
- 🔧 **Dry Run Mode**: Preview extraction results without writing files
- 📝 **Verbose Logging**: Detailed processing information when needed
## Installation
### Using pip
```bash
pip install tikz-extractor
```
### Using Poetry
```bash
poetry add tikz-extractor
```
### Development Installation
```bash
git clone https://github.com/vaibhavblayer/tikz-extractor.git
cd tikz-extractor
poetry install --with dev
```
## Usage
### Command Line Interface
#### Basic Usage
Extract TikZ blocks from the current directory:
```bash
tikz-extract
```
#### Advanced Usage
```bash
# Specify source and output directories
tikz-extract --src ./documents --out ./extracted_tikz
# Process specific file types
tikz-extract --ext .tex,.md,.rst
# Generate custom AI context file
tikz-extract --ai-file my_tikz_context.txt
# Dry run to preview results
tikz-extract --dry-run --verbose
# Full example with all options
tikz-extract \
--src ./latex_project \
--out ./tikz_output \
--ext .tex,.md \
--ai-file tikz_for_ai.txt \
--verbose
```
#### CLI Parameters
| Parameter | Short | Default | Description |
|-----------|-------|---------|-------------|
| `--src` | `-s` | `.` | Source directory to scan recursively |
| `--out` | `-o` | `tikz` | Output directory for extracted `.tex` files |
| `--ext` | `-e` | `.tex,.md,.py` | Comma-separated list of file extensions to process |
| `--ai-file` | `-a` | `ai_context.txt` | Path for the AI context file |
| `--dry-run` | `-d` | `False` | Preview mode - show results without writing files |
| `--verbose` | `-v` | `False` | Enable detailed logging output |
| `--help` | `-h` | - | Show help message and exit |
### Python Module Interface
#### Basic Programmatic Usage
```python
from tikz_extractor import extractor
from pathlib import Path
# Extract TikZ blocks from a directory
src_dir = Path("./documents")
out_dir = Path("./extracted")
extensions = [".tex", ".md"]
metadata = extractor.extract_from_directory(src_dir, out_dir, extensions)
# Process the results
for block_info in metadata:
print(f"Extracted from: {block_info['source']}")
print(f"Saved to: {block_info['out_path']}")
print(f"Block index: {block_info['index']}")
```
#### Advanced Programmatic Usage
```python
from tikz_extractor.extractor import (
find_files,
extract_tikz_from_text,
write_extracted_blocks,
build_ai_context
)
from pathlib import Path
# Step-by-step extraction process
src_dir = Path("./my_project")
out_dir = Path("./tikz_blocks")
extensions = [".tex", ".md"]
# 1. Find all relevant files
files = find_files(src_dir, extensions)
print(f"Found {len(files)} files to process")
# 2. Process each file
all_metadata = []
for file_path in files:
try:
content = file_path.read_text(encoding='utf-8')
tikz_blocks = extract_tikz_from_text(content)
if tikz_blocks:
metadata = write_extracted_blocks(tikz_blocks, file_path, out_dir)
all_metadata.extend(metadata)
print(f"Extracted {len(tikz_blocks)} blocks from {file_path}")
except Exception as e:
print(f"Error processing {file_path}: {e}")
# 3. Generate AI context file
if all_metadata:
ai_file = Path("tikz_context.txt")
build_ai_context(all_metadata, ai_file)
print(f"AI context file created: {ai_file}")
```
#### Individual Function Usage
```python
from tikz_extractor.extractor import extract_tikz_from_text, sanitize_name
from pathlib import Path
# Extract TikZ blocks from text content
latex_content = """
Some text here...
\\begin{tikzpicture}
\\draw (0,0) -- (1,1);
\\end{tikzpicture}
More content...
"""
blocks = extract_tikz_from_text(latex_content)
print(f"Found {len(blocks)} TikZ blocks")
# Generate safe filenames
path = Path("src/diagrams/flow_chart.tex")
safe_name = sanitize_name(path)
print(f"Safe filename: {safe_name}") # Output: src__diagrams__flow_chart.tex
```
## Output Format
### Extracted Files
Each TikZ block is saved as a separate `.tex` file with the naming pattern:
```
{sanitized_source_path}__tikz{index}.tex
```
**Examples:**
- `src/diagrams/network.tex` → `src__diagrams__network.tex__tikz1.tex`
- `docs/README.md` → `docs__README.md__tikz1.tex`
### AI Context File
The AI context file contains all extracted TikZ blocks with structured headers:
```
### Source: src/diagrams/network.tex
### Snippet: src__diagrams__network.tex__tikz1.tex
\begin{tikzpicture}
\node (A) at (0,0) {Start};
\node (B) at (2,0) {End};
\draw[->] (A) -- (B);
\end{tikzpicture}
---
### Source: docs/README.md
### Snippet: docs__README.md__tikz1.tex
\begin{tikzpicture}
\draw (0,0) circle (1);
\end{tikzpicture}
---
```
## Examples
### Example 1: LaTeX Project
```bash
# Extract from a LaTeX thesis project
tikz-extract \
--src ./thesis \
--out ./thesis_tikz \
--ext .tex \
--ai-file thesis_diagrams.txt \
--verbose
```
### Example 2: Documentation with Embedded TikZ
```bash
# Process Markdown documentation with TikZ diagrams
tikz-extract \
--src ./docs \
--ext .md,.rst \
--out ./doc_diagrams \
--ai-file documentation_tikz.txt
```
### Example 3: Mixed Codebase
```bash
# Extract from various file types in a research project
tikz-extract \
--src ./research_project \
--ext .tex,.md,.py,.txt \
--out ./all_tikz \
--dry-run # Preview first
```
## API Reference
### Core Functions
#### `extract_from_directory(src: Path, out_dir: Path, exts: List[str]) -> List[Dict]`
Orchestrates the complete TikZ extraction workflow.
**Parameters:**
- `src`: Source directory to scan
- `out_dir`: Output directory for extracted files
- `exts`: List of file extensions to process
**Returns:** List of metadata dictionaries for each extracted block
#### `find_files(src: Path, exts: List[str]) -> List[Path]`
Recursively finds files with specified extensions.
**Parameters:**
- `src`: Directory to search
- `exts`: List of file extensions (with or without leading dots)
**Returns:** List of Path objects for matching files
#### `extract_tikz_from_text(text: str) -> List[str]`
Extracts TikZ picture environments from text content.
**Parameters:**
- `text`: Text content to search
**Returns:** List of complete TikZ block strings
#### `write_extracted_blocks(blocks: List[str], src_path: Path, out_dir: Path) -> List[Dict]`
Writes TikZ blocks to individual files and generates metadata.
**Parameters:**
- `blocks`: List of TikZ block strings
- `src_path`: Original source file path
- `out_dir`: Output directory
**Returns:** List of metadata dictionaries
#### `build_ai_context(metadata: List[Dict], ai_file: Path) -> None`
Creates an AI context file with all extracted blocks.
**Parameters:**
- `metadata`: List of block metadata
- `ai_file`: Path for the output context file
## Error Handling
The tool is designed to be robust and continue processing even when encountering issues:
- **Unreadable files**: Skipped with optional logging
- **Encoding issues**: Attempts UTF-8, skips on failure
- **Permission errors**: Skipped with warning messages
- **Missing directories**: Output directories are created automatically
- **Malformed TikZ blocks**: Extracts what's parseable
- **Empty results**: Informative message, graceful exit
## Development
### Setting up Development Environment
```bash
git clone https://github.com/vaibhavblayer/tikz-extractor.git
cd tikz-extractor
poetry install --with dev
```
### Running Tests
```bash
# Run all tests
poetry run pytest
# Run with coverage
poetry run pytest --cov=tikz_extractor
# Run specific test file
poetry run pytest tests/test_extractor.py -v
```
### Code Quality
```bash
# Format code
poetry run black tikz_extractor tests
# Sort imports
poetry run isort tikz_extractor tests
# Lint code
poetry run flake8 tikz_extractor tests
# Type checking
poetry run mypy tikz_extractor
```
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history and changes.
## Support
- **Issues**: [GitHub Issues](https://github.com/vaibhavblayer/tikz-extractor/issues)
- **Discussions**: [GitHub Discussions](https://github.com/vaibhavblayer/tikz-extractor/discussions)
## Related Projects
- [TikZ](https://tikz.dev/) - The original TikZ package for LaTeX
- [LaTeX](https://www.latex-project.org/) - Document preparation system
- [Click](https://click.palletsprojects.com/) - Python CLI framework used by this project
Raw data
{
"_id": null,
"home_page": "https://github.com/vaibhavblayer/tikz-extractor",
"name": "tikz-extractor",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "tikz, latex, extraction, cli, ai-context, tex, tikzpicture",
"author": "vaibhavblayer",
"author_email": "vaibhavblayer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c5/66/1e05d37d4408b77b39e0269b9a1705c999157cf9ca41f3f44bca6caf1332/tikz_extractor-0.2.5.tar.gz",
"platform": null,
"description": "# TikZ Extractor CLI\n\nA Python package for extracting TikZ picture environments from codebases and generating AI context files. This tool recursively scans directories, extracts TikZ blocks from various file types, saves them as individual `.tex` files, and creates a consolidated context file for AI model consumption.\n\n## Features\n\n- \ud83d\udd0d **Recursive Directory Scanning**: Automatically finds TikZ blocks in specified file types\n- \ud83d\udcc4 **Multiple File Format Support**: Works with `.tex`, `.md`, `.py`, and other text files\n- \ud83c\udfaf **Smart Extraction**: Uses robust regex patterns to extract complete TikZ picture environments\n- \ud83d\udcc1 **Organized Output**: Saves each TikZ block as a separate `.tex` file with descriptive names\n- \ud83e\udd16 **AI Context Generation**: Creates a consolidated file with all extracted blocks for LLM consumption\n- \ud83d\udda5\ufe0f **CLI Interface**: Easy-to-use command-line interface with flexible options\n- \ud83d\udce6 **Python Module**: Importable package for programmatic usage\n- \ud83d\udd27 **Dry Run Mode**: Preview extraction results without writing files\n- \ud83d\udcdd **Verbose Logging**: Detailed processing information when needed\n\n## Installation\n\n### Using pip\n\n```bash\npip install tikz-extractor\n```\n\n### Using Poetry\n\n```bash\npoetry add tikz-extractor\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/vaibhavblayer/tikz-extractor.git\ncd tikz-extractor\npoetry install --with dev\n```\n\n## Usage\n\n### Command Line Interface\n\n#### Basic Usage\n\nExtract TikZ blocks from the current directory:\n\n```bash\ntikz-extract\n```\n\n#### Advanced Usage\n\n```bash\n# Specify source and output directories\ntikz-extract --src ./documents --out ./extracted_tikz\n\n# Process specific file types\ntikz-extract --ext .tex,.md,.rst\n\n# Generate custom AI context file\ntikz-extract --ai-file my_tikz_context.txt\n\n# Dry run to preview results\ntikz-extract --dry-run --verbose\n\n# Full example with all options\ntikz-extract \\\n --src ./latex_project \\\n --out ./tikz_output \\\n --ext .tex,.md \\\n --ai-file tikz_for_ai.txt \\\n --verbose\n```\n\n#### CLI Parameters\n\n| Parameter | Short | Default | Description |\n|-----------|-------|---------|-------------|\n| `--src` | `-s` | `.` | Source directory to scan recursively |\n| `--out` | `-o` | `tikz` | Output directory for extracted `.tex` files |\n| `--ext` | `-e` | `.tex,.md,.py` | Comma-separated list of file extensions to process |\n| `--ai-file` | `-a` | `ai_context.txt` | Path for the AI context file |\n| `--dry-run` | `-d` | `False` | Preview mode - show results without writing files |\n| `--verbose` | `-v` | `False` | Enable detailed logging output |\n| `--help` | `-h` | - | Show help message and exit |\n\n### Python Module Interface\n\n#### Basic Programmatic Usage\n\n```python\nfrom tikz_extractor import extractor\nfrom pathlib import Path\n\n# Extract TikZ blocks from a directory\nsrc_dir = Path(\"./documents\")\nout_dir = Path(\"./extracted\")\nextensions = [\".tex\", \".md\"]\n\nmetadata = extractor.extract_from_directory(src_dir, out_dir, extensions)\n\n# Process the results\nfor block_info in metadata:\n print(f\"Extracted from: {block_info['source']}\")\n print(f\"Saved to: {block_info['out_path']}\")\n print(f\"Block index: {block_info['index']}\")\n```\n\n#### Advanced Programmatic Usage\n\n```python\nfrom tikz_extractor.extractor import (\n find_files,\n extract_tikz_from_text,\n write_extracted_blocks,\n build_ai_context\n)\nfrom pathlib import Path\n\n# Step-by-step extraction process\nsrc_dir = Path(\"./my_project\")\nout_dir = Path(\"./tikz_blocks\")\nextensions = [\".tex\", \".md\"]\n\n# 1. Find all relevant files\nfiles = find_files(src_dir, extensions)\nprint(f\"Found {len(files)} files to process\")\n\n# 2. Process each file\nall_metadata = []\nfor file_path in files:\n try:\n content = file_path.read_text(encoding='utf-8')\n tikz_blocks = extract_tikz_from_text(content)\n \n if tikz_blocks:\n metadata = write_extracted_blocks(tikz_blocks, file_path, out_dir)\n all_metadata.extend(metadata)\n print(f\"Extracted {len(tikz_blocks)} blocks from {file_path}\")\n except Exception as e:\n print(f\"Error processing {file_path}: {e}\")\n\n# 3. Generate AI context file\nif all_metadata:\n ai_file = Path(\"tikz_context.txt\")\n build_ai_context(all_metadata, ai_file)\n print(f\"AI context file created: {ai_file}\")\n```\n\n#### Individual Function Usage\n\n```python\nfrom tikz_extractor.extractor import extract_tikz_from_text, sanitize_name\nfrom pathlib import Path\n\n# Extract TikZ blocks from text content\nlatex_content = \"\"\"\nSome text here...\n\\\\begin{tikzpicture}\n\\\\draw (0,0) -- (1,1);\n\\\\end{tikzpicture}\nMore content...\n\"\"\"\n\nblocks = extract_tikz_from_text(latex_content)\nprint(f\"Found {len(blocks)} TikZ blocks\")\n\n# Generate safe filenames\npath = Path(\"src/diagrams/flow_chart.tex\")\nsafe_name = sanitize_name(path)\nprint(f\"Safe filename: {safe_name}\") # Output: src__diagrams__flow_chart.tex\n```\n\n## Output Format\n\n### Extracted Files\n\nEach TikZ block is saved as a separate `.tex` file with the naming pattern:\n```\n{sanitized_source_path}__tikz{index}.tex\n```\n\n**Examples:**\n- `src/diagrams/network.tex` \u2192 `src__diagrams__network.tex__tikz1.tex`\n- `docs/README.md` \u2192 `docs__README.md__tikz1.tex`\n\n### AI Context File\n\nThe AI context file contains all extracted TikZ blocks with structured headers:\n\n```\n### Source: src/diagrams/network.tex\n### Snippet: src__diagrams__network.tex__tikz1.tex\n\\begin{tikzpicture}\n\\node (A) at (0,0) {Start};\n\\node (B) at (2,0) {End};\n\\draw[->] (A) -- (B);\n\\end{tikzpicture}\n\n---\n\n### Source: docs/README.md\n### Snippet: docs__README.md__tikz1.tex\n\\begin{tikzpicture}\n\\draw (0,0) circle (1);\n\\end{tikzpicture}\n\n---\n```\n\n## Examples\n\n### Example 1: LaTeX Project\n\n```bash\n# Extract from a LaTeX thesis project\ntikz-extract \\\n --src ./thesis \\\n --out ./thesis_tikz \\\n --ext .tex \\\n --ai-file thesis_diagrams.txt \\\n --verbose\n```\n\n### Example 2: Documentation with Embedded TikZ\n\n```bash\n# Process Markdown documentation with TikZ diagrams\ntikz-extract \\\n --src ./docs \\\n --ext .md,.rst \\\n --out ./doc_diagrams \\\n --ai-file documentation_tikz.txt\n```\n\n### Example 3: Mixed Codebase\n\n```bash\n# Extract from various file types in a research project\ntikz-extract \\\n --src ./research_project \\\n --ext .tex,.md,.py,.txt \\\n --out ./all_tikz \\\n --dry-run # Preview first\n```\n\n## API Reference\n\n### Core Functions\n\n#### `extract_from_directory(src: Path, out_dir: Path, exts: List[str]) -> List[Dict]`\n\nOrchestrates the complete TikZ extraction workflow.\n\n**Parameters:**\n- `src`: Source directory to scan\n- `out_dir`: Output directory for extracted files\n- `exts`: List of file extensions to process\n\n**Returns:** List of metadata dictionaries for each extracted block\n\n#### `find_files(src: Path, exts: List[str]) -> List[Path]`\n\nRecursively finds files with specified extensions.\n\n**Parameters:**\n- `src`: Directory to search\n- `exts`: List of file extensions (with or without leading dots)\n\n**Returns:** List of Path objects for matching files\n\n#### `extract_tikz_from_text(text: str) -> List[str]`\n\nExtracts TikZ picture environments from text content.\n\n**Parameters:**\n- `text`: Text content to search\n\n**Returns:** List of complete TikZ block strings\n\n#### `write_extracted_blocks(blocks: List[str], src_path: Path, out_dir: Path) -> List[Dict]`\n\nWrites TikZ blocks to individual files and generates metadata.\n\n**Parameters:**\n- `blocks`: List of TikZ block strings\n- `src_path`: Original source file path\n- `out_dir`: Output directory\n\n**Returns:** List of metadata dictionaries\n\n#### `build_ai_context(metadata: List[Dict], ai_file: Path) -> None`\n\nCreates an AI context file with all extracted blocks.\n\n**Parameters:**\n- `metadata`: List of block metadata\n- `ai_file`: Path for the output context file\n\n## Error Handling\n\nThe tool is designed to be robust and continue processing even when encountering issues:\n\n- **Unreadable files**: Skipped with optional logging\n- **Encoding issues**: Attempts UTF-8, skips on failure\n- **Permission errors**: Skipped with warning messages\n- **Missing directories**: Output directories are created automatically\n- **Malformed TikZ blocks**: Extracts what's parseable\n- **Empty results**: Informative message, graceful exit\n\n## Development\n\n### Setting up Development Environment\n\n```bash\ngit clone https://github.com/vaibhavblayer/tikz-extractor.git\ncd tikz-extractor\npoetry install --with dev\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npoetry run pytest\n\n# Run with coverage\npoetry run pytest --cov=tikz_extractor\n\n# Run specific test file\npoetry run pytest tests/test_extractor.py -v\n```\n\n### Code Quality\n\n```bash\n# Format code\npoetry run black tikz_extractor tests\n\n# Sort imports\npoetry run isort tikz_extractor tests\n\n# Lint code\npoetry run flake8 tikz_extractor tests\n\n# Type checking\npoetry run mypy tikz_extractor\n```\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and changes.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/vaibhavblayer/tikz-extractor/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/vaibhavblayer/tikz-extractor/discussions)\n\n## Related Projects\n\n- [TikZ](https://tikz.dev/) - The original TikZ package for LaTeX\n- [LaTeX](https://www.latex-project.org/) - Document preparation system\n- [Click](https://click.palletsprojects.com/) - Python CLI framework used by this project",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for extracting TikZ picture environments from codebases and generating AI context files",
"version": "0.2.5",
"project_urls": {
"Documentation": "https://github.com/vaibhavblayer/tikz-extractor",
"Homepage": "https://github.com/vaibhavblayer/tikz-extractor",
"Repository": "https://github.com/vaibhavblayer/tikz-extractor"
},
"split_keywords": [
"tikz",
" latex",
" extraction",
" cli",
" ai-context",
" tex",
" tikzpicture"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "387dd3e295b3a703a90b34761c08624ad855261b3aa1916af581b6652aea5c8b",
"md5": "5c229d686ede9843948e03a4e020bb28",
"sha256": "18f18c8bca831fb4db4c480f2197c56b05efba218d21e75b81da104649ffa18f"
},
"downloads": -1,
"filename": "tikz_extractor-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5c229d686ede9843948e03a4e020bb28",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 16247,
"upload_time": "2025-10-26T12:06:02",
"upload_time_iso_8601": "2025-10-26T12:06:02.687680Z",
"url": "https://files.pythonhosted.org/packages/38/7d/d3e295b3a703a90b34761c08624ad855261b3aa1916af581b6652aea5c8b/tikz_extractor-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c5661e05d37d4408b77b39e0269b9a1705c999157cf9ca41f3f44bca6caf1332",
"md5": "f4d39549a4063384a9a45583ba95afe4",
"sha256": "93c55c458f1637255eb8affb0ca4af3ca6a7e80f3d13a6022e2be280b709c23a"
},
"downloads": -1,
"filename": "tikz_extractor-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "f4d39549a4063384a9a45583ba95afe4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 16267,
"upload_time": "2025-10-26T12:06:03",
"upload_time_iso_8601": "2025-10-26T12:06:03.935468Z",
"url": "https://files.pythonhosted.org/packages/c5/66/1e05d37d4408b77b39e0269b9a1705c999157cf9ca41f3f44bca6caf1332/tikz_extractor-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 12:06:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vaibhavblayer",
"github_project": "tikz-extractor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tikz-extractor"
}
JSON
