결제 라우팅 오케스트레이터

핫 경로에는 증거, 가장자리에는 AI.

전송 직전의 카드 승인 요청이 주어지면, 경험적 승인 증거를 바탕으로 어떤 결제 서비스 제공업체(PSP)가 이를 받을지 결정한다. 운영자가 실제 단위로 명시한 수수료 허용치 내에서 판단한다. 승인 시도가 거절되면, 거절 사유의 오류 클래스를 키로 하는 상태 머신이 다음 단계를 결정한다: 같은 PSP를 나중에 다시 시도, 지금 페일오버, 다른 채널, 또는 중단. 라우팅 결정 자체는 결정적이고 감사 가능하며, 그 안에서 어떤 언어 모델도 실행되지 않는다.

Claude Code 안에서 빌드되어 배포되었다: 엔진, AI 엣지 레이어, 평가 하네스, 웹 UI, API와 이 README는 모두 에이전트 세션에서 만들어졌다 — 하나의 오케스트레이션 세션이 서브에이전트(백엔드, UI, 배포, 사례 연구)에 위임하는 방식 — 그리고 직접 실행해 볼 수 있는 테스트와 평가로 게이트가 걸려 있다. 엔지니어링 원칙은 nutri.에 설명된 것과 동일하다: 에이전트가 반드시 로드해야 하는 규칙, 구조적 가드레일, 그리고 완료의 정의로서의 약속이 아닌 머신. 가드레일이 실제로 배포될 뻔한 문제들을 잡아냈다: 모든 API 경로를 삭제한 재작성(배포 후 검증에서 발견), 유효한 발급사를 미발견으로 잘못 표시한 UI, 그리고 작성자의 두 가지 잘못된 가정(페이지 수 규칙, DNS 설정)에 대해 서브에이전트가 실행을 거부한 사례.

라이브 데모 https://orchestrator.vryahn.com · 사례 연구 https://vryahn.com/work/routing · API api/README.md · MCP MCP.md

84,011건의 TEST 거래(2231일, 테이블은 121일로 학습)에 대한 표본 외 리플레이: cost_bias=0에서 기대 승인율 72.02% 대 실제 관측 66.13% — +5.89%p, 방향성을 가진 결과이며 A/B 결과는 아니다. 한계 참조.

실행

Python 3.11. requirements.txt는 런타임이다 — fastapi와 표준 라이브러리이며, Vercel이 설치하는 유일한 항목이다. requirements-dev.txt는 데이터 재생성, 백테스트 실행, MCP 서빙, 또는 로컬 테스트에 필요한 오프라인 스택(duckdb, pandas, numpy, pyarrow, mcp, uvicorn, httpx)을 추가한다.

python3.11 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
.venv/bin/python cli.py --txn-file demo_transactions.json   # 8 decision-boundary cases
.venv/bin/uvicorn api.index:app --reload --port 8000        # API on /api/*, UI from public/

엔진이 읽는 테이블(routing_tables.json, routing_meta.json)은 커밋되어 있으므로, 새 클론은 오프라인 파이프라인 없이도 라우팅 — 그리고 배포 — 된다. 데이터 모델이 변경될 때만 재생성하라:

.venv/bin/python synth_attempts.py         # seeded ~300k attempts -> attempts.parquet
.venv/bin/python build_routing_tables.py   # -> routing_tables.json, routing_meta.json
.venv/bin/python backtest.py --json        # -> backtest_summary.json
.venv/bin/python tests.py                  # engine
.venv/bin/python tests_ai.py               # AI edges + HTTP contract
.venv/bin/python evals/decline_eval.py     # normalizer against the golden set

Related MCP server: ai-log-mcp-server

아키텍처

