# myselfsiddharth/legalai architecture

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

- Interactive diagram: https://gitdiagram.com/myselfsiddharth/legalai
- Repository: https://github.com/myselfsiddharth/legalai

## Overview

This repository is a legal-AI research pipeline for extracting structured legal concepts from judgments, checking cited authorities against citation metadata, and studying signed citation networks and model baselines. A user-facing run can process a case through ontology-guided extraction, citation verification, and an IRAC report; batch evaluation scores those outputs. Separate data-preparation and graph-analysis branches build the case sample and signed citation graph. Relationships are limited to excerpted code references and documented inputs/outputs; several listed modules were not sampled, so their internal behavior is represented only at subsystem level.

Main entry points: [`scripts/ode_lib.py`](https://github.com/myselfsiddharth/legalai/blob/main/scripts/ode_lib.py) (Grounding library), [`scripts/phase3_verify.py`](https://github.com/myselfsiddharth/legalai/blob/main/scripts/phase3_verify.py) (IRAC verification), [`Data/processed/citations_classified.jsonl`](https://github.com/myselfsiddharth/legalai/blob/main/Data/processed/citations_classified.jsonl) (Citation metadata), [`scripts/fetch_sample_pdfs.py`](https://github.com/myselfsiddharth/legalai/blob/main/scripts/fetch_sample_pdfs.py) (PDF retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Case preparation"]
  node_landdata[("Land-dispute data")]
  node_citation_metadata[("Citation metadata")]
  node_case_sample["Case sampling<br/>[build_sample.py]"]
  node_drive_index["Drive index"]
  node_pdf_fetch["PDF retrieval"]
  node_judgments[("Judgment PDFs")]
end

subgraph group_extract["Legal extraction"]
  node_ode_pipeline["ODE pipeline<br/>[ode_pipeline.py]"]
  node_ode_lib["Grounding library<br/>[ode_lib.py]"]
  node_ontology["Legal ontology"]
  node_learned_rules["Learned rules<br/>[learned_rules.json]"]
  node_verification["IRAC verification<br/>[phase3_verify.py]"]
  node_irac_reports[("IRAC reports")]
end

subgraph group_graph["Citation analysis"]
  node_headnote_signs["Headnote sign extraction"]
  node_modern_signs["Modern sign classification"]
  node_signed_graph["Signed citation graph"]
  node_graph_outputs[("Graph scores")]
end

subgraph group_evaluate["Evaluation"]
  node_evaluation_batch["Batch evaluation"]
  node_baseline_runner["Baseline comparison<br/>[run_baselines.py]"]
  node_evaluation_lib["Evaluation metrics<br/>[eval_lib.py]"]
  node_evaluation_results[("Evaluation results")]
end

node_researcher(("Researcher"))
node_llm{{"LLM service"}}
node_google_drive{{"Google Drive"}}

node_researcher -->|"runs extraction"| node_ode_pipeline
node_landdata -->|"provides cases"| node_case_sample
node_citation_metadata -->|"filters cases"| node_case_sample
node_case_sample -->|"selects cases"| node_pdf_fetch
node_drive_index -->|"indexes files"| node_pdf_fetch
node_pdf_fetch -->|"downloads PDFs"| node_google_drive
node_pdf_fetch -->|"writes PDFs"| node_judgments
node_ode_pipeline -->|"uses grounding"| node_ode_lib
node_ode_lib -->|"grounds sentences"| node_llm
node_ode_lib -->|"loads ontology"| node_ontology
node_ode_lib -->|"loads rules"| node_learned_rules
node_verification -->|"reuses extraction"| node_ode_lib
node_verification -->|"checks authorities"| node_citation_metadata
node_verification -->|"writes report"| node_irac_reports
node_headnote_signs -->|"reads PDFs"| node_judgments
node_modern_signs -->|"loads citations"| node_citation_metadata
node_modern_signs -->|"classifies mentions"| node_llm
node_headnote_signs -->|"provides sign labels"| node_signed_graph
node_modern_signs -->|"provides sign labels"| node_signed_graph
node_citation_metadata -->|"provides citation edges"| node_signed_graph
node_signed_graph -->|"writes scores"| node_graph_outputs
node_evaluation_batch -->|"runs extraction"| node_ode_lib
node_evaluation_batch -->|"uses metrics"| node_evaluation_lib
node_baseline_runner -->|"uses metrics"| node_evaluation_lib
node_evaluation_lib -->|"imports grounding"| node_ode_lib
node_evaluation_lib -->|"imports verifier"| node_verification
node_evaluation_batch -->|"writes summaries"| node_evaluation_results
node_baseline_runner -->|"writes comparison"| node_evaluation_results

click node_landdata "https://github.com/myselfsiddharth/legalai/tree/main/Data/Legal%20AI%20Dataset"
click node_citation_metadata "https://github.com/myselfsiddharth/legalai/blob/main/Data/processed/citations_classified.jsonl"
click node_case_sample "https://github.com/myselfsiddharth/legalai/blob/main/scripts/build_sample.py"
click node_drive_index "https://github.com/myselfsiddharth/legalai/blob/main/scripts/build_drive_index.py"
click node_pdf_fetch "https://github.com/myselfsiddharth/legalai/blob/main/scripts/fetch_sample_pdfs.py"
click node_ode_pipeline "https://github.com/myselfsiddharth/legalai/blob/main/scripts/ode_pipeline.py"
click node_ode_lib "https://github.com/myselfsiddharth/legalai/blob/main/scripts/ode_lib.py"
click node_ontology "https://github.com/myselfsiddharth/legalai/blob/main/scripts/ontology/land_dispute_ontology.json"
click node_learned_rules "https://github.com/myselfsiddharth/legalai/blob/main/scripts/ontology/learned_rules.json"
click node_verification "https://github.com/myselfsiddharth/legalai/blob/main/scripts/phase3_verify.py"
click node_irac_reports "https://github.com/myselfsiddharth/legalai/tree/main/Data/processed"
click node_headnote_signs "https://github.com/myselfsiddharth/legalai/blob/main/scripts/extract_headnote_signs.py"
click node_modern_signs "https://github.com/myselfsiddharth/legalai/blob/main/scripts/classify_modern_signs.py"
click node_signed_graph "https://github.com/myselfsiddharth/legalai/blob/main/scripts/build_signed_graph.py"
click node_graph_outputs "https://github.com/myselfsiddharth/legalai/tree/main/Data/processed"
click node_evaluation_batch "https://github.com/myselfsiddharth/legalai/blob/main/scripts/run_evaluation_batch.py"
click node_baseline_runner "https://github.com/myselfsiddharth/legalai/blob/main/scripts/run_baselines.py"
click node_evaluation_lib "https://github.com/myselfsiddharth/legalai/blob/main/scripts/eval_lib.py"
click node_evaluation_results "https://github.com/myselfsiddharth/legalai/tree/main/Data/processed"

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_landdata,node_citation_metadata,node_case_sample,node_drive_index,node_pdf_fetch,node_judgments toneBlue
class node_ode_pipeline,node_ode_lib,node_ontology,node_learned_rules,node_verification,node_irac_reports toneAmber
class node_headnote_signs,node_modern_signs,node_signed_graph,node_graph_outputs toneMint
class node_evaluation_batch,node_baseline_runner,node_evaluation_lib,node_evaluation_results toneRose
class node_researcher,node_llm,node_google_drive toneIndigo
```

## Components

### Case preparation

- [Land-dispute data](https://github.com/myselfsiddharth/legalai/tree/main/Data/Legal%20AI%20Dataset): `Data/Legal AI Dataset`
- [Citation metadata](https://github.com/myselfsiddharth/legalai/blob/main/Data/processed/citations_classified.jsonl): `Data/processed/citations_classified.jsonl`
- [Case sampling](https://github.com/myselfsiddharth/legalai/blob/main/scripts/build_sample.py): `scripts/build_sample.py`
- [Drive index](https://github.com/myselfsiddharth/legalai/blob/main/scripts/build_drive_index.py): `scripts/build_drive_index.py`
- [PDF retrieval](https://github.com/myselfsiddharth/legalai/blob/main/scripts/fetch_sample_pdfs.py): `scripts/fetch_sample_pdfs.py`
- **Judgment PDFs**

### Legal extraction

- [ODE pipeline](https://github.com/myselfsiddharth/legalai/blob/main/scripts/ode_pipeline.py): `scripts/ode_pipeline.py`
- [Grounding library](https://github.com/myselfsiddharth/legalai/blob/main/scripts/ode_lib.py): `scripts/ode_lib.py`
- [Legal ontology](https://github.com/myselfsiddharth/legalai/blob/main/scripts/ontology/land_dispute_ontology.json): `scripts/ontology/land_dispute_ontology.json`
- [Learned rules](https://github.com/myselfsiddharth/legalai/blob/main/scripts/ontology/learned_rules.json): `scripts/ontology/learned_rules.json`
- [IRAC verification](https://github.com/myselfsiddharth/legalai/blob/main/scripts/phase3_verify.py): `scripts/phase3_verify.py`
- [IRAC reports](https://github.com/myselfsiddharth/legalai/tree/main/Data/processed): `Data/processed`

### Citation analysis

- [Headnote sign extraction](https://github.com/myselfsiddharth/legalai/blob/main/scripts/extract_headnote_signs.py): `scripts/extract_headnote_signs.py`
- [Modern sign classification](https://github.com/myselfsiddharth/legalai/blob/main/scripts/classify_modern_signs.py): `scripts/classify_modern_signs.py`
- [Signed citation graph](https://github.com/myselfsiddharth/legalai/blob/main/scripts/build_signed_graph.py): `scripts/build_signed_graph.py`
- [Graph scores](https://github.com/myselfsiddharth/legalai/tree/main/Data/processed): `Data/processed`

### Evaluation

- [Batch evaluation](https://github.com/myselfsiddharth/legalai/blob/main/scripts/run_evaluation_batch.py): `scripts/run_evaluation_batch.py`
- [Baseline comparison](https://github.com/myselfsiddharth/legalai/blob/main/scripts/run_baselines.py): `scripts/run_baselines.py`
- [Evaluation metrics](https://github.com/myselfsiddharth/legalai/blob/main/scripts/eval_lib.py): `scripts/eval_lib.py`
- [Evaluation results](https://github.com/myselfsiddharth/legalai/tree/main/Data/processed): `Data/processed`

### Other components

- **Researcher**
- **LLM service**
- **Google Drive**

## Connections

- Researcher → ODE pipeline: runs extraction (evidence: `scripts/ode_pipeline.py`)
- Land-dispute data → Case sampling: provides cases (evidence: `scripts/build_sample.py`)
- Citation metadata → Case sampling: filters cases (evidence: `scripts/build_sample.py`)
- Case sampling → PDF retrieval: selects cases (evidence: `scripts/fetch_sample_pdfs.py`)
- Drive index → PDF retrieval: indexes files (evidence: `scripts/fetch_sample_pdfs.py`)
- PDF retrieval → Google Drive: downloads PDFs (evidence: `scripts/fetch_sample_pdfs.py`)
- PDF retrieval → Judgment PDFs: writes PDFs (evidence: `scripts/fetch_sample_pdfs.py`)
- ODE pipeline → Grounding library: uses grounding (evidence: `scripts/ode_pipeline.py`)
- Grounding library → LLM service: grounds sentences (evidence: `scripts/ode_lib.py`)
- Grounding library → Legal ontology: loads ontology (evidence: `scripts/ode_lib.py`)
- Grounding library → Learned rules: loads rules (evidence: `scripts/ode_lib.py`)
- IRAC verification → Grounding library: reuses extraction (evidence: `scripts/phase3_verify.py`)
- IRAC verification → Citation metadata: checks authorities (evidence: `scripts/phase3_verify.py`)
- IRAC verification → IRAC reports: writes report (evidence: `scripts/phase3_verify.py`)
- Headnote sign extraction → Judgment PDFs: reads PDFs (evidence: `scripts/extract_headnote_signs.py`)
- Modern sign classification → Citation metadata: loads citations (evidence: `scripts/classify_modern_signs.py`)
- Modern sign classification → LLM service: classifies mentions (evidence: `scripts/classify_modern_signs.py`)
- Headnote sign extraction → Signed citation graph: provides sign labels (evidence: `scripts/build_signed_graph.py`)
- Modern sign classification → Signed citation graph: provides sign labels (evidence: `scripts/build_signed_graph.py`)
- Citation metadata → Signed citation graph: provides citation edges (evidence: `scripts/build_signed_graph.py`)
- Signed citation graph → Graph scores: writes scores (evidence: `scripts/build_signed_graph.py`)
- Batch evaluation → Grounding library: runs extraction (evidence: `scripts/run_evaluation_batch.py`)
- Batch evaluation → Evaluation metrics: uses metrics (evidence: `scripts/eval_lib.py`)
- Baseline comparison → Evaluation metrics: uses metrics (evidence: `scripts/run_baselines.py`)
- Evaluation metrics → Grounding library: imports grounding (evidence: `scripts/eval_lib.py`)
- Evaluation metrics → IRAC verification: imports verifier (evidence: `scripts/eval_lib.py`)
- Batch evaluation → Evaluation results: writes summaries (evidence: `scripts/run_evaluation_batch.py`)
- Baseline comparison → Evaluation results: writes comparison (evidence: `scripts/run_baselines.py`)
