# xmudeeplit/legalgraphrag architecture

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

- Interactive diagram: https://gitdiagram.com/xmudeeplit/legalgraphrag
- Repository: https://github.com/xmudeeplit/legalgraphrag

## Overview

#### Purpose and entry points
LegalGraphRAG is a Python evaluation framework for criminal legal judgment prediction. It builds a feature/case graph, retrieves graph-grounded legal context, and uses LLM agents to predict charges, applicable law articles, and imprisonment. The operational entry point is `run.py`; offline scoring is `evaluation/evaluate_results.py`.

#### Orchestration and execution
`run.py` loads dotenv configuration, selects a model/runtime, optionally builds or loads a serialized graph, distributes cases across requested GPU devices, and writes combined per-dataset predictions and run statistics. The central application coordinator is `core/LegalGraphRAG.py`, which connects preprocessing, retrieval, prompts, and judgment stages.

Grounding: `run.py`, `core/LegalGraphRAG.py`, `configs/main.env`.

#### Case preprocessing and feature extraction
Raw or evaluation cases are segmented, pre-judged, and converted into structured legal features used as graph nodes/retrieval keys. The preparation pipeline can generate sampled CAIL inputs, case features, law-dependency hints, and merged law-to-crime resources before inference.

Grounding: `core/preprocess/case_seg.py`, `core/preprocess/get_features.py`, `core/preprocess/preJudge.py`; orchestration scripts: `scripts/prepare_data.py`, `scripts/prepare_case_features.py`.

#### Graph construction and persistence
The graph layer converts feature-enriched historical cases and law resources into a retrievable graph database. It uses embeddings during construction/retrieval and persists the graph as a pickle artifact so parallel inference workers can reload a common read-only-ish graph rather than rebuild it. Rebuilds are required when graph-construction model/configuration changes.

Grounding: `core/graph_construct/feature_graph.py`, `core/graph_construct/graph_db.py`, `datas/main_experiment/cases_with_feature_big.json`.

#### Retrieval-to-judgment pipeline
For each target case, the system uses structured features to retrieve relevant precedent/law graph context, then routes that evidence through specialized legal decision agents. Crime and law judgments are separate boundaries, allowing charge reasoning and statutory-article reasoning to be independently produced before the final result schema is emitted.

Grounding: `core/LegalGraphRAG.py`, `core/judge/judge_crime.py`, `core/judge/judge_law.py`.

#### Model and prompt boundary
A common model abstraction supports local Hugging Face Transformers models and OpenAI-compatible API models. Model-specific implementations encapsulate loading/inference details; prompt packages separate graph, retrieval, preprocessing, and judge prompt families, with Chinese/English selection configured externally.

Grounding: `core/models/base.py`, `core/models/transformers_base.py`, `core/models/openai_base.py`; examples: `core/models/transformers/qwen3_model.py`, `core/models/openai/gpt4o_mini.py`.

#### Data assets, infrastructure, and evaluation
The main experiment consumes a 14,049-case graph corpus plus CAIL and CMDL evaluation inputs, criminal-law records, and crime-category metadata. It requires Python 3.10+, CUDA/PyTorch for local large models and multi-GPU execution; embeddings come from an externally running Ollama-compatible endpoint (default `localhost:11434/api/embed`, `bge-m3`). API-backed models additionally require configured credentials. Metrics evaluate charge/law exact match and Micro-F1, plus sentence exact match and month MAE.

Grounding: `datas/main_experiment/crime_data_CAIL_small.json`, `datas/main_experiment/crime_data_CMDL_small.json`, `datas/main_experiment/criminal_law_processed.json`, `evaluation/evaluate_results.py`.

