structurecc 1.0.5 → 2.0.1

package/README.md

@@ -1,7 +1,7 @@
 <h1 align="center">STRUCTURE</h1>
 
 <p align="center">
-<strong>Landing AI charges $500/month for agentic document structuring.<br>This is free.</strong>
+<strong>Extract structured data from PDFs, Word docs, and images using Claude Code.</strong>
 </p>
 
 <p align="center">
@@ -13,76 +13,18 @@
 <img src="assets/terminal.png" alt="structurecc" width="550">
 </p>
 
-<p align="center">
-<em>Works on Mac, Windows, and Linux</em>
-</p>
-
----
-
-## The Problem
-
-You have a 50-page PDF with figures, tables, and charts. You need that data.
-
-**Manual approach:** Screenshot each figure. Transcribe tables cell by cell. Spend hours on one document.
-
-**With structurecc:** One command. Walk away. Come back to perfectly structured markdown.
-
-```
-/structure paper.pdf
-```
-
-Spawns parallel AI agents. Each agent analyzes one visual element. All run simultaneously. Done in minutes, not hours.
-
----
-
-## What is this?
-
-Give it a document. It extracts every image. Spawns one AI agent per image. Each agent exhaustively analyzes its element—tables become markdown tables, figures get descriptions, charts get data points extracted.
-
-Runs inside **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** (Anthropic's terminal assistant). One command. ~$0.50-$5 per document.
-
-Like [Landing AI's Agentic Document Extraction](https://landing.ai/agentic-document-extraction), but running locally via Claude Code.
-
----
-
-## Before You Start
-
-You need two things:
-
-### 1. Node.js
-
-Check if you have it:
-
-```bash
-node --version
-```
-
-If you see a version number, you're good. If you see "command not found", download Node.js from **[nodejs.org](https://nodejs.org/)** and install it.
-
-### 2. Anthropic API Key or Pro/Max Plan
-
-You need one of these to use Claude Code:
-
-- **API key:** Get one at **[console.anthropic.com](https://console.anthropic.com/)**. Requires a payment method.
-- **Pro or Max plan:** If you subscribe to Claude Pro ($20/mo) or Max ($100/mo), you can use Claude Code without a separate API key.
-
 ---
 
-## Setup (5 minutes)
-
-### Step 1: Open your terminal
+## Requirements
 
-**Mac:** Press `Cmd + Space`, type `Terminal`, press Enter
-
-**Windows:** Press `Win + X`, click "Terminal" or "PowerShell"
-
-**Linux:** Press `Ctrl + Alt + T`
+- **Node.js** - [nodejs.org](https://nodejs.org/)
+- **Claude Code** - Requires API key or Pro/Max subscription
 
 ---
 
-### Step 2: Install Claude Code
+## Install
 
-Copy this command and paste it into your terminal:
+### Step 1: Install Claude Code
 
 ```bash
 npm install -g @anthropic-ai/claude-code
@@ -92,13 +34,7 @@ npm install -g @anthropic-ai/claude-code
 <img src="assets/screenshots/step0.png" alt="Install Claude Code" width="550">
 </p>
 
-Wait for it to finish.
-
----
-
-### Step 3: Install structurecc
-
-Copy and run this:
+### Step 2: Install structurecc
 
 ```bash
 npx structurecc
@@ -108,34 +44,9 @@ npx structurecc
 <img src="assets/screenshots/step1.png" alt="Install structurecc" width="420">
 </p>
 
-You will see a STRUCTURE banner. That means it worked. You only do this once.
-
----
-
-### Step 4: Set up your document folder
+### Step 3: Start Claude Code
 
-Create a folder with your document:
-
-<p align="center">
-<img src="assets/screenshots/step2.png" alt="Folder structure" width="380">
-</p>
-
-```
-documents/
-├── document.pdf          ← your PDF, DOCX, or image
-└── images/               ← extracted images go here (created automatically)
-    ├── figure_1.png
-    ├── table_2.png
-    └── chart_3.png
-```
-
-**Put your document in a folder. That's it.**
-
----
-
-### Step 5: Open Claude Code
-
-Navigate to your document folder and start Claude Code:
+Navigate to your document folder and run:
 
 ```bash
 cd ~/Desktop/documents
@@ -146,131 +57,40 @@ claude
 <img src="assets/screenshots/step3a.png" alt="Start Claude Code" width="460">
 </p>
 
-**Windows users:** Replace `~/Desktop/documents` with your actual path, like `C:\Users\YourName\Desktop\documents`
-
-The first time you run `claude`, it will ask for your API key. Paste it in.
+### Step 4: Run structure
 
----
-
-### Step 6: Run structure
-
-Now you are inside Claude Code. Type this command:
+Inside Claude Code:
 
 ```
 /structure document.pdf
 ```
 
 <p align="center">
-<img src="assets/screenshots/step3.png" alt="Run /structure" width="500">
+<img src="assets/screenshots/step3.png" alt="Run /structure" width="520">
 </p>
 
-**Important:** The `/structure` command only works inside Claude Code. If you type it in your regular terminal, it will not work.
-
-structurecc will:
-1. Extract every image from your document
-2. Spawn one agent per image (all running in parallel)
-3. Each agent exhaustively analyzes its visual element
-4. Combine everything into `STRUCTURED.md`
+Supports **PDF**, **DOCX**, **PNG**, **JPG**, and **TIFF**.
 
 ---
 
-## What You Get
-
-A comprehensive markdown file with every visual element extracted:
+## Output
 
 ```
 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
-- Confidence level: High
-- * Missing data excluded from analysis
+├── images/              # Extracted visuals
+├── elements/            # Markdown per element
+└── STRUCTURED.md        # Combined output
 ```
 
-### Example: Chart Analysis
-
-```markdown
-# Kaplan-Meier Survival Curves
-
-**Type:** Chart (Line/Survival)
-**Source:** Page 7, clinical_trial.pdf
-
-## Content
-
-Survival curves comparing treatment (blue) vs placebo (red) over 24 months.
-
-Key data points:
-- 12-month survival: Treatment 0.89, Placebo 0.78
-- 24-month survival: Treatment 0.76, Placebo 0.61
-- Log-rank p = 0.003
-
-## Labels & Annotations
-- Y-axis: "Survival Probability"
-- X-axis: "Time (months)"
-- Legend: "Treatment (n=245)", "Placebo (n=248)"
-```
-
----
-
-## Cost
-
-| 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** for complex tables and charts.
-
----
-
-## Supported Formats
-
-- **PDF** - Extracts embedded images via PyMuPDF
-- **DOCX** - Extracts images from Word's media folder
-- **PNG/JPG/TIFF** - Analyzes images directly
-
 ---
 
 ## Troubleshooting
 
-**"npm: command not found"**
-
-You need Node.js. Download it from [nodejs.org](https://nodejs.org/).
-
-**"bash: /structure: No such file or directory"**
-
-You typed `/structure` in your regular terminal. You need to type it inside Claude Code. First run `claude` to start Claude Code, then type `/structure`.
-
-**"No images found"**
-
-Make sure your PDF contains actual images, not just text. Some PDFs render everything as text.
-
-**Claude Code asks for an API key**
-
-Either get an API key at [console.anthropic.com](https://console.anthropic.com/), or subscribe to Claude Pro/Max at [claude.ai](https://claude.ai/).
+| Issue | Solution |
+|-------|----------|
+| `npm: command not found` | Install Node.js from [nodejs.org](https://nodejs.org/) |
+| `/structure: No such file` | Run `claude` first, then type `/structure` inside Claude Code |
+| No images found | PDF may be text-only with no embedded images |
 
 ---
 
@@ -285,9 +105,3 @@ npx structurecc --uninstall
 ## License
 
 MIT
-
----
-
-<p align="center">
-<strong>Unstructured in. Structured out.</strong>
-</p>

package/agents/structurecc-classifier.md

@@ -0,0 +1,135 @@
+---
+name: structurecc-classifier
+description: Phase 1 - Classify visual elements for specialized extraction
+---
+
+# Visual Element Classifier
+
+You are a rapid visual classifier. Your ONLY job is to identify what type of visual element an image contains so the correct specialized extractor can be dispatched.
+
+## Classification Task
+
+Given an image, output a JSON classification. Nothing else.
+
+## Classification Types
+
+| Type | Description |
+|------|-------------|
+| `table_simple` | Standard grid table with clear rows/columns, no merged cells |
+| `table_complex` | Table with merged cells, nested headers, or irregular structure |
+| `chart_kaplan_meier` | Survival curves / time-to-event plots with step functions |
+| `chart_bar` | Bar charts (horizontal or vertical), grouped or stacked |
+| `chart_line` | Line graphs showing trends over continuous x-axis |
+| `chart_scatter` | Scatter plots with individual data points |
+| `chart_box` | Box plots / whisker plots showing distributions |
+| `chart_pie` | Pie charts or donut charts |
+| `chart_area` | Area charts (filled line charts) |
+| `chart_forest` | Forest plots (meta-analysis results) |
+| `chart_volcano` | Volcano plots (differential expression) |
+| `heatmap` | Color-coded matrix (correlation, expression, etc.) |
+| `diagram_flowchart` | Process flows with boxes and arrows |
+| `diagram_timeline` | Temporal sequences, study timelines, CONSORT diagrams |
+| `diagram_network` | Network graphs, pathway diagrams, interaction maps |
+| `diagram_schematic` | Technical schematics, anatomical diagrams |
+| `diagram_venn` | Venn diagrams showing set overlaps |
+| `multi_panel` | Composite figure with labeled panels (A, B, C, D) |
+| `photograph` | Real-world photographs, microscopy images, scans |
+| `equation` | Mathematical equations, formulas |
+| `text_block` | Text-heavy image, caption, or label |
+| `unknown` | Cannot confidently classify |
+
+## Output Format
+
+Return ONLY valid JSON:
+
+```json
+{
+  "classification": {
+    "primary_type": "chart_kaplan_meier",
+    "confidence": 0.95,
+    "secondary_type": null,
+    "is_multi_panel": false,
+    "panel_count": 1,
+    "contains_table": false,
+    "contains_text_annotations": true
+  },
+  "routing": {
+    "extractor": "structurecc-extract-chart",
+    "extraction_hints": ["survival_curve", "two_groups", "has_risk_table"]
+  }
+}
+```
+
+## Field Definitions
+
+### classification
+- `primary_type`: Main visual type from the table above
+- `confidence`: 0.0-1.0 confidence in classification
+- `secondary_type`: If image contains a secondary element (e.g., chart with embedded table)
+- `is_multi_panel`: True if figure has labeled sub-panels (A, B, C...)
+- `panel_count`: Number of panels if multi-panel
+- `contains_table`: True if any tabular data is present
+- `contains_text_annotations`: True if significant text labels/annotations present
+
+### routing
+- `extractor`: Which specialized extractor to use
+- `extraction_hints`: List of specific features to watch for
+
+## Extractor Routing
+
+| Primary Type | Extractor |
+|--------------|-----------|
+| `table_simple`, `table_complex` | `structurecc-extract-table` |
+| `chart_*` | `structurecc-extract-chart` |
+| `heatmap` | `structurecc-extract-heatmap` |
+| `diagram_*` | `structurecc-extract-diagram` |
+| `multi_panel` | `structurecc-extract-multipanel` |
+| `photograph`, `equation`, `text_block`, `unknown` | `structurecc-extract-generic` |
+
+## Rules
+
+1. **Be fast** - This is a triage step, not deep analysis
+2. **Be decisive** - Pick the best match, use confidence to express uncertainty
+3. **Detect multi-panel** - If you see A, B, C, D labels, set `is_multi_panel: true`
+4. **Note secondary elements** - Charts often have risk tables, legends, etc.
+5. **Output ONLY JSON** - No explanations, no markdown, just the JSON object
+
+## Examples
+
+**Kaplan-Meier curve with risk table below:**
+```json
+{
+  "classification": {
+    "primary_type": "chart_kaplan_meier",
+    "confidence": 0.98,
+    "secondary_type": "table_simple",
+    "is_multi_panel": false,
+    "panel_count": 1,
+    "contains_table": true,
+    "contains_text_annotations": true
+  },
+  "routing": {
+    "extractor": "structurecc-extract-chart",
+    "extraction_hints": ["survival_curve", "has_risk_table", "has_confidence_intervals"]
+  }
+}
+```
+
+**Four-panel figure with A=bar chart, B=heatmap, C=box plot, D=table:**
+```json
+{
+  "classification": {
+    "primary_type": "multi_panel",
+    "confidence": 0.99,
+    "secondary_type": null,
+    "is_multi_panel": true,
+    "panel_count": 4,
+    "contains_table": true,
+    "contains_text_annotations": true
+  },
+  "routing": {
+    "extractor": "structurecc-extract-multipanel",
+    "extraction_hints": ["panel_A_bar", "panel_B_heatmap", "panel_C_boxplot", "panel_D_table"]
+  }
+}
+```