# karthikeyagit28/midsem_assignment architecture

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

- Interactive diagram: https://gitdiagram.com/karthikeyagit28/midsem_assignment
- Repository: https://github.com/karthikeyagit28/midsem_assignment

## Overview

LegalLens is an interactive search system for Indian Supreme Court judgments. A user submits a legal question in the Streamlit app; the app selects a retrieval mode, and the hybrid ranker combines BM25 and dense semantic scores, returning ranked cases with score breakdowns and a relevant passage. Separate capabilities include TF-IDF baseline search, legal query expansion, positional phrase indexing, and benchmark evaluation. The README documents dataset preparation and index/model building; unsampled implementation details are not inferred beyond those documented capabilities.

Main entry points: [`app/streamlit_app.py`](https://github.com/karthikeyagit28/midsem_assignment/blob/main/app/streamlit_app.py) (Streamlit search app), [`src/evaluation.py`](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/evaluation.py) (IR evaluation), [`src/hybrid_ranker.py`](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/hybrid_ranker.py) (Hybrid ranking), [`src/bm25_retriever.py`](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/bm25_retriever.py) (BM25 retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Corpus preparation"]
  node_dataset["IndicLegalQA data"]
  node_prep_pipeline["Document preparation<br/>[preprocessing.py]"]
  node_documents["Canonical judgments<br/>[documents.json]"]
end

subgraph group_retrieval["Retrieval and ranking"]
  node_index[("Positional index<br/>[indexing.py]")]
  node_bm25["BM25 retrieval<br/>[bm25_retriever.py]"]
  node_semantic["Dense retrieval"]
  node_tfidf["TF-IDF baseline<br/>[tfidf_retriever.py]"]
  node_hybrid["Hybrid ranking<br/>[hybrid_ranker.py]"]
  node_passages["Passage extraction"]
  node_extensions["Legal query expansion<br/>[extensions.py]"]
  node_utils["Score and result helpers<br/>[utils.py]"]
end

subgraph group_experience["Search experience"]
  node_app["Streamlit search app<br/>[streamlit_app.py]"]
end

subgraph group_benchmark["Evaluation"]
  node_evaluation["IR evaluation<br/>[evaluation.py]"]
  node_queries["Evaluation queries<br/>[queries_test.json]"]
  node_metrics["Benchmark results<br/>[metrics.csv]"]
end

node_user(("Legal searcher"))

node_user -->|"submits query"| node_app
node_dataset -->|"prepares records"| node_prep_pipeline
node_prep_pipeline -->|"creates judgments"| node_documents
node_documents -->|"builds postings"| node_index
node_index -->|"supplies postings"| node_bm25
node_documents -->|"encodes judgments"| node_semantic
node_documents -->|"fits document matrix"| node_tfidf
node_app -->|"runs hybrid search"| node_hybrid
node_app -->|"runs lexical search"| node_bm25
node_app -->|"runs dense search"| node_semantic
node_app -->|"runs baseline search"| node_tfidf
node_app -->|"uses expansion"| node_extensions
node_hybrid -->|"scores lexically"| node_bm25
node_hybrid -->|"scores semantically"| node_semantic
node_hybrid -->|"extracts passage"| node_passages
node_bm25 -->|"formats results"| node_utils
node_semantic -->|"formats results"| node_utils
node_tfidf -->|"formats results"| node_utils
node_app -.->|"shows evaluation"| node_evaluation
node_queries -->|"benchmarks rankings"| node_evaluation
node_evaluation -->|"evaluates baseline"| node_tfidf
node_evaluation -->|"evaluates retrieval"| node_bm25
node_evaluation -->|"evaluates retrieval"| node_semantic
node_evaluation -->|"evaluates fusion"| node_hybrid
node_evaluation -->|"exports metrics"| node_metrics

click node_dataset "https://github.com/karthikeyagit28/midsem_assignment/blob/main/data/raw/IndicLegalQA_Dataset_10K_Revised.json"
click node_prep_pipeline "https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/preprocessing.py"
click node_documents "https://github.com/karthikeyagit28/midsem_assignment/blob/main/data/processed/documents.json"
click node_index "https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/indexing.py"
click node_bm25 "https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/bm25_retriever.py"
click node_semantic "https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/semantic_retriever.py"
click node_tfidf "https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/tfidf_retriever.py"
click node_hybrid "https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/hybrid_ranker.py"
click node_passages "https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/passage_retrieval.py"
click node_extensions "https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/extensions.py"
click node_utils "https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/utils.py"
click node_app "https://github.com/karthikeyagit28/midsem_assignment/blob/main/app/streamlit_app.py"
click node_evaluation "https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/evaluation.py"
click node_queries "https://github.com/karthikeyagit28/midsem_assignment/blob/main/data/processed/queries_test.json"
click node_metrics "https://github.com/karthikeyagit28/midsem_assignment/blob/main/results/metrics.csv"

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_dataset,node_prep_pipeline,node_documents toneBlue
class node_index,node_bm25,node_semantic,node_tfidf,node_hybrid,node_passages,node_extensions,node_utils toneAmber
class node_app toneMint
class node_evaluation,node_queries,node_metrics toneRose
class node_user toneIndigo
```

## Components

### Corpus preparation

- [IndicLegalQA data](https://github.com/karthikeyagit28/midsem_assignment/blob/main/data/raw/IndicLegalQA_Dataset_10K_Revised.json): `data/raw/IndicLegalQA_Dataset_10K_Revised.json`
- [Document preparation](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/preprocessing.py): `src/preprocessing.py`
- [Canonical judgments](https://github.com/karthikeyagit28/midsem_assignment/blob/main/data/processed/documents.json): `data/processed/documents.json`

### Retrieval and ranking

- [Positional index](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/indexing.py): `src/indexing.py`
- [BM25 retrieval](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/bm25_retriever.py): `src/bm25_retriever.py`
- [Dense retrieval](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/semantic_retriever.py): `src/semantic_retriever.py`
- [TF-IDF baseline](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/tfidf_retriever.py): `src/tfidf_retriever.py`
- [Hybrid ranking](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/hybrid_ranker.py): `src/hybrid_ranker.py`
- [Passage extraction](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/passage_retrieval.py): `src/passage_retrieval.py`
- [Legal query expansion](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/extensions.py): `src/extensions.py`
- [Score and result helpers](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/utils.py): `src/utils.py`

### Search experience

- [Streamlit search app](https://github.com/karthikeyagit28/midsem_assignment/blob/main/app/streamlit_app.py): `app/streamlit_app.py`

### Evaluation

- [IR evaluation](https://github.com/karthikeyagit28/midsem_assignment/blob/main/src/evaluation.py): `src/evaluation.py`
- [Evaluation queries](https://github.com/karthikeyagit28/midsem_assignment/blob/main/data/processed/queries_test.json): `data/processed/queries_test.json`
- [Benchmark results](https://github.com/karthikeyagit28/midsem_assignment/blob/main/results/metrics.csv): `results/metrics.csv`

### Other components

- **Legal searcher**

## Connections

- Legal searcher → Streamlit search app: submits query (evidence: `README.md`)
- IndicLegalQA data → Document preparation: prepares records (evidence: `README.md`)
- Document preparation → Canonical judgments: creates judgments (evidence: `README.md`)
- Canonical judgments → Positional index: builds postings (evidence: `README.md`)
- Positional index → BM25 retrieval: supplies postings (evidence: `src/bm25_retriever.py`)
- Canonical judgments → Dense retrieval: encodes judgments (evidence: `README.md`)
- Canonical judgments → TF-IDF baseline: fits document matrix (evidence: `src/tfidf_retriever.py`)
- Streamlit search app → Hybrid ranking: runs hybrid search (evidence: `app/streamlit_app.py`)
- Streamlit search app → BM25 retrieval: runs lexical search (evidence: `app/streamlit_app.py`)
- Streamlit search app → Dense retrieval: runs dense search (evidence: `app/streamlit_app.py`)
- Streamlit search app → TF-IDF baseline: runs baseline search (evidence: `app/streamlit_app.py`)
- Streamlit search app → Legal query expansion: uses expansion (evidence: `app/streamlit_app.py`)
- Hybrid ranking → BM25 retrieval: scores lexically (evidence: `src/hybrid_ranker.py`)
- Hybrid ranking → Dense retrieval: scores semantically (evidence: `src/hybrid_ranker.py`)
- Hybrid ranking → Passage extraction: extracts passage (evidence: `src/hybrid_ranker.py`)
- BM25 retrieval → Score and result helpers: formats results (evidence: `src/bm25_retriever.py`)
- Dense retrieval → Score and result helpers: formats results (evidence: `src/semantic_retriever.py`)
- TF-IDF baseline → Score and result helpers: formats results (evidence: `src/tfidf_retriever.py`)
- Streamlit search app → IR evaluation: shows evaluation
- Evaluation queries → IR evaluation: benchmarks rankings (evidence: `README.md`)
- IR evaluation → TF-IDF baseline: evaluates baseline (evidence: `src/evaluation.py`)
- IR evaluation → BM25 retrieval: evaluates retrieval (evidence: `src/evaluation.py`)
- IR evaluation → Dense retrieval: evaluates retrieval (evidence: `src/evaluation.py`)
- IR evaluation → Hybrid ranking: evaluates fusion (evidence: `src/evaluation.py`)
- IR evaluation → Benchmark results: exports metrics (evidence: `README.md`)
