Content
# legal-kb-builder
**An integrated factory for building local legal knowledge bases.**
From a collection of "PDF/DOCX/images/Markdown/Q&A legal materials" to a "business consulting intelligent agent that can be served externally", all in one package:
- 🔀 **Dual-layer routing**: First, determine if it's Markdown (if not, hand it over to your configured parsing backend), then decide which pipeline to use: book KB, judgment document KB, Q&A KB, or Agentic real-time retrieval.
- 🧩 **Pluggable parsing backend**: MinerU, Alibaba Cloud Baolian, Hehe Information TextIn, PaddleOCR, LibreOffice, pandoc, or any custom script - configure them in `assets/parser-backends.yaml`.
- 🔎 **Three-way fusion retrieval**: BM25 (`jieba` + `rank_bm25`) + vector (`bge-small-zh-v1.5` + FAISS) + structural indexing, fused using RRF.
- 💬 **Q&A pipeline**: Supports FAQ, business consulting Q&A, training Q&A, and other Q&A forms, with "question matching as primary and answer recall as secondary" dual-index retrieval.
- 🤖 **Business consulting intelligent agent**: Cross-library orchestration (intent classification → KB routing → multi-source retrieval → structured response), supporting multi-turn dialogue.
- 🌐 **External service**: HTTP API (FastAPI) + DingTalk/Feishu webhook + MCP Server, supporting front-end Q&A platforms and IM robots.
- ⚖️ **Legal semantics-oriented**: Distinguishes between "book directory entries" and "body references", avoiding common issues like building 489 indexes for a 69-article judicial interpretation.
- 📦 **Zero platform binding**: All scripts are self-contained, with relative paths, and can be directly used as skill packages in any AI Agent environment, such as Claude Code, Cursor, QoderWork, Gemini CLI, or OpenCode.
## Quick Start
```bash
# 1) Dependencies
python3 -m pip install -r requirements.txt
# 2) Configure parsing backend (enable at least one)
cp assets/parser-backends.example.yaml assets/parser-backends.yaml
# Open parser-backends.yaml, enable and fill in token/cmd for the backend you want to use
# 3) One-click build (factory entry automatically routes and builds)
python3 scripts/kb_factory.py build ~/legal_materials/contract_law_faq.pdf \
--output ~/kbs/faq_kb --name "contract_law_faq"
# 4) Provide external service
# a) Command-line consultation
python3 scripts/consultation_agent.py --qa-kb ~/kbs/faq_kb ask "invalid format clause?"
# b) HTTP API (front-end/DingTalk/Feishu)
python3 scripts/api_server.py --qa-kb ~/kbs/faq_kb --port 8000
# c) MCP (Claude Desktop/Cursor)
python3 scripts/mcp_server.py # With KB_PATH/QA_KB_PATH environment variables
```
## Four Pipelines + Consulting Intelligent Agent
| Type | Applicable Scenario | Main Script |
|---|---|---|
| **book_kb** | Legal commentary/ judicial interpretation/ academic monographs/ textbooks/ case compilations/ regulatory compilations/ practical guidelines | `scripts/legal_kb.py` |
| **case_kb** | Court judgment documents (judgments/ rulings/ mediation documents/ decisions) | `scripts/judgment_kb.py` |
| **qa_kb** | FAQ/ business consulting Q&A/ training Q&A/ customer service scripts/ legal consulting Q&A collections | `scripts/qa_kb.py` |
| **agentic** | Exploratory academic materials (papers/ comparative law/ reports/ single-book lookup) | `scripts/monte_carlo_sampler.py` |
| **consult** | Cross-library business consulting (intent classification → KB routing → multi-source retrieval → structured response) | `scripts/consultation_agent.py` |
For details, see [SKILL.md](SKILL.md).
## Directory
```
legal-kb-builder/
├── SKILL.md # Detailed usage instructions (can be read directly by AI Agents as skill definitions)
├── README.md # This file
├── requirements.txt
├── scripts/ # All executable scripts
│ ├── kb_factory.py # Factory main entry (one-click routing and building)
│ ├── consultation_agent.py # Business consulting intelligent agent
│ ├── api_server.py # HTTP API service (DingTalk/Feishu webhook)
│ ├── mcp_server.py # MCP service
│ └── ... # Four pipelines + retrieval engine
├── assets/ # Configuration: parsing backend/ routing rules/ dictionaries/ regular expressions/ Q&A/ consultation
└── references/ # In-depth documentation (retrieval mode/ index template/ configuration fields/ end-to-end examples)
```
## Design Principles
1. **Directory as anchor**: Everything in book-type knowledge bases is based on the book's real directory.
2. **Body reference ≠ structural entry**: In a 69-article judicial interpretation book, "Civil Code Article 584" mentioned in the body is a reference, not a book entry.
3. **Only include main text**: Exclude forewords, prefaces, afterwords, acknowledgments, footnotes, and publication information.
4. **Question matching as primary**: Q&A collection retrieval focuses on semantic alignment between user queries and library questions, with answer recall as secondary.
5. **Zero external dependencies**: API SDKs are not tightly coupled with the tool; instead, adapters are provided, and users decide which backend to use.
## License
Dual licensing: **CC BY-NC-ND 4.0 + 6 additional terms**: attribution/non-commercial/no derivatives + no AI training/ no paid platform listing/ enterprise and administrative agencies recognized as commercial/ academic citation format/ no endorsement/ rights reserved. See [LICENSE](LICENSE) for full terms. For commercial authorization, enterprise deployment authorization, and AI training exemption, contact the author: You Chu <994559732@qq.com>.
