Hoi Model Analysis

Install the required Python packages:

# Option A: pip
pip install torch numpy matplotlib hoi

# Option B: uv
uv add torch numpy matplotlib hoi

No pip package installation is needed for this skill itself -- the scripts are self-contained and run directly with python.

Workflow

Follow these phases in order. Do NOT skip the information-gathering phase.

Phase 1: Gather Information

Ask the user these questions (one at a time, use the question tool):

1. Model location: "Where is your PyTorch model defined? I need a Python file with a build_model() function that returns a torch.nn.Module."

   • If the user has an existing model file, check it defines build_model().
   • If not, help them create model.py using references/model-template.py as a starting point.

2. Inference runner: "Do you have a script that runs inference on your model? I need a Python file with a run(model, data_path, *, max_batches=None) function that yields batch info during forward passes."

   • If the user has an existing runner, check it defines run() with the correct signature.
   • If not, help them create run.py using references/run-template.py as a starting point.

3. Data path: "Where is the data your model processes?"

4. Analysis goal (use question tool with choices):

   • "Which layers interact most similarly?" -> cross-layer scalar analysis
   • "What are the internal information patterns within each layer?" -> within-layer PCA analysis
   • "Both / not sure" -> start with cross-layer, suggest within-layer as follow-up

Phase 2: Validate Inputs

Before running the pipeline, validate:

# 1. Check model loads and list layers
python scripts/probe.py --model <model.py>

• If this fails with AttributeError: model.py is missing build_model(). Help the user fix it.
• If it succeeds: show the layer list to the user and ask which layers to analyze. Save chosen layers to layers.txt (one per line).

Layer selection guidance:

• For cross-layer analysis: select 3+ layers (more is better, but > 20 gets slow). Suggest picking layers from different depths (early, middle, late).
• For within-layer PCA: each selected layer must produce activations with dimensionality >= 3 (otherwise PCA with k=3 is impossible).
• Default: use all probed layers if <= 10, otherwise pick every N-th layer to get ~10 layers.

Phase 3: Extract Activations

Choose the right mode based on Phase 1 analysis goal:

Cross-layer analysis (scalar mode):

python scripts/extract.py \
  --model <model.py> \
  --run <run.py> \
  --data <data_path> \
  --layers layers.txt \
  --agg l2 \
  --out outputs/<run_id>/ \
  --repr scalar

Within-layer analysis (PCA mode):

python scripts/extract.py \
  --model <model.py> \
  --run <run.py> \
  --data <data_path> \
  --layers layers.txt \
  --out outputs/<run_id>/ \
  --repr pca \
  --pca-k 5

• --pca-k: number of PCA components per layer. Use 5 as default; increase for wide layers, decrease if layers have low dimensionality.
• --max-batches N: limit inference batches for large datasets. Suggest 50-100 for initial exploration.
• --agg: only applies in scalar mode. l2 (default) uses L2 norm, mean uses mean. Recommend l2 unless user has a reason to prefer mean.

Common errors:

• "Unknown layer name(s)": layer names in layers.txt don't match probe output. Re-run probe and fix the file.
• "No tensor found for layer": the layer's forward hook didn't capture a tensor. Try a different layer.
• "pca_k is required when repr='pca'": add --pca-k.

Phase 4: Analyze

Cross-layer:

python scripts/analyze.py \
  --activations outputs/<run_id>/activations.npz \
  --out outputs/<run_id>/ \
  --n-best 10 \
  --scope cross-layer

Within-layer:

python scripts/analyze.py \
  --activations outputs/<run_id>/activations.npz \
  --out outputs/<run_id>/ \
  --n-best 10 \
  --scope within-layer

Common errors:

• "Need at least 3 variables": not enough layers/components. Go back to Phase 2 and select more layers, or increase --pca-k.
• "Layer X has N variables, need at least 3": for within-layer mode, that layer has fewer than 3 PCA components. Either increase --pca-k or exclude that layer.

Phase 5: Interpret Results

After analysis completes, read the outputs and explain them to the user:

1. Read report.md - summarize key findings.

2. Read top_multiplets.json - explain the top triplets:

   • Redundant triplets (positive O-info): these layer groups share overlapping information. They encode similar features. In a model compression context, some of these layers might be safely prunable.
   • Synergistic triplets (negative O-info): these layer groups combine information in ways that cannot be decomposed into pairwise interactions. They form an "information integration core" - critical for complex reasoning.

3. Show plots if the user's environment supports it:

   • top_multiplets.png - bar chart of most redundant (red) and synergistic (blue) triplets.
   • oinfo_distribution.png - histogram showing the overall distribution of O-information values.
   • For within-layer: layer_comparison.png - comparison of max redundancy/synergy across layers.

4. Suggest next steps based on results:

   • If strong redundancy found: "You might explore pruning the highly redundant layers, or investigate why they encode similar information."
   • If strong synergy found: "The synergistic layers form a critical information integration core. These are likely essential for your model's complex behaviors."
   • If user did cross-layer only: "For deeper insight, try within-layer PCA analysis to see how information is structured inside individual layers."
   • If user wants to go further: mention PhiID analysis as a future capability (see references/phiid-future.md).

Convenience: Full Pipeline

For users who want to skip the step-by-step workflow (e.g., re-running with different parameters), use the pipeline script:

python scripts/run_pipeline.py \
  --model <model.py> \
  --run <run.py> \
  --data <data_path> \
  --out outputs/<run_id>/ \
  --repr scalar \
  --scope cross-layer \
  --n-best 10

This chains probe -> extract -> analyze automatically. If --layers is omitted, it uses the first 10 probed layers.

Reference

• references/cli-contract.md - complete CLI interface specification
• references/model-template.py - template for creating model.py
• references/run-template.py - template for creating run.py
• references/phiid-future.md - future PhiID extension roadmap
• examples/mini_torch_model/ - minimal working example

Key Concepts (for explaining to users)

• O-information (Oinfo): A measure that quantifies whether a group of variables (layers) interact redundantly or synergistically. Positive = redundancy, negative = synergy.
• Triplets: The analysis examines all combinations of 3 variables at a time (minsize=maxsize=3), which is the minimal unit for detecting higher-order effects beyond pairwise correlations.
• Gaussian Copula (gc): The estimation method used. It assumes the joint distribution can be modeled via a Gaussian copula, which is efficient and works well for continuous activations.
• Scalar vs PCA: Scalar mode collapses each layer to a single number per sample (good for cross-layer comparison). PCA mode preserves multiple dimensions per layer (good for analyzing within-layer structure).