Vibe-Trading을 통한 섀도 계정 백테스팅 기능을 갖춘 개인 트레이딩 에이전트

# Vibe-Trading 설정 가이드

아래는 요청하신 6단계를 이 저장소에서 수행하기 위한 구체적인 절차입니다. 실제 브로커리지 계좌나 지갑은 연결하지 않습니다.

## 1. Python 3.11 가상환경 및 패키지 설치

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install "vibe-trading-ai==<PINNED_VERSION>"
```

`requirements.txt`에 버전을 고정합니다:

```
vibe-trading-ai==<PINNED_VERSION>
```

> 참고: `vibe-trading-ai`의 실제 최신 버전과 API 표면은 설치 시점에 `pip index versions vibe-trading-ai`로 확인하고, 해당 버전의 문서를 기준으로 아래 단계를 조정하세요. 패키지명/버전은 제가 임의로 확정하지 않습니다.

## 2. 환경 변수 템플릿과 gitignore

`.env.example`:

```dotenv
# Model provider
MODEL_API_KEY=your_model_api_key_here
MODEL_PROVIDER=your_provider_here

# Market data
MARKET_DATA_API_KEY=your_market_data_key_here
MARKET_DATA_BASE_URL=https://your-market-data-endpoint.example

# Local server
VIBE_TRADING_HOST=127.0.0.1
VIBE_TRADING_PORT=8765
```

`.gitignore`에 추가:

```
.env
.venv/
runs/*/secrets*
```

`.env`는 절대 커밋하지 않습니다.

## 3. 로컬 API/MCP 서버 기동 및 헬스 체크

```bash
cp .env.example .env   # 값 채우기
vibe-trading serve --host 127.0.0.1 --port 8765 &
curl -sS http://127.0.0.1:8765/health
```

정상이라면 `{"status":"ok", ...}` 형태의 응답이 와야 합니다. 응답이 없으면 로그에서 포트/키 오류를 확인하세요.

## 4. MCP 도구 등록 및 목록 확인

에이전트 클라이언트(예: Claude Desktop, Cursor 등)의 MCP 설정에 로컬 서버를 등록합니다. 예시(클라이언트별 스키마는 다를 수 있음):

```json
{
  "mcpServers": {
    "vibe-trading": {
      "command": "vibe-trading",
      "args": ["mcp", "--url", "http://127.0.0.1:8765"]
    }
  }
}
```

등록 후 도구 목록을 확인:

```bash
vibe-trading mcp list-tools --url http://127.0.0.1:8765
```

출력된 트레이딩 도구(예: 시세 조회, 백테스트, Shadow Account 관리 등)를 기록해 두세요. 실제 도구 이름은 설치된 버전에 따라 다릅니다.

## 5. Shadow Account 생성 및 12개월 백테스트

`runs/` 아래에 설정과 결과를 저장합니다.

```bash
mkdir -p runs/shadow-baseline
```

`runs/shadow-baseline/config.yaml` (예시 구조):

```yaml
account:
  type: shadow
  name: personal-shadow
  starting_cash: 10000
  currency: USD

strategy:
  name: simple-momentum
  params:
    lookback_days: 20
    rebalance: weekly

watchlist:
  - AAPL
  - MSFT
  - SPY

backtest:
  start: "2024-01-01"
  end: "2024-12-31"
  data_source: market_data_api
```

실행:

```bash
vibe-trading shadow create --config runs/shadow-baseline/config.yaml
vibe-trading backtest run --config runs/shadow-baseline/config.yaml \
  --out runs/shadow-baseline/results.json
```

결과(`results.json`)와 실행 로그를 `runs/shadow-baseline/`에 함께 보관합니다. 브로커리지/지갑 연결 옵션은 사용하지 않습니다.

## 6. README 섹션 추가

`README.md`에 다음 섹션을 추가하세요:

```markdown
## Vibe-Trading (personal shadow agent)

### Reproduce the baseline run
1. `python3.11 -m venv .venv && source .venv/bin/activate`
2. `pip install -r requirements.txt`
3. `cp .env.example .env` and fill in model + market-data keys
4. `vibe-trading serve --host 127.0.0.1 --port 8765 &`
5. `curl http://127.0.0.1:8765/health`
6. `vibe-trading shadow create --config runs/shadow-baseline/config.yaml`
7. `vibe-trading backtest run --config runs/shadow-baseline/config.yaml --out runs/shadow-baseline/results.json`

### Caveats
- **Data quality**: results depend on the configured market-data provider; gaps, splits, and survivorship bias are not corrected by default. Treat outputs as illustrative.
- **Non-advisory**: this is a personal research tool. Nothing here is financial advice, and no real brokerage account or wallet is connected.
- **Shadow only**: all accounts are simulated; no orders are routed to any venue.
```

## 확인 필요 사항

- `vibe-trading-ai`의 정확한 버전, CLI 서브커맨드(`serve`, `mcp`, `shadow`, `backtest`), MCP 등록 스키마는 설치 후 `vibe-trading --help`와 패키지 문서로 검증해야 합니다. 위 명령은 일반적인 형태이며 버전에 따라 조정이 필요할 수 있습니다.
- 헬스 엔드포인트 경로(`/health`)와 MCP 전송 방식(stdio vs HTTP)도 버전별로 다를 수 있으니 서버 로그로 확인하세요.