xgen-harness
LLM 자율 조립 에이전트 하네스. 10-stage 고정 파이프라인 한 줄 설정으로 에이전트를 돌리고, 그 워크플로우를 그대로 컴파일(npm tarball / Python wheel)해 env-only standalone(또는 MCP 서버)으로 실행한다.
- 도메인 agnostic 엔진 — xgen/canvas/cluster 같은 특정 플랫폼 어휘를 모른다. 도메인 지식은 외부 패키지가
entry_points로 끼워넣는다(이식측 =harness_bridge). - 버전 히스토리: CHANGELOG.md.
pip install xgen-harness
# 선택: pip install "xgen-harness[api,mcp]"
핵심 개념
- Planner 없음 (v1.1.0+): 10 Stage 가 항상 순서대로 실행.
HarnessConfig만 만들면 돈다. - Stage = 점진 노출: 각 Stage 는 자기 담당(capability/도구/리소스)만 LLM 에 노출하고, 본문 LLM 이 그 안에서 도구를 자율 호출한다.
- Strategy 핀: Stage 구현만 골라 끼운다. 나머지는 디폴트.
from xgen_harness import HarnessConfig, Pipeline
# 표준 — 직선 흐름
config = HarnessConfig(max_iterations=5)
# 특정 stage strategy 핀
config = HarnessConfig(active_strategies={
"s06_context": "cascade", # 컨텍스트 압축 자동
"s08_decide": "judge_then_loop", # 응답 품질 평가(judge) 활성
})
# 도구 없이 단순 LLM 호출
config = HarnessConfig(active_strategies={"s04_tool": "none"})
# Pipeline 이 config + provider + tool_source 를 받아 10-stage 실행
# (이식측은 XgenAdapter 등으로 provider/tool_source 를 주입)
10 Stage
| # | Stage | 책임 | 기본 strategy |
|---|---|---|---|
| 0 | s00_harness |
LLM 핸들 owner + 본문호출 dispatcher | streaming |
| 1 | s01_input ✱ |
입력 정규화·멀티모달 추출 | default |
| 2 | s02_history |
같은 interaction 이전 turn 로드 | default |
| 3 | s03_prompt |
system_prompt·citation·thinking_mode | section_priority |
| 4 | s04_tool |
도구 카탈로그(ToolSource 단일 채널) + Capability 자동발견 | progressive_3level |
| 5 | s05_policy |
Guard 체인 ×4 훅 (guards 비면 bypass) |
— |
| 6 | s06_context |
scope 선언(RAG/Ontology/DB/폴더/파일) + 토큰 컴팩션 (검색은 s07 도구) | cascade |
| 7 | s07_act |
도구 실행 (read 병렬 / write 직렬) | default |
| 8 | s08_decide ✱ |
루프 계속/종료 + (선택)응답 품질 judge | threshold |
| 9 | s09_finalize ✱ |
최종 응답 + Metrics + (선택)DB 기록 | default |
✱ = REQUIRED_STAGES(비활성 불가). 그룹: 초기화(04, 1회) · 루프(58, max_iterations회) · 종료(9, 1회).
도구 — ToolSource 단일 채널
도구는 전부 s04_tool 의 ToolSource 인터페이스로 들어온다(list_tools / call_tool). 엔진은 인터페이스만 정의하고, 구체 소스(MCP·캔버스 노드·HTTP API·캔버스 워크플로우 등)는 외부/이식측이 구현·등록한다.
- MCP 받기: 외부 MCP 서버를 하네스 안 도구로 노출.
- MCP 내보내기: 하네스 워크플로우를 MCP stdio 서버로 발행.
- Capability: 선언적 도구 wiring 자동 발견.
Compile — 워크플로우 → 단일 산출물
하네스 워크플로우를 npm tarball / Python wheel 로 컴파일하면 동일 spec 으로 env-only standalone 실행(+ serve-mcp 모드). NOM IR(wheel + MCP 카탈로그 + 격리 페이로드 단일 그래프) + 발행 전 Sandbox 격리 검증 지원.
장기실행(multi-session) 메모리
세션은 분리 실행되고 각 세션은 이전 기억 없이 시작한다(Anthropic long-running-agents). xgen_harness.memory 가 세션 간 상태 인계를 책임진다(s06_context 의 세션 내 압축과 보완).
ProgressLog/ProgressItem— 세션 밖에 사는 progress artifact(작업항목·검증절차·pass/fail).pending()으로 다음 할 일 즉시 복원.RecallSet/RecallItem(v1.19.1) — 긴 작업 에이전트의 작업기억 보존소. 우선순위 태깅 + dedup + cap 된 항목 집합. 전체 본문은 PD(pd_stores["recall"])로 step-in(fetch_pd), compact 뷰는 step-out(render()). opt-in 빌트인keep/check/recall로 policy 는 의미 결정만, 엔진이 bookkeeping. 세션 압축에도 살아남음.SessionStore(Protocol) —InMemory/File빌트인(무거운 의존성 0). 플랫폼은entry_points로 자기 DB 백엔드를 코어 수정 없이 끼운다.save_session/load_session으로 세션↔store 인계.
자가단조(Self-Forging) — 설정 자가개선 (opt-in, v1.20.0)
하네스가 자기 실행 trace 로 약점을 진단해 HarnessConfig 자체를 진화시킨다. stage 코드는 불변 — 어느 stage 에 어느 등록된 strategy/guard/criteria/scalar 를 쓸지(노브)만 바꾼다.
- 치환대수(
EngineAlgebra) — 합법 수는 엔진 레지스트리(strategies·guards·evaluation_criteria·orchestrators·runtime_defaults)에서 introspection 으로만 생성(무하드코딩). 각 수는apply/inverse가역 → 롤백 결정론적. - 루프(
SelfForge) —measure(J) → 진단(reflect) → 수 제안 → cross-check(제안자와 독립 validator) → inertia-brake(벤치 J 전후 비교) → 개선시 채택·회귀시 롤백 → 감사로그. Runner단일 계약 —PipelineRunner(실 Pipeline 구동, J=validation_score) /SyntheticRunner(오프라인) /FakeProvider(무API). 실·모의 동일 인터페이스.- Goodhart 방어 objective(v1.22.0) — 루프는 judge 를 게이밍하므로: dev 로 최적화 → 동결 held-out 으로 승급 게이트 → 2차 judge-독립 지표 비회귀 → held-out 정점서 early-stop. proxy↑인데 held-out↓면
overopt플래그 후 롤백.Objective(runner, dev, heldout, secondary=...); 평범한 bench 리스트는Objective.from_bench(dev==held-out)로 기존 동작 유지. - GEPA 반성 리플렉터(v1.23.0) —
GepaReflector(provider)가 실패 trace 피드백을 자연어로 반성해 system_prompt 의 관리 블록(<forge_guidance>)을 append_guidance 수로 진화(GEPA arXiv:2507.19457). provider 있으면 LLM aux-reflect, 없으면 휴리스틱. objective(held-out)로 게이트돼 효과 있는 가이던스만 생존.register_reflector(GepaReflector(p))로 plug. - 확장점(전부 레지스트리+entry_points, 무하드코딩) — 신호추출
register_signal_extractor(forge_signal_extractors) · 진단규칙register_symptom_fix· 반성register_reflector(forge_reflectors, GEPA/LLM 리플렉터) · 프리미티브 합성register_synthesizer(forge_synthesizers, Voyager/LATM 안전부분집합 — 선언적 프리미티브만, 코드실행 X) · 2차지표register_secondary_metric(forge_secondary_metrics). - opt-in:
import xgen_harness시 미로드.
from xgen_harness.forge import SelfForge, PipelineRunner
res = SelfForge(PipelineRunner(provider=my_provider)).run(base_config, bench)
print(res.initial_j, "->", res.final_j) # 벤치(=목표)만 주면 수렴까지 자율
안정 에러코드
모든 HarnessError 는 exec.<component>.<reason> 코드(메시지와 독립한 머신 식별자)를 들고 다닌다. 이식측·외부 소비자가 릴리즈 간 안정 분기 가능. error_code(exc) / ALL_ERROR_CODES.
외부 확장점 (entry_points)
외부 패키지가 자기 pyproject.toml 의 [project.entry-points."xgen_harness.<group>"] 에 항목을 추가하면 부팅 시 자동 발견·register (엔진 소스 수정 0). 주요 group:
stages · strategies · node_adapters · tool_sources · providers · capabilities · fan_out_strategies · evaluation_criteria · orchestrators · sandbox_verifiers · tools(갤러리) · phases · node_plugins · model_pricing · term_expanders · guards · active_policy_renderers · collection_enrichers · resource_providers · session_stores
내장 Guard 7종(token_budget·cost_budget·iteration·content·tool_precondition·hitl·tool_diversity)도
guardsgroup 으로 등록 — 외부 기여자도 같은 경로.tool_diversity(v1.19.1)는 동일 도구를 같은 인자로 반복 호출(무의미한 루프)하면 PRE_TOOL 에서 차단·교정.
공식 Public API
xgen_harness.__all__ 참조. 핵심: Pipeline, PipelineState, HarnessConfig, TokenUsage, ALL_STAGES, REQUIRED_STAGES, PRESETS, compile_nom_graph, NOMGraph, ProgressLog, RecallSet, RecallItem, Priority, SessionStore, FileSessionStore, ALL_ERROR_CODES. (__version__ 은 설치 wheel 메타에서 런타임 조회.)
이식(PORT) 분리 원칙
- 엔진(이 레포) = generic. 특정 플랫폼 어휘 금지.
- 이식측(예:
xgen-workflow/harness_bridge) = 엔진을 플랫폼에 연결(provider·tool_source·정책 default·locale·평가전략을entry_points/주입으로 끼움). - 의존 방향: 이식이
xgen-harness>=N,<2.0으로 엔진 wheel 을 핀. 엔진 먼저 고치고 publish → 이식 핀 범프.
배포 (Release)
엔진은 PyPI 패키지 xgen-harness 로 배포된다. 버전을 올리고 두 가지 방법 중 하나로 발행한다.
0. 버전 올리기 + 테스트
# pyproject.toml 의 version 을 X.Y.Z 로 수정 후
python -m pytest -q # tests/ 전부 green 확인
A. 수동 배포 (어디서든 즉시 — PyPI 토큰만 있으면 됨)
python -m build # dist/xgen_harness-X.Y.Z-*.whl + .tar.gz
TWINE_USERNAME=__token__ TWINE_PASSWORD=<pypi-token> \
python -m twine upload dist/xgen_harness-X.Y.Z* # PyPI 발행
git push <remote> main && git push <remote> vX.Y.Z # GitHub 반영 (+ 태그)
Windows 콘솔에서 진행바 유니코드가 깨지면
PYTHONUTF8=1 ... twine upload --disable-progress-bar.
B. 자동 배포 (태그 push → GitHub Actions OIDC)
v* 태그를 push 하면 publish.yml 이 PyPI Trusted Publishing(OIDC) 으로 발행한다(토큰 불필요). 사전 1회: PyPI → xgen-harness → Settings → Publishing 에 해당 repo + publish.yml 을 trusted publisher 로 등록. (여러 repo 를 등록하면 어디서 태그를 밀든 발행 가능.)
git tag vX.Y.Z && git push <remote> vX.Y.Z # → Actions 가 build + publish
- 컴파일된 사용자 워크플로우 wheel(
plateer-xgen-wf-*)은publish-user-wheel.yml(cluster repository_dispatch) 으로 별도 발행. - 이식측(
xgen-harness>=N,<2.0핀)은 엔진 publish 후 핀을 범프하면 자동 반영.
링크: Repository · CHANGELOG
1 maintainer
Metadata
1 maintainer
Release files for xgen-harness 1.29.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| xgen_harness-1.29.4.tar.gz | 438.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| xgen_harness-1.29.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 941.4 kB
Release files / xgen_harness-1.29.4.tar.gz
| Download URL | xgen_harness-1.29.4.tar.gz |
|---|---|
| Size | 438.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f88c2450db666edb9905a3a0e0a849c8bf016c5d361617c1c8222a78d870c3de
|
|
BLAKE2b-256 checksum How to use checksums |
9fabff225a79ea87633f9af9c405e5cfb0449c5d1fba1f6317c3eb5bdf1147b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / xgen_harness-1.29.4-py3-none-any.whl
| Download URL | xgen_harness-1.29.4-py3-none-any.whl |
|---|---|
| Size | 502.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
09aebd52976d4dba21c235953e9e3f77eae5db6880b9beb9f0511ae8eee3b29c
|
|
BLAKE2b-256 checksum How to use checksums |
5efba68854647b045ec579084ca402ee76bb0bfeec85b97bbd01d792208a4963
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
