pzqpzq/LSF_MDia

📚 머신 다이아렉토로지 (MDia)

무엇인가요 – MDia는 대규모 언어 모델(LLM)의 중간 추론 단계를 기계 간 통신 프로토콜 로 간주할 수 있는 연구용 Python 라이브러리입니다. 인간이 읽기 쉬운 사고 흐름(chain-of-thought)을 전달하는 대신, 발화자 모델 은 컴팩트한 언어 상징 프레임워크(LSF) 카드 를 생성합니다. 이는 '방언'을 정의하는 것으로, 기호, 문법, 재사용 가능한 연산자, 유효성 규칙, 그리고 경험적 프로파일을 포함합니다. 청취자 모델 은 이 방언을 해석하고 실행합니다. MDia는 이러한 방언 카드의 생성, 진화, 프로파일링, 선택, 라우팅, 검증을 위한 전체 라이프사이클을 제공하며, 엄격한 재현성 보장을 합니다.

🎯 핵심 아이디어

개념	의미
방언 카드(LSF)	지속 가능한 사양 `D = (V, G, O, R, ρ)` – 기호, 문법, 연산자, 규칙, 데이터 기반 프로파일.
발화자 → 청취자	하나의 모델이 방언 카드를 생성하고, 다른 모델이 이를 소비함.
유용성은 관계적	방언의 가치는 발화자, 청취자, 작업, 라우팅 정책, 토큰 예산에 따라 달라짐.
결정론적 파이프라인	8단계 CLI 스테이지(`collect → create → evolve → profile → select → run → validate-rules → report`)로, 평가 전에 증거를 고정함.
구성에 의한 재현성	불변 데이터 파티션, 콘텐츠 기반 ID, 완전한 토큰 계산, 외부 API 키 없이 작동하는 토이 오프라인 테스트 환경.

⚙️ 주요 기능 (README에 기술됨)

블랙박스 LLM 호환 – 모든 API 기반 모델과 호환되며, 내부 상태 접근이 필요 없음.
재사용 가능한 방언 카드 – 버전 관리, 해시 식별, 아카이브 가능하여 나중에 재사용 가능.
라우팅 정책 – single, aggregate, compose, abstain/raw-fallback 계획을 제공하며 예산, 위험, 청취자 개방성 고려.
규칙 기반 검증 – 100개의 기계 사회언어학적 규칙 백업, 각 규칙은 증거 수준(완전, 강력, 평가되지 않음) 포함.
이질적 모델 간 프로파일링 – 정확도, 토큰 비용, 실패 모드, 공개성, 교육적 우위 등 측정.
CLI 우선 설계 – mdia 명령어에 파이프라인의 모든 스테이지용 서브커맨드 포함, --help로 상세 옵션 표시.
오프라인 결정론적 데모 – examples/toy/에 테스트 픽스처 제공, 외부 API 키 없이 로컬에서 전체 라이프사이클 실행 가능.
풍부한 문서화 – 아키텍처, 파이프라인, 규칙 검증, 확장 가이드, 논문-코드 매핑 포함.
CI 및 품질 게이트 – Python 3.10–3.12에서 테스트, 정적 분석(ruff, mypy), 포맷팅, 시크릿 스캔 수행.

🚀 일반적인 사용 사례

시나리오	MDia의 도움
모델 간 통신 연구	재사용 가능한 LSF 생성, 진화, 서로 다른 모델 패밀리가 서로의 방언에서 어떤 이점을 얻는지 측정.
토큰 효율적인 추론	긴 CoT 추적을 대체하여 하위 모델이 필요로 하는 상태를 유지하는 컴팩트한 방언 카드 사용, 생성 토큰 약 70% 감소 (논문 보고).
커리큘럼 스타일 교육	약한 발화자가 '교육용 방언' 생성, 다른 모델이 높은 유용성으로 채택 가능.
예산 제약 하에서 강건한 라우팅	토큰 예산을 존중하면서, 청취자가 거부할 것으로 알려진 방언을 피하는 `single` 또는 `compose` 라우팅 계획 배포.
검증 가능한 재현성	테스트 평가 전에 방언 선택 및 라우팅 결정 고정, 휴지된 데이터에서의 누출 방지.

📦 설치 (README에서)

# 리포지토리 클론
git clone https://github.com/pzqpzq/LSF_MDia.git
cd LSF_MDia

# 가상 환경 생성 (Python 3.10+ 필요)
python -m venv .venv
source .venv/bin/activate

# 편집 가능 모드로 패키지 설치 (모든 종속성 포함)
pip install -e .

토이 데모에서는 외부 API 키가 필요 없음. 실제 실행에는 docs/extending.md에 설명된 대로 호환 모델 제공자 어댑터를 추가해야 함.

🏃‍♀️ 빠른 시작 예제 (README에서)

# 결정론적 토이 파이프라인 실행
mdia pipeline --config configs/toy_mdia.yaml

이 명령어는 버전 관리된 실행 디렉터리(runs/<run_id>/)를 생성하며, 다음을 포함함:

원시 추적 데이터
생성된 방언 카드
진화 및 라우터 검증 프로파일
고정된 방언 백업
라우팅 계획, 예측, 토큰 계산, 완전한 재현성 보고서 같은 시드로 재실행하면 정확히 동일한 아티팩트 재현됨.

📉 제한 및 범위 (기재 또는 암시됨)

연구용만 – 제어된 실험용으로 설계됨. 프로덕션용 서빙 스택 아님.
벤치마크 전용 테스트 데이터 – 오프라인 데모는 소규모 재배포 가능한 데이터셋 사용. 논문 수치 재현에는 정확한 모델 리비전과 비공개 벤치마크 데이터 필요.
블랙박스 의존성 – MDia는 하위 LLM이 표준 API로 쿼리 가능하다는 가정. 내부 상태를 노출하는 모델은 지원 안 함.
규칙 백업은 보수적 – 100개 규칙 중 19개만 강력한 실증적 근거 보유. 나머지는 약한 증거로 표시.
라우팅 결정은 고정 필요 – 검증과 테스트 파티션 간 엄격한 분리 강제로, 빠른 프로토타이핑에는 제약으로 느껴질 수 있음.

📄 라이선스

프로젝트는 MIT 라이선스 (see LICENSE) 하에 배포됨.

📚 인용 (README에서)

MDia를 논문에 사용할 경우, 동반된 ICML 2026 포스터와 arXiv 사전 인쇄를 인용하세요:

@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}
}

(정확한 저자 목록은 arXiv 항목에서 가져올 수 있음.)

🔗 다음에 할 일

새로운 모델 제공자 구현 방법을 이해하려면 아키텍처 가이드 (docs/architecture.md)를 읽으세요.
사회언어학적 제약을 추가하거나 수정하고 싶다면 규칙 시스템 (docs/rules.md)을 탐색하세요.
토이 파이프라인을 시도하고 생성된 report.md를 확인해 증거 연결이 어떻게 기록되는지 확인하세요.
역사적 맥락이 필요하면 레거시 워크스페이스 (legacy/)를 확인하세요.

MDia는 이질적 LLM 에이전트 간 재사용 가능한 기호적 프로토콜을 연구하는 진정한 오픈소스 연구 플랫폼입니다. 위의 모든 정보는 리포지토리의 README에서 직접 가져왔습니다.