matrix-engine

name	matrix-engine
description	Matrix Engine module. Reads structured paper JSONs from hypotheses/translated/, extracts problem and method axes, builds a 2D chessboard matrix, identifies research gaps, and outputs matrix.json + matrix.csv. User-triggered.
metadata	{"version":"1.0.0","last_updated":"2026-05-29","status":"active","task_type":"open-ended"}

⚠️ Mandatory Pre-Load

Before execution, you must read:

1. Read agents/matrix_engine_agent.md — the sole agent definition for this module

If this file is not loaded, do not begin execution.

---

⚠️ Preconditions

This module requires structured paper data from the Literature Reader module:

1. workspaces/ProjectX/hypotheses/translated/ must contain at least 1 JSON file
2. Each JSON must follow the schema output by paper_cruncher_agent (containing task_definition, core_mechanism, evaluation, research_gap)

If no translated JSONs exist, this module cannot run. Instruct the user to run Literature Reader first.

---

Matrix Engine Module

Reads structured paper data, extracts two axes (problems × methods), builds a chessboard matrix, identifies research gaps, and outputs machine-readable + human-readable files.

Core positioning: This module does not search literature, read PDFs, or converse with the user. It does one thing only: turn structured paper data into a 2D research landscape map.

---

Trigger Conditions

Trigger Method

User-triggered. This module does not run automatically.

Trigger Keywords

• "生成矩阵" / "更新棋盘" / "generate matrix" / "update matrix"
• "分析研究空白" / "找 gap" / "find research gaps"
• "build chessboard" / "research landscape"

Pre-Execution Check (Mandatory)

Does hypotheses/translated/ contain at least 1 .json file?

YES → Continue execution
NO  → Tell user "No translated paper data found. Please run Literature Reader first." and terminate.

Non-Trigger Scenarios

Scenario	Use Instead
User wants to search for papers	Literature Scout module
User wants to read/understand papers	Literature Reader module
User wants guided research dialogue	Socratic Method module

---

Agent Team (1)

#	Agent	Role
1	matrix_engine_agent	Reads all translated JSONs, extracts axes, normalizes labels, fills matrix, identifies gaps, outputs JSON + CSV

---

Orchestration Flow

User triggers "generate matrix"
     |
=== Pre-check ===
     |
     +-> hypotheses/translated/ has .json files?
     |   - No → Tell user to run Literature Reader first, terminate
     |   - Yes → Continue
     |
