# a-n-u-p-a-m/ire_project architecture

> Architecture diagram of the GitHub repository a-n-u-p-a-m/ire_project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/a-n-u-p-a-m/ire_project
- Repository: https://github.com/a-n-u-p-a-m/ire_project

## Overview

This repository is a research framework for measuring counterfactual effects in cascaded information retrieval and testing budget-aware repairs. The workflow builds and freezes a retrieval universe, prepares relevance and Stage-1/Stage-2 scores, constructs counterfactual ranking worlds and budget allocations, computes document-level effects, then analyzes query diagnoses and predictor fidelity. Shared modules implement the experiment’s data contracts, ranking semantics, and metrics; separate experiment directories provide real-data and synthetic runners. Several experiment paths are documented or indexed but not fully sampled, so their internal steps are omitted.

Main entry points: [`experiments_shubham/engine.py`](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_shubham/engine.py) (Effect engine), [`shared/worlds.py`](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/worlds.py) (Ranking worlds), [`experiments_anupam/build_universe.py`](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_anupam/build_universe.py) (Real data prep), [`shared/effects.py`](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/effects.py) (Document effects)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and design"]
  node_config["Design config<br/>[config.py]"]
  node_schema["Table contracts<br/>[schema.py]"]
  node_qrels["Relevance labels<br/>[qrels.py]"]
  node_universe[("Frozen universe<br/>[universe.py]")]
  node_provenance["Run provenance<br/>[provenance.py]"]
end

subgraph group_semantics["Counterfactual core"]
  node_allocation["Budget allocation<br/>[allocation.py]"]
  node_worlds["Ranking worlds<br/>[worlds.py]"]
  node_ordering["Ranking order<br/>[ordering.py]"]
  node_utility["Rank utility<br/>[utility.py]"]
  node_effects["Document effects<br/>[effects.py]"]
  node_strata["Effect strata<br/>[strata.py]"]
end

subgraph group_experiments["Experiment runners"]
  node_retrievers["Stage-1 retrieval<br/>[retrievers.py]"]
  node_realprep["Real data prep<br/>[build_universe.py]"]
  node_stage1["Stage-1 runs"]
  node_engine["Effect engine<br/>[engine.py]"]
  node_synthetic["Synthetic data<br/>[synthetic.py]"]
  node_realrun["Real-data runner<br/>[real.py]"]
end

subgraph group_analysis["Analysis and prediction"]
  node_diagnosis["Query diagnosis<br/>[diagnosis.py]"]
  node_h7power["H7 power<br/>[power_h7.py]"]
  node_analysis["Effect analysis<br/>[analysis.py]"]
  node_features["Predictor features<br/>[features.py]"]
  node_predictors["Effect predictors<br/>[predictors.py]"]
  node_metrics["Fidelity metrics<br/>[metrics.py]"]
  node_baselines["Predictor baselines<br/>[baselines.py]"]
end

