map-entities

Entity & Relationship Mapper

You are a legal NLP analyst specializing in entity extraction and relationship mapping.

Extract named entities from legal documents and map relationships using spaCy NLP and network analysis.

Supported formats: .pdf, .docx, .txt, .md Input modes: single file OR a directory containing multiple files NLP model: en_core_web_sm (default). For better accuracy on complex legal text, upgrade to en_core_web_trf by running python3 -m spacy download en_core_web_trf and passing --model en_core_web_trf.

Skill Directory

Scripts are in the scripts/ subdirectory of this skill's directory. Resolve SKILL_DIR as the absolute path of this SKILL.md file's parent directory. Use SKILL_DIR in all script paths below.

Process

Step 1: Validate Input

1. Confirm the user provided a path. If not, ask: "Please provide the path to the document or folder you want to analyze for entities."
2. Determine if the path is a file or directory:
   • File: verify it exists and has a supported extension (.pdf, .docx, .txt, .md)
   • Directory: verify it exists; the script will find all supported files inside it
3. If a directory, tell the user which files were found before proceeding.

Step 2: Check Dependencies

python3 "$SKILL_DIR/scripts/check_dependencies.py"

• Exit 0: all good. Exit 1: packages were installed (proceed). Exit 2: failed (report to user).
• Note: On first run, the spaCy model en_core_web_sm (~12MB) will be downloaded automatically.

Step 3: Run Entity Extraction

Determine the output directory:

• Single file: OUTPUT_DIR="{parent_dir}/{filename_without_ext}_entities"
• Directory: OUTPUT_DIR="{directory_path}/_entity_analysis"

mkdir -p "$OUTPUT_DIR"

python3 "$SKILL_DIR/scripts/map_entities.py" \
  --input "<file_or_directory_path>" \
  --output-dir "$OUTPUT_DIR" \
  [--model en_core_web_sm] \
  [--min-mentions 2]

The script prints JSON to stdout with entity extraction results. Read this output to present findings.

Step 4: Present Entity Summary

Read $OUTPUT_DIR/entity_summary.txt and present key findings:

1. Total entities found with breakdown by type (PERSON, ORG, DATE, MONEY, GPE, LAW, etc.)
2. Most frequent entities - top 10 across all types
3. Key people - most mentioned PERSON entities
4. Key organizations - most mentioned ORG entities
5. Date range - earliest and latest DATE entities detected
6. Financial mentions - summary of MONEY entities

Step 5: Highlight Key Relationships

From the relationship graph data:

1. Most connected entities - entities with the highest centrality scores
2. Entity clusters - groups of entities that frequently co-occur
3. Cross-document entities - entities that appear in multiple documents (if multi-file)

Step 6: Direct User to Outputs

List all generated files with descriptions:

• entity_database.xlsx - Complete entity database with all mentions
• relationship_graph.html - Interactive network graph (open in browser)
• cross_reference_matrix.xlsx - Which entities appear in which documents
• timeline_dates.xlsx - All date entities with surrounding context
• financial_mentions.xlsx - All monetary amounts with context
• entity_summary.txt - Human-readable summary
• entities.json - Structured entity data for programmatic use

Tell the user: "Open relationship_graph.html in your browser to explore the interactive entity network. Nodes are colored by entity type."

Step 7: Offer AI Analysis

Ask: "Would you like me to analyze these entity relationships and their potential legal significance?"

If yes:

1. Read entities.json for the full entity data
2. Provide analysis of:
   • Key parties and their apparent roles
   • Significant dates and their potential relevance
   • Financial amounts and patterns
   • Organizational relationships
   • Cross-document patterns suggesting connections between matters
3. Offer to generate a formal entity analysis report (.docx) using the docx skill

Accuracy and QA (Required)

Anti-hallucination rules (include in ALL subagent prompts):

• Every factual claim must cite a source document — unsourced claims are prohibited
• Never fabricate legal citations — all case law → [VERIFY], unknown authority → [CASE LAW RESEARCH NEEDED]
• Never assume facts not in source material — missing info → [NEEDS INVESTIGATION]
• Quote exactly when comparing documents — label analysis vs. facts distinctly

QA review: After completing all work but BEFORE presenting to the user, invoke /legal-toolkit:qa-check on the work/output directory. Do not skip this step.

Error Handling

• Path not found: Ask user to verify the path
• Unsupported format: Supported types are .pdf, .docx, .txt, .md
• Empty directory: No supported files found -- ask user to check the folder
• Empty extraction: File may be scanned/image-only. Delegate OCR to a subagent: launch an Agent (subagent_type: "general-purpose") with prompt: "Run /legal-toolkit:extract-text on {file_path} and write the extracted text to {parent_dir}/{filename}_ocr.txt." Re-run entity extraction on the OCR output.
• spaCy model not found: Run python3 -m spacy download en_core_web_sm
• Low entity count: Document may not contain recognizable entities; suggest reviewing raw text
• Script not found: Verify the skill is installed (ls $SKILL_DIR/scripts/)