LARK

Grammar-Constrained Neuro-Symbolic Agents for Low-Resource Historical Languages

Syriac · Arabic · Hebrew

PES University | PES1UG23AM005 · PES1UG23AM040 · PES1UG23AM913

🌟 Overview

LARK is a neuro-symbolic (NeSy) research system for morphological reasoning over low-resource historical languages, beginning with Classical Syriac. It combines:

Symbolic reasoning — A formal DSL compiled to Z3 SMT constraints, grounded in a Neo4j knowledge graph
Neural generation — A fine-tuned mT5 model trained with constraint-violation loss
Planner–Generator–Verifier loop — A three-stage inference pipeline with rule-level trace JSON

Research Question

Does constraint-aware training and decoding improve morphological accuracy on Syriac compared to a standard language model baseline, especially under low-resource (10–50% data) conditions?

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/your-username/lark.git
cd lark

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install LARK in development mode
pip install -e .

Configuration

Create a .env file in the project root:

# Neo4j Database
URI=bolt://localhost:7687
GRAPHDB_USERNAME=neo4j
GRAPHDB_PASSWORD=your_password

# Mistral AI (for rule mining)
MISTRAL=your_mistral_api_key

# Google Gemini (for OCR)
GEMINILARK=your_gemini_api_key

Usage

Command Line Interface

# Analyze a single Syriac word
lark analyze "ܐܳܟܠܳܐ"

# Analyze multiple words
lark analyze "ܐܳܟܠܳܐ" "ܡܠܟܐ" "ܐܢܐ"

# Analyze from file
lark analyze -f words.txt -o results.json

# Enable verbose logging
lark analyze "ܐܳܟܠܳܐ" -v

Python API

from lark import analyze_L, Neo4jClient, RuleEngine

# Analyze a word
features = analyze_L("ܐܳܟܠܳܐ")
print(f"POS: {features.pos}, Gender: {features.gender}")

# Connect to knowledge graph
client = Neo4jClient(uri, username, password)
rules = client.fetch_rules()

# Apply morphological rules
rule_engine = RuleEngine(rules)
matched_rules = rule_engine.apply(features)

📓 Jupyter Notebooks

Interactive notebooks demonstrating LARK capabilities and training workflows

🚀 Core Notebooks

🎯 LARK-Constraint-Finetuning.ipynb

⭐ Main Training Notebook - Start Here!

Complete end-to-end fine-tuning pipeline with LARK constraints:

Dataset Preparation: Peshitta Bible translation (Syriac ↔ English)
LARK System: Morphological analysis + constraint validation
Custom Training: Constraint-aware loss with Neo4j rules
Model: Cohere TinyAya fine-tuning with LoRA adapters
Evaluation: Grammar metrics and violation scoring

Features:

✅ Comprehensive markdown documentation
✅ Security best practices (environment variables)
✅ Memory-optimized training (T4 GPU compatible)
✅ Bidirectional translation prompts
✅ Real-time constraint violation monitoring

Use Case: Production-ready training with morphological constraints

🏗️ BaseFinetuning.ipynb

Foundation Model Fine-Tuning

Baseline fine-tuning without LARK constraints:

Model: mT5-small base model training
Dataset: Peshitta Bible verses
Focus: Standard translation task
Purpose: Establish performance baseline

Use Case: Compare constrained vs unconstrained training

📊 DataProcessing.ipynb

Dataset Engineering & Preprocessing

Complete data pipeline for Syriac biblical texts:

Text Extraction: ASCII to Syriac Unicode conversion
Data Cleaning: Normalization, diacritic handling
Format Conversion: JSONL to training datasets
Quality Control: Text validation and filtering
Statistics: Dataset analysis and reporting

Use Case: Prepare custom datasets for training

🏷️ EnglishDatasetTagging.ipynb

English Translation Annotation

Annotation and quality assessment for English translations:

Manual Tagging: Translation quality assessment
Error Analysis: Common translation patterns
Dataset Validation: Verify English-Syriac alignment
Quality Metrics: Translation accuracy scoring

Use Case: Improve dataset quality and alignment

⚖️ RuleMining.ipynb

Grammar Rule Extraction

Automated mining of morphological rules from grammars:

LLM Integration: Mistral API for rule extraction
Pattern Recognition: Identify morphological patterns
Neo4j Loading: Populate knowledge graph automatically
Rule Validation: Z3 constraint verification
Bulk Processing: Process entire grammar texts

Use Case: Expand Neo4j rule base from grammar sources

📋 Notebook Usage

Quick Start

# Clone repository
git clone https://github.com/aaronmat1905/LARK.git
cd LARK

# Install dependencies
pip install -r requirements.txt

# Start Jupyter
jupyter notebook

Environment Setup

Create .env file before running notebooks:

# Neo4j Connection
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password

# GitHub (for repo cloning in notebooks)
GITHUB_TOKEN=your_github_pat

# HuggingFace (for model upload)
HF_TOKEN=your_huggingface_token

Recommended Order

📊 DataProcessing.ipynb - Understand the dataset
🏷️ EnglishDatasetTagging.ipynb - Learn data quality
⚖️ RuleMining.ipynb - Build Neo4j rules
🎯 LARK-Constraint-Finetuning.ipynb - Train with constraints
🏗️ BaseFinetuning.ipynb - Compare baseline performance

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     LARK System Architecture                │
└─────────────────────────────────────────────────────────────┘

┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Grammar   │ -> │  Gemini OCR  │ -> │  Raw Text Data  │
│   PDFs      │    │              │    │                 │
└─────────────┘    └──────────────┘    └─────────────────┘
                                               │
                                               ▼
┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│ Mistral     │ -> │   Rule       │ -> │  Neo4j Knowledge │
│ LLM Mining  │    │   Mining     │    │  Graph          │
└─────────────┘    └──────────────┘    └─────────────────┘
                                               │
                                               ▼
┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│ Z3 SMT      │ <- │   DSL        │ <- │  Language       │
│ Solver      │    │   Compiler   │    │  Analyzer       │
└─────────────┘    └──────────────┘    └─────────────────┘
                                               │
                                               ▼
┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│ Evaluation  │ <- │  NeSy Model  │ <- │  Training Loop  │
│ Suite       │    │  (mT5)       │    │                 │
└─────────────┘    └──────────────┘    └─────────────────┘

Components

Language Adapters (src/lark/language/)
- Unicode normalization for Syriac script
- Morphological feature extraction
- Multi-language support (Syriac, Arabic, Hebrew)
DSL & Constraints (src/lark/dsl/)
- Z3-based constraint specification
- Predicate library (Agree, HasSuffix, etc.)
- Rule compiler for SMT solving
Knowledge Graph (src/lark/graph/)
- Neo4j integration for rule storage
- 206 rules · 361 constraints · 1,333 relationships
- Live synchronization from grammar texts
Pipeline (src/lark/pipeline/)
- Planner–Generator–Verifier architecture
- Rule engine with constraint satisfaction
- Explanation generation

📊 Project Status

Sprint Progress

Sprint	Focus	Status
Sprint 1	✅ Repo scaffold · Z3 hello-world · Grammar survey · Feature schema	~100%
Sprint 2	✅ Language adapter · DSL predicates · Z3 compiler · Rule mining	~100%
Sprint 3	🔄 mT5 LoRA training · NeSy loss · Planner–Generator–Verifier	~60%
Sprint 4	🔲 Full evaluation · Error analysis · Rule trace analysis	~0%

Overall: ~65% complete

Knowledge Graph Stats

206 Rules covering morphological phenomena
361 Constraints with Z3 verification
1,333 Relationships in the knowledge graph
117 Features in the universal schema

🧪 Testing

Run Tests

# Run all tests
pytest

# Run specific test module
pytest tests/test_language/

# Run with coverage
pytest --cov=src/lark --cov-report=html

# Skip integration tests
pytest -m "not integration"

Test Structure

tests/
├── test_dsl/          # DSL predicate tests
├── test_graph/        # Neo4j integration tests
├── test_language/     # Language analyzer tests
└── test_pipeline/     # Pipeline integration tests

📖 Documentation

Architecture Guide — System design and data flow
API Reference — Complete API documentation
User Guide — Usage examples and tutorials
Contributing — Development guidelines

👥 Team

Name	Roll No	Role
Aaron Thomas Mathew	PES1UG23AM005	System Architecture & Neo4j
Aman Kumar Mishra	PES1UG23AM040	DSL Development & Z3 Integration
Preetham V J	PES1UG23AM913	Language Processing & ML

📚 References

Primary Sources

Grammar: Compendious Syriac Grammar — Theodor Nöldeke (Internet Archive)
Corpora: ETCBC Syriac, ALP (Annotated Lexica and Paradigms)

Models & APIs

OCR: Google Gemini gemini-2.5-flash
LLM: Mistral ministral-8b-latest (Apache 2.0)
Base Model: google/mt5-small

🛠️ Development

Setup Development Environment

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run linting
black src/ tests/
flake8 src/ tests/
mypy src/

Project Structure

lark/
├── src/lark/           # Main package (v0.2.0)
├── tests/              # Test suite
├── docs/               # Documentation
├── data/               # Dataset files (Peshitta Bible)
├── notebooks/          # 📓 Jupyter notebooks (interactive demos)
├── legacy/             # Deprecated development files
├── config/             # Configuration files
├── scripts/            # Utility scripts
└── requirements.txt    # Dependencies

⚠️ License & Citation

License

Citation

If you use LARK in your research, please cite:

@software{lark2024,
  title={LARK: Grammar-Constrained Neuro-Symbolic Agents for Low-Resource Historical Languages},
  author={Mathew, Aaron Thomas and Mishra, Aman Kumar and J, Preetham V},
  year={2024},
  institution={PES University},
  note={Research Use Only}
}

🙏 Acknowledgments

PES University — Academic guidance and resources
Nöldeke's Grammar — Foundation for Syriac linguistic rules
Open Source Community — Z3, Neo4j, and HuggingFace

📧 Contact

For questions, issues, or collaboration:

GitHub Issues: github.com/your-username/lark/issues
Email: research@lark-project.edu (hypothetical)

Built with ❤️ for low-resource historical language preservation

⬆ Back to Top

Name		Name	Last commit message	Last commit date
.claude		.claude
data		data
docs		docs
notebooks		notebooks
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AUTHORS.md		AUTHORS.md
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CONTRIBUTING.md		CONTRIBUTING.md
LARK_UPDATE_SUMMARY.md		LARK_UPDATE_SUMMARY.md
LICENSE		LICENSE
README.md		README.md
SECURITY-INCIDENT-REPORT.md		SECURITY-INCIDENT-REPORT.md
SECURITY-UPDATE.md		SECURITY-UPDATE.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation