Backtrader를 기반으로 구축된 알고리즘 트레이딩을 위한 전문적인 설정 중심 (config-driven) 백테스팅 프레임워크입니다. 주식, 암호화폐 (crypto), 외환 (forex) 시장 전반에서 대규모 언어 모델 (LLMs)과 함께 트레이딩 전략을 원활하게 테스트, 최적화 및 통합할 수 있습니다.

설정 중심 워크플로우 (Config-Driven Workflows): 재현 가능한 결과를 위해 버전 관리가 가능한 YAML 파일로 백테스트를 정의하고 관리합니다.
원활한 LLM 통합 (Seamless LLM Integration): 내장된 MCP (Model Context Protocol) 서버를 통해 Claude와 같은 AI 어시스턴트가 백테스트를 실행하고, 데이터를 가져오며, 전략을 분석할 수 있습니다.
다중 시장 지원 (Multi-Market Support): 미국 주식, 대만 주식, 암호화폐 및 외환 시장에서 전략을 테스트할 수 있습니다.
광범위한 전략 라이브러리 (Extensive Strategy Library): 클래식 지표부터 고급 적응형 모델까지 20개 이상의 내장 전략을 제공합니다.
강력한 CLI (Powerful CLI): 백테스트 실행, 시장 데이터 가져오기, 전략 목록 확인을 위한 풍부한 명령줄 인터페이스를 제공합니다.
개발자 친화적 (Developer Friendly): 간단한 헬퍼와 명확한 구조를 통해 커스텀 전략을 쉽게 생성하고 테스트할 수 있습니다.

1. 설치 (Installation)

옵션 A: PyPI에서 설치 (CLI 사용 시 권장)

pip install ai-trader

다음과 같은 경우에 이 방법을 사용하세요:

• CLI 명령어를 사용하려는 경우:
  ai-trader run
ai-trader fetch
ai-trader quick

• 본인의 데이터 파일로 백테스트를 실행하려는 경우

• Python 프로젝트에서 라이브러리로 사용하려는 경우

옵션 B: 소스에서 설치 (예제 및 설정 템플릿 확인 시 권장)

git clone https://github.com/whchien/ai-trader.git
cd ai-trader
# 의존성 설치 (한 가지 방법 선택)
...

다음과 같은 경우에 이 방법을 사용하세요:

• config/backtest/에 있는 설정 기반 예제를 실행하려는 경우
• data/에 있는 예제 데이터 파일을 사용하려는 경우
• scripts/examples/에 있는 예제 스크립트를 실행하려는 경우
• 기여(Contribute)하거나 전략을 커스텀하려는 경우

2. CLI를 통한 백테스트 실행 (Run a Backtest via CLI)

소스에서 클론한 경우, 설정 파일을 사용하여 미리 정의된 백테스트를 실행하세요:

# 설정 파일로부터 백테스트 실행 (소스 설치 필요)
ai-trader run config/backtest/classic/sma_example.yaml

또는, 모든 데이터 파일에 대해 빠른 백테스트를 실행할 수 있습니다 (pip 및 소스 설치 방식 모두 지원):

# 사용자 데이터 파일로 빠른 백테스트 실행
ai-trader quick CrossSMAStrategy your_data.csv --cash 100000

3. 시장 데이터 가져오기 (Fetch Market Data)

지원되는 모든 시장의 과거 데이터를 다운로드합니다:

# 미국 주식 (기본값: CSV로 저장)
ai-trader fetch TSM --market us_stock --start-date 2020-01-01
# 대만 주식 (台灣股票)
...

SQLite를 이용한 지속적 데이터 저장 (Persistent Data Storage with SQLite)

기본적으로 ai-trader fetch는 데이터를 CSV로 저장합니다. 반복적인 백테스트를 더 빠르게 수행하려면 SQLite를 사용하세요:

# 첫 번째 가져오기: API에서 다운로드하여 SQLite에 캐싱 (~2-3초)
ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite
# 반복적인 가져오기: 캐시에서 로드 (~50ms, API 호출 없음)
...

백테스트를 실행하는 가장 견고한 방법은 YAML 설정 파일 (config file)을 사용하는 것입니다.

my_backtest.yaml:

broker:
cash: 1000000
commission: 0.001425
...

실행 방법:

ai-trader run my_backtest.yaml

더 많은 예시는 config/backtest/를 참조하세요.

더 세밀한 제어가 필요하거나 다른 Python 스크립트에 통합하려는 경우:

간단한 접근 방식:

from ai_trader import run_backtest
from ai_trader.backtesting.strategies.classic.sma import CrossSMAStrategy
# 예제 데이터로 백테스트 실행
...

단계별 제어:
상세한 예시는 scripts/examples/02_step_by_step.py를 참조하세요.

ai-trader를 서버로 실행하여 AI 어시스턴트가 백테스팅 엔진과 상호작용할 수 있도록 할 수 있습니다.

서버 시작 (테스트용):

python -m ai_trader.mcp

Claude Desktop으로 설정 (권장):

• Claude Desktop 설정 파일의 위치를 찾습니다:

macOS/Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

• mcpServers 섹션에 ai-trader MCP 서버를 추가합니다:

{
"mcpServers": {
"ai-trader": {
...

설정 참고 사항:

• /path/to/ai-trader를 교체하세요.

실제 ai-trader 프로젝트 디렉토리로 교체하세요 - 가상 환경 (Virtual Environment)을 사용하는 경우, Python 실행 파일의 전체 경로를 사용하세요:
/path/to/.venv/bin/python3

• 설정 파일을 업데이트한 후 Claude Desktop을 재시작하세요.

설정이 완료되면, 다음과 같은 자연어 명령을 통해 Claude를 사용하여 백테스팅 엔진 (Backtesting Engine)과 상호작용할 수 있습니다:

*"2020-2022년 TSM 데이터를 사용하여 CrossSMAStrategy의 백테스트를 실행해줘."
*"사용 가능한 모든 트레이딩 전략 (Trading Strategies)을 나열해줘."
*"2021년부터 2024년까지의 Apple 주식 데이터를 가져와줘."

새로운 전략을 만드는 가장 빠른 방법은 Claude Code의 /add-strategy 스킬을 사용하는 것입니다. 이 스킬은 대화형으로 프로세스를 안내합니다:

/add-strategy classic

이 명령은 다음 사항을 요청합니다:

• 전략 이름 (예: "MACDBBands")
• 설명 (Description)
• 기본값이 포함된 파라미터 (Parameters)
• 진입 (Entry) 및 청산 (Exit) 조건
• 기타 사용자 정의 지표 (Custom Indicators)

이 스킬은 다음 사항을 자동으로 처리합니다:

• 적절한 명명 규칙 (Naming Conventions)을 따른 파일 생성
• 포괄적인 독스트링 (Docstrings)
• __init__.py 내 자동 등록
• 구문 검증 (Syntax Validation)

Claude Code 스킬에 대해 더 알아보기: https://code.claude.com/docs/en/skills

ai_trader/backtesting/strategies/classic/ 디렉토리에 새 파일을 생성하고 BaseStrategy를 상속받으세요.

# ai_trader/backtesting/strategies/classic/my_strategy.py
import backtrader as bt
from ai_trader.backtesting.strategies.base import BaseStrategy
...

새로운 전략은 CLI 및 run_backtest 함수에서 자동으로 사용할 수 있게 됩니다.

전략 예시 (Strategy Examples): 내장된 전략에 대한 상세 정보.
예제 스크립트 (Example Scripts): 다양한 사용 사례를 위한 5가지 완전한 작동 예제.
설정 템플릿 (Config Templates): YAML 설정 템플릿.
마이그레이션 가이드 (Migration Guide): v0.1.x 버전에서 업그레이드하는 방법.

기여(Contributions)를 환영합니다! 버그를 보고하거나, 기능을 제안하거나, 풀 리퀘스트 (Pull Requests)를 제출해 주세요.

이 프로젝트가 도움이 되었다면, 별(Star)을 눌러주세요!

이 프로젝트는 GNU General Public License v3 (GPL-3.0)에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.