# anilkumara9/scbi architecture

> Architecture diagram of the GitHub repository anilkumara9/scbi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anilkumara9/scbi
- Repository: https://github.com/anilkumara9/scbi

## Overview

SCBI is a research framework for testing whether inference-time representation changes can improve a frozen foundation model. Its core runtime accepts hidden activations, constructs candidate subspaces, scores and selects one, then returns projected activations while checking that model parameters remain unchanged. The repository also contains a broad experimental program, including candidate-generator studies, routing and intervention benchmarks, and cross-model replications. The README describes a larger research architecture than the supplied tree; this map focuses on the implemented package and visible experiment scripts. Some experiment wiring is therefore omitted.

Main entry points: [`scbi/core/engine.py`](https://github.com/anilkumara9/scbi/blob/main/scbi/core/engine.py) (Inference engine), [`scbi/core/frozen_model.py`](https://github.com/anilkumara9/scbi/blob/main/scbi/core/frozen_model.py) (Frozen wrapper), [`scbi/core/basis.py`](https://github.com/anilkumara9/scbi/blob/main/scbi/core/basis.py) (Subspace basis), [`scbi/baselines/matched_baseline.py`](https://github.com/anilkumara9/scbi/blob/main/scbi/baselines/matched_baseline.py) (Matched baseline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["SCBI core"]
  node_engine["Inference engine<br/>[engine.py]"]
  node_frozen_wrapper["Frozen wrapper<br/>[frozen_model.py]"]
  node_basis["Subspace basis<br/>[basis.py]"]
end

subgraph group_methods["Generators and baselines"]
  node_activation_generators["Activation generators"]
  node_matched_baseline["Matched baseline"]
end

subgraph group_research["Experiments"]
  node_controller_landscape["Controller landscape"]
  node_applicability_router["Applicability routing"]
  node_candidate_studies["Candidate studies"]
  node_causal_studies["Causal interventions"]
  node_transfer_studies["Transfer replication"]
  node_experiment_scripts["Experiment suite"]
end

node_researcher(("Researcher"))
node_activations["Hidden activations"]
node_foundation_model["Foundation model"]

node_researcher -->|"runs inference"| node_engine
node_activations -->|"provides input"| node_engine
node_foundation_model -->|"wrapped by"| node_frozen_wrapper
node_engine -->|"checks immutability"| node_frozen_wrapper
node_engine -->|"generates candidates"| node_basis
node_engine -->|"projects activations"| node_basis
node_engine -->|"scores and selects"| node_engine
node_researcher -->|"runs studies"| node_experiment_scripts
node_controller_landscape -->|"evaluates interventions"| node_foundation_model
node_applicability_router -->|"evaluates routing"| node_foundation_model
node_candidate_studies -->|"characterizes"| node_activation_generators
node_causal_studies -->|"tests interventions"| node_foundation_model
node_transfer_studies -->|"replicates on"| node_foundation_model
node_matched_baseline -->|"checks immutability"| node_frozen_wrapper

click node_engine "https://github.com/anilkumara9/scbi/blob/main/scbi/core/engine.py"
click node_frozen_wrapper "https://github.com/anilkumara9/scbi/blob/main/scbi/core/frozen_model.py"
click node_basis "https://github.com/anilkumara9/scbi/blob/main/scbi/core/basis.py"
click node_activation_generators "https://github.com/anilkumara9/scbi/blob/main/scbi/generators/activation_cluster.py"
click node_matched_baseline "https://github.com/anilkumara9/scbi/blob/main/scbi/baselines/matched_baseline.py"
click node_controller_landscape "https://github.com/anilkumara9/scbi/blob/main/experiments/scripts/run_exp030_controller_landscape.py"
click node_applicability_router "https://github.com/anilkumara9/scbi/blob/main/experiments/scripts/run_exp042_applicability_router.py"
click node_candidate_studies "https://github.com/anilkumara9/scbi/blob/main/experiments/scripts/run_exp015a_generator_characterization.py"
click node_causal_studies "https://github.com/anilkumara9/scbi/blob/main/experiments/scripts/run_exp029b_loss_of_function.py"
click node_transfer_studies "https://github.com/anilkumara9/scbi/blob/main/experiments/scripts/run_exp066_pythia410m_replication.py"
click node_experiment_scripts "https://github.com/anilkumara9/scbi/tree/main/experiments/scripts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_engine,node_frozen_wrapper,node_basis toneBlue
class node_activation_generators,node_matched_baseline toneAmber
class node_controller_landscape,node_applicability_router,node_candidate_studies,node_causal_studies,node_transfer_studies,node_experiment_scripts toneMint
class node_researcher,node_activations,node_foundation_model toneIndigo
```

## Components

### SCBI core

- [Inference engine](https://github.com/anilkumara9/scbi/blob/main/scbi/core/engine.py): `scbi/core/engine.py`
- [Frozen wrapper](https://github.com/anilkumara9/scbi/blob/main/scbi/core/frozen_model.py): `scbi/core/frozen_model.py`
- [Subspace basis](https://github.com/anilkumara9/scbi/blob/main/scbi/core/basis.py): `scbi/core/basis.py`

### Generators and baselines

- [Activation generators](https://github.com/anilkumara9/scbi/blob/main/scbi/generators/activation_cluster.py): `scbi/generators/activation_cluster.py`
- [Matched baseline](https://github.com/anilkumara9/scbi/blob/main/scbi/baselines/matched_baseline.py): `scbi/baselines/matched_baseline.py`

### Experiments

- [Controller landscape](https://github.com/anilkumara9/scbi/blob/main/experiments/scripts/run_exp030_controller_landscape.py): `experiments/scripts/run_exp030_controller_landscape.py`
- [Applicability routing](https://github.com/anilkumara9/scbi/blob/main/experiments/scripts/run_exp042_applicability_router.py): `experiments/scripts/run_exp042_applicability_router.py`
- [Candidate studies](https://github.com/anilkumara9/scbi/blob/main/experiments/scripts/run_exp015a_generator_characterization.py): `experiments/scripts/run_exp015a_generator_characterization.py`
- [Causal interventions](https://github.com/anilkumara9/scbi/blob/main/experiments/scripts/run_exp029b_loss_of_function.py): `experiments/scripts/run_exp029b_loss_of_function.py`
- [Transfer replication](https://github.com/anilkumara9/scbi/blob/main/experiments/scripts/run_exp066_pythia410m_replication.py): `experiments/scripts/run_exp066_pythia410m_replication.py`
- [Experiment suite](https://github.com/anilkumara9/scbi/tree/main/experiments/scripts): `experiments/scripts`

### Other components

- **Researcher**
- **Hidden activations**
- **Foundation model**

## Connections

- Researcher → Inference engine: runs inference
- Hidden activations → Inference engine: provides input
- Foundation model → Frozen wrapper: wrapped by
- Inference engine → Frozen wrapper: checks immutability
- Inference engine → Subspace basis: generates candidates
- Inference engine → Subspace basis: projects activations
- Inference engine → Inference engine: scores and selects
- Researcher → Experiment suite: runs studies
- Controller landscape → Foundation model: evaluates interventions
- Applicability routing → Foundation model: evaluates routing
- Candidate studies → Activation generators: characterizes
- Causal interventions → Foundation model: tests interventions
- Transfer replication → Foundation model: replicates on
- Matched baseline → Frozen wrapper: checks immutability