Main entry points: [`core/LegalGraphRAG.py`](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/LegalGraphRAG.py) (LegalGraphRAG coordinator), [`run.py`](https://github.com/xmudeeplit/legalgraphrag/blob/main/run.py) (Run entry point), [`core/graph_construct/feature_graph.py`](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/graph_construct/feature_graph.py) (Feature graph builder), [`core/models/base.py`](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/models/base.py) (Model abstraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Execution"]
  node_run["Run entry point<br/>Python CLI<br/>[run.py]"]
end

subgraph group_knowledge["Knowledge Build"]
  node_case_segmentation["Case segmentation<br/>preprocessor<br/>[case_seg.py]"]
  node_feature_extraction["Legal feature extraction<br/>preprocessor<br/>[get_features.py]"]
  node_pre_judgment["Pre-judgment<br/>preprocessor<br/>[preJudge.py]"]
  node_data_preparation["Preparation scripts<br/>offline pipeline<br/>[prepare_data.py]"]
  node_case_feature_prep["Case feature preparation<br/>offline pipeline"]
  node_historical_cases["Historical case corpus<br/>JSON dataset"]
  node_feature_graph["Feature graph builder<br/>graph construction<br/>[feature_graph.py]"]
  node_graph_database[("Persistent graph database<br/>graph store<br/>[graph_db.py]")]
end

subgraph group_inference["RAG Judgment"]
  node_coordinator["LegalGraphRAG coordinator<br/>application pipeline<br/>[LegalGraphRAG.py]"]
  node_graph_retrieval["Graph-grounded retrieval<br/>RAG retrieval"]
  node_crime_judge["Crime judgment agent<br/>legal decision agent<br/>[judge_crime.py]"]
  node_law_judge["Law judgment agent<br/>legal decision agent<br/>[judge_law.py]"]
end

subgraph group_models["Model Boundary"]
  node_model_abstraction["Model abstraction<br/>LLM interface<br/>[base.py]"]
  node_transformers_runtime["Transformers runtime<br/>local model runtime"]
  node_openai_runtime["OpenAI-compatible runtime<br/>API model runtime<br/>[openai_base.py]"]
  node_embedding_endpoint{{"Embedding endpoint<br/>external service"}}
end

subgraph group_evaluation["Evaluation"]
  node_evaluation_inputs["CAIL and CMDL inputs<br/>JSON datasets"]
  node_result_evaluation["Offline evaluator<br/>metrics job"]
end

node_run -->|"starts"| node_coordinator
node_run -->|"loads or rebuilds"| node_graph_database
node_run -->|"distributes cases from"| node_evaluation_inputs
node_data_preparation -->|"feeds"| node_case_feature_prep
node_case_feature_prep -->|"uses"| node_case_segmentation
node_case_segmentation -->|"segments for"| node_feature_extraction
node_pre_judgment -->|"enriches"| node_feature_extraction
node_historical_cases -->|"source cases"| node_feature_graph
node_feature_extraction -->|"structured features"| node_feature_graph
node_feature_graph -->|"builds"| node_graph_database
node_embedding_endpoint -->|"embeddings"| node_feature_graph
node_coordinator -->|"retrieves context"| node_graph_retrieval
node_graph_database -->|"searches"| node_graph_retrieval
node_embedding_endpoint -->|"embeddings"| node_graph_retrieval
node_graph_retrieval -->|"evidence"| node_crime_judge
node_graph_retrieval -->|"evidence"| node_law_judge
node_crime_judge -->|"charge prediction"| node_coordinator
node_law_judge -->|"law prediction"| node_coordinator
node_model_abstraction -->|"implements"| node_transformers_runtime
node_model_abstraction -->|"implements"| node_openai_runtime
node_coordinator -->|"invokes"| node_model_abstraction
node_run -.->|"outputs scored by"| node_result_evaluation
node_evaluation_inputs -->|"ground truth"| node_result_evaluation

click node_run "https://github.com/xmudeeplit/legalgraphrag/blob/main/run.py"
click node_coordinator "https://github.com/xmudeeplit/legalgraphrag/blob/main/core/LegalGraphRAG.py"
click node_case_segmentation "https://github.com/xmudeeplit/legalgraphrag/blob/main/core/preprocess/case_seg.py"
click node_feature_extraction "https://github.com/xmudeeplit/legalgraphrag/blob/main/core/preprocess/get_features.py"
click node_pre_judgment "https://github.com/xmudeeplit/legalgraphrag/blob/main/core/preprocess/preJudge.py"
click node_data_preparation "https://github.com/xmudeeplit/legalgraphrag/blob/main/scripts/prepare_data.py"
click node_case_feature_prep "https://github.com/xmudeeplit/legalgraphrag/blob/main/scripts/prepare_case_features.py"
click node_historical_cases "https://github.com/xmudeeplit/legalgraphrag/blob/main/datas/main_experiment/cases_with_feature_big.json"
click node_feature_graph "https://github.com/xmudeeplit/legalgraphrag/blob/main/core/graph_construct/feature_graph.py"
click node_graph_database "https://github.com/xmudeeplit/legalgraphrag/blob/main/core/graph_construct/graph_db.py"
click node_crime_judge "https://github.com/xmudeeplit/legalgraphrag/blob/main/core/judge/judge_crime.py"
click node_law_judge "https://github.com/xmudeeplit/legalgraphrag/blob/main/core/judge/judge_law.py"
click node_model_abstraction "https://github.com/xmudeeplit/legalgraphrag/blob/main/core/models/base.py"
click node_transformers_runtime "https://github.com/xmudeeplit/legalgraphrag/blob/main/core/models/transformers_base.py"
click node_openai_runtime "https://github.com/xmudeeplit/legalgraphrag/blob/main/core/models/openai_base.py"
click node_evaluation_inputs "https://github.com/xmudeeplit/legalgraphrag/blob/main/datas/main_experiment/crime_data_CAIL_small.json"
click node_result_evaluation "https://github.com/xmudeeplit/legalgraphrag/blob/main/evaluation/evaluate_results.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_run toneBlue
class node_case_segmentation,node_feature_extraction,node_pre_judgment,node_data_preparation,node_case_feature_prep,node_historical_cases,node_feature_graph,node_graph_database toneAmber
class node_coordinator,node_graph_retrieval,node_crime_judge,node_law_judge toneMint
class node_model_abstraction,node_transformers_runtime,node_openai_runtime,node_embedding_endpoint toneRose
class node_evaluation_inputs,node_result_evaluation toneIndigo
```

## Components

### Execution

- [Run entry point](https://github.com/xmudeeplit/legalgraphrag/blob/main/run.py): Python CLI · Selects runtime, distributes cases across GPUs, and writes predictions. · `run.py`

### Knowledge Build

- [Case segmentation](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/preprocess/case_seg.py): preprocessor · `core/preprocess/case_seg.py`
- [Legal feature extraction](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/preprocess/get_features.py): preprocessor · Produces structured retrieval keys and graph-node features. · `core/preprocess/get_features.py`
- [Pre-judgment](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/preprocess/preJudge.py): preprocessor · `core/preprocess/preJudge.py`
- [Preparation scripts](https://github.com/xmudeeplit/legalgraphrag/blob/main/scripts/prepare_data.py): offline pipeline · Creates sampled inputs, features, and law-dependency resources. · `scripts/prepare_data.py`
- [Case feature preparation](https://github.com/xmudeeplit/legalgraphrag/blob/main/scripts/prepare_case_features.py): offline pipeline · `scripts/prepare_case_features.py`
- [Historical case corpus](https://github.com/xmudeeplit/legalgraphrag/blob/main/datas/main_experiment/cases_with_feature_big.json): JSON dataset · Feature-enriched source corpus for the precedent graph. · `datas/main_experiment/cases_with_feature_big.json`
- [Feature graph builder](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/graph_construct/feature_graph.py): graph construction · `core/graph_construct/feature_graph.py`
- [Persistent graph database](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/graph_construct/graph_db.py): graph store · Serializes a shared graph artifact for inference workers. · `core/graph_construct/graph_db.py`

### RAG Judgment

- [LegalGraphRAG coordinator](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/LegalGraphRAG.py): application pipeline · Connects preprocessing, graph retrieval, prompts, and judgment. · `core/LegalGraphRAG.py`
- **Graph-grounded retrieval**: RAG retrieval · Finds relevant precedent and law context from case features.
- [Crime judgment agent](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/judge/judge_crime.py): legal decision agent · Predicts criminal charges from retrieved evidence. · `core/judge/judge_crime.py`
- [Law judgment agent](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/judge/judge_law.py): legal decision agent · Predicts applicable statutory articles. · `core/judge/judge_law.py`

### Model Boundary

- [Model abstraction](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/models/base.py): LLM interface · Unifies local Transformers and OpenAI-compatible models. · `core/models/base.py`
- [Transformers runtime](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/models/transformers_base.py): local model runtime · `core/models/transformers_base.py`
- [OpenAI-compatible runtime](https://github.com/xmudeeplit/legalgraphrag/blob/main/core/models/openai_base.py): API model runtime · `core/models/openai_base.py`
- **Embedding endpoint**: external service · Ollama-compatible embedding service used for graph construction and retrieval.

### Evaluation

- [CAIL and CMDL inputs](https://github.com/xmudeeplit/legalgraphrag/blob/main/datas/main_experiment/crime_data_CAIL_small.json): JSON datasets · `datas/main_experiment/crime_data_CAIL_small.json`
- [Offline evaluator](https://github.com/xmudeeplit/legalgraphrag/blob/main/evaluation/evaluate_results.py): metrics job · Scores charge/law matches, Micro-F1, sentence match, and month MAE. · `evaluation/evaluate_results.py`

## Connections

- Run entry point → LegalGraphRAG coordinator: starts
- Run entry point → Persistent graph database: loads or rebuilds
- Run entry point → CAIL and CMDL inputs: distributes cases from
- Preparation scripts → Case feature preparation: feeds
- Case feature preparation → Case segmentation: uses
- Case segmentation → Legal feature extraction: segments for
- Pre-judgment → Legal feature extraction: enriches
- Historical case corpus → Feature graph builder: source cases
- Legal feature extraction → Feature graph builder: structured features
- Feature graph builder → Persistent graph database: builds
- Embedding endpoint → Feature graph builder: embeddings
- LegalGraphRAG coordinator → Graph-grounded retrieval: retrieves context
- Persistent graph database → Graph-grounded retrieval: searches
- Embedding endpoint → Graph-grounded retrieval: embeddings
- Graph-grounded retrieval → Crime judgment agent: evidence
- Graph-grounded retrieval → Law judgment agent: evidence
- Crime judgment agent → LegalGraphRAG coordinator: charge prediction
- Law judgment agent → LegalGraphRAG coordinator: law prediction
- Model abstraction → Transformers runtime: implements
- Model abstraction → OpenAI-compatible runtime: implements
- LegalGraphRAG coordinator → Model abstraction: invokes
- Run entry point → Offline evaluator: outputs scored by
- CAIL and CMDL inputs → Offline evaluator: ground truth