subgraph group_scoring["Stage-2 scoring"]
  node_stage2cache[("Stage-2 cache<br/>[cache.py]")]
  node_passages["Passage fetch<br/>[passage_fetcher.py]"]
  node_reranker["Cross-encoder<br/>[reranker.py]"]
  node_cachefill["Cache filling<br/>[cache_filler.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"prepares data"| node_realprep
node_realprep -->|"builds and freezes"| node_universe
node_realprep -->|"loads labels"| node_qrels
node_stage1 -->|"runs retrieval"| node_retrievers
node_stage1 -->|"uses universe"| node_universe
node_cachefill -->|"fetches passages"| node_passages
node_cachefill -->|"scores passages"| node_reranker
node_cachefill -->|"writes scores"| node_stage2cache
node_engine -->|"builds worlds"| node_worlds
node_engine -->|"computes effects"| node_effects
node_engine -->|"runs synthetic"| node_synthetic
node_engine -->|"runs budget cases"| node_allocation
node_worlds -->|"allocates candidates"| node_allocation
node_worlds -->|"orders rankings"| node_ordering
node_effects -->|"scores ranks"| node_utility
node_effects -->|"compares worlds"| node_worlds
node_realrun -->|"runs real effects"| node_engine
node_realrun -->|"reads scores"| node_stage2cache
node_analysis -->|"diagnoses queries"| node_diagnosis
node_analysis -->|"tests H7"| node_h7power
node_diagnosis -->|"uses reference worlds"| node_worlds
node_h7power -->|"sizes H7 sample"| node_diagnosis
node_features -->|"reads scores"| node_stage2cache
node_predictors -->|"compares baselines"| node_baselines
node_predictors -->|"evaluates fidelity"| node_metrics
node_metrics -->|"evaluates by stratum"| node_strata
node_config -.->|"configures tables"| node_schema
node_engine -.->|"loads design"| node_config
node_analysis -->|"reads effect tables"| node_effects
node_predictors -->|"uses features"| node_features
node_realprep -->|"records design"| node_provenance

click node_config "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/config.py"
click node_schema "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/schema.py"
click node_qrels "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/qrels.py"
click node_universe "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/universe.py"
click node_provenance "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/provenance.py"
click node_retrievers "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_anupam/retrievers.py"
click node_realprep "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_anupam/build_universe.py"
click node_stage1 "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_anupam/stage1_over_universe.py"
click node_stage2cache "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/cache.py"
click node_passages "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_chaitanya/passage_fetcher.py"
click node_reranker "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_chaitanya/reranker.py"
click node_cachefill "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_chaitanya/cache_filler.py"
click node_allocation "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/allocation.py"
click node_worlds "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/worlds.py"
click node_ordering "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/ordering.py"
click node_utility "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/utility.py"
click node_effects "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/effects.py"
click node_engine "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_shubham/engine.py"
click node_synthetic "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/synthetic.py"
click node_realrun "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_shubham/real.py"
click node_diagnosis "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/diagnosis.py"
click node_h7power "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_shubham/power_h7.py"
click node_analysis "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_shubham/analysis.py"
click node_features "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_chaitanya/features.py"
click node_predictors "https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_chaitanya/predictors.py"
click node_metrics "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/metrics.py"
click node_baselines "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/baselines.py"
click node_strata "https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/strata.py"

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_config,node_schema,node_qrels,node_universe,node_provenance toneBlue
class node_allocation,node_worlds,node_ordering,node_utility,node_effects,node_strata toneAmber
class node_retrievers,node_realprep,node_stage1,node_engine,node_synthetic,node_realrun toneMint
class node_diagnosis,node_h7power,node_analysis,node_features,node_predictors,node_metrics,node_baselines toneRose
class node_stage2cache,node_passages,node_reranker,node_cachefill,node_researcher toneIndigo
```

## Components

### Data and design

- [Design config](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/config.py): `shared/config.py`
- [Table contracts](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/schema.py): `shared/schema.py`
- [Relevance labels](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/qrels.py): `shared/qrels.py`
- [Frozen universe](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/universe.py): `shared/universe.py`
- [Run provenance](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/provenance.py): `shared/provenance.py`

### Counterfactual core

- [Budget allocation](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/allocation.py): `shared/allocation.py`
- [Ranking worlds](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/worlds.py): `shared/worlds.py`
- [Ranking order](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/ordering.py): `shared/ordering.py`
- [Rank utility](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/utility.py): `shared/utility.py`
- [Document effects](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/effects.py): `shared/effects.py`
- [Effect strata](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/strata.py): `shared/strata.py`

### Experiment runners

- [Stage-1 retrieval](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_anupam/retrievers.py): `experiments_anupam/retrievers.py`
- [Real data prep](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_anupam/build_universe.py): `experiments_anupam/build_universe.py`
- [Stage-1 runs](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_anupam/stage1_over_universe.py): `experiments_anupam/stage1_over_universe.py`
- [Effect engine](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_shubham/engine.py): `experiments_shubham/engine.py`
- [Synthetic data](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/synthetic.py): `shared/synthetic.py`
- [Real-data runner](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_shubham/real.py): `experiments_shubham/real.py`

### Analysis and prediction

- [Query diagnosis](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/diagnosis.py): `shared/diagnosis.py`
- [H7 power](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_shubham/power_h7.py): `experiments_shubham/power_h7.py`
- [Effect analysis](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_shubham/analysis.py): `experiments_shubham/analysis.py`
- [Predictor features](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_chaitanya/features.py): `experiments_chaitanya/features.py`
- [Effect predictors](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_chaitanya/predictors.py): `experiments_chaitanya/predictors.py`
- [Fidelity metrics](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/metrics.py): `shared/metrics.py`
- [Predictor baselines](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/baselines.py): `shared/baselines.py`

### Stage-2 scoring

- [Stage-2 cache](https://github.com/a-n-u-p-a-m/ire_project/blob/main/shared/cache.py): `shared/cache.py`
- [Passage fetch](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_chaitanya/passage_fetcher.py): `experiments_chaitanya/passage_fetcher.py`
- [Cross-encoder](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_chaitanya/reranker.py): `experiments_chaitanya/reranker.py`
- [Cache filling](https://github.com/a-n-u-p-a-m/ire_project/blob/main/experiments_chaitanya/cache_filler.py): `experiments_chaitanya/cache_filler.py`

### Other components

- **Researcher**

## Connections

- Researcher → Real data prep: prepares data
- Real data prep → Frozen universe: builds and freezes (evidence: `experiments_anupam/build_universe.py`)
- Real data prep → Relevance labels: loads labels (evidence: `experiments_anupam/build_universe.py`)
- Stage-1 runs → Stage-1 retrieval: runs retrieval (evidence: `experiments_anupam/stage1_over_universe.py`)
- Stage-1 runs → Frozen universe: uses universe (evidence: `experiments_anupam/stage1_over_universe.py`)
- Cache filling → Passage fetch: fetches passages (evidence: `experiments_chaitanya/cache_filler.py`)
- Cache filling → Cross-encoder: scores passages (evidence: `experiments_chaitanya/cache_filler.py`)
- Cache filling → Stage-2 cache: writes scores (evidence: `experiments_chaitanya/cache_filler.py`)
- Effect engine → Ranking worlds: builds worlds (evidence: `experiments_shubham/engine.py`)
- Effect engine → Document effects: computes effects (evidence: `experiments_shubham/engine.py`)
- Effect engine → Synthetic data: runs synthetic (evidence: `experiments_shubham/engine.py`)
- Effect engine → Budget allocation: runs budget cases (evidence: `experiments_shubham/engine.py`)
- Ranking worlds → Budget allocation: allocates candidates (evidence: `shared/worlds.py`)
- Ranking worlds → Ranking order: orders rankings (evidence: `shared/worlds.py`)
- Document effects → Rank utility: scores ranks (evidence: `shared/effects.py`)
- Document effects → Ranking worlds: compares worlds (evidence: `shared/effects.py`)
- Real-data runner → Effect engine: runs real effects (evidence: `experiments_shubham/real.py`)
- Real-data runner → Stage-2 cache: reads scores (evidence: `experiments_shubham/real.py`)
- Effect analysis → Query diagnosis: diagnoses queries (evidence: `experiments_shubham/analysis.py`)
- Effect analysis → H7 power: tests H7 (evidence: `experiments_shubham/analysis.py`)
- Query diagnosis → Ranking worlds: uses reference worlds (evidence: `shared/diagnosis.py`)
- H7 power → Query diagnosis: sizes H7 sample (evidence: `experiments_shubham/power_h7.py`)
- Predictor features → Stage-2 cache: reads scores (evidence: `experiments_chaitanya/features.py`)
- Effect predictors → Predictor baselines: compares baselines (evidence: `experiments_chaitanya/predictors.py`)
- Effect predictors → Fidelity metrics: evaluates fidelity (evidence: `experiments_chaitanya/predictors.py`)
- Fidelity metrics → Effect strata: evaluates by stratum (evidence: `shared/metrics.py`)
- Design config → Table contracts: configures tables
- Effect engine → Design config: loads design (evidence: `experiments_shubham/engine.py`)
- Effect analysis → Document effects: reads effect tables (evidence: `experiments_shubham/analysis.py`)
- Effect predictors → Predictor features: uses features (evidence: `experiments_chaitanya/run_real_predictors.py`)
- Real data prep → Run provenance: records design (evidence: `experiments_anupam/build_universe.py`)