=== Read all translated JSONs ===
     |
     +-> Scan hypotheses/translated/*.json
     +-> Parse each file (skip and log errors for unparseable files)
     |
=== Extract axes ===
     |
     +-> Y-axis: task_definition.research_scenario from each paper
     +-> X-axis: core_mechanism.foundation + core_mechanism.innovation_modules from each paper
     |
=== Normalize axis labels ===
     |
     +-> Unify case
     +-> Remove filler words (based, using, via, with, for)
     +-> Expand abbreviations (GNN = Graph Neural Networks, LLM = Large Language Model)
     +-> Extract core noun phrases
     +-> Merge identical normalized labels
     |
=== Fill matrix ===
     |
     +-> For each paper, determine (Y, X) cell(s)
     +-> A paper may appear in multiple cells (if it uses multiple methods)
     |
=== Identify gaps ===
     |
     +-> All (Y, X) combinations with no papers = research gaps
     +-> Generate gap_description for each
     |
=== Calculate statistics ===
     |
     +-> coverage_ratio = filled_cells / total_cells
     |
=== Output ===
     |
     +-> Write matrix.json (machine-readable, full structure)
     +-> Write matrix.csv (human-readable, Excel-compatible)
     |
=== Report to user ===
     |
     +-> "Matrix generated: X problems × Y methods"
     +-> "Found Z research gaps (coverage: NN%)"
     +-> "Files saved: matrix.json + matrix.csv"
     +-> "You can now use supervised Socratic dialogue to explore these gaps."

---

Inputs

Source	Path	Content
Literature Reader output	workspaces/ProjectX/hypotheses/translated/*.json	Structured paper data (4 dimensions)

Expected JSON Structure (per paper)

{
  "paper_name": "...",
  "task_definition": {
    "research_scenario": "...",
    "input_x": "...",
    "output_y": "..."
  },
  "core_mechanism": {
    "foundation": "...",
    "innovation_modules": ["...", "...", "..."]
  },
  "evaluation": {
    "datasets": "...",
    "baselines": "..."
  },
  "research_gap": {
    "unresolved_blind_spots": "...",
    "identifiable": true
  }
}

Field-to-Axis Mapping

JSON Field	Maps To	Notes
task_definition.research_scenario	Y-axis (Problems / Applications)	1 label per paper
core_mechanism.foundation	X-axis (Methods / Techniques)	Coarse-grained
core_mechanism.innovation_modules[]	X-axis (Methods / Techniques)	Fine-grained, each element independent

---

Outputs

File	Format	Purpose	Consumer
workspaces/ProjectX/matrix.json	JSON	Machine-readable matrix with full structure	Socratic Method (supervised), Profile Module
workspaces/ProjectX/matrix.csv	CSV (UTF-8-BOM)	Human-readable, Excel-compatible	User direct viewing

Output Behavior

• Full regeneration every run: Overwrites existing matrix.json and matrix.csv
• No incremental updates
• No partial writes during processing

---

Normalization Rules

Rule	Example
Unify case	"concept bottleneck" = "Concept Bottleneck"
Remove filler words	"framework utilizing neural language models" → "neural language models"
Expand abbreviations	"GNN" → "Graph Neural Networks"
Extract core noun phrase	"Concept bottleneck framework utilizing BERT" → "Concept Bottleneck"
Merge identical after normalization	Two labels that normalize to the same string → one axis item

---

Absolute Rules

1. Full regeneration — Every run overwrites existing matrix.json and matrix.csv completely
2. Normalization must be effective — Obviously identical concepts must not appear as separate axis labels
3. Every paper must be placed — Each paper appears in at least 1 cell
4. All gaps must be identified — Every empty cell must appear in the gaps list
5. Coverage math must be correct — filled_cells + empty_cells == total_cells
6. Single file failure does not halt — If one JSON is unparseable, skip it and continue
7. CSV must be Excel-compatible — Use UTF-8-BOM encoding, no garbled characters

---

Failure Paths

Failure Scenario	Trigger	Recovery
translated/ is empty	No paper JSONs	Tell user to run Literature Reader first, terminate
Single JSON parse failure	Malformed file	Skip that file, log error, continue with others
All JSONs fail to parse	All files malformed	Tell user, terminate
Cannot extract any axis labels	All fields empty	Tell user, terminate
Only 1 paper available	Minimal data	Generate 1×N or N×1 matrix (still valid)

---

Relationship to Other Modules

[Literature Reader] → hypotheses/translated/*.json
    ↓
[Matrix Engine] → matrix.json + matrix.csv
    ↓
[Socratic Method (Supervised)] → Reads matrix for Layer 2-3
[Profile Module] → Reads matrix to supplement empty search_seeds
[Literature Scout] → Reads matrix gaps for targeted search (future)

---

Quality Standards

1. Full coverage: Every JSON in translated/ must be processed or logged as error
2. Normalization effective: No obviously duplicate axis labels
3. Paper placement correct: Every paper in at least 1 cell
4. Gap identification complete: All empty cells in gaps list
5. Coverage calculation correct: Math checks out
6. Output parseable: matrix.json must be strictly valid JSON
7. CSV openable: Excel opens without encoding issues

---

Agent File Reference

Agent	Definition File
matrix_engine_agent	agents/matrix_engine_agent.md

---

Output Language

• Academic content in JSON/CSV uses English (consistent with Literature Reader output)
• CSV header row may use bilingual labels for user convenience
• User interaction uses the user's language