structurecc 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 James Weatherhead
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+<h1 align="center">STRUCTUREIT</h1>
+
+<p align="center">
+<strong>Agentic Document Extraction for Claude Code</strong><br>
+<em>One command. Every figure. Every table.</em>
+</p>
+
+<p align="center">
+<a href="https://www.npmjs.com/package/structurecc"><img src="https://img.shields.io/npm/v/structurecc.svg" alt="npm version"></a>
+<a href="https://github.com/JamesWeatherhead/structurecc/stargazers"><img src="https://img.shields.io/github/stars/JamesWeatherhead/structurecc" alt="GitHub stars"></a>
+<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+<em>Unstructured in. Structured out.</em>
+</p>
+
+---
+
+## The Problem
+
+You have a PDF with figures, tables, and charts. You need that data.
+
+**Manual approach:** Screenshot each figure. Copy tables cell by cell. Spend hours on one document.
+
+**structurecc:**
+```
+/structure paper.pdf
+```
+
+Done.
+
+---
+
+## What It Does
+
+```
+PDF  ───▶  [Agent 1]  ───┐
+           [Agent 2]  ───┤
+           [Agent 3]  ───┼───▶  STRUCTURED.md
+           [Agent N]  ───┘
+```
+
+1. **Extracts** every image from your document
+2. **Spawns** one AI agent per image (running in parallel)
+3. **Analyzes** each element exhaustively
+4. **Outputs** clean, structured markdown
+
+Like [Landing AI's Agentic Document Extraction](https://landing.ai/agentic-document-extraction), but running locally via Claude Code.
+
+---
+
+## Install
+
+```bash
+npx structurecc
+```
+
+## Use
+
+In Claude Code:
+
+```
+/structure path/to/document.pdf
+```
+
+Works with: **PDF, DOCX, PNG, JPG**
+
+---
+
+## What You Get
+
+```
+document_extracted/
+├── images/           # All extracted visuals
+├── elements/         # One markdown file per element
+│   ├── element_1.md  # Table fully extracted
+│   ├── element_2.md  # Figure analyzed
+│   └── ...
+└── STRUCTURED.md     # Everything combined
+```
+
+### Example: Table Extraction
+
+```markdown
+# Patient Demographics
+
+**Type:** Table
+**Source:** Page 3, clinical_trial.pdf
+
+## Content
+
+| Group | N | Age (mean±SD) | Male (%) |
+|-------|---|---------------|----------|
+| Treatment | 245 | 54.3±12.1 | 58.4 |
+| Placebo | 248 | 53.8±11.9 | 56.9 |
+| p-value | - | 0.67 | 0.73 |
+
+## Notes
+- * Missing data excluded
+```
+
+### Example: Figure Analysis
+
+```markdown
+# Kaplan-Meier Survival Curves
+
+**Type:** Figure
+**Source:** Page 7, clinical_trial.pdf
+
+## Content
+
+Survival curves comparing treatment (blue) vs placebo (red) over 24 months.
+
+- 12-month survival: Treatment 0.89, Placebo 0.78
+- 24-month survival: Treatment 0.76, Placebo 0.61
+- Log-rank p = 0.003
+
+## Labels & Text
+- "Survival Probability"
+- "Time (months)"
+- "Treatment (n=245)"
+- "Placebo (n=248)"
+```
+
+---
+
+## How It Works
+
+1. **Extract** - PyMuPDF pulls all images from PDF (or unzip DOCX media folder)
+2. **Swarm** - Launch N parallel agents, one per image
+3. **Analyze** - Each agent reads its image, extracts everything, writes markdown
+4. **Combine** - Merge all element files into STRUCTURED.md
+
+Agents run simultaneously. 10 images = 10 agents = fast.
+
+---
+
+## Cost
+
+Depends on document complexity:
+
+| Document | Elements | ~Cost |
+|----------|----------|-------|
+| Simple paper | 5-10 | $0.50-$1 |
+| Full paper | 15-25 | $2-$4 |
+| Dense report | 40+ | $5-$10 |
+
+Uses Claude's multimodal vision. Works best with **Opus 4.5**.
+
+---
+
+## Requirements
+
+- Node.js
+- Claude Code (`npm install -g @anthropic-ai/claude-code`)
+- Anthropic API key or Claude Pro/Max
+
+PyMuPDF installed automatically if needed.
+
+---
+
+## Uninstall
+
+```bash
+npx structurecc --uninstall
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+<strong>Stop copying tables by hand.</strong>
+</p>

package/agents/structureit-extractor.md

@@ -0,0 +1,70 @@
+---
+name: structureit-extractor
+description: Extract and analyze any visual element from documents
+---
+
+# Visual Element Extractor
+
+You are an expert at extracting structured data from document images.
+
+## Your Task
+
+Given an image from a document, you:
+
+1. **Identify** what type of visual this is
+2. **Extract** every piece of data and text visible
+3. **Structure** the output as clean markdown
+4. **Ground** your extraction to the source location
+
+## Visual Types You Handle
+
+- Tables (any format - simple, complex, merged cells)
+- Figures (scientific, photographs, illustrations)
+- Charts (bar, line, pie, scatter, area, box plots)
+- Heatmaps (color matrices, correlation plots, expression data)
+- Diagrams (flowcharts, architectures, schematics, networks)
+- Forms (fields, checkboxes, filled forms)
+- Mixed (images containing multiple element types)
+
+## Extraction Rules
+
+1. **Be exhaustive** - Extract EVERY visible data point, label, annotation
+2. **Be exact** - Copy text verbatim, preserve numbers precisely
+3. **Be structured** - Output clean markdown tables when appropriate
+4. **Be honest** - Mark unclear items with [?], note confidence levels
+5. **Be grounded** - Always cite source page/location
+
+## Output Format
+
+```markdown
+# [Descriptive Title Based on Content]
+
+**Type:** [table/figure/chart/heatmap/diagram/form/mixed]
+**Source:** Page [N], [document name]
+
+## Content
+
+[Primary extraction - tables as markdown tables, descriptions for figures,
+data points for charts, etc.]
+
+## Labels & Annotations
+
+[All text visible in the image, verbatim]
+
+## Notes
+
+[Extraction observations, confidence levels, anything unclear]
+```
+
+## Special Handling
+
+**For complex heatmaps:**
+- Extract all row/column labels
+- Describe the color scale
+- Identify patterns and notable regions
+- Sample representative values if matrix is very large
+
+**For multi-panel figures:**
+- Label each panel (A, B, C, etc.)
+- Extract each panel's content separately
+- Note relationships between panels

package/bin/install.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const VERSION = '1.0.0';
+const PACKAGE_NAME = 'structurecc';
+
+// Colors
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+  white: '\x1b[37m'
+};
+
+function log(msg, color = '') {
+  console.log(`${color}${msg}${colors.reset}`);
+}
+
+function banner() {
+  console.log(`
+${colors.cyan}
+    ╔══════════════════════════════════════════════════════════════════════════════╗
+    ║                                                                              ║
+    ║  ███████╗████████╗██████╗ ██╗   ██╗ ██████╗████████╗██╗   ██╗██████╗ ███████╗║
+    ║  ██╔════╝╚══██╔══╝██╔══██╗██║   ██║██╔════╝╚══██╔══╝██║   ██║██╔══██╗██╔════╝║
+    ║  ███████╗   ██║   ██████╔╝██║   ██║██║        ██║   ██║   ██║██████╔╝█████╗  ║
+    ║  ╚════██║   ██║   ██╔══██╗██║   ██║██║        ██║   ██║   ██║██╔══██╗██╔══╝  ║
+    ║  ███████║   ██║   ██║  ██║╚██████╔╝╚██████╗   ██║   ╚██████╔╝██║  ██║███████╗║
+    ║  ╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝  ╚═════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝╚══════╝║
+    ║                                                                              ║
+    ║  ${colors.reset}${colors.bright}Agentic Document Extraction${colors.reset}${colors.cyan}                                            ║
+    ║  ${colors.reset}${colors.dim}One command. Every figure. Every table.${colors.reset}${colors.cyan}                                  ║
+    ║                                                                              ║
+    ╠══════════════════════════════════════════════════════════════════════════════╣
+    ║                                                                              ║
+    ║  ${colors.reset}${colors.yellow}PDF${colors.cyan}  ───▶  ${colors.green}[Agent 1]${colors.cyan}  ───┐                                             ║
+    ║            ${colors.green}[Agent 2]${colors.cyan}  ───┤                                             ║
+    ║            ${colors.green}[Agent 3]${colors.cyan}  ───┼───▶  ${colors.magenta}STRUCTURED.md${colors.cyan}                         ║
+    ║            ${colors.green}[Agent N]${colors.cyan}  ───┘                                             ║
+    ║                                                                              ║
+    ║  ${colors.reset}${colors.white}Unstructured in. Structured out.${colors.reset}${colors.cyan}                                       ║
+    ║                                                                              ║
+    ╚══════════════════════════════════════════════════════════════════════════════╝
+${colors.reset}
+${colors.bright}structurecc${colors.reset} v${VERSION}
+`);
+}
+
+function getClaudeDir() {
+  return path.join(os.homedir(), '.claude');
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function copyDir(src, dest) {
+  ensureDir(dest);
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function install() {
+  const claudeDir = getClaudeDir();
+  const commandsDir = path.join(claudeDir, 'commands', 'structure');
+  const agentsDir = path.join(claudeDir, 'agents');
+
+  const packageDir = path.resolve(__dirname, '..');
+  const srcCommandsDir = path.join(packageDir, 'commands', 'structure');
+  const srcAgentsDir = path.join(packageDir, 'agents');
+
+  log('Installing structurecc...', colors.yellow);
+  log('');
+
+  // Install command
+  if (fs.existsSync(srcCommandsDir)) {
+    copyDir(srcCommandsDir, commandsDir);
+    log('  ✓ Installed /structure command', colors.green);
+  }
+
+  // Install agents
+  if (fs.existsSync(srcAgentsDir)) {
+    const agentFiles = fs.readdirSync(srcAgentsDir);
+    ensureDir(agentsDir);
+    for (const file of agentFiles) {
+      if (file.startsWith('structureit-')) {
+        fs.copyFileSync(
+          path.join(srcAgentsDir, file),
+          path.join(agentsDir, file)
+        );
+        log(`  ✓ Installed ${file.replace('.md', '')}`, colors.green);
+      }
+    }
+  }
+
+  log('');
+  log(`${colors.green}Done!${colors.reset}`);
+  log('');
+  log(`Run in Claude Code:`, colors.bright);
+  log(`  /structure path/to/document.pdf`, colors.cyan);
+  log('');
+  log(`${colors.dim}Supports: PDF, DOCX, PNG, JPG, TIFF${colors.reset}`);
+  log('');
+}
+
+function uninstall() {
+  const claudeDir = getClaudeDir();
+  const commandsDir = path.join(claudeDir, 'commands', 'structure');
+  const agentsDir = path.join(claudeDir, 'agents');
+
+  log('Uninstalling structurecc...', colors.yellow);
+
+  if (fs.existsSync(commandsDir)) {
+    fs.rmSync(commandsDir, { recursive: true });
+    log('  ✓ /structure command removed', colors.green);
+  }
+
+  if (fs.existsSync(agentsDir)) {
+    const agentFiles = fs.readdirSync(agentsDir);
+    for (const file of agentFiles) {
+      if (file.startsWith('structureit-')) {
+        fs.unlinkSync(path.join(agentsDir, file));
+        log(`  ✓ Removed ${file}`, colors.green);
+      }
+    }
+  }
+
+  log('');
+  log('Uninstall complete.', colors.green);
+  log('');
+}
+
+// Main
+const args = process.argv.slice(2);
+
+banner();
+
+if (args.includes('--uninstall') || args.includes('-u')) {
+  uninstall();
+} else if (args.includes('--help') || args.includes('-h')) {
+  log('Usage: npx structurecc [options]', colors.bright);
+  log('');
+  log('Options:', colors.bright);
+  log('  --help, -h       Show this help', colors.dim);
+  log('  --uninstall, -u  Remove from Claude Code', colors.dim);
+  log('');
+  log('After install, use in Claude Code:', colors.bright);
+  log('  /structure path/to/document.pdf', colors.cyan);
+  log('  /structure path/to/document.docx', colors.cyan);
+  log('');
+} else {
+  install();
+}

package/commands/structure/structure.md

@@ -0,0 +1,242 @@
+---
+name: structure
+description: Extract structured data from PDFs and Word docs using AI agent swarms
+arguments:
+  - name: path
+    description: Path to document (PDF, DOCX, or image)
+    required: true
+---
+
+# /structure - Agentic Document Extraction
+
+Turn complex documents into structured markdown using parallel AI subagents.
+
+## Overview
+
+1. Extract all images from the document
+2. Spawn ONE subagent PER IMAGE (all in parallel)
+3. Each agent analyzes its image and writes structured markdown
+4. Combine into final STRUCTURED.md
+
+## Step 1: Setup
+
+Create output directory next to the document:
+```
+<document_name>_extracted/
+├── images/           # Extracted visuals
+├── elements/         # Per-element markdown
+└── STRUCTURED.md     # Final output
+```
+
+## Step 2: Extract Images
+
+**For PDF files** - Use PyMuPDF:
+
+```python
+import fitz
+import os
+
+pdf_path = "<document_path>"
+output_dir = "<output_dir>"
+images_dir = os.path.join(output_dir, "images")
+os.makedirs(images_dir, exist_ok=True)
+
+doc = fitz.open(pdf_path)
+extracted = []
+
+for page_num in range(len(doc)):
+    page = doc[page_num]
+    for img_idx, img in enumerate(page.get_images()):
+        xref = img[0]
+        pix = fitz.Pixmap(doc, xref)
+        if pix.n - pix.alpha > 3:
+            pix = fitz.Pixmap(fitz.csRGB, pix)
+
+        img_name = f"p{page_num + 1}_img{img_idx + 1}.png"
+        pix.save(os.path.join(images_dir, img_name))
+        extracted.append({"path": os.path.join(images_dir, img_name), "page": page_num + 1, "name": img_name})
+        pix = None
+
+doc.close()
+print(f"Extracted {len(extracted)} images")
+```
+
+**For DOCX files** - Unzip and extract media:
+
+```python
+from zipfile import ZipFile
+import os
+
+docx_path = "<document_path>"
+output_dir = "<output_dir>"
+images_dir = os.path.join(output_dir, "images")
+os.makedirs(images_dir, exist_ok=True)
+
+extracted = []
+with ZipFile(docx_path, 'r') as z:
+    for f in z.namelist():
+        if f.startswith('word/media/'):
+            name = os.path.basename(f)
+            path = os.path.join(images_dir, name)
+            with z.open(f) as src, open(path, 'wb') as dst:
+                dst.write(src.read())
+            extracted.append({"path": path, "name": name})
+
+print(f"Extracted {len(extracted)} images")
+```
+
+**For standalone images** - Just process directly.
+
+Also extract main text:
+- PDF: `page.get_text()` for each page
+- DOCX: `textutil -convert txt "<path>" -stdout`
+
+## Step 3: Spawn Agent Swarm
+
+**CRITICAL:** Launch ALL agents in ONE message with MULTIPLE Task tool calls.
+
+For EACH extracted image:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Extract element [N]",
+  prompt: """
+You are extracting structured data from a document image.
+
+**Image:** <full_path_to_image>
+**Source:** Page <N> of <document_name>
+**Output:** Write to <output_dir>/elements/element_<N>.md
+
+## Instructions
+
+1. Read the image carefully
+2. Identify what it contains (table, figure, chart, heatmap, diagram, etc.)
+3. Extract ALL visible data - be exhaustive
+4. Structure as clean markdown
+
+## Output Format
+
+Write this to the output file:
+
+```markdown
+# [Descriptive Title]
+
+**Type:** [table/figure/chart/heatmap/diagram/other]
+**Source:** Page [N], [document name]
+
+## Content
+
+[For tables: markdown table with all data]
+[For figures: detailed description + all visible text/labels]
+[For charts: data points, axes, trends]
+[For heatmaps: labels, color scale, patterns]
+[For diagrams: components, relationships, flow]
+
+## Labels & Text
+
+[Every piece of text visible, verbatim]
+
+## Notes
+
+[Confidence level, unclear items marked with [?]]
+```
+
+Be thorough. Extract every data point.
+"""
+)
+```
+
+Launch 10 images = 10 Task calls in ONE message. They run in parallel.
+
+## Step 4: Extract Main Text
+
+Save document text to `elements/main_text.md`:
+
+```markdown
+# Main Document Text
+
+**Source:** [document name]
+
+---
+
+[Full text extracted from document, preserving structure]
+```
+
+## Step 5: Combine Results
+
+After all agents complete, read all `elements/*.md` files and create:
+
+**STRUCTURED.md:**
+
+```markdown
+# [Document Name] - Structured Extraction
+
+**Original:** [filename]
+**Extracted:** [date/time]
+**Elements:** [N] visual elements processed
+
+---
+
+## Main Text
+
+[Content from main_text.md]
+
+---
+
+## Visual Elements
+
+### Element 1
+[Content from element_1.md]
+
+### Element 2
+[Content from element_2.md]
+
+[... continue for all elements ...]
+
+---
+
+## Extraction Summary
+
+| # | Type | Source | Status |
+|---|------|--------|--------|
+| 1 | Table | Page 2 | ✓ |
+| 2 | Figure | Page 3 | ✓ |
+| ... | ... | ... | ... |
+```
+
+## Step 6: Display Results
+
+```
+╔═══════════════════════════════════════════════════════════╗
+║  EXTRACTION COMPLETE                                      ║
+╠═══════════════════════════════════════════════════════════╣
+║                                                           ║
+║  Document:  [name]                                        ║
+║  Output:    [path]_extracted/                             ║
+║                                                           ║
+║  Extracted: [N] visual elements                           ║
+║                                                           ║
+║  Files:                                                   ║
+║    images/         [N] extracted images                   ║
+║    elements/       [N] element markdown files             ║
+║    STRUCTURED.md   Combined output                        ║
+║                                                           ║
+╚═══════════════════════════════════════════════════════════╝
+```
+
+Then open: `open "<output_dir>/STRUCTURED.md"`
+
+## Dependencies
+
+Install PyMuPDF if not present:
+```bash
+pip3 install PyMuPDF --quiet
+```
+
+## Tips
+
+- Use opus model for best extraction quality on complex visuals
+- Each image = one agent = one API call
+- Agents run in parallel for speed
+- Check individual element files if one extraction looks wrong

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "structurecc",
+  "version": "1.0.0",
+  "description": "Agentic document extraction for Claude Code. One command. Every figure. Every table.",
+  "keywords": [
+    "document-extraction",
+    "pdf",
+    "structure",
+    "agentic",
+    "claude-code",
+    "llm",
+    "multimodal",
+    "tables",
+    "figures",
+    "markdown",
+    "ai-agents",
+    "ocr"
+  ],
+  "author": "James Weatherhead",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JamesWeatherhead/structurecc"
+  },
+  "homepage": "https://github.com/JamesWeatherhead/structurecc#readme",
+  "bin": {
+    "structurecc": "./bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "agents/"
+  ]
+}