Claude Skill

academic-repo-analyzer

Analyze ML, AI4Science, Systems, and research repositories into an evidence-backed semantic architecture graph for paper figure planning. Code serves as supporting evidence; paper narrative and user intent remain the primary source of truth.

LLM Mart · 0 points · 17 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download Azhi-ss-academic-figure-skills-academic-repo-analyzer-3e38b08.zip · 18 KB

azhi-ss/academic-figure-skills 121 13 forks MIT Updated 12d ago

Part of azhi-ss/academic-figure-skills — 5 skills

Install

skills CLI npx skills add https://github.com/Azhi-ss/academic-figure-skills/tree/main/academic-repo-analyzer

Claude Code

claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install azhi-ss-academic-figure-skills@llmmart

Git git clone https://github.com/Azhi-ss/academic-figure-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole azhi-ss/academic-figure-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Academic Repo Analyzer

Produce a concise repository understanding document plus a machine-readable Semantic Architecture Handoff v1. The handoff describes scientific roles and executable relationships, not the repository's folder layout or engineering boilerplate.

Read keywords.md only when task or framework classification is uncertain. Read references/missing-info-policy.md when evidence is sparse.

Core Principle: Narrative Priority & Non-Intrusive Extraction

Paper & User Narrative > Code Implementation:
- A paper figure depicts the scientific contribution and conceptual data flow, not the full software engineering artifact.
- Omit engineering plumbing (such as DataLoader, Trainer, Logger, ConfigParser, DeviceManager, or Optimizer setup) unless the paper specifically contributes a training algorithm or infrastructure system.
Fact-Checking & Parameter Grounding:
- When a paper draft or user architecture is already present, the repo analyzer acts as a supporting fact-checker (verifying tensor dimensions, loss formulas, exact module names, and execution directions) rather than re-inventing the architecture.

Input contract

Prefer: repository path, README, dependencies, entry points, core model/algorithm files, configs, and tests that establish behavior.
Accept: partial repository, isolated model files, core algorithm script.
Minimum: one README, entry point, or core implementation file.
Record the source revision when Git metadata is available.
Treat names and README claims as leads; verify figure-critical claims in code or tests.

Output contract

Keep the human summary to roughly 30–70 lines, then emit the handoff block below.

Repository overview and scientific task.
Evidence/completeness statement listing what was inspected.
Semantic components and their responsibilities.
Executed/advisory/feedback/persistence connections.
Authority or trust boundaries when agents, tools, evaluators, or external systems are involved.
Figure suggestions (Overall Framework, Network Architecture, Module Detail, Concept/Motivation, Protocol/Sequence).
Semantic Architecture Handoff v1.

Workflow

1. Locate evidence

Find the README, dependency files, entry scripts (train, main, eval, inference, predict, run, simulate, benchmark), configs, and core algorithm files. Top-level directories are discovery cues only; they are never counted as architecture modules.

For a large repository, inspect the top level and a justified sample of core files. State the sampling boundary. Do not claim full coverage from keyword hits.

2. Classify task and implementation stack

Identify the scientific objective, primary framework, data/experiment interface, and main execution path with file or symbol evidence. Mark unsupported inferences explicitly.

3. Build the semantic graph

Create one component only when it has a distinct scientific or execution responsibility that belongs in a paper figure. A component may span several files, and one file may implement several components.

For every component record:

stable id and short display label;
role:
- General ML / Deep Learning: input_data, encoder_backbone, fusion_interaction, loss_objective, task_head, model, output;
- Agentic / Interactive: reasoning, decision, deterministic_execution, observation, memory, persistence, advisory, exception;
- Systems / Modular: source, scheduler, processor, storage, sink, other;
figure_importance: primary or secondary;
evidence pointers such as path:line, class, function, test, or config key;
one-sentence responsibility and explicit non-authority when scientifically important.

Record connections separately. Use executed, advisory, feedback, persistence, or exception as the connection kind. Do not infer an edge solely because two files import each other.

4. Derive visual groups

Group related components by responsibility or narrative stage. Report:

semantic_component_count: number of evidence-backed components;
visual_group_count: number of meaningful regions in the proposed figure;
peer_module_count: largest set of genuinely equivalent sibling components.

These counts help layout planning. None of them selects a palette by itself.

5. Emit the handoff

{
  "schema": "academic-figure/SemanticArchitecture@1",
  "source_revision": "<commit-or-unknown>",
  "domain": "<controlled-domain>",
  "evidence_level": "high|partial|sparse",
  "components": [
    {
      "id": "backbone",
      "label": "Encoder Backbone",
      "role": "encoder_backbone",
      "figure_importance": "primary",
      "responsibility": "Extracts multi-scale feature representations.",
      "evidence": ["models/backbone.py:ResNet"]
    }
  ],
  "connections": [
    {
      "from": "input_data",
      "to": "backbone",
      "kind": "executed",
      "label": "raw inputs",
      "evidence": ["models/pipeline.py:forward"]
    }
  ],
  "authority_boundaries": [],
  "semantic_component_count": 1,
  "visual_group_count": 1,
  "peer_module_count": 0,
  "figure_types": ["Overall Framework"],
  "forbidden_claims": ["<claims the figure must not imply>"]
}

Controlled domain: CV, NLP, Speech/Audio, RL, Robotics, Multimodal, TimeSeries, Generative, Protein/AI4Science, GNN/ScientificComputing, Systems/Infrastructure, ScientificComputing(non-ML), or Other.

Sparse evidence

No README: infer cautiously from code and label the inference.
No entry point: limit the result to component-level structure.
No core implementation: report task/stack only and omit unsupported edges.
Almost empty repository: provide the minimum missing materials instead of inventing an architecture.

Stop

Stop when the human summary and valid handoff are delivered. Suggest figure planning only when the user wants the next stage.

Files (academic-figure-skills)

references

missing-info-policy.md 1 KB

# Missing-Info Policy

Shared by all academic-figure skills. Domain skills add only their own cases.

## Rule

When evidence is incomplete: ship a **conservative, useful** partial result. Label every claim beyond evidence as `推断` or `待确认`. Prefer placeholders over invention.

## Completeness block (every deliverable)

```
- 已分析材料: ...
- 当前输出类型: 完整 / 阶段性 / 局部 / 骨架
- 高置信信息: ...
- 待确认信息: ...
- 建议补充材料: 1–3 highest-value items
```

## Stop vs continue

| Situation | Action |
|-----------|--------|
| Core deliverable possible with placeholders | continue |
| Zero usable source (no paper, repo, figure type, or image) | stop; list minimum materials |
| User asked only this stage | stop after that stage |
| Next stage needs material user has not provided | stop; do not invent |

