Legal Terms Agent (LangGraph)

Local pipeline to:

1. Extract English legal/regulatory terms from .docx/.pdf study pages (via an OpenAI-compatible LLM such as LM Studio), or consume a plain bullet/line list.
2. Look up definitions in Black's Law Dictionary PDF volumes using a BM25 + cascade matcher (EXACT → NORMALIZED → COMPONENT).
3. Optionally map terms to Russian wording + retrieve snippets from your own .txt corpus of Russian legislation (mini-RAG).

Setup

python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
# Edit .env for LM Studio: LLM_BASE_URL / LLM_MODEL

Place dictionary PDFs in any folder. You can point to that folder with --dictionary-dir.

Mac: full setup from scratch + DMG

See docs/MAC_SETUP.md.

CLI

# 1) Extract terms from a textbook (needs running LLM server)
legal-agent run-extract -i ./18-33.docx --out-json terms.json

# 2) Lookup a fixed list against Black's PDFs
legal-agent run-lookup \
  --terms ./data/sample_terms.txt \
  --dictionary-dir . \
  --dictionary-glob '*.pdf' \
  --output ./output

# 3) Full graph (uses --terms if provided, otherwise LLM extraction from --input)
legal-agent run-all -i ./18-33.docx --dictionary-dir . --dictionary-glob '*.pdf' --output ./output

# Optional RU mini-RAG (corpus is your local .txt files)
legal-agent run-lookup \
  --terms ./data/sample_terms.txt \
  --dictionary-dir . \
  --dictionary-glob '*.pdf' \
  --output ./output_ru \
  --enable-ru \
  --ru-corpus ./data/sample_ru_corpus.txt

# 4) Super-simple mode (for non-technical users)
legal-agent run-simple \
  --terms ./data/sample_terms.txt \
  --dictionary-dir ./dictionaries \
  --output ./output_simple

Non-technical quick start

1. Put dictionary PDF files in one of these places:
   • ./dictionaries/ (inside the project folder), or
   • ../dictionaries/ (same parent folder as the project — handy next to a copied app folder), or
   • macOS + DMG: a folder named dictionaries next to the .dmg file` on disk (same directory as the disk image).
2. Put your terms (one per line) into one of:
   • terms.txt next to the .dmg on Mac (recommended for DMG), or words.txt / sample_terms.txt / my_terms.txt there,
   • or ./data/sample_terms.txt inside the project,
   • or ../terms.txt next to the project folder.
3. Run (auto-detects terms + dictionaries; optional explicit paths):

bash ./run_simple.sh

Explicit dictionary/output (still supported):

bash ./run_simple.sh ./data/sample_terms.txt ./dictionaries ./output_simple

Result file: ./output_simple/results_human.xlsx inside the project when writable.
If you run from a read-only DMG, the Excel report is written **next to the .dmg file** (same folder as terms.txt/dictionaries/): output_simple/results_human.xlsxthere. Only if that folder is not writable does it fall back to~/Library/Application Support/LegalTermsAgent/output_simple/`.

Notes:

• You do not need to create .venv manually. The script creates it automatically on first run (under the project or under ~/Library/Application Support/LegalTermsAgent on read-only media).
• If the executable bit is missing after copying project files, use bash ./run_simple.sh ... (works without chmod +x).

Outputs:

• results.json — structured TermWithRuMapping records
• results.xlsx — flattened columns for review
• results_human.xlsx — simplified table: word / status / confidence / definition
• run_meta.json — which inputs/dictionaries were used

Index cache

First PDF index build can take several minutes for large volumes. Reuse cache:

legal-agent run-lookup --terms data/sample_terms.txt --index-cache .cache/blacks_index.pkl

Skip cache with --no-index-cache.

Architecture

LangGraph nodes live in app/graphs/legal_terms_graph.py:

load_input → extract_terms → normalize_terms → lookup_definitions → validate_output → optional_ru → export_report

Evaluation notes

See docs/EVALUATION.md.

Limitations

• PDF retrieval uses page/chunk windows; quotes may start mid-entry if a dictionary page is split.
• FOUND_COMPONENT matches can be noisy for very generic words—review manual_review rows.
• LM Studio must expose an OpenAI-compatible /v1/chat/completions endpoint for extraction/RU translation steps.