mirror of
https://github.com/shawnkim1997/All-in-one-Financial-Analysis.git
synced 2026-08-13 18:38:06 +00:00
docs: Add AI agent documentation and navigation hub
- Create directory for AI coding agents and new developers - Add as the main navigation hub and entrypoint - Add project context files: , , , , , - Add development guidelines and architecture decisions: , (including 429 error handling and 10-year DCF logic)
This commit is contained in:
whitesmoke-sketch
@@ -0,0 +1,18 @@
|
||||
architecture_decisions:
|
||||
- id: ADL-001
|
||||
title: "하이브리드 처리 및 선택적 섹션 추출 (429 에러 해결)"
|
||||
context: "10-K 원본 전체를 LLM에 전송할 경우 Token 한도 초과 및 Rate Limit(429) 발생."
|
||||
decision: "정규식으로 Item 7(MD&A), Item 1A 등 핵심 텍스트만 추출(Targeted Parsing). 정량 데이터(Item 8)는 yfinance로 대체 처리하여 토큰 사용량을 80% 이상 절감."
|
||||
status: "Implemented"
|
||||
|
||||
- id: ADL-002
|
||||
title: "10년 2단계(2-Stage) DCF 모델 채택"
|
||||
context: "고성장 기업의 경우 일반적인 5년 DCF 모델은 영구 가치(Terminal Value)를 과대평가하는 왜곡 발생."
|
||||
decision: "1~5년차는 예상 성장률 적용, 6~10년차는 영구 성장률(2.5%)까지 선형 하락(Fade)시키는 기관급 10년 모델 적용."
|
||||
status: "Implemented"
|
||||
|
||||
- id: ADL-003
|
||||
title: "금융 데이터 다중 폴백(Fallback) 시스템"
|
||||
context: "S&P 500 이외의 주식은 yfinance 등에서 특정 재무 데이터가 누락되는 문제 발생."
|
||||
decision: "yahooquery를 1순위로 사용하되, 실패 시 yfinance의 여러 속성(fast_info -> info -> balance_sheet)을 순차적으로 탐색(Fallback). 연간 데이터 누락 시 분기별 데이터(TTM) 합산 처리."
|
||||
status: "Implemented"
|
||||
@@ -0,0 +1,30 @@
|
||||
graph TD
|
||||
User([User]) -->|Inputs: API Key, Email, Ticker| UI[Streamlit UI]
|
||||
|
||||
subgraph Frontend/Backend Application
|
||||
UI --> Tab1[10-K & MD&A Insights]
|
||||
UI --> Tab2[DCF Valuation]
|
||||
UI --> Tab3[Sector Analysis]
|
||||
|
||||
Tab1 --> QualParser[Regex & BeautifulSoup Parser]
|
||||
Tab2 --> QuantProcessor[Pandas Financial Processor]
|
||||
Tab3 --> PeerProcessor[Comps Processor]
|
||||
end
|
||||
|
||||
subgraph External APIs
|
||||
SEC[(SEC EDGAR Database)]
|
||||
YF[(yfinance / yahooquery)]
|
||||
LLM[Google Gemini 2.0 Flash]
|
||||
end
|
||||
|
||||
QualParser -->|Fetch 10-K HTML| SEC
|
||||
QualParser -->|Cleaned Text (Item 1A, 7)| LLM
|
||||
LLM -->|Qualitative Insights| Tab1
|
||||
LLM -->|Industry Outlook| Tab3
|
||||
|
||||
QuantProcessor -->|Fetch Financials| YF
|
||||
PeerProcessor -->|Fetch Multiples| YF
|
||||
YF -->|Raw Data| QuantProcessor
|
||||
|
||||
QuantProcessor -->|DCF, Ratios| Tab2
|
||||
QuantProcessor -->|DuPont, Sankey| Tab1
|
||||
@@ -0,0 +1,14 @@
|
||||
# Directory Map
|
||||
|
||||
```text
|
||||
FQDC Project/
|
||||
├── app.py # 메인 스트림릿 애플리케이션 로직 (UI, API 연동, 데이터 처리)
|
||||
├── find_toc.py # SEC EDGAR 문서를 크롤링하여 목차(TOC) 위치를 식별하는 유틸리티 스크립트
|
||||
├── push_to_github.sh # GitHub 원격 저장소 자동 커밋/푸시 스크립트
|
||||
├── requirements.txt # 의존성 패키지 (streamlit, google-generativeai, yfinance 등)
|
||||
├── README.md # 프로젝트 소개, 실행 방법 및 아키텍처 설명
|
||||
├── TECHNICAL_NOTES.md # 토큰 최적화 및 Rate Limit 대응 기술 문서 (ADL 기반)
|
||||
├── .env.example # 환경변수 템플릿 파일
|
||||
├── .gitignore # Git 버전 관리 제외 목록 (가상환경, 로컬 설정 파일 등)
|
||||
├── data/ # (런타임 생성) 추출된 10-K 항목별 JSON 캐시 저장 폴더
|
||||
└── .app_prefs.json # (런타임 생성) 사용자 환경설정(API Key, Email)을 임시 저장하는 파일
|
||||
@@ -0,0 +1,15 @@
|
||||
# Flows
|
||||
|
||||
본 애플리케이션은 **정성적 흐름(Qualitative Flow)**과 **정량적 흐름(Quantitative Flow)**을 완전히 분리하여 설계되었습니다.
|
||||
|
||||
## 1. 정성 데이터 흐름 (Qualitative Flow)
|
||||
1. **다운로드:** `sec-edgar-downloader`를 사용하여 입력받은 티커와 이메일로 가장 최신 10-K HTML 문서를 가져옵니다.
|
||||
2. **파싱 및 클렌징:** HTML 문서에서 `lxml`과 `BeautifulSoup`을 사용해 테이블, 이미지, 스크립트를 제거하고 정규식으로 Item 1A(Risk Factors)와 Item 7(MD&A) 섹션만 추출합니다.
|
||||
3. **캐싱 및 Chunking:** 추출된 텍스트를 로컬 디렉토리(`data/`)에 캐시로 저장하고, Gemini API 한도를 넘지 않도록 `smart_chunk()` 함수를 통해 중간 내용을 생략하여 압축합니다.
|
||||
4. **LLM 추론:** Gemini API를 호출하여 경영진 전략, 주요 리스크, 핵심 인사이트를 생성하고 결과를 화면에 스트리밍합니다.
|
||||
|
||||
## 2. 정량 데이터 흐름 (Quantitative Flow)
|
||||
1. **검색 및 식별:** 사용자가 입력한 기업명으로 `yahooquery`를 통해 티커 및 거래소 식별자를 추론합니다.
|
||||
2. **데이터 페칭:** `yfinance` 및 `yahooquery`를 통해 재무상태표, 손익계산서, 현금흐름표를 호출합니다.
|
||||
3. **폴백(Fallback) 연산:** 특정 값이 없을 경우 `fast_info`, `info`, `quarterly` 데이터 순으로 TTM(Trailing 12 Months) 값을 대체 연산합니다.
|
||||
4. **모델링 및 렌더링:** 전처리된 데이터를 바탕으로 Pandas 연산을 통해 DCF 내재가치, Piotroski F-Score, DuPont 분석 값을 산출하고 Plotly 차트(Radar, Sankey)로 시각화합니다.
|
||||
@@ -0,0 +1,28 @@
|
||||
infrastructure:
|
||||
environment:
|
||||
language: "Python 3.9+"
|
||||
framework: "Streamlit >= 1.28.0"
|
||||
|
||||
external_apis:
|
||||
- name: "Google Gemini API"
|
||||
library: "google-generativeai >= 0.8.0"
|
||||
usage: "MD&A 인사이트 도출, 리스크 분석, 산업 전망 리포트 생성"
|
||||
auth: "API Key (GOOGLE_API_KEY)"
|
||||
|
||||
- name: "SEC EDGAR API"
|
||||
library: "sec-edgar-downloader >= 5.0.0"
|
||||
usage: "최신 10-K 공시 원문(HTML) 다운로드"
|
||||
auth: "User-Agent Email (SEC_EDGAR_EMAIL)"
|
||||
|
||||
- name: "Yahoo Finance API"
|
||||
library: ["yfinance >= 0.2.40", "yahooquery >= 2.2.0"]
|
||||
usage: "티커 검색, 재무제표, 현금흐름, 주식수, 경쟁사 멀티플 추출"
|
||||
auth: "None Required"
|
||||
|
||||
data_processing:
|
||||
- name: "Pandas"
|
||||
version: ">= 2.0.0"
|
||||
- name: "BeautifulSoup4 / lxml"
|
||||
version: ">= 4.12.0 / 4.9.0"
|
||||
- name: "Plotly"
|
||||
version: ">= 5.18.0"
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"project_name": "10-K Financial Analyzer Dashboard",
|
||||
"version": "1.0.0",
|
||||
"description": "A hybrid architecture application unifying qualitative LLM-driven insights and quantitative financial valuation.",
|
||||
"author": "shawnkim1997",
|
||||
"entrypoint": "app.py",
|
||||
"components": [
|
||||
"10-K Text Extraction & LLM Summarizer",
|
||||
"10-Year 2-Stage DCF Valuation Model",
|
||||
"Top-down Industry Comparables Analyzer"
|
||||
],
|
||||
"technologies": [
|
||||
"Python",
|
||||
"Streamlit",
|
||||
"Gemini 2.0 Flash",
|
||||
"yfinance",
|
||||
"BeautifulSoup"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,20 @@
|
||||
# Product Requirements Document (PRD)
|
||||
## 프로젝트명: All-in-One Financial Analysis Dashboard
|
||||
|
||||
### 1. 프로젝트 비전 및 목표
|
||||
- **목표:** 주식 리서치 과정의 비효율성(방대한 공시 자료, 분산된 밸류에이션 모델 등)을 단일 워크플로우로 통합하는 하이브리드 대시보드 구축.
|
||||
- **비전:** 개인 투자자와 금융 전문가(애널리스트, 포트폴리오 매니저 등)를 대상으로 하는 B2C/B2B SaaS 형태의 상용화.
|
||||
|
||||
### 2. 핵심 가치 제안 (하이브리드 아키텍처)
|
||||
- 언어 모델(Gemini)은 텍스트 중심의 정성적 분석에만 사용하여 토큰 비용을 최소화.
|
||||
- 정량적 수치(DCF, 멀티플 등)는 무료 API(`yfinance`, `yahooquery`)에서 가져와 재무 데이터의 정확성 확보.
|
||||
|
||||
### 3. 주요 기능 (Tabs)
|
||||
1. **10-K & MD&A Insights:** SEC EDGAR에서 10-K(Item 1A, Item 7)를 가져와 Gemini로 경영진 어조, 전략적 변화, 잠재적 리스크 분석.
|
||||
2. **3-Scenario DCF Valuation:** 10년 2단계 DCF 모델 (1~5년 성장, 6~10년 Fade). WACC, Terminal Growth 슬라이더 지원 및 Bull/Base/Bear 시나리오별 내재가치 도출.
|
||||
3. **Top-Down Sector Analysis:** 특정 산업군 선택 시 경쟁사들의 멀티플(P/E, EV/EBITDA, P/B) 비교 및 Gemini 기반 거시적 산업 전망 생성.
|
||||
|
||||
### 4. 핵심 UI/UX 요구사항
|
||||
- Streamlit 기반의 3개 탭 구성.
|
||||
- 사이드바를 통한 전역 설정 (Google API Key, SEC Email, 다국어 지원 기업 검색).
|
||||
- 정량 차트 시각화: Sankey Diagram, Radar Chart, F-Score 등 (Plotly 사용).
|
||||
@@ -0,0 +1,19 @@
|
||||
# Project Development Rules
|
||||
|
||||
### 1. 예외 및 폴백(Fallback) 처리 필수
|
||||
- 금융 API(`yfinance`, `yahooquery`)는 데이터 누락이 잦으므로, 항상 `try-except` 구문을 사용해 에러를 방지하세요.
|
||||
- 데이터 조회 실패 시 빈 데이터프레임(`pd.DataFrame()`)이나 기본값(`0.0`, `None`)을 반환하도록 설계해야 합니다.
|
||||
- 수치 데이터 파싱 시에는 직접 형변환(`float(x)`)을 지양하고, 반드시 예외처리가 포함된 `_safe_float(x)` 헬퍼 함수를 사용하세요.
|
||||
|
||||
### 2. LLM 호출 시 토큰 최적화
|
||||
- 대형 HTML을 LLM에 전송하기 전 반드시 `BeautifulSoup` 및 정규식(`re`)을 사용하여 태그와 표 데이터를 클렌징해야 합니다.
|
||||
- 텍스트 길이가 길어질 경우 `smart_chunk()` 함수를 통해 중간 내용을 버리고 핵심(앞부분과 뒷부분)만 남겨 토큰 한도를 준수해야 합니다.
|
||||
- 429 Error(Rate Limit) 방지를 위해 Gemini 호출 시 `_generate_with_retry()` 래퍼 함수를 통해 자동 재시도 로직을 적용하세요.
|
||||
|
||||
### 3. 상태 관리 및 캐싱
|
||||
- 재무 데이터와 분석 결과는 `@st.cache_data(ttl=300)`을 사용해 캐싱하여 속도를 향상시킵니다.
|
||||
- 10-K 분석 텍스트는 `data/` 경로 하위에 JSON 파일 형태로 영구 저장하여 불필요한 SEC API 재요청을 최소화해야 합니다.
|
||||
|
||||
### 4. 코드 스타일
|
||||
- 모든 UI 출력 문자열과 변수명은 명확성을 위해 일관성 있게 작성되어야 합니다.
|
||||
- Pandas 데이터프레임에서 빈 값(None, NaN)을 화면에 출력할 경우, 반드시 `"N/A"` 포맷으로 변경하여 사용자 혼동을 피하세요 (`_na()` 함수 활용).
|
||||
@@ -0,0 +1,21 @@
|
||||
# Agent Navigation Hub (AGENT.md)
|
||||
|
||||
이 문서는 AI 코딩 에이전트 및 개발자가 `10-K-summariser-project`의 구조와 컨텍스트를 빠르게 파악하기 위한 **진입점(Entrypoint)**입니다.
|
||||
|
||||
작업을 시작하거나 코드를 수정하기 전에, 필요한 정보에 맞춰 아래의 문서를 먼저 확인하십시오. (모든 문서는 `agent/` 디렉토리에 위치합니다.)
|
||||
|
||||
## 🧭 Context & Documentation Map
|
||||
|
||||
| 문서명 | 역할 및 포함 내용 |
|
||||
| :--- | :--- |
|
||||
| **[PRD](./prd.md)** | 프로젝트 비전, 주요 기능 요구사항(3개의 탭), 타겟 유저 등 **프로젝트 기획 배경** |
|
||||
| **[Architecture](./architecture.mermaid)** | 시스템의 전체적인 구조를 보여주는 **Mermaid 아키텍처 다이어그램** |
|
||||
| **[Data Flows](./data_flows.md)** | 정성 파이프라인(LLM)과 정량 파이프라인(Pandas)이 어떻게 나뉘어 동작하는지 설명하는 **데이터 흐름도** |
|
||||
| **[Directory Map](./directory_map.md)** | 루트 디렉토리 및 주요 파일들(`app.py`, `find_toc.py` 등)의 역할과 **파일 구조** |
|
||||
| **[ADL](./adl.yaml)** | 429 에러 해결, 10년 2단계 DCF 도입, 다중 폴백 구조 등 **주요 기술적 의사결정 기록** |
|
||||
| **[Infra](./infra.yaml)** | Python 버전, Streamlit, Gemini API, yfinance 등 **의존성 및 인프라 환경** |
|
||||
| **[Manifest](./manifest.json)** | 프로젝트 메타데이터 (이름, 버전, 사용 기술 스택 등) |
|
||||
| **[Rules](./rules.md)** | ⚠️ 에러 핸들링, 토큰 최적화, 상태 관리 등 코드를 작성할 때 반드시 지켜야 할 **개발 가드레일 및 규칙** |
|
||||
|
||||
---
|
||||
**💡 Agent Action Item:** 코드를 수정하거나 새로운 기능을 구현할 때, 반드시 **[Rules](./rules.md)**를 먼저 숙지하고, 기존 아키텍처를 훼손하지 않도록 **[Architecture](./architecture.mermaid)** 및 **[Data Flows](./data_flows.md)**와 일치하게 작업하십시오.
|
||||
Reference in New Issue
Block a user