## Invention ban

Do not invent modules, losses, dimensions, experiment results, or architecture layers that never appear in the source. Rewrite unknowns as explicit placeholders (`[module_name]`, `R^(?×?)`).

palettes.md 20.7 KB

# Academic Palettes — Single Source of Truth

This file defines **12 classic presets**, three pastel-airy schemes, and paired illustrated semantic-zone tokens. Skills that need hex values or style routing should load this file rather than maintaining private copies.

## Decision order

Apply evidence in this order:

1. explicit user colors, style, print, and accessibility requirements
2. supplied reference image grammar
3. hard production constraints such as grayscale output and text contrast
4. figure semantics and visual-zone relationships
5. an existing paper-wide visual system or explicit submission rule
6. conservative default

A reference image is the highest-priority inferred style source. Extract composition, panel surfaces, outline strength, shadow treatment, typography character, icon style, nesting depth, density, arrow grammar, and paired fill/outline colors. Match those properties without copying the reference's labels, branded assets, or method content.

`module_count` is a density clue only. It does not trigger monochrome. Choose hue count from the number and relationship of semantic zones shown in the figure.

| Missing evidence | Conservative default |
|---|---|
| No reference or style cue, classic technical figure | **Okabe-Ito** |
| Explicit airy UI/token figure | **P2 Cool Research** |
| Narrative framework or agent/scientific workflow | **I1 Illustrated Zones** |
| Accessibility unspecified | colorblind-aware dual encoding and validated text contrast |

Always state the branch (`user`, `reference`, `scene`, or `default`) and offer one alternate.

## Style profiles first

Palette values only make sense with a surface and line treatment. Select a profile before assigning tokens.

| Signals | Profile | Primary skill | Visual grammar |
|---|---|---|---|
| technical stack, compact network, classic vector, strict print | **`classic-technical`** | `academic-figure-designer` | restrained geometry, fine borders, white or near-white modules, compact sans labels |
| airy, token flow, interface-like, soft cards | **`pastel-airy-ui`** | `academic-figure-designer` | white cards, subtle border/shadow, floating pills and tokens, generous whitespace |
| hand-drawn academic infographic, modular narrative, agent/scientific workflow, tinted zones | **`illustrated-modular`** | `academic-figure-designer` | asymmetric hero layout, soft semantic-zone fills, strong same-hue outlines, no shadow, one-level subcards, controlled line illustrations |
| supplied reference does not fit one preset | **`reference-led`** | `academic-figure-designer` | override defaults with observed grammar; do not assume an illustrated surface |

Do not force a supplied reference into a binary classic/pastel label. A coherent figure may combine a classic flat canvas, tinted modular zones, and hand-drawn illustrations. State the observed properties so the combination is intentional rather than a style-word mixture.

### Pastel airy UI schemes

Small body text remains neutral `#24323D`. The colored values below are heading accents on white; validate them again before placing small text on a tinted token.

| Scheme | Scene | Soft fills | Accessible heading accents on white |
|---|---|---|---|
| **P1 Warm ML** | playful, teaching, human-centered | `#FFD0D0` `#BBDEFB` `#FFF3C4` `#E1BEE7` `#C8E6C9` | `#A93636` `#146C61` `#6A5ACD` `#2F7430` |
| **P2 Cool Research** | calm token-centric research figure | `#B3E5FC` `#C5CAE9` `#CFD8DC` `#B2DFDB` `#D1C4E9` | `#1565C0` `#3949AB` `#006F65` |
| **P3 Earthy Warm** | natural or embodied visual direction | `#FFE0B2` `#D7CCC8` `#C8E6C9` `#E0E0E0` `#EFEBE9` | `#6D4C41` `#827717` `#2E7D32` |
| **P4 Airy Agentic BO** | surrogate backend, agent decision, charcoal eval anchor | `#FAE8DC` (Peach) `#DBE7FB` (Periwinkle) `#4B5563` (Slate) `#E9E9EC` (Gray) | `#1E293B` `#0F172A` `#FFFFFF` `#334155` |

If a reference is present, derive its token pairs instead of snapping every soft figure to the nearest P1–P4 scheme.

---

## I1 Illustrated Zones — paired semantic tokens

Each token is a coordinated surface system rather than a standalone accent. `title_text` values meet normal-text contrast against their paired fills; small body text may use neutral `#24323D` throughout.

| Token | `soft_fill` | `dark_outline` | `title_text` | `icon_accent` |
|---|---|---|---|---|
| **I1 Blue** | `#EDF4FB` | `#194166` | `#163E64` | `#2E6B9E` |
| **I1 Green** | `#F3FBF0` | `#3B7D23` | `#2F681D` | `#4E8D36` |
| **I1 Peach** | `#FBE3D6` | `#A94417` | `#9E3F13` | `#C65A22` |
| **I1 Purple** | `#F5ECF5` | `#77206E` | `#65185E` | `#8B3B83` |
| **I1 Cyan** | `#DBF3FE` | `#236E96` | `#195876` | `#2F81A8` |
| **I1 Gold** | `#FBF1D1` | `#856B1B` | `#66500F` | `#9B7B1C` |
| **I1 Coral** | `#FDE8E5` | `#B83A2F` | `#8F2A24` | `#C94D42` |

Recommended material treatment: white canvas; 1.5–2.5px zone outlines; 6–14px corner radius scaled to output size; no drop shadows; white or lighter same-hue subcards; dark neutral arrows `#334155` unless the edge itself carries a zone meaning.

## Semantic color binding contract

Bind tokens to the roles present in the current paper and retain those bindings across its figures. The mappings below are customizable defaults across different scientific domains:

### 1) Standard Multi-Stage Pipeline & Modular Systems
| Domain Role / Stage | Suggested Illustrated Token | Classic/Airy Adaptation |
|---|---|---|
| **Stage 1: Input / Raw Data / Context** | I1 Green (`#F3FBF0` / `#3B7D23`) | Green accent / data pill |
| **Stage 2: Representation / Encoders** | I1 Blue (`#EDF4FB` / `#194166`) | Blue outline / primary container |
| **Stage 3: Core Mechanism / Transformation** | I1 Peach (`#FBE3D6` / `#A94417`) | Orange/peach hero zone |
| **Stage 4: Optimization / Supervision / Loss** | I1 Purple (`#F5ECF5` / `#77206E`) | Purple accent / dashed constraint |
| **Stage 5: Output / Evaluation / Benchmark** | I1 Gold (`#FBF1D1` / `#856B1B`) | Gold heading / output badge |

