bikoret/kushya_generator/README.md

Kushya Generator — Component F (Architecture §3.6)

Fine-tuned Mistral Medium 3.1 whose sole function is to generate adversarial challenges (kushyot) to proposed Torah interpretations.

Eilu v'eilu divrei Elohim chayim, v'halakhah k'beit Hillel. Both these and those are the words of the living God; the law follows Beit Hillel — but the dispute is preserved (Eruvin 13b).

Status

This directory holds the scaffolding for a fine-tuned kushya generator. The actual training run requires a GPU + curated dataset and is the operator's task. Until then, kushya generation in production falls back to:

1. Rule-based kushyot from the Talmudic Engine (see talmudic_engine/src/reasoning/challenge.pl)
2. External-model consultation via Korban Processor (Step 22) wrapped in the offering protocol so external output is never treated as authoritative

The fine-tuned generator replaces step 2 with a model that has consumed only the kushya-generation function — eliminating the eish zarah risk that general-purpose model output presents.

Layout

kushya_generator/
├── README.md                       This file
├── data/
│   ├── prepare_training.py         Extracts (interpretation, kushya) pairs
│   └── training_pairs/
│       ├── seed_pairs.jsonl        Hand-curated seed pairs to bootstrap
│       └── README.md               Provenance and curation notes
├── fine_tune/
│   ├── config.yaml                 QLoRA configuration
│   └── train.py                    Fine-tuning script (transformers + peft)
├── inference/
│   ├── kushya_api.py               In-process API the Talmudic Engine calls
│   └── serve.py                    HTTP server (when self-hosted)
└── test/
    └── test_dataset.py             Validates training data structure

How a Kushya is Built

A kushya must:

1. Reference a specific Torah passage that creates tension with the proposed interpretation
2. Identify the logical or textual weakness in the interpretation
3. Be expressible as a question, not a statement
4. Not be resolvable by trivial clarification

These four requirements are encoded in data/prepare_training.py's validator — every training pair must pass them or be rejected.

Data Sources

The training data should come from the existing rabbinic tradition:

• Talmud Bavli — kushyot from disputes recorded in the Gemara
• Talmud Yerushalmi — parallel disputes
• Rishonim — Rashi, Tosafot, Rambam's challenges to other rishonim
• Acharonim — later commentary kushyot

The seed_pairs.jsonl in this repo is a small hand-curated set sufficient to validate the training pipeline. A production training run requires several thousand pairs.

Fine-Tuning

# Activate environment with PyTorch + transformers + peft + bitsandbytes
python fine_tune/train.py --config fine_tune/config.yaml

Output: a LoRA adapter that wraps the base Mistral Medium 3.1 model. Quantize to GGUF Q5_K_M and serve via inference/serve.py over llama.cpp.

Until Then

The Talmudic Engine generates rule-based kushyot. The pipeline can also consult external models via the Korban Processor's consult_external_model function, with output passing through the offering protocol.

The system has been built to NOT depend on this fine-tuned model. When the fine-tuned model exists, it strengthens kushya generation; until then, the system functions on rule-based + external testimony.