flowchart LR
    subgraph offline["OFFLINE — batch, once per rebuild"]
        G["synth_attempts.py<br/>seeded generator"] --> A[("attempts.parquet<br/>1 row = 1 attempt, ~300k")]
        A -->|"build_routing_tables.py"| T[("routing_tables.json + routing_meta.json<br/>segment x PSP: n, approvals, p_hat, Wilson LB<br/>4-level hierarchy")]
        A -->|"backtest.py — train d1-21, test d22-31"| B["backtest_summary.json<br/>out-of-sample lift"]
    end

    subgraph edgein["EDGE IN — language to enum"]
        RAW["raw PSP decline<br/>ISO 8583 / decline_code / refusalReason / bank prose"] --> N{"decline_normalizer.py<br/>table -> LLM -> safe fallback"}
        EV["evals/ — 48 golden declines<br/>accuracy by route, hallucination gate"] -.->|"scores"| N
    end

    subgraph online["ONLINE — pure engine, never touches raw data"]
        X["txn: amount, bin6/issuer, funding,<br/>channel, attempt #, error history"] --> D{"decide(txn, config)"}
        T --> D
        N -->|"error_class"| D
        D --> S1["1. resolve segment per PSP<br/>walk L0 to L3 until n >= min_support"]
        S1 --> S2["2. score = Wilson LB x amount x (1 - fee)<br/>= expected net collected"]
        S2 --> S3["3. pick PSP — cost_bias 0..1 maps to<br/>fee tolerance 0..10pp; psps_down excluded"]
        S3 --> S4["4. retry state machine<br/>keyed on last error_class"]
        S4 --> R["Decision: route_psp, eligible_psps with scores,<br/>retry policy, reasoning lines"]
    end

    R --> OPS["ops.py — route, explain, simulate,<br/>evidence, normalize, backtest"]
    B --> OPS
    OPS --> CLI["cli.py"]
    OPS --> API["api/index.py — FastAPI on Vercel<br/>+ public/ web UI, same origin"]
    OPS --> MCP["mcp_server.py — 6 MCP tools"]

이 설계의 이유

• 오프라인/온라인 분리. decide(txn, config) -> Decision은 순수 함수다. 사전에 머티리얼라이즈된 테이블을 한 번 로드하고 원시 시도 데이터를 절대 읽지 않으므로, 결정은 마이크로초 단위이며, 데이터베이스 없이 테스트 가능하고, 사후 감사가 가능하다. 이는 프로덕션에서 조정(reconciliation) 레이어와 라우팅 레이어 사이에 그리는 것과 동일한 경계다.

• 폴백이 있는 세그먼트 계층. L0은 gateway_group × funding × issuer_bucket × amount_band이고, L3은 gateway_group 단독이다. 지원(support)은 PSP별로 한 차원씩(금액대 → 발급사 → 자금 유형) 해석되며, 셀이 min_support(기본 200)를 넘을 때까지 진행되고, 사용된 레벨이 결정과 함께 보고된다. 채널은 일급 객체이며 절대 버려지지 않는다: 사용자 직접 참여와 오프세션은 다른 세계다.

• 원시 비율이 아닌 Wilson 하한. 3/3 승인인 세그먼트는 100% 세그먼트가 아니다. 하한은 지원이 얇아질수록 0으로 수렴하므로, 증거가 충분한 78%가 별도의 신뢰도 규칙을 덧붙이지 않고도 운 좋은 100%를 이긴다.

• 실제 단위로 표현된 명시적 노브(knob)로서의 cost_bias. 트레이드오프는 "더 저렴한 PSP를 위해 포기할 승인율의 퍼센트 포인트"로 표현된다 — tolerance = cost_bias × 10pp, 그리고 최고 승인자와의 이 허용치 안에서 가장 저렴한 PSP가 승리한다. 혼합 점수는 소수점 단위의 수수료 차이가 두 자릿수 승인율 격차를 조용히 무시하도록 만들 수 있지만, 허용치 필터는 그럴 수 없다. 백테스트가 노브의 가격을 매긴다: cost_bias=0에서 72.02% / +5.89%p 승인율, 0.5에서 71.56% / +5.43%p, 1.0에서 69.57% / +3.44%p.

• 맹목적인 카운터가 아닌 오류 클래스 기반 재시도. insufficient_funds는 계좌 문제이므로 다음 청구 주기에 같은 PSP를 재시도한다. bank_auth_required 오프세션은 고객 없이는 충족될 수 없으므로, 시도를 소진하는 대신 사용자 직접 참여 채널로 재일정한다. fraud_risk는 체인을 영구히 중단한다. generic_decline은 점수 기준으로 다음 PSP에 페일오버한다. 인식되지 않은 클래스는 일반 페일오버 정책으로 폴백되며 그 사실을 명시한다.