### 2) Deep Learning & Neural Architectures
| Architecture Component | Suggested Illustrated Token | Visual Metaphor / Shape |
|---|---|---|
| **Raw Input / Embeddings / Tokens** | I1 Green | Structured grid, token pill, or feature map |
| **Backbone / Feature Extractor** | I1 Blue | Layered orthogonal blocks or stacked cards |
| **Cross-Modal Fusion / Attention Core** | I1 Peach | Heatmap matrix or bipartite connection web |
| **Loss Function / Objective / Regularizer** | I1 Purple | Mathematical constraint box or curve |
| **Prediction Head / Downstream Task** | I1 Gold | Terminal prediction pill or task badge |

### 3) Agentic & Scientific Interactive Loops
| Agentic Role | Suggested Illustrated Token | Visual Metaphor / Shape |
|---|---|---|
| **Reasoning / Policy / Planner** | I1 Blue | Decision glyph, thought bubble, or planning box |
| **Evidence / Context / Observation** | I1 Green | Document icon, coordinate plot, or context card |
| **Deterministic Harness / Tool Execution**| I1 Peach | Solid process container or simulation box |
| **Advisory / Feedback / Uncertainty** | I1 Purple | Dashed feedback arrow or advisory pill |
| **Memory / Storage / Provenance** | I1 Cyan | Network graph or database/checkpoint cylinder |
| **Final Output / Report** | I1 Gold | Formatted report card or badge |
| **Exception / Guardrail / Stop** | I1 Coral | Warning badge or coral STOP boundary |

### 4) Dual-Fidelity & Bayesian Optimization Loops
| Optimization Role | Suggested Illustrated Token | Visual Metaphor / Shape |
|---|---|---|
| **High-Fidelity / Real-World Experiment / Discrepancy** | I1 Coral (`#FDE8E5` / `#B83A2F`) | Laboratory glassware, oscilloscope/monitor, focused residual peak $\mathcal{X}_R^*$ |
| **Low-Fidelity / LLM Prior / Global Surrogate** | I1 Blue (`#EDF4FB` / `#194166`) | Electronic brain, prompt balloon, 3D smooth GP surface |
| **Candidate Selection / Acquisition Function** | I1 Peach (`#FBE3D6` / `#A94417`) | 1D search curve, peak marker $x^*$, candidate generator table |
| **Gating Criterion / Adaptive Decision** | Decision Diamond (Neutral/Red/Green) | Diamond node $p_\Delta < \tau$, green checkmark / red cross status badges |
| **Prior Domain Knowledge / Constraints** | I1 Green / Slate (`#F3FBF0` / `#3B7D23`) | Literature stack, coordinate scatter plot, constraint box |

Repeated roles reuse a token; adjacent unrelated zones should also differ by label, geometry, or line style.

---

## Scene → profile and palette decision

After explicit user and reference-grammar requirements, apply production constraints and then choose from figure semantics. Venue and domain are suggestions, not guarantees of a single visual style.

### 1) Hard constraints

| Constraint | Choose | Alternate |
|------------|--------|-----------|
| Strict B&W / grayscale print only | **Print-Safe Gray** | Grayscale |
| Theory paper, no color budget | **Grayscale** | Print-Safe Gray |
| Color-vision accessibility required or prudent | Start from Okabe-Ito / ML TopConf Colorblind / a verified monochrome ramp, then dual-encode and test | Never treat a palette name as proof of accessibility |
| Must match existing Matplotlib Tab10 experiment plots | **ML TopConf Tab10** | ML TopConf Colorblind if a11y matters more than match |
| Reference has tinted zones and strong outlines | **Illustrated modular + derived pairs** | I1 Illustrated Zones |

### 2) Figure type

| Figure type | Prefer | Alternate | Why |
|-----------|--------|-----------|-----|
| Overall Framework, technical pipeline | Okabe-Ito | ML TopConf Colorblind | clear categorical accents |
| Overall Framework, modular narrative | **Illustrated modular + I1** | reference-derived pairs | semantic zones and hierarchy |
| Network Architecture | Okabe-Ito or Blue Monochrome | Nature Blue for a restrained single-family stack | structure > decoration |
| Module Detail | **Blue Monochrome** | Okabe-Ito | detail density; gray-print friendly |
| Comparison / Ablation (few panels) | Purple-Green | Okabe-Ito | category contrast |
| Dense multi-panel ablation | **ML TopConf Deep** | Purple-Green | softer multi-hue grid |
| Data Behavior (curves / heatmaps / t-SNE) | ML TopConf Colorblind | Okabe-Ito | series/categories stay separable |
| Qualitative image grids | Okabe-Ito accents only | Grayscale frames | color on labels, not photo washes |

### 3) Venue and domain constraints

Do not map a venue or research domain directly to a palette. Use venue/domain
information only when it supplies a concrete production constraint: an official
grayscale rule, an existing paper-wide color system, a required plot palette,
an accessibility requirement, or a reference figure. Otherwise choose from the
content relationships above. “Nature”, “CVPR”, “biology”, “materials”, or
“robotics” alone is not a color instruction.

### 4) Vibe words → concrete choice

| User says | Family | Palette / scheme |
|-----------|--------|------------------|
| 高级 / 克制 / 顶刊 | ask for observable traits or use a supplied reference | no venue-name palette default |
| 科技感 / 工程感 / 干净 | `classic-technical` | Blue Monochrome or Okabe-Ito |
| 柔和 / 空气感 / token 卡片 | `pastel-airy-ui` | P2 |
| 手绘 / 叙事 / 模块拼图 / agent 框架 | `illustrated-modular` | I1 or reference-derived pairs |
| 活泼 / 教学感 | `pastel-airy-ui` or `illustrated-modular` | P1 or reference-derived pairs |
| 自然 / 生物感 | classic Warm Earth, airy P3, or illustrated zones | state accessibility tradeoff |
| 不要花 | any coherent profile | reduce active semantic zones; monochrome only if hierarchy remains clear |
| 和实验曲线一个色 | `classic-technical` | ML TopConf Tab10 / Colorblind |
| 黑白印刷 | `classic-technical` | Print-Safe Gray / Grayscale |

---

## Worked decision recipes

| Scenario | Family | Palette | One-line reason |
|----------|--------|---------|-----------------|
| Technical three-stage method pipeline, no reference | `classic-technical` | Okabe-Ito | categorical accents and compact geometry |
| Modular agent/scientific framework, no reference | `illustrated-modular` | I1 Illustrated Zones | semantic zones plus asymmetric hierarchy |
| Reference with tinted panels and dark outlines | `reference-led` (observed illustrated grammar) | derived paired tokens | preserve observed visual grammar without assuming every reference is illustrated |
| Dense 2×3 ablation grid | `classic-technical` | ML TopConf Deep | multiple comparable panels |
| Token-flow explainer with white cards | `pastel-airy-ui` | P2 | token-centric surface grammar |
| Continuous single-family mechanism with an explicit restrained-blue preference | `classic-technical` | Nature Blue | user request and hierarchy support one hue family |
| Strict B&W journal output | `classic-technical` | Print-Safe Gray | hard print constraint |
| Human-centered concept diagram | `pastel-airy-ui` or reference-supported `illustrated-modular` | content/reference dependent | distinguish UI cards from narrative zones |
| High-density module detail with no reference | `classic-technical` | Blue Monochrome or accessible custom | detail density and print behavior |
| User: 配色随便 | profile from content; Okabe-Ito/P2/I1 | profile default | safe default branch |

---

## Decision checklist (emit with every Palette Decision)

1. Explicit user constraints recorded.
2. Reference grammar summarized, or `no reference supplied`.
3. Canonical profile: `classic-technical` / `pastel-airy-ui` / `illustrated-modular` / `reference-led`.
4. Hard constraint fired? (print / accessibility / match existing plots).
5. Semantic zones and color carriers identified.
6. Primary + alternate named with exact classic colors or paired tokens.
7. Small-text contrast and grayscale dual encoding checked.
8. Branch stated: `user` / `reference` / `scene` / `default`.


## Palette Decision handoff

Downstream skills consume:

```
style_profile: <classic-technical | pastel-airy-ui | illustrated-modular | reference-led>
style_preset: <named library variant | none>
reference_grammar: <summary | none>
palette_or_token_set: <name>
canvas / body_text / arrow / divider: <hex>
semantic_zone_tokens:
  <role>: {soft_fill: <hex>, dark_outline: <hex>, title_text: <hex>, icon_accent: <hex>}
reason: <one line>
accessibility: colorblind-aware-tested | needs dual encoding/testing | print-only
```

---

## 1. Okabe-Ito — default polychrome

**Use:** general categorical starting palette when several roles need distinct hues; always add non-color cues and test the rendered figure

| role | hex | use |
|------|-----|-----|
| primary | `#0072B2` | core module borders, section labels |
| secondary | `#E69F00` | secondary borders, alternate highlight |
| tertiary | `#009E73` | output / result (sparse) |
| text | `#333333` | body text |
| fill | `#FFFFFF` | canvas / boxes |
| section_bg | `#F7F7F7` | region grouping |
| border | `#767676` | semantic outline (4.54:1 on white) |
| arrow | `#4D4D4D` | arrows / lines |

---

## 2. Blue Monochrome

**Use:** module detail; grayscale-friendly journals

| role | hex |
|------|-----|
| primary | `#1565C0` |
| secondary | `#42A5F5` |
| tertiary | `#90CAF9` |
| text | `#212121` |
| fill | `#FFFFFF` |
| section_bg | `#F5F8FC` |
| border | `#607D8B` |
| arrow | `#37474F` |

---

## 3. Warm Earth

**Use:** explicit earth-toned user/reference direction. Dual-encode; do not infer this palette from a research domain alone.

| role | hex |
|------|-----|
| primary | `#C0392B` |
| secondary | `#E67E22` |
| tertiary | `#F39C12` |
| text | `#2C2C2C` |
| fill | `#FFFFFF` |
| section_bg | `#FDF6EC` |
| border | `#8D6E63` |
| arrow | `#5D4037` |

---

## 4. Purple-Green

**Use:** two-category comparison or ablation when purple/green fits the labels and reference; never bind a hue to “ours” without the spec

| role | hex |
|------|-----|
| primary | `#6A1B9A` |
| secondary | `#2E7D32` |
| tertiary | `#AB47BC` |
| text | `#1A1A1A` |
| fill | `#FFFFFF` |
| section_bg | `#F8F5FC` |
| border | `#7B1FA2` |
| arrow | `#4A148C` |

---

## 5. Grayscale

**Use:** explicit grayscale/print-only requirement or a user-selected austere monochrome treatment

| role | hex |
|------|-----|
| primary | `#212121` |
| secondary | `#616161` |
| tertiary | `#9E9E9E` |
| text | `#111111` |
| fill | `#FFFFFF` |
| section_bg | `#F5F5F5` |
| border | `#757575` |
| arrow | `#424242` |

Distinguish categories by shape / line weight, not hue.

---

## 6. Teal-Coral

**Use:** explicit teal/coral two-category contrast. Dual-encode and test for color-vision deficiencies.

| role | hex |
|------|-----|
| primary | `#00695C` |
| secondary | `#E64A19` |
| tertiary | `#26A69A` |
| text | `#212121` |
| fill | `#FFFFFF` |
| section_bg | `#F0F9F8` |
| border | `#00796B` |
| arrow | `#004D40` |

---

## 7. ML TopConf Tab10

**Use:** match an existing Matplotlib Tab10 experiment palette; do not choose from venue name alone

| role | hex |
|------|-----|
| primary | `#1F77B4` |
| secondary | `#FF7F0E` |
| tertiary | `#2CA02C` |
| text | `#1F2937` |
| fill | `#FFFFFF` |
| section_bg | `#F8FAFC` |
| border | `#64748B` |
| arrow | `#334155` |

---

## 8. ML TopConf Colorblind

**Use:** muted colorblind-aware categorical starting palette; still requires dual encoding and rendered-output checks

| role | hex |
|------|-----|
| primary | `#0173B2` |
| secondary | `#DE8F05` |
| tertiary | `#029E73` |
| text | `#1F2937` |
| fill | `#FFFFFF` |
| section_bg | `#F8FAFC` |
| border | `#64748B` |
| arrow | `#334155` |

---

## 9. ML TopConf Deep

**Use:** multi-panel ablation / dense comparison grids

| role | hex |
|------|-----|
| primary | `#4C72B0` |
| secondary | `#DD8452` |
| tertiary | `#55A868` |
| text | `#1F2937` |
| fill | `#FFFFFF` |
| section_bg | `#F8FAFC` |
| border | `#64748B` |
| arrow | `#334155` |

---

## 10. Print-Safe Gray

**Use:** explicit strict black-and-white print requirement

| role | hex |
|------|-----|
| primary | `#000000` |
| secondary | `#333333` |
| tertiary | `#666666` |
| text | `#333333` |
| fill | `#FFFFFF` |
| section_bg | `#F7F7F7` |
| border | `#666666` |
| arrow | `#4D4D4D` |

