# irlab-sdu/fuzi.mingcha architecture

> Architecture diagram of the GitHub repository irlab-sdu/fuzi.mingcha, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/irlab-sdu/fuzi.mingcha
- Repository: https://github.com/irlab-sdu/fuzi.mingcha

## Overview

##### Project Type and Purpose
- This is an open‑source AI tool: a Chinese judicial large language model (“夫子·明察司法大模型”) built on ChatGLM‑6B.
- It exposes a CLI for legal Q&A, case retrieval, statute retrieval, and syllogistic reasoning, combining LLM inference with retrieval modules (Elasticsearch and PyLucene).

##### Key Elements from File Structure
- Top‐level:
- README.md, LICENSE, CITATION.cff, images/ (screenshots)
- src/ (all code and configs)
- src/:
- cli_demo.py – the entrypoint for model deployment and user interaction
- es_task1/api.py, es_task2/api.py – Elasticsearch–based statute & case retrieval
- pylucene_task1/api.py, pylucene_task2/api.py – PyLucene–based retrieval with CSV seed data
- src/requirements.txt – Python dependencies
- Singularity安装与使用.md – containerization instructions
- csv_files/ – seed data for Lucene indexes

##### High‑Level Components to Model
a. User & Interface
– CLI (cli_demo.py): accepts user question or legal case description
b. Retrieval Layer
– Elasticsearch Service
- es_task1: statute retrieval
- es_task2: case retrieval
– Local Lucene Index
- pylucene_task1: statute retrieval from CSV
- pylucene_task2: case retrieval from CSV
c. Model Inference Layer
– ChatGLM‑6B model loaded locally (ModelScope/HuggingFace API)
– Prompt assembler: integrates retrieved statutes/cases into prompt
d. Data Stores and Preprocessing
– CSV seed files (pylucene_task*/csv_files)
– External datasets (HuggingFace datasets for training/tuning)
e. External Services
– HuggingFace / ModelScope (model weights & datasets)

##### Relationships and Data Flow
1. User → CLI
2. CLI dispatches to Retrieval Layer in parallel (ES + Lucene)
3. Retrieval Layer → returns top‑k statutes & case snippets
4. CLI / Prompt assembler → builds final prompt combining user input + retrieved context
5. Prompt → LLM Inference Layer (via Python SDK)
6. LLM → generates legal consultation / judgment / reasoning
7. CLI → outputs result back to user

##### Architectural Patterns & Principles
- Modular separation: retrieval modules are pluggable (swap ES with Lucene or other retrievers)
- Pipeline pattern: input → retrieval → prompt assembly → LLM inference → output
- Single‐process Python orchestrator (no web server)—monolithic CLI tool
- Containerization support (Singularity recipe) for reproducible deployments

##### Essential Details to Capture
- The dual retrieval paths and how they feed into prompt construction
- The external dependency on HuggingFace/ModelScope for model weights
- The CLI as the single orchestrator (no front‑end or web server)
- Containerization instructions in Singularity安装与使用.md as an optional deployment layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface"
        direction TB
        User["User"]:::external
        CLI["CLI Interface\n(cli_demo.py)"]:::interface
    end
    User -->|"query→"| CLI

    subgraph "Retrieval Layer"
        direction TB
        ES["Elasticsearch Statute\n(es_task1/api.py)"]:::retrieval
        ESC["Elasticsearch Case\n(es_task2/api.py)"]:::retrieval
        LucStat["PyLucene Statute\n(pylucene_task1/api.py)"]:::retrieval
        LucCase["PyLucene Case\n(pylucene_task2/api.py)"]:::retrieval
    end
    CLI -->|"dispatch→"| ES
    CLI -->|"dispatch→"| ESC
    CLI -->|"dispatch→"| LucStat
    CLI -->|"dispatch→"| LucCase

    ES -->|"results→"| CLI
    ESC -->|"results→"| CLI
    LucStat -->|"results→"| CLI
    LucCase -->|"results→"| CLI

    subgraph "Model Inference Layer"
        direction TB
        Prompt["Prompt Assembler\n(cli_demo.py)"]:::inference
        LLM["ChatGLM-6B Model"]:::inference
    end
    CLI -->|"prompt→"| Prompt
    Prompt -->|"invoke→"| LLM
    LLM -->|"response→"| CLI

    subgraph "Data Stores"
        direction TB
        CSV1["Statute CSV\n(data_task1.csv)"]:::datastore
        CSV2["Case CSV\n(data_task2.csv)"]:::datastore
        ExtData["External Datasets\n(HF datasets)"]:::datastore
    end
    CSV1 -.-> LucStat
    CSV2 -.-> LucCase
    ExtData -.-> LLM

    subgraph "External Services"
        direction TB
        HF["HuggingFace/ModelScope"]:::external
    end
    HF -->|"model weights→"| LLM

    subgraph "Deployment"
        direction TB
        Singularity["Containerization\n(Singularity安装与使用.md)"]:::datastore
        Requirements["Dependencies\n(requirements.txt)"]:::datastore
    end

    click CLI "https://github.com/irlab-sdu/fuzi.mingcha/blob/main/src/cli_demo.py"
    click ES "https://github.com/irlab-sdu/fuzi.mingcha/blob/main/src/es_task1/api.py"
    click ESC "https://github.com/irlab-sdu/fuzi.mingcha/blob/main/src/es_task2/api.py"
    click LucStat "https://github.com/irlab-sdu/fuzi.mingcha/blob/main/src/pylucene_task1/api.py"
    click CSV1 "https://github.com/irlab-sdu/fuzi.mingcha/blob/main/src/pylucene_task1/csv_files/data_task1.csv"
    click LucCase "https://github.com/irlab-sdu/fuzi.mingcha/blob/main/src/pylucene_task2/api.py"
    click CSV2 "https://github.com/irlab-sdu/fuzi.mingcha/blob/main/src/pylucene_task2/csv_files/data_task2.csv"
    click Singularity "https://github.com/irlab-sdu/fuzi.mingcha/blob/main/src/Singularity安装与使用.md"
    click Requirements "https://github.com/irlab-sdu/fuzi.mingcha/blob/main/src/requirements.txt"

    classDef interface fill:#6fcf97,stroke:#2d8659,color:#000;
    classDef retrieval fill:#56ccf2,stroke:#2a8fcf,color:#000;
    classDef inference fill:#f2994a,stroke:#b86b29,color:#000;
    classDef datastore fill:#bdbdbd,stroke:#8b8b8b,color:#000;
    classDef external fill:#bb6bd9,stroke:#8a3db3,color:#fff;
```