AI가 속한 곳 — 그리고 속하지 않는 곳

decide() 안에는 LLM이 없다. 돈은 샘플링된 토큰 위에서 움직여서는 안 된다. 언어 모델은 자연어가 실제로 문제인 두 가장자리에만 국한된다.

속함 — decline_normalizer.py. 각 PSP는 저마다의 방언으로 거절한다: ISO 8583 숫자 코드, Stripe 스타일의 decline_code, Adyen 스타일의 refusalReason, 또는 원시 은행 문장. 재시도 상태 머신은 하나의 열거형을 키로 사용하므로, 엔진이 보기 전에 방언들이 수렴되어야 한다. 결정적 테이블이 볼륨을 차지하는 코드들을 처리한다 — 신뢰도 1.0, 지연 없음, 비용 없음. 테이블 미스만 모델 체인(Gemini, 그다음 Mistral)에 도달하며, 모델은 제약된 열거형 스키마로 응답한다. 열거형 밖의 것이나 0.6 미만의 신뢰도는 generic_decline을 위해 폐기되며, 이는 재시도 정책 자체의 안전한 기본값이다. API 키가 없어도 저장소는 그린으로 실행된다.

측정되지 않으면 신뢰하지 않음 — evals/. 48개의 골든 거절 사례: 약 60% 테이블 적중, 약 40% 의도적으로 테이블 밖(철자 오류, 장황한 은행 텍스트, 흔치 않은 코드)이며, generic_decline이 정답인 진정으로 모호한 사례 몇 개도 포함한다. evals/baseline.json은 두 기준선을 기록한다. 테이블 전용(키 없음): 32/48 = 66.67%, 즉 테이블 경로의 28건에서 100%, 폴스루하는 20건에서 안전한 generic_decline 기본값. LLM(키 구성, 배포된 API에 --remote로 실행): 48/48 = 100% — 28건 테이블, 19건 gemini-3.6-flash가 응답, 1건은 generic_decline이 기대 답안이었던 낮은 신뢰도 폴백. 실행기는 경로별 정확도와 클래스별 혼동 행렬을 보고하고, 환각이 0건임을 단언하며, 정확도가 매칭 기준선보다 2%p 이상 떨어지면 빌드를 실패시킨다.

속하지 않음 — mcp_server.py. 여섯 개의 MCP 도구 — route_transaction, explain_decision, simulate, segment_evidence, normalize_decline, backtest_summary — 는 에이전트가 영어로 엔진을 조작할 수 있게 한다. 에이전트는 모든 결정을 조회할 수 있고 그 어떤 것도 변경할 수 없다. MCP.md 참조.

한계

• 데이터는 합성이다. 구조는 라우팅 결정이 사소하지 않도록 설계되었으며, 실제 포트폴리오를 재현하기 위한 것이 아니다.

• 실제 PSP 커넥터가 없다: 엔진은 결정만 하고 전송하지 않는다.

• 사기 점수 산정, 3DS 오케스트레이션, 네트워크 토큰, 또는 스킴 재시도 규칙 적용이 없다.

• 백테스트는 방향성을 가진다. 과거 라우팅은 무작위화되지 않았고, 용량 제한은 모델링되지 않았으며, "기대 승인율"은 TEST 볼륨에 적용된 TRAIN 기간 Wilson-LB 비율일 뿐 — 라이브 A/B 결과가 아니다.

• 백테스트가 훈련할 때 테이블이 모든 시도를 풀링하고 첫 시도만 리플레이하는 반면, 프로덕션 테이블은 첫 시도 전용이어야 하는 것이 다음 수정 사항이다.

• LLM 평가는 48건의 단일 실행이다. 이렇게 작은 골든 세트에서의 100%는 회귀 방지 게이트일 뿐, 프로덕션의 긴 꼬리에 대한 주장이 아니다.

파일 맵

Bryan Rodríguez Abarca · vryahn.com · 기술 연습에서 시작되어 개인 프로젝트로 일반화됨. 합성 데이터.