---

## 11. Journal Standard

**Use:** figures with several verified categories that genuinely need additional accents; not a journal-name default

| role | hex |
|------|-----|
| primary | `#1F77B4` |
| secondary | `#FF7F0E` |
| tertiary | `#2CA02C` |
| accent1 | `#D62728` |
| accent2 | `#9467BD` |
| accent3 | `#8C564B` |
| text | `#1F2937` |
| fill | `#FFFFFF` |
| section_bg | `#F8FAFC` |
| border | `#64748B` |
| arrow | `#334155` |

Activate only the category colors needed by the current comparison and repeat them consistently.

---

## 12. Nature Blue — restrained monochrome

**Use:** a continuous single-family hierarchy, an explicit restrained-blue direction, matching reference grammar, or verified grayscale-friendly output. Do not select it from module count, venue, or domain alone.

| role | hex |
|------|-----|
| primary | `#1B3A5C` |
| secondary | `#2E6B9E` |
| tertiary | `#5BA0D0` |
| gray | `#8EAEC4` |
| text | `#333333` |
| fill | `#FFFFFF` |
| section_bg | `#F7F7F7` |
| border | `#5B7890` |
| arrow | `#4D4D4D` |

---

## Monochrome vs semantic-zone color

| | monochrome (Blue Monochrome / Nature Blue) | semantic-zone color (Okabe-Ito / I1 / custom pairs) |
|---|---|---|
| visual unity | one hue family | coordinated role-based pairs |
| separation | lightness + border + label | fill/outline pair + label + shape |
| best when | hierarchy within one conceptual family | readers must scan distinct subsystems or decisions |
| print / colorblind | usually robust after value check | robust when dual-encoded and contrast-checked |

---

## Production checks

- Preserve explicit user constraints and reference-image grammar unless accessibility or print requirements require an explained adjustment.
- Use white, near-white, or soft tinted panel surfaces according to the selected profile; tinted semantic zones are valid academic material.
- Use the fewest semantic tokens that keep roles easy to scan, without an arbitrary module-count or three-hue cutoff.
- Dual-encode important categories with label, shape, border, icon, or line style in addition to color.
- Normal-size text and its actual background should meet a 4.5:1 contrast target; do not use pale accent colors for small text.
- Essential outlines, arrow shafts/heads, markers, and focus boundaries should meet a 3:1 graphical contrast target against adjacent colors. Lighter dividers may be decorative only and must not carry meaning.
- Avoid unintentional gradients, glossy 3D chrome, photorealistic decoration, and rainbow ordering. Follow a supplied reference when a different treatment is deliberate and legible.
- Check the downscaled figure and a grayscale preview before handoff.

## Custom palette minimum

```
style_profile: <name>
canvas: #XXXXXX
body_text: #XXXXXX
arrow: #XXXXXX
semantic_zone:
  soft_fill: #XXXXXX
  dark_outline: #XXXXXX
  title_text: #XXXXXX
  icon_accent: #XXXXXX
```

Add only the semantic zones the figure needs. Validate text contrast, colorblind distinguishability, and grayscale reproduction before handoff.

scripts

create_sparse_fixture.py 1.4 KB

#!/usr/bin/env python3
"""Create ref_repos/fixture-sparse: a minimal non-ML scientific repo (no model files, no train entry)."""
import shutil
from pathlib import Path

ROOT = Path(__file__).resolve().parents[2] / "ref_repos" / "fixture-sparse"

README = "# Sparse Scientific Simulator\n\nToy N-body simulator used as a sparse-input fixture.\nNo neural networks, no training scripts.\n"
SIMULATE = '"""Entry point: python simulate.py --steps 100"""\nimport argparse\n\ndef main():\n    p = argparse.ArgumentParser()\n    p.add_argument("--steps", type=int, default=100)\n    a = p.parse_args()\n    print(f"simulated {a.steps} steps")\n\nif __name__ == "__main__":\n    main()\n'
LJ = '"""Lennard-Jones potential."""\n\ndef potential(r: float) -> float:\n    return 4 * (r ** -12 - r ** -6)\n'
INTEGRATOR = '"""Velocity-Verlet integrator."""\n\ndef step(positions, velocities, dt: float):\n    return [p + v * dt for p, v in zip(positions, velocities)], velocities\n'

def main() -> None:
    if ROOT.exists():
        shutil.rmtree(ROOT)
    (ROOT / "src").mkdir(parents=True)
    (ROOT / "README.md").write_text(README, encoding="utf-8")
    (ROOT / "simulate.py").write_text(SIMULATE, encoding="utf-8")
    (ROOT / "src" / "lennard_jones.py").write_text(LJ, encoding="utf-8")
    (ROOT / "src" / "integrator.py").write_text(INTEGRATOR, encoding="utf-8")
    print(f"fixture created: {ROOT}")

if __name__ == "__main__":
    main()

fetch_benchmark_repos.py 2.8 KB

#!/usr/bin/env python3
"""Shallow-clone benchmark repos into git-ignored ref_repos/.

Usage:
  python3 fetch_benchmark_repos.py --manifest ../../examples/benchmarks/manifest.json
  python3 fetch_benchmark_repos.py --manifest <path> --repos nanogpt esm --clean
"""
import argparse
import json
import shutil
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path


def run_git(args, cwd=None):
    return subprocess.run(
        ["git", *args], cwd=cwd, capture_output=True, text=True
    )


def main() -> int:
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("--manifest", required=True)
    parser.add_argument("--repos", nargs="+", default=None, help="subset of repo ids")
    parser.add_argument(
        "--clean", action="store_true", help="delete existing target dirs first"
    )
    args = parser.parse_args()
    root = Path(__file__).resolve().parents[2]
    data = json.loads(Path(args.manifest).read_text(encoding="utf-8"))
    out = root / data["clone_root"]
    out.mkdir(parents=True, exist_ok=True)
    wanted = set(args.repos) if args.repos else None
    results = []
    ok = True
    for repo in data["repos"]:
        if wanted and repo["id"] not in wanted:
            continue
        dest = out / repo["id"]
        if args.clean and dest.exists():
            shutil.rmtree(dest)
        cloned = not dest.exists()
        if cloned:
            clone = run_git(
                [
                    "clone",
                    "--depth",
                    "1",
                    "--filter=blob:none",
                    repo["url"],
                    str(dest),
                ]
            )
            if clone.returncode != 0:
                print(
                    f"clone FAILED {repo['id']}: {clone.stderr.strip()}",
                    file=sys.stderr,
                )
                results.append({"id": repo["id"], "ok": False})
                ok = False
                continue
        head = run_git(["rev-parse", "HEAD"], cwd=dest)
        commit = head.stdout.strip()
        print(f"{repo['id']}: {'cloned' if cloned else 'existing'} @ {commit}")
        results.append(
            {"id": repo["id"], "ok": head.returncode == 0, "commit": commit}
        )
        ok = ok and head.returncode == 0
    log = out / "fetch-log.json"
    log.write_text(
        json.dumps(
            {
                "fetched_at": datetime.now(timezone.utc).isoformat(),
                "manifest": str(args.manifest),
                "results": results,
            },
            indent=2,
        ),
        encoding="utf-8",
    )
    print(f"fetch-log: {log}")
    return 0 if ok else 1


