Imported from davitsargsyan0/ar-lex_graph (AGENTS.md). Install upstream with npx skills add davitsargsyan0/ar-lex_graph. Copyright stays with the author.

Ar-Lex Graph — Capstone Project

Project Overview

Multi-agent Graph-RAG system for statutory interpretation of Armenian law. Compares Graph-RAG (Neo4j + three-agent swarm) vs standard RAG on the Armenian legal corpus.

Capstone Proposal Davit Sargsyan DS2026.pdf - holds the original proposal of the project.

literature_review.md - holds a strong review which will help us understand the best practice how to complete this project.

Architecture

• Data source: Arlis.am (Armenian legal database)
• Knowledge graph: Neo4j 5 Community Edition (Docker)
• Embeddings: sentence-transformers/paraphrase-multilingual-mpnet-base-v2
• Vector store: FAISS
• LLM: Codex Codex-sonnet-4-6 via Anthropic SDK (tool_use mode)
• Agent framework: Three-agent swarm (Researcher → Jurist → Consultant)

Three Application Agents (NOT Codex agents — these are Python classes)

• Agent A (Researcher): agents/researcher.py — Queries Neo4j, uses graph_search + get_subgraph tools
• Agent B (Jurist): agents/jurist.py — Validates hierarchy + temporal validity. Hierarchy: Constitution > ConstitutionalLaw > Code > Law > Decree
• Agent C (Consultant): agents/consultant.py — Synthesizes answer in Armenian, MUST cite Arlis.am URLs

Key Technical Decisions

• Use neo4j Python driver (not py2neo)
• All agent tool calls use Anthropic SDK tool_use / tool_result message format
• Each agent returns a typed dataclass (ResearchResult, JuristResult, ConsultantResult)
• Hierarchy level encoded as integers: Constitution=5, ConstitutionalLaw=4, Code=3, Law=2, Decree=1
• All Armenian text handled as UTF-8; do NOT transliterate
• Scraper rate limit: 1 request/second (sleep between requests)
• Data files in data/ are gitignored (large); schema + code are committed

Environment

• macOS (Apple Silicon / Intel)
• Python 3.14
• Virtual env at .venv — ALWAYS activate with source .venv/bin/activate before running anything
• Use python (not python3) after venv activation
• Dependencies in requirements.txt
• Secrets in .env (gitignored): NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD, ANTHROPIC_API_KEY
• Neo4j running via Docker Desktop on localhost:7687
• Docker commands: use docker compose (not docker-compose) — modern Docker Desktop syntax

Coding Standards

• All public functions have type hints and docstrings
• All modules have a if __name__ == "__main__": block for standalone testing
• Use dataclasses for data structures, not dicts
• Errors raise custom exceptions defined in utils/exceptions.py
• Logging via Python logging module (not print statements)
• Tests in tests/ using pytest

File Naming

• Scraper output: data/raw/statutes_raw.jsonl
• Processed output: data/processed/statutes_clean.jsonl
• Embeddings: data/embeddings/faiss_index.bin + data/embeddings/article_ids.json

When Writing New Code

1. Check if a similar utility already exists in utils/ before creating new ones
2. Every new Python file gets a module docstring
3. Hard-code nothing — use constants from config.py