[!WARNING] 개인 의사결정 보조 도구다. 매매 기능은 없고(토스 API 읽기전용), 출력은 투자 권유가 아니다.

왜 이렇게 만들었나

LLM에게 포트폴리오를 물으면 그럴듯한 수치를 지어내고, 틀려도 조용하다. 이 시스템은 그 실패 모드를 구조로 막는다.

어떻게 도는가

flowchart LR
    subgraph SRC["📥 sources · 읽기전용"]
        T["토스증권<br/>보유·시세"]
        D["DART / EDGAR<br/>공시 원문"]
    end
    subgraph ENG["⚙️ engines · LLM 없음"]
        Q["quant<br/>집중도·상관·리스크"]
        TH["thesis<br/>논지 상태머신"]
    end
    subgraph JUD["🧠 판단"]
        B["근거 번들 E#<br/>(그라운딩 원장)"]
        L["Claude Code<br/>종합"]
        G{"게이트<br/>근거·무효화·수치 대조"}
    end
    ST[("MySQL<br/>SoT")]
    V["📓 vault<br/>Obsidian 미러"]

    T --> Q --> B
    D --> TH --> B
    B --> L --> G
    G -->|"통과"| ST
    G -->|"반려"| L
    ST --> V

    style G fill:#D97757,stroke:#8B3A2B,color:#fff
    style ST fill:#4479A1,stroke:#2C5378,color:#fff

게이트는 ① 인용된 근거 E#이 실제로 원장에 있는지 ② 무효화 조건이 붙었는지 ③ 수치가 원본과 일치하는지 ④ 보유 종목 전원에 판단이 있는지를 검사한다. 통과분만 저장된다.

셋업

요구사항 — Python 3.11+, MySQL 8.x (uv 권장) LLM API 키는 필요 없다. 판단 합성은 Claude Code 또는 로컬 CLI로만 실행된다.

# 1) 의존성
uv venv --python 3.12 && source .venv/bin/activate
uv pip install -e ".[dev]"

# 2) 시크릿 — MYSQL_DSN · TOSS_* · DART_API_KEY 를 채운다
cp .env.example .env

# 3) 스키마 + 점검
python -m src.cli.brief init-db
python -m src.cli.brief doctor

사용

python -m src.cli.brief review          # 온디맨드 심층 판단
python -m src.cli.brief review --mock   # 토스 키 없이 mock 픽스처로 파이프라인 확인
python -m src.cli.brief daily           # 일일 다이제스트 (코드 수치만, LLM 없음)
python -m src.cli.brief watch           # 백그라운드 논지 감시 — 무효화 트리거 시에만 알림
python -m src.cli.brief retrospect      # 제안 vs 실제 행동 vs 결과 회고

python -m src.cli.brief thesis add <TICKER> --entry-price <가격> --weight <비중> \
    --thesis "<왜 샀는가 한 줄>" --assumption "<핵심 가정>" \
    --cond "<서술>|price<<임계값>|broken" --cond "<질적 조건>||watch"

판단 LLM = Claude Code

1차 경로 — Claude Code 안에서 /review. portfolio MCP 서버의 review_begin이 그라운딩 근거 번들을 만들고, Claude Code가 내부 추론으로 판단 JSON을 작성해 review_submit에 제출한다.

폴백 — 터미널 단독 실행 시 SYNTHESIS_PROVIDER=auto가 로컬 CLI를 탐지한다: claude -p → gemini → ollama → 없으면 번들만 출력. 어떤 엔진이든 게이트는 동일하다.

claude mcp add portfolio -s project -- python -m src.mcp.portfolio_server
claude mcp add sources   -s project -- python -m src.mcp.sources_server
claude mcp list   # 헬스 확인

구조

계층은 위에서 아래로만 의존한다. 관찰 트랙(회색 점선)은 판단 경로에 닿지 않는다 — 확률적 신호가 의사결정에 새어드는 걸 구조로 막는다.

flowchart TB
    subgraph L1["&nbsp;①&nbsp; 진입 &nbsp;·&nbsp; <i>Claude Code · 터미널</i>&nbsp;"]
        direction LR
        CLI["<b>cli/</b><br/>brief.py<br/><sub>review · daily · watch</sub>"]
        MCPS["<b>mcp/</b><br/>portfolio · sources<br/><sub>stdio 서버</sub>"]
    end

    subgraph L2["&nbsp;②&nbsp; 판단 &nbsp;·&nbsp; <i>여기서만 LLM</i>&nbsp;"]
        SYN["<b>synthesis/</b><br/>decision · prompts · llm<br/><sub>근거·무효화 게이트</sub>"]
    end

    subgraph L3["&nbsp;③&nbsp; 도메인 &nbsp;·&nbsp; <i>LLM 없음 · 순수 코드</i>&nbsp;"]
        direction LR
        ENG["<b>engines/</b><br/>quant · thesis<br/><sub>계산 · 상태머신</sub>"]
        OBSV["<b>engines/</b><br/>technical · sentiment<br/><sub>관찰 트랙 — 격리</sub>"]
    end

    subgraph L4["&nbsp;④&nbsp; 데이터&nbsp;"]
        direction LR
        SRC["<b>sources/</b><br/>toss · dart · edgar<br/><sub>읽기전용</sub>"]
        STO["<b>storage/</b><br/>Repository → MySQL<br/><sub>정형 SoT</sub>"]
        KNW["<b>knowledge/</b><br/>vault export<br/><sub>생성물 미러</sub>"]
    end

    CLI --> SYN
    MCPS --> SYN
    SYN --> ENG
    ENG --> SRC
    ENG --> STO
    STO --> KNW
    OBSV -.->|"판단 우회"| KNW
    SRC -.-> OBSV

    style SYN fill:#D97757,stroke:#8B3A2B,stroke-width:2px,color:#fff
    style STO fill:#4479A1,stroke:#2C5378,stroke-width:2px,color:#fff
    style OBSV fill:#F0F1F3,stroke:#8C959F,stroke-dasharray:4 3,color:#57606A
    style KNW fill:#F0F1F3,stroke:#8C959F,color:#24292F
    linkStyle 6,7 stroke:#8C959F,stroke-dasharray:4 3

테스트

pytest   # 전부 오프라인 — 외부 API · LLM · MySQL 불필요 (fake/mock 기반)

라이선스

이 저장소는 MIT다. 핵심 의존성(httpx · pymysql · cryptography · python-dotenv · mcp · numpy)은 전부 BSD/MIT/Apache 계열이라 충돌이 없다.

[!IMPORTANT] 선택적 extra [yolo] 는 AGPL-3.0 이다. 차트 패턴 탐지에 쓰이는 ultralytics는 AGPL-3.0 이며, 이는 이 저장소의 MIT 와 다른 조건이다. 이 저장소는 ultralytics 코드도 모델 가중치도 포함하지 않는다 — engines/patterns.py 에서 lazy import 할 뿐이고, 미설치 시 조용히 비활성화된다. uv pip install -e ".[yolo]" 를 실행하는 순간부터 AGPL-3.0 조건이 적용되며, 준수 책임은 설치한 쪽에 있다. AGPL 이 곤란하다면 이 extra 를 설치하지 마라 — 의사결정 코어는 YOLO 없이 완전히 동작한다 (애초에 관찰 트랙이라 판단 경로에 닿지 않는다).

[sentiment] extra(transformers, Apache-2.0)와 [technical] extra(matplotlib, PSF)는 허용적 라이선스다.

문서