if __name__ == "__main__":
    sys.exit(main())

run_repo_benchmarks.py 10.2 KB

#!/usr/bin/env python3
"""Score repo-analyzer outputs against examples/benchmarks/manifest expectations.

Writes ref_repos/benchmark-report.md. Exit 0 iff every check passes.
"""
import argparse
import json
import re
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import List

ANALYSIS_DIR = "analysis"
LICENSE_FILES = ("LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING", "NOTICE", "LICENCE")

EXPECTED = {
    "stable-diffusion": {
        "framework": ["PyTorch"],
        "task_any": ["diffusion", "latent diffusion", "text-to-image"],
        "paths_any": ["ldm/", "models/"],
        "architecture_any": ["U-Net", "UNet", "autoencoder", "VAE", "CLIP"],
        "module_count": {"source": ["top_level_dirs", "component_scan"], "value_min": 4},
        "completeness_block": True,
        "figure_suggestions": True,
    },
    "nanogpt": {
        "framework": ["PyTorch"],
        "task_any": ["GPT", "transformer", "language model"],
        "paths_any": ["model.py"],
        "architecture_any": ["GPT", "transformer", "attention"],
        "module_count": {"source": ["top_level_dirs"], "value": 1},
        "completeness_block": True,
        "figure_suggestions": True,
    },
    "esm": {
        "framework": ["PyTorch"],
        "task_any": ["protein", "esm"],
        "paths_any": ["esm/"],
        "architecture_any": ["transformer"],
        "module_count": {"source": ["top_level_dirs", "component_scan"], "value_min": 2},
        "completeness_block": True,
        "figure_suggestions": True,
    },
    "alphafold": {
        "framework_any": ["JAX", "Haiku"],
        "task_any": ["protein"],
        "paths_any": ["alphafold/", "alphafold/model/"],
        "architecture_any": ["Evoformer", "structure module", "MSA"],
        "module_count": {"source": ["top_level_dirs", "component_scan"], "value_min": 4},
        "completeness_block": True,
        "figure_suggestions": True,
    },
    "graphcast": {
        "framework_any": ["JAX", "Haiku"],
        "task_any": ["weather", "forecast"],
        "paths_any": ["graphcast/"],
        "architecture_any": ["GNN", "graph neural", "message passing", "GraphCast"],
        "module_count": {"source": ["top_level_dirs", "component_scan"], "value_min": 2},
        "completeness_block": True,
        "figure_suggestions": True,
    },
    "transformers": {
        "framework": ["PyTorch"],
        "task_any": ["transformer", "language model", "LLM"],
        "limited_sample": True,
        "no_keyword_scan_mention": True,
        "module_count": {"source": ["top_level_dirs"], "value_min": 10},
        "completeness_block": True,
        "figure_suggestions": True,
    },
    "fixture-sparse": {
        "entry_script": ["simulate.py"],
        "evidence_insufficient": True,
        "no_keyword_scan_mention": True,
        "module_count": {"source": ["component_scan"], "value": 2},
        "completeness_block": True,
        "figure_suggestions": True,
    },
    "cyclegan": {
        "framework": ["PyTorch"],
        "task_any": ["GAN", "image translation", "image-to-image", "unpaired"],
        "paths_any": ["models/", "data/"],
        "architecture_any": ["generator", "discriminator", "PatchGAN", "ResNet", "cycle"],
        "module_count": {"source": ["top_level_dirs"], "value_min": 4},
        "completeness_block": True,
        "figure_suggestions": True,
    },
    "nerf": {
        "framework_any": ["TensorFlow", "tensorflow"],
        "task_any": ["NeRF", "neural radiance", "volume rendering", "3D", "view synthesis"],
        "paths_any": ["run_nerf.py", "run_nerf_helpers.py"],
        "architecture_any": ["MLP", "positional encoding", "ray", "volume rendering", "render_rays"],
        "module_count": {"source": ["component_scan"], "value_min": 3},
        "completeness_block": True,
        "figure_suggestions": True,
    },
    "detr": {
        "framework": ["PyTorch"],
        "task_any": ["detection", "object detection", "DETR", "transformer"],
        "paths_any": ["models/", "datasets/", "engine.py", "main.py"],
        "architecture_any": ["transformer", "backbone", "object quer", "bipartite", "Hungarian", "matcher", "encoder", "decoder"],
        "module_count": {"source": ["top_level_dirs"], "value_min": 4},
        "completeness_block": True,
        "figure_suggestions": True,
    },
    "whisper": {
        "framework": ["PyTorch"],
        "task_any": ["speech", "ASR", "transcrib", "audio", "Whisper"],
        "paths_any": ["whisper/", "whisper/model.py", "whisper/audio.py", "whisper/decoding.py"],
        "architecture_any": ["encoder", "decoder", "transformer", "attention", "mel", "convolution"],
        "module_count": {"source": ["top_level_dirs"], "value_min": 1},
        "completeness_block": True,
        "figure_suggestions": True,
    },
}

LICENSE_BY_ID = {
    "stable-diffusion": "CreativeML Open RAIL-M",
    "nanogpt": "MIT",
    "esm": "MIT",
    "alphafold": "Apache",
    "graphcast": "Apache",
    "transformers": "Apache",
    "fixture-sparse": None,
    "cyclegan": "Redistribution",
    "nerf": "MIT",
    "detr": "Apache",
    "whisper": "MIT",
}


def load_text(path: Path) -> str:
    return path.read_text(encoding="utf-8") if path.exists() else ""


def has_any(text: str, needles) -> bool:
    low = text.lower()
    return any(needle.lower() in low for needle in needles)


