# Table Spec Extractor

> 【非推奨】spec-value-finder を使用してください。Excel/PDFの仕様書テーブルをTable TransformerでAST化しNeo4jグラフへ保存・GraphRAG検索するパイプライン（deprecated）。Neo4j・GPU依存が重く可搬性に欠けるため後継スキルへ移行。

- Skill: `ynitto/table-spec-extractor` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add ynitto/table-spec-extractor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ynitto/table-spec-extractor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: ynitto (https://skillmd.com/u/ynitto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ynitto/table-spec-extractor

---


> ⚠️ **【非推奨】このスキルは deprecated です。**
> Neo4j サーバと Table Transformer（torch/transformers, ~1-2GB）への依存が重く、
> スキルとしての可搬性に欠けるため、後継の **`spec-value-finder`**（純Python・サーバ/GPU不要）へ移行してください。
> 「元仕様書から記入すべき値を探す」用途は `spec-value-finder` がカバーします。

# テーブル仕様抽出パイプライン

Excel/PDFの仕様書テーブルを解析し、Neo4jグラフとして蓄積・検索するパイプライン。
結合セルの階層構造を保持したまま保存できるため、「どの画面の・どの機能の・どの設定値か」という文脈を壊さずに管理できる。

> **Windows / macOS / Linux** 対応。コマンド例はすべて `python` を使用する（環境によっては `python3`）。

## モード一覧

| モード | 目的 | 最初に使うか |
|--------|------|------------|
| `init` | 依存インストール＋Neo4j疎通確認 | 初回必須 |
| `save` | ドキュメント→AST→Neo4jへロード | ドキュメント追加時 |
| `search` | グラフ全文＋列コンテキスト付き検索 | 検索時 |
| `config` | 複数Neo4jプロファイル管理 | 接続先変更時 |

## スクリプト配置

```
scripts/
├── run.py                 # エントリポイント（__file__ 基準でパス解決、どこから実行しても動作）
├── models.py              # Document ASTノード定義（Cell.path含む）
├── ingest.py              # PDF描画（pypdfium2）・Excel読込（openpyxl）
├── table_extractor.py     # Table Transformer検出・構造認識
├── ast_builder.py         # AST組み立て＋carry-forward breadcrumb推定
├── markdown_serializer.py # Table → Markdown変換（LLM向け中間表現）
├── graph_loader.py        # Neo4j MERGE＋インデックス作成
├── search.py              # GraphRAGクエリ（全文＋SAME_COLUMNトラバーサル）
├── config.py              # プロファイル管理（複数Neo4j対応）
└── requirements.txt       # 依存ライブラリ一覧
```

`run.py` は `__file__` を基準にパスを解決するため、スキルが `.github/skills/`・`~/.claude/skills/` など
どこに配置されていても動作する。

---

## configモード（複数Neo4jプロファイル管理）

保存先ごとに接続情報とローカルデータパスを設定できる。
設定ファイル: `~/.table-spec-extractor/config.json`（`TABLE_SPEC_EXTRACTOR_CONFIG` 環境変数で上書き可）

```bash
# プロファイルを追加
python scripts/run.py config add local \
  --neo4j bolt://localhost:7687 \
  --user neo4j --password "" \
  --data-path ~/graph-data/local \
  --set-default

python scripts/run.py config add prod \
  --neo4j bolt://prod-server:7687 \
  --user neo4j --password secret \
  --data-path ~/graph-data/prod

# 一覧・詳細
python scripts/run.py config list
python scripts/run.py config show local

# デフォルト変更・削除
python scripts/run.py config set-default prod
python scripts/run.py config remove local
```

`data-path`: saveモード実行時にASTのJSONスナップショットを保存するディレクトリ。
Neo4jが不要な場合はここだけ設定してローカル保存のみも可能。

---

## initモード

依存ライブラリをインストールし、Neo4j接続を確認する。**初回に必ず実行する。**

Excel のみ使う場合（デフォルト・軽量）:
```bash
python scripts/run.py init
```

PDF も処理する場合（torch / transformers / Pillow 等を追加インストール）:
```bash
python scripts/run.py init --enable-pdf
```

Neo4j 疎通確認を同時に行う場合:
```bash
python scripts/run.py init --profile local
python scripts/run.py init --enable-pdf --neo4j bolt://localhost:7687 --password secret
```

| requirements | 内容 | サイズ目安 |
|---|---|---|
| `requirements.txt` | openpyxl, neo4j | ~数MB |
| `requirements-pdf.txt` | pypdfium2, pdfplumber, torch, transformers, Pillow | ~1-2GB |

---

## saveモード

Excel/PDFをTable Transformerで解析してNeo4jへロードする。
テーブルはMarkdown形式でも保存されるため、LLMが`markdown_text`プロパティを直接参照できる。

### Step 1 — dry-run（ASTを事前確認）

```bash
python scripts/run.py save <FILE> --dry-run
```

セクション数・テーブル数・段落数を確認する。テーブルが0件の場合はStep 1で止まり、
`--dpi 200`（解像度向上）や `--threshold 0.7`（検出感度向上）を提案する。

### Step 2 — Neo4jへロード

```bash
# プロファイル使用（data-pathへのスナップショット保存も自動実行）
python scripts/run.py save <FILE> --profile local

# URI直接指定
python scripts/run.py save <FILE> --neo4j bolt://localhost:7687 --password secret
```

### saveオプション

| オプション | デフォルト | 説明 |
|-----------|-----------|------|
| `--profile` | "" | 使用するプロファイル名 |
| `--dpi` | 150 | PDF描画解像度（高いほど検出精度向上・低速） |
| `--threshold` | 0.9 | テーブル検出信頼度（下げると検出数増加） |
| `--device` | cpu | Torchデバイス（`cuda` 指定で高速化） |
| `--data-path` | "" | ローカルスナップショット保存先（プロファイルを上書き） |
| `--dry-run` | — | Neo4jへロードせずASTをJSON表示 |

---

## searchモード

Neo4jグラフを全文検索＋グラフトラバーサルで検索する。
セル検索では同一列のヘッダーセルとbreadcrumb pathをコンテキストとして付与する。

```bash
python scripts/run.py search "検索クエリ" --profile local
python scripts/run.py search "売上" --neo4j bolt://localhost:7687 --limit 20
python scripts/run.py search "MaxConnections" --profile prod --json
```

ヒットが0件の場合はsaveモードでドキュメントがロード済みか確認する。

---

## グラフスキーマ

```
(:Document)-[:HAS_SECTION]->(:Section)
(:Section)-[:CONTAINS]->(:Table | :Paragraph)
(:Table {markdown_text})-[:HAS_ROW]->(:Row)
(:Row)-[:HAS_CELL]->(:Cell {text, path, is_header})
(:Row)-[:NEXT_ROW]->(:Row)
(:Cell)-[:NEXT_CELL]->(:Cell)    # 同行・左→右
(:Cell)-[:SAME_COLUMN]->(:Cell)  # 同列・上→下（GraphRAGの要）
```

**Cell.path** は breadcrumb 配列。例: `["Config", "Network", "IP Address"]`
**Table.markdown_text** はLLM向けMarkdown表現。

全文インデックス: `cell_fulltext`（Cell.text）、`para_fulltext`（Paragraph.text）

---

## ベクトル検索（将来の拡張）

Neo4j 5.x+ は vector index をサポートする。以下の手順で追加可能:
1. `sentence-transformers` などで Cell.text / Paragraph.text の埋め込みを生成
2. `CREATE VECTOR INDEX cell_vector FOR (n:Cell) ON (n.embedding) OPTIONS {indexConfig: {...}}`
3. `CALL db.index.vector.queryNodes(...)` で近傍検索

現時点では依存の重量（~500MB）から本スキルには含めていない。

---

## エラー対処

| エラー | 原因 | 対処 |
|--------|------|------|
| `No module named pypdfium2` | initが未実行 | `init`モードを実行 |
| テーブル0件 | 低解像度・高閾値 | `--dpi 200 --threshold 0.7` |
| `ServiceUnavailable` | Neo4j未起動 | Neo4jサービスを確認 |
| `index not found` | インデックス未作成 | `save`を一度実行してインデックスを作成 |
| `KeyError: 'profiles'` | config.json形式不正 | `config list`で確認後、手動で修正 |