Xenon
CI
codecov
Release
GitHub stars
License: MIT
Python 3.10+
<p align="center">
<img src="https://raw.githubusercontent.com/xianyu-sheng/Xenon/HEAD/docs/logo-animated.gif" alt="Xenon — 픽셀 러너가 중앙선을 따라 달리다가 점차 사라지며 블록 XENON 식별자로 재구성됩니다." width="440">
</p>
<h3 align="center">하나의 루프, 하나의 장부(Ledger), 재현 가능한 진실 세트</h3>
<p align="center">모델은 제안할 수 있지만, 검증되지 않은 결과를 거래 완료로 간주할 수는 없습니다.<br/>Xenon은 모든 단계의 도구 실행을 '타입이 지정된 영수증(typed receipt)'으로 만들고, 각 주장(claim)을 사실(fact)에 연결하며, 검증할 수 없는 부분은 명시적으로 부채(debt) 또는 기권(abstain)으로 처리합니다.</p>
<p align="center">
<b>SWE-bench Lite 블라인드 테스트</b>: 고정 30개 사례 <b>62.2%</b> · 중복 없는 홀드아웃 세트 <b>52.2%</b> · <b>4,000+</b> 테스트 · <b>Python 3.10–3.12</b>
</p>
<p align="center">
<a href="#빠른-시작">빠른 시작</a> ·
<a href="#핵심-아키텍처">핵심 아키텍처</a> ·
<a href="#증거와-실패-의미론">증거</a> ·
<a href="#평가">평가</a> ·
<a href="docs/OPERATION_GUIDE.md">문서</a> ·
<a href="https://github.com/xianyu-sheng/Xenon/issues">Issues</a> ·
<a href="README.en.md">English</a>
</p>
[!TIP]
모델이 제안하고, 하네스(harness)가 증명합니다. Xenon은 LLM을 심판으로 간주하지 않으며, 여러 동형 엔진들이 각자 도구를 해석하도록 허용하지 않습니다. 오직 하나의 LoopRuntime만을 유지합니다: 모델이 capability action을 출력하고, catalog이 도구를 바인딩하며, gateway가 영수증(receipt)을 반환하고, controller가 repair/debt를 결정하며, Finalizer가 배포 제출을 전담합니다.
빠른 시작
pip install https://github.com/xianyu-sheng/Xenon/releases/download/v0.9.5/xenon_harness-0.9.5-py3-none-any.whl
...
Windows에서 'xenon'은 내부 또는 외부 명령이 아닙니다라는 메시지가 표시되면, pip 출력의 Scripts 경로를 PATH에 추가하거나 python -m xenon을 직접 사용하십시오.
git clone --depth 1 https://github.com/xianyu-sheng/Xenon.git
cd Xenon && python -m venv .venv
...
왜 단일 루프인가
이전 버전의 Xenon에는 7개의 '추론 엔진'이 있었습니다. engine/registry.py는 스스로 인정합니다: 일곱 가지 내장 패러다임은 실행 흐름이 완전히 동형적이며, 차이는 오직 엔진 클래스, 소량의 매개변수, 패턴 문자열 및 패널 제목에 불과했습니다. 그 결과, 동일한 루프가 7번 복사되었고, 도구 의미론(tool semantics)은 prompt, plan 검증, TaskState, ClaimGate, delivery 다섯 곳에 흩어져 있었습니다.
이제는 단 하나의 제어 흐름만 남았습니다:
TaskSpec
→ LoopRuntime(유일한 작성자, 명시적 phase machine)
view = Projection(ledger[0..seq], catalog, spec)
...
핵심 아키텍처 (Core Architecture)
┌──────────── LoopRuntime(유일한 작성자)────────────┐
TaskSpec ─────────▶│ intake → running → tool_call → reconciling │
│ → auditing → delivering → finalized │
...
7가지 불변성 (Seven Invariants)
- I1 단일 작성자(Single Writer):
LoopRuntime만이 ledger에 내용을 추가할 수 있습니다.
- I2 단일 진입점(Single Entry Point): 모든 도구의 부작용은
ToolGateway를 거치며, 최종 제출(delivery submission)은 Finalizer가 독점합니다.
- I3 단일 사실 원천(Single Source of Truth): ledger는 유일한 진실이며, 다른 것은 모두
input_seq가 붙은 읽기 전용 투영(read-only projection)입니다.
- I4 의미론적 인터페이스(Semantic Interface): kernel은 capability / obligation / receipt만을 인식하며, 도구 이름은 catalog에만 존재합니다.
- I5 제안/사실 분리(Proposal/Fact Separation): LLM의 출력은
claim-* / hyp-*이며, fact-*를 생성할 수 있는 것은 binder뿐입니다.
- I6 단일 결정권(Single Decision Authority):
VerificationController가 repair / replan / abstain / abort를 결정합니다.
- I7 재현 가능성(Replayability): 동일한 ledger 접두사에서 매 바이트마다 일치하는 투영을 생성하며, 재현 과정에는 네트워크가 필요 없습니다.
한 턴의 진행 방식 (How a Turn Proceeds)
입력
→ TaskSpec: objective / user_objective / obligations / budget / permission
→ 모델 제안: think / call_tool / submit_plan / update_plan / finish / abort
...
ToolCatalog는 7가지 종류의 capability를 사용하여 도구 의미론을 표현합니다: read / search / edit / verify / vcs / shell / remote;- 도구 이름은 catalog/spec에만 존재하며, kernel은 구체적인 도구 이름을 분기하지 않습니다;
- MCP는 도구별 ToolSpec을 사용하며, 모든 도구를 모델에게 주입하는 방식이 아닙니다;
- 도구 예산은 objective를 기준으로 결정론적 선택을 합니다 (예: 46개의 GitHub 도구 중 16개만 주입), 알 수 없는 도구는
unresolved로 처리됩니다;
- approval은 외부 MCP 호출의 경계입니다. 매번 승인은 목표(target)와 TTL(Time To Live)을 바인딩하며, 호출 직후 취소됩니다;
git push는 명시적인 TaskSpec.allow_push가 있기 전까지 거부권(veto)이 유지됩니다.
증거 및 실패 의미론 (Evidence and Failure Semantics)
| 레벨 | 검사 항목 | 권위 |
|---|
| V0 | exit code, no-op write, target 매칭, 실제 test target, commit sha, worktree delta | controller |
| ... | | |
- 도구 실패는 키워드 추측으로 성공 처리되지 않습니다;
- 0개 매칭은
unresolved이며, 다중 매칭은 ambiguous입니다. 이 둘 모두 침묵하며 하나를 선택하지 않습니다;
- 결정론적으로 검증할 수 없는 의미론적 요구사항은 pass가 아니라
abstained여야 합니다;
- debt는 fact가 생성되거나 사용자가 명시적으로 승인하기 전까지 delivery를 막습니다;
- 해시 체인은 과정이 변조되지 않았음을 증명하지만, 모델 결론의 정확성을 증명하지는 않습니다.
/evidence 현재 kernel ledger, V2 coverage, claims, debt 및 체인 검증을 확인합니다
/goal 목표/단계/계획/미결 부채를 확인합니다
/resume ledger 포인터만 복구하며, 이미 실행된 부작용은 재현하지 않습니다
평가 (Evaluation)
고정 프로토콜, 항목별 동결(freezing), 누구나 재현 가능:
| 항목 | 값 |
|---|
| 프로토콜 | 완전 블라인드 테스트: 문제 해결 단계에서 공식 test patch를 적용하지 않으며, prompt에 FAIL_TO_PASS라는 명칭이 포함되지 않음 |
| ... | |
| 샘플 | 이번 프레임워크 |
| --- | ---: |
| 고정 30개 사례 (seed 20260729) | 62.2% |
| 비중복 여유 집합 (seed 20261016) | 52.2% |
전체 프로토콜, 순차 결과, 판정 로그 및 sha256 아카이빙은 EVAL_RESULTS에서 확인할 수 있습니다.
포함 리소스 (Included)
자주 사용되는 명령어 (Common Commands)
/evidence 증거 사슬 / 커널 원장(kernel ledger) / V2 커버리지
/goal 목표, 단계, 계획, 부채
/resume 세션 및 원장 포인터 복구
...
문서 (Documentation)
명시적 경계 및 주의사항 (Honest Boundaries)
- 해시 체인 증명 과정은 결론을 증명하지 않습니다. 이는 손상, 단일 지점 변조 및 재배열을 발견할 수 있지만, 선택적 HMAC 앵커를 활성화하지 않는 한 쓰기 권한이 있는 사용자가 전체 체인을 다시 계산하는 것을 막지는 못합니다.
- abstain은 제품 동작입니다. 결정론적으로 검증할 수 없는 의미 요구사항은 pass로 포장되지 않습니다.
- 승인(approval)은 샌드박스가 아닙니다. 외부 MCP 서버는 여전히 통제된 환경에서 실행되어야 하며, approval은 단지 호출 경계일 뿐입니다.
- SWE-bench의 수치는 샘플 및 예산 제한이 있습니다. EVAL_RESULTS의 프로토콜에 따라 읽어주시고, 30개 사례 집합을 순위표 결론으로 간주하지 마십시오.
라이선스 (License)
MIT