def check(repo_id: str, root: Path, manifest_root: Path) -> List[str]:
    errs = []
    exp = EXPECTED[repo_id]
    repo_dir = manifest_root / repo_id
    analysis = load_text(repo_dir / ANALYSIS_DIR / f"{repo_id}-analysis.md")
    if not analysis:
        return [f"{repo_id}: missing {ANALYSIS_DIR}/{repo_id}-analysis.md"]
    if exp.get("framework") and not has_any(analysis, exp["framework"]):
        errs.append(f"{repo_id}: framework {exp['framework']} not found")
    if exp.get("framework_any") and not has_any(analysis, exp["framework_any"]):
        errs.append(f"{repo_id}: none of {exp['framework_any']} found")
    if exp.get("task_any") and not has_any(analysis, exp["task_any"]):
        errs.append(f"{repo_id}: task keywords {exp['task_any']} not found")
    if exp.get("paths_any") and not has_any(analysis, exp["paths_any"]):
        errs.append(f"{repo_id}: paths {exp['paths_any']} not found")
    if exp.get("architecture_any") and not has_any(analysis, exp["architecture_any"]):
        errs.append(f"{repo_id}: architecture {exp['architecture_any']} not found")
    if exp.get("entry_script") and not has_any(analysis, exp["entry_script"]):
        errs.append(f"{repo_id}: entry script {exp['entry_script']} not found")
    if exp.get("completeness_block") and not has_any(analysis, ["信息完整度", "completeness"]):
        errs.append(f"{repo_id}: completeness block missing")
    if exp.get("figure_suggestions") and not has_any(analysis, ["配图建议", "figure suggestion"]):
        errs.append(f"{repo_id}: figure suggestions missing")
    if exp.get("limited_sample") and not has_any(analysis, ["抽样", "limited sample", "huge repo"]):
        errs.append(f"{repo_id}: limited-sample note missing")
    if exp.get("evidence_insufficient") and not has_any(
        analysis, ["证据不足", "evidence insufficient"]
    ):
        errs.append(f"{repo_id}: evidence-insufficient label missing")
    if exp.get("no_keyword_scan_mention") and re.search(r"keyword.scan", analysis, re.I):
        errs.append(
            f"{repo_id}: analysis mentions keyword-scan (internal method, must not leak)"
        )
    module_count = exp.get("module_count")
    if module_count:
        match = re.search(
            r"module_count[^\n]*?source:\s*([A-Za-z_]+)[^\n]*?value:\s*(\d+)",
            analysis,
        )
        if not match:
            errs.append(
                f"{repo_id}: handoff module_count line missing "
                "(need 'module_count' + 'source:' + 'value:')"
            )
        else:
            source, value = match.group(1), int(match.group(2))
            if source not in module_count["source"]:
                errs.append(
                    f"{repo_id}: module_count source={source} not in {module_count['source']}"
                )
            if "value" in module_count and value != module_count["value"]:
                errs.append(
                    f"{repo_id}: module_count value={value} != {module_count['value']}"
                )
            if "value_min" in module_count and value < module_count["value_min"]:
                errs.append(
                    f"{repo_id}: module_count value={value} < {module_count['value_min']}"
                )
    license_name = LICENSE_BY_ID[repo_id]
    if license_name:
        if not any((repo_dir / filename).exists() for filename in LICENSE_FILES):
            errs.append(f"{repo_id}: no LICENSE-like file found in clone")
        elif not has_any(
            "\n".join(
                load_text(repo_dir / filename)
                for filename in LICENSE_FILES
                if (repo_dir / filename).exists()
            ),
            [license_name],
        ):
            errs.append(f"{repo_id}: license text does not contain '{license_name}'")
    return errs


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--manifest", required=True)
    parser.add_argument("--repos", nargs="+", default=None)
    args = parser.parse_args()
    root = Path(__file__).resolve().parents[2]
    data = json.loads(Path(args.manifest).read_text(encoding="utf-8"))
    base = root / data["clone_root"]
    repo_ids = [repo["id"] for repo in data["repos"]] + [
        fixture["id"] for fixture in data.get("synthetic_fixtures", [])
    ]
    if args.repos:
        repo_ids = [repo_id for repo_id in repo_ids if repo_id in set(args.repos)]
    all_errs = []
    for repo_id in repo_ids:
        all_errs.extend(check(repo_id, root, base))
    report = base / "benchmark-report.md"
    lines = [
        "# Repo Benchmark Report",
        f"- generated: {datetime.now(timezone.utc).isoformat()}",
        f"- repos: {len(repo_ids)}",
        f"- result: {'PASS' if not all_errs else 'FAIL'}",
        "",
    ]
    lines += [f"- [FAIL] {error}" for error in all_errs] or ["- all checks passed"]
    report.write_text("\n".join(lines) + "\n", encoding="utf-8")
    print("\n".join(lines))
    return 0 if not all_errs else 1


if __name__ == "__main__":
    sys.exit(main())

keywords.md 2.2 KB

# Repo Analyzer Keywords

Load when classifying task type, stack, or architecture.

## Task type

| type | keywords | file cues |
|------|----------|-----------|
| CV | image, cv2, PIL, resnet, vit, unet, detection, segmentation, classification | image datasets; torchvision, mmcv |
| NLP | text, token, bert, gpt, transformer, llm, sentence, corpus | transformers, datasets, tokenizers |
| Speech/Audio | asr, speech, audio, transcription, whisper, tts, mel-spectrogram, voice | audio.py, mel filters, ffmpeg, decoder |
| RL | policy, agent, environment, reward, ppo, dqn, sac, gym, env | env loop; reward fn |
| Robotics | robot, kinematics, dynamics, simulation, gazebo, ros, control | physics sim; robot models |
| Multimodal | image-text, vision-language, clip, multimodal, cross-modal | dual image+text paths |
| Time series | timeseries, forecast, temporal, sequence, lstm, gru | temporal dims |
| Generative | gan, diffusion, vae, generative, generation, synthesize | generator / diffusion loop |
| Protein / AI4Science | protein, esm, alphafold, evoformer, MSA, folding, sequence embedding | pdb/mmCIF inputs; `alphafold/`, `esm/` packages |
| GNN / Scientific computing | gnn, graph neural, message passing, graphcast, weather, forecast | grid/graph datasets; jax + haiku |

## Frameworks

| framework | cues |
|-----------|------|
| PyTorch | `import torch`, `nn.Module` |
| TensorFlow | `import tensorflow`, `tf.keras` |
| JAX/Flax/Haiku | `import jax`, flax, haiku, optax |
| MxNet | `import mxnet`, gluon |
| PaddlePaddle | `import paddle` |

## Aux libraries

