pzqpzq/LSF_MDia

📚 Machine Dialectology (MDia)

What it is – MDia is a research‑grade Python library that lets you treat the intermediate reasoning steps of large language models (LLMs) as machine‑to‑machine communication protocols. Instead of passing a long, human‑readable chain‑of‑thought, a speaker model emits a compact Language Symbolism Framework (LSF) card – a “dialect” that defines symbols, grammar, reusable operators, validity rules, and an empirical profile. A listener model then parses and executes that dialect. MDia provides the full lifecycle for creating, evolving, profiling, selecting, routing, and validating these dialect cards, with strict reproducibility guarantees.

---

🎯 Core ideas

Concept	Meaning
Dialect card (LSF)	A persistent specification D = (V, G, O, R, ρ) – symbols, grammar, operators, rules, and a data‑driven profile.
Speaker → Listener	One model produces a dialect card; another consumes it.
Utility is relational	The value of a dialect depends on speaker, listener, task, routing policy, and token budget.
Deterministic pipeline	Eight CLI stages (collect → create → evolve → profile → select → run → validate‑rules → report) that freeze evidence before any held‑out evaluation.
Reproducibility by construction	Immutable data partitions, content‑derived IDs, full token accounting, and a toy offline fixture that runs without any external API keys.

---

⚙️ Key features (as described in the README)

• Black‑box LLM compatible – works with any API‑based model; no hidden‑state access required.
• Reusable dialect cards – versioned, hash‑identified, and archivable for later reuse.
• Routing policies – single, aggregate, compose, and abstain/raw‑fallback plans that respect budget, risk, and listener openness.
• Rule‑based validation – a bank of 100 machine‑sociolinguistic rules, each with evidence levels (full, strong, not‑evaluated).
• Profiling across heterogeneous models – captures accuracy, token cost, failure modes, publicness, teaching advantage, and more.
• CLI‑first design – mdia command with sub‑commands for every pipeline stage; --help shows detailed options.
• Offline deterministic demo – examples/toy/ provides fixtures so the whole lifecycle can be run locally without any API key.
• Extensive documentation – architecture, pipeline, rule validation, extension guides, and a paper‑to‑code map.
• CI & quality gates – tests across Python 3.10‑3.12, static analysis (ruff, mypy), formatting, and secret scanning.

---

🚀 Typical use cases

Scenario	How MDia helps
Research on inter‑model communication	Create reusable LSFs, evolve them, and measure how different model families benefit from each other’s dialects.
Token‑efficient reasoning	Replace verbose CoT traces with compact dialect cards that retain the state needed by a downstream listener, cutting generated tokens by ~70 % (as reported in the paper).
Curriculum‑style teaching	Use a weaker speaker to generate a “teaching dialect” that other models can adopt with high utility.
Robust routing under budget constraints	Deploy single or compose routing plans that respect a token budget while avoiding dialects that a listener is known to resist.
Auditable reproducibility	Freeze dialect selection and routing decisions before test‑time evaluation, ensuring no leakage from held‑out data.

---

📦 Installation (from the README)

# Clone the repo
git clone https://github.com/pzqpzq/LSF_MDia.git
cd LSF_MDia

# Create a virtual environment (Python 3.10+ required)
python -m venv .venv
source .venv/bin/activate

# Install the package in editable mode (pulls in all dependencies)
pip install -e .

No external API keys are needed for the toy demo; real‑world runs require you to add a compatible model provider adapter as described in docs/extending.md.

---

🏃‍♀️ Quick‑start example (from the README)

# Run the deterministic toy pipeline
mdia pipeline --config configs/toy_mdia.yaml

The command creates a versioned run directory (runs/<run_id>/) containing:

• raw traces,
• generated dialect cards,
• evolution and router validation profiles,
• a frozen dialect bank,
• route plans, predictions, token accounting, and a full reproducibility report. Re‑running with the same seed reproduces exactly the same artifacts.

---

📉 Limitations & scope (as stated or implied)

• Research‑grade only – the library is built for controlled experiments; it is not a production‑ready serving stack.
• Benchmark‑specific fixtures – the offline demo uses a small, redistributable dataset; reproducing the paper’s numbers requires the exact model revisions and private benchmark data.
• Black‑box reliance – MDia assumes the underlying LLM can be queried via a standard API; it does not support models that expose internal state.
• Rule bank is conservative – only 19 of the 100 rules have strong empirical support; the rest are marked as weaker evidence.
• Routing decisions must be frozen – the framework enforces a strict separation between validation and test partitions, which may feel restrictive for rapid prototyping.

---

📄 License

The project is released under the MIT License (see LICENSE).

---

📚 Citation (from the README)

If you use MDia in a publication, cite the accompanying ICML 2026 poster and arXiv pre‑print:

@inproceedings{mdia2026,
  title = {Machine Dialectology: from verbose reasoning traces to a measurable ecology of machine dialects},
  author = {…},
  booktitle = {Proceedings of the 2026 International Conference on Machine Learning (ICML)},
  year = {2026},
  url = {https://arxiv.org/abs/2606.29354},
  note = {Poster 61557}
}

(Exact author list can be taken from the arXiv entry.)

---

🔗 Where to go next

• Read the architecture guide (docs/architecture.md) to understand how to implement a new model provider.
• Explore the rule system (docs/rules.md) if you want to add or modify sociolinguistic constraints.
• Try the toy pipeline and inspect the generated report.md to see how provenance links are recorded.
• Check the legacy workspaces (legacy/) for earlier versions of the CLSR framework if you need historical context.

---

MDia is a genuine, open‑source research platform for studying reusable symbolic protocols among heterogeneous LLM agents. All the information above is taken directly from the repository’s README.