{"id":50412309,"url":"https://github.com/cskwork/kr-ai-trader","last_synced_at":"2026-05-31T04:04:54.027Z","repository":{"id":358903552,"uuid":"1242962246","full_name":"cskwork/kr-ai-trader","owner":"cskwork","description":"LLM-driven automated trading template for Korean retail (KIS Open API + multi-LLM: Claude API / OpenAI / Claude Code CLI / Codex CLI / Ollama)","archived":false,"fork":false,"pushed_at":"2026-05-19T15:21:45.000Z","size":714,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T17:00:52.219Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cskwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-18T23:34:05.000Z","updated_at":"2026-05-19T15:32:59.000Z","dependencies_parsed_at":"2026-05-19T17:01:12.430Z","dependency_job_id":null,"html_url":"https://github.com/cskwork/kr-ai-trader","commit_stats":null,"previous_names":["cskwork/kr-ai-trader"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cskwork/kr-ai-trader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fkr-ai-trader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fkr-ai-trader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fkr-ai-trader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fkr-ai-trader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cskwork","download_url":"https://codeload.github.com/cskwork/kr-ai-trader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fkr-ai-trader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33718496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T04:04:53.201Z","updated_at":"2026-05-31T04:04:54.011Z","avatar_url":"https://github.com/cskwork.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kr-ai-trader\n\n한국 리테일 투자자를 위한 LLM 기반 자동매매 봇 템플릿. **모의투자 디폴트**, **결정론 리스크 게이트**, **멀티 LLM 백엔드**(Claude API / OpenAI API / Claude Code CLI / Codex CLI / Ollama), **Tauri 데스크톱 관측 UI**.\n\n[![CI](https://github.com/cskwork/kr-ai-trader/actions/workflows/ci.yml/badge.svg)](https://github.com/cskwork/kr-ai-trader/actions/workflows/ci.yml)\n\n투자 의사결정 원칙은 자매 리포지토리 **[cskwork/investment-agent-rules](https://github.com/cskwork/investment-agent-rules)** — Buffett, Munger, Graham, Lynch, Dalio, Marks, Soros, Druckenmiller, Simons, Greenblatt 에서 추출한 10대 계명 + 한국시장 오버레이 + AI 봇 시행 매핑. **kr-ai-trader 코드에 어느 계명이 어디에서 강제되는지** 는 [docs/principles-mapping.md](./docs/principles-mapping.md) 참고 (4 enforced / 5 partial / 1 missing).\n\n\u003e **DISCLAIMER**: 이 코드는 교육/연구 목적입니다. 실제 자금 손실 책임은 전적으로 사용자에게 있습니다. 자세한 내용은 [DISCLAIMER.md](./DISCLAIMER.md) 참고.\n\n## 데스크톱 앱 (Tauri)\n\n`desktop/app/` 에 Vite + React + TypeScript + Tauri 2.x 로 4-뷰 관측 UI 가 들어 있습니다.\n\n| 탭 | 보여주는 것 |\n|---|---|\n| **Dashboard** | LLM provider/모델, 유니버스 크기, 리스크 파라미터, HALT 상태, 포지션 테이블, 현재 equity/cash |\n| **Run cycle** | 티커 입력 → WebSocket 스트림 → `settings_loaded → features_computed → moderator_started → proposal_built (thesis + risks) → risk_gate_decision (accepted + reasons) → order_placed/rejected → cycle_done` 까지 단계별 카드로 표시 |\n| **Journal** | 오늘 자 `journal/YYYY-MM-DD.md` 를 그대로 렌더링. 모든 매매 의사결정의 thesis/risks/거부 사유 보존 |\n| **Observability** | 3초 주기 equity 샘플링 sparkline + 백엔드 상태 메트릭 |\n\n### 실행\n\n```bash\n# 1. Python 백엔드 (8765 포트)\npip install -e \".[api]\"\nmake api\n\n# 2. 데스크톱 앱 (다른 터미널)\nmake desktop   # 또는 cd desktop/app \u0026\u0026 pnpm install \u0026\u0026 pnpm tauri dev\n```\n\n데스크톱 앱은 백엔드(127.0.0.1:8765) 에 HTTP + WebSocket 으로 연결합니다. `VITE_API_BASE` 환경변수로 백엔드 주소 오버라이드 가능.\n\n## 실시장 풀사이클 검증\n\n`make smoke-llm \u0026\u0026 make paper` 한 줄로 실데이터 풀사이클이 돈다.\n\n```text\n# 2026-05-18 KRX 종가로 검증한 실제 사이클\n삼성전자 (005930)   RSI 70.85, 20d +29% → Risk Officer no_action\nSK하이닉스 (000660) RSI 79.43, 20d +59% → LLM sell proposal (conv 0.72) → RiskGate 차단 (short-selling blocked)\nNAVER (035420)      RSI 39.06, 20d -8%  → 모더레이터 no_action\n```\n\n체인: `pykrx OHLCV → compute_features → Bull+Bear+RiskOfficer (claude code -p --json-schema) → RiskGate → PaperBroker → Journal 마크다운`.\n\n## 핵심 원칙\n\n- **LLM은 분석가, 코드가 리스크매니저** — LLM은 매매 *제안*만, 실제 주문은 결정론 게이트가 결정\n- **모의투자가 디폴트** — 실계좌 전환은 환경변수 `KIS_LIVE=1` 명시 필요\n- **티커 화이트리스트** — LLM 환각으로 존재하지 않는 종목 주문 방지\n- **멱등 주문 ID + reconciliation** — 중복/유실 방지\n\n## 아키텍처\n\n```\n[데이터: KIS WS / OpenBB / DART / 뉴스]\n              │\n              ▼\n[멀티에이전트: Analyst(Bull) / Critic(Bear) / RiskOfficer / Moderator]\n              │  structured JSON {ticker, side, conviction, thesis, risks}\n              ▼\n[결정론 리스크 게이트: 화이트리스트·포지션·드로다운·서킷브레이커]\n              │\n              ▼\n[Broker: KIS 모의/실 또는 PaperBroker]\n              │\n              ▼\n[Journal: 일별 마크다운 + Slack/Telegram 알람]\n```\n\n## LLM 백엔드\n\n| Provider | 인증 | 비고 |\n|---|---|---|\n| `anthropic_api` | `ANTHROPIC_API_KEY` | Claude Sonnet/Opus, tool_use로 structured output |\n| `openai_api` | `OPENAI_API_KEY` | GPT-5 계열, `response_format=json_schema` |\n| `claude_code_cli` | **API 키 불필요** | `claude -p --json-schema` 가 envelope `structured_output` 으로 검증 JSON 반환 |\n| `codex_cli` | **API 키 불필요** | `codex` CLI 로그인된 세션 활용 |\n| `ollama` | 로컬 | `http://localhost:11434`, `llama3.1`/`qwen2.5` 등 |\n\n`.env`의 `LLM_PROVIDER` 한 줄로 전환됩니다.\n\n## 시작 순서\n\n```bash\n# 1. 클론 후 설치\ngit clone \u003cyour-fork\u003e\ncd kr-ai-trader\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[dev]\"\npre-commit install\n\n# 2. KIS Open API 키 발급 (한국투자증권 apiportal.koreainvestment.com)\ncp .env.example .env\n# .env에 KIS_APP_KEY, KIS_APP_SECRET, KIS_ACCOUNT_NUMBER 입력\n# 모의투자 계정으로 시작\n\n# 3. LLM 백엔드 선택\n# 옵션 A: Claude Code CLI (API 키 0원) — 권장\n#   claude --version  # 로그인된 세션 사용\n#   LLM_PROVIDER=claude_code_cli\n# 옵션 B: Ollama 로컬\n#   docker compose up -d ollama\n#   ollama pull qwen2.5:14b-instruct\n#   LLM_PROVIDER=ollama\n# 옵션 C: API 키\n#   LLM_PROVIDER=anthropic_api  (or openai_api)\n\n# 4. 스모크 테스트\nmake smoke-llm          # LLM 프로바이더 핑\nmake smoke-kis          # KIS 모의계좌 현재가 조회 + 잔고\n\n# 5. 페이퍼 트레이딩 루프 (모의투자)\nmake paper\n\n# 6. 백테스트\nmake backtest UNIVERSE=kospi200 FROM=2024-01-01 TO=2025-12-31\n\n# 7. (충분한 검증 후) 실계좌\nKIS_LIVE=1 make live\n```\n\n## 디렉토리\n\n```\nsrc/kr_ai_trader/\n  config.py          # Pydantic settings\n  llm/               # 5종 LLM provider 추상화\n  broker/            # KIS + PaperBroker\n  agents/            # Bull/Bear/RiskOfficer/Moderator\n  risk/              # 결정론 리스크 게이트\n  execution/         # 멱등 주문 + reconciliation\n  data/              # 시세·유니버스\n  backtest/          # vectorbt 래퍼\n  journal/           # 일별 마크다운 저널\n  cli.py             # 진입점\n```\n\n## 안전 기본값\n\n- `MAX_POSITION_PCT=3` (종목당 3%)\n- `MAX_SECTOR_PCT=30`\n- `DAILY_LOSS_HALT_PCT=2` (일일 -2% 도달 시 신규진입 중단)\n- `DAILY_LOSS_FLATTEN_PCT=4` (-4% 시 전량청산)\n- `LEVERAGE=0` (신용·미수 금지)\n- `HARD_STOP_PCT=7`\n\n`.env`로 조정 가능. 변경 시 백테스트 재실행 권장.\n\n## 라이선스\n\nMIT. 상세는 [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fkr-ai-trader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcskwork%2Fkr-ai-trader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fkr-ai-trader/lists"}