- CV: torchvision, mmcv, detectron2, albumentations
- NLP: transformers, datasets, tokenizers, nltk, spacy
- Speech: librosa, torchaudio, ffmpeg, tiktoken
- RL: gym, stable-baselines3, ray[rllib]
- Science: numpy, scipy, pandas, matplotlib
- Tracking: wandb, mlflow, tensorboard
- Distributed: torch.distributed, deepspeed, accelerate

## Architecture tokens

Transformer, Attention, Self-Attention, Cross-Attention, CNN, ResNet, ViT, Swin, U-Net, FPN, RNN, LSTM, GRU, Seq2Seq, GNN, GCN, GAT, GAN, Diffusion, VAE, Flow

## Algorithm dig sites

- losses: `loss =`, `criterion =`, `loss_fn`
- novel modules / nonstandard layer names
- augmentation pipeline
- optimizers / LR schedules

SKILL.md 6.2 KB

---
name: academic-repo-analyzer
description: Analyze ML, AI4Science, Systems, and research repositories into an evidence-backed semantic architecture graph for paper figure planning. Code serves as supporting evidence; paper narrative and user intent remain the primary source of truth.
metadata:
  version: "1.5.0"
  stages: [research, review]
---

# Academic Repo Analyzer

Produce a concise repository understanding document plus a machine-readable **Semantic Architecture Handoff v1**. The handoff describes scientific roles and executable relationships, not the repository's folder layout or engineering boilerplate.

Read `keywords.md` only when task or framework classification is uncertain. Read `references/missing-info-policy.md` when evidence is sparse.

## Core Principle: Narrative Priority & Non-Intrusive Extraction

1. **Paper & User Narrative > Code Implementation**:
   - A paper figure depicts the **scientific contribution and conceptual data flow**, not the full software engineering artifact.
   - Omit engineering plumbing (such as `DataLoader`, `Trainer`, `Logger`, `ConfigParser`, `DeviceManager`, or `Optimizer` setup) unless the paper specifically contributes a training algorithm or infrastructure system.
2. **Fact-Checking & Parameter Grounding**:
   - When a paper draft or user architecture is already present, the repo analyzer acts as a **supporting fact-checker** (verifying tensor dimensions, loss formulas, exact module names, and execution directions) rather than re-inventing the architecture.

## Input contract

- Prefer: repository path, README, dependencies, entry points, core model/algorithm files, configs, and tests that establish behavior.
- Accept: partial repository, isolated model files, core algorithm script.
- Minimum: one README, entry point, or core implementation file.
- Record the source revision when Git metadata is available.
- Treat names and README claims as leads; verify figure-critical claims in code or tests.

## Output contract

Keep the human summary to roughly 30–70 lines, then emit the handoff block below.

1. Repository overview and scientific task.
2. Evidence/completeness statement listing what was inspected.
3. Semantic components and their responsibilities.
4. Executed/advisory/feedback/persistence connections.
5. Authority or trust boundaries when agents, tools, evaluators, or external systems are involved.
6. Figure suggestions (Overall Framework, Network Architecture, Module Detail, Concept/Motivation, Protocol/Sequence).
7. `Semantic Architecture Handoff v1`.

## Workflow

### 1. Locate evidence

Find the README, dependency files, entry scripts (`train`, `main`, `eval`, `inference`, `predict`, `run`, `simulate`, `benchmark`), configs, and core algorithm files. Top-level directories are discovery cues only; they are never counted as architecture modules.

For a large repository, inspect the top level and a justified sample of core files. State the sampling boundary. Do not claim full coverage from keyword hits.

### 2. Classify task and implementation stack

Identify the scientific objective, primary framework, data/experiment interface, and main execution path with file or symbol evidence. Mark unsupported inferences explicitly.

### 3. Build the semantic graph

Create one component only when it has a distinct scientific or execution responsibility that belongs in a paper figure. A component may span several files, and one file may implement several components.

For every component record:

- stable `id` and short display `label`;
- `role`:
  - **General ML / Deep Learning**: `input_data`, `encoder_backbone`, `fusion_interaction`, `loss_objective`, `task_head`, `model`, `output`;
  - **Agentic / Interactive**: `reasoning`, `decision`, `deterministic_execution`, `observation`, `memory`, `persistence`, `advisory`, `exception`;
  - **Systems / Modular**: `source`, `scheduler`, `processor`, `storage`, `sink`, `other`;
- `figure_importance`: `primary` or `secondary`;
- evidence pointers such as `path:line`, class, function, test, or config key;
- one-sentence responsibility and explicit non-authority when scientifically important.

Record connections separately. Use `executed`, `advisory`, `feedback`, `persistence`, or `exception` as the connection kind. Do not infer an edge solely because two files import each other.

### 4. Derive visual groups

Group related components by responsibility or narrative stage. Report:

- `semantic_component_count`: number of evidence-backed components;
- `visual_group_count`: number of meaningful regions in the proposed figure;
- `peer_module_count`: largest set of genuinely equivalent sibling components.

These counts help layout planning. None of them selects a palette by itself.

### 5. Emit the handoff

```json
{
  "schema": "academic-figure/SemanticArchitecture@1",
  "source_revision": "<commit-or-unknown>",
  "domain": "<controlled-domain>",
  "evidence_level": "high|partial|sparse",
  "components": [
    {
      "id": "backbone",
      "label": "Encoder Backbone",
      "role": "encoder_backbone",
      "figure_importance": "primary",
      "responsibility": "Extracts multi-scale feature representations.",
      "evidence": ["models/backbone.py:ResNet"]
    }
  ],
  "connections": [
    {
      "from": "input_data",
      "to": "backbone",
      "kind": "executed",
      "label": "raw inputs",
      "evidence": ["models/pipeline.py:forward"]
    }
  ],
  "authority_boundaries": [],
  "semantic_component_count": 1,
  "visual_group_count": 1,
  "peer_module_count": 0,
  "figure_types": ["Overall Framework"],
  "forbidden_claims": ["<claims the figure must not imply>"]
}
```

Controlled domain: `CV`, `NLP`, `Speech/Audio`, `RL`, `Robotics`, `Multimodal`, `TimeSeries`, `Generative`, `Protein/AI4Science`, `GNN/ScientificComputing`, `Systems/Infrastructure`, `ScientificComputing(non-ML)`, or `Other`.

## Sparse evidence

- No README: infer cautiously from code and label the inference.
- No entry point: limit the result to component-level structure.
- No core implementation: report task/stack only and omit unsupported edges.
- Almost empty repository: provide the minimum missing materials instead of inventing an architecture.

## Stop

Stop when the human summary and valid handoff are delivered. Suggest figure planning only when the user wants the next stage.