LLM Tool Request Contract¶
Studio AI 채팅에서 LLM이 호출하는 백테스트 도구 요청의 필드 정의입니다.
백테스트 요청은 단일 tool=backtest + requests[] 형식을 사용합니다.
채팅 요청 surface 값¶
Cloud LLM 채팅 요청의 surface 필드는 아래 값만 허용됩니다.
| 값 | 설명 |
|---|---|
studio |
Studio 에디터 AI 채팅 |
generate_dsl |
자연어 → DSL 생성 |
runtime_chat |
런타임 채팅 질의 |
backtest_analysis |
백테스트 결과 분석/개선 루프 |
backtest¶
| 필드 | 필수 | 설명 |
|---|---|---|
tool |
필수 | backtest |
goalMetric |
선택 | 최적화 기준 지표 (기본: total_return_pct) |
requests |
필수 | 백테스트 요청 배열 (최소 1개) |
requests[*] 필드¶
| 필드 | 필수 | 설명 |
|---|---|---|
label |
필수 (binder fallback) | 요청 식별 라벨 (예: "baseline", "period=20") |
script |
필수 (editor 우선) | 실행 가능한 DSL 원문 전체. 항상 현재 에디터 스크립트(current_script)가 우선하며, LLM이 제안한 script는 에디터 스크립트가 비어 있을 때만 fallback으로 사용됨 |
symbols |
필수 (context fallback) | 종목코드 배열. 단일 종목 = ["005930"], 다중 = ["005930","000660"] |
timeframe |
필수 (context fallback) | 타임프레임 |
fromDate / toDate |
필수 (context fallback) | 기간 (YYYYMMDD) |
scriptParams |
선택 | 스크립트 파라미터 |
simParams |
선택 | 시뮬레이션 파라미터 (아래 참조) |
savedUniverseId |
선택 | 저장 유니버스 ID 참조 |
savedUniverseName |
선택 | 저장 유니버스 이름 참조 |
savedUniverseId 또는 savedUniverseName이 있고 symbols가 비어 있으면, 해당 유니버스의 종목을 symbols[]로 채웁니다. 참조한 유니버스를 찾을 수 없으면 에러가 반환됩니다.
requests[*].script 입력 규칙:
- placeholder를 넣으면 안 됩니다. 금지 예:
same as above,위 코드,<...>, 요약문/자연어 설명 - 실제 실행 가능한 DSL 전체 본문을 넣어야 하며, 누락 시 compile preflight 단계에서
simulation_compile_error가 날 수 있습니다.
simParams 필드¶
| 필드 | 기본값 | 설명 |
|---|---|---|
initial_budget |
10_000_000 |
초기 자본금 |
evaluation_step |
추천값 자동 계산 | timeframe + script scale + order_on의 최대공약수로 추천. 스크립트에 strategy.order_on/rule.order_on이 있으면 그 값을 우선하고, 없으면 기본 order_on=5T를 사용한다. 비지원 단위는 더 작은 지원 공약수(최소 1T)로 정규화 |
order_on |
"5T" |
주문 발동 기준 스케일 (스크립트 strategy.order_on이 우선) |
stop_loss_pct |
0 (비활성) |
손절매율. 0이면 비활성이며 DSL 스크립트에서 명시 시에만 적용 |
take_profit_pct |
0 (비활성) |
익절률. 0이면 비활성이며 DSL 스크립트에서 명시 시에만 적용 |
allow_cash_reduction |
true |
현금 부족 시 수량 축소 허용 |
max_notional |
500_000 |
최대 주문 금액 |
tax_rate_by_symbol |
null |
심볼별 매도세율 override 맵. key는 심볼 대문자, value는 0 이상 수치 |
evaluation_step 선택 가능 범위는 지원되는 공약수 스케일 전체(1T 포함)입니다.
응답 추가 필드¶
| 필드 | 조건 | 설명 |
|---|---|---|
missing_scales |
일부 스케일 fetch 실패 시 | 누락된 스케일 목록 (예: ["1W"]) |
일부 종목 실행이 실패하면 전체 결과가 실패로 표시될 수 있습니다. 실패 원인은 결과 카드에서 확인할 수 있습니다.
symbols[].length > 1이면 runtime이 portfolio 엔진을 자동 선택합니다. symbols[].length == 1이면 single-symbol 엔진을 사용합니다.
비교나 파라미터 탐색은 requests[]에 여러 항목을 넣어 표현합니다. 각 항목의 label로 의도를 구분합니다.
backtest_analysis (AI 결과 분석)¶
백테스트 실행 완료 후 "AI 결과 분석" 버튼으로 1회성 분석을 요청합니다. 프론트엔드가 백테스트 결과 + 컨텍스트를 조립해 서버로 전송하며, 서버가 LLM 분석을 수행합니다.
전송 컨텍스트에는 성과 지표, 매매 통계 외에 다음이 포함됩니다:
| 필드 | 설명 | 제한 |
|---|---|---|
trading_days |
실제 거래일 수 | - |
initial_budget / final_equity |
초기·최종 자산 | - |
script_text |
전략 스크립트 원문 | 최대 8,000자 |
sim_params |
시뮬레이션 파라미터 (수수료, 세율 등) | - |
monthly_returns |
월별 수익률 맵 ({월: 수익률%}) |
- |
긴 스크립트는 8,000자까지만 전송되며, 초과분은 분석에서 제외됩니다.
참고¶
이 문서는 Studio AI가 백테스트 요청을 구성할 때 필요한 사용자 입력 계약을 설명합니다. 내부 전송 형식이나 서버 구현 상세는 사용자 가이드 범위에 포함하지 않습니다.