Alpha Vantage API에서 미국 주식 분석기 만들기 8)

이번 포스팅에서는 FinAgent-Lab의 시장 분석 에이전트 프로젝트에 기여한 내용을 공유하려고 합니다. 특히 미국 주식 시장의 수익성과 안정성 지표 분석 기능을 구현하고 통합하는 작업에 대해 설명드리겠습니다.

해결한 과제

프로젝트에 기여하면서 다음 네 가지 주요 과제를 해결했습니다:

1. GitHub Settings 접근 권한 이슈
2. 환경변수 정의하기
3. 파이프라인 코드 추가
4. 리포트 양식 정의

각 과제에 대한 해결 방법을 하나씩 살펴보겠습니다.

1. GitHub Settings 접근 권한 이슈

프로젝트에 기여하는 과정에서 GitHub 레포지토리의 Settings에 접근할 권한이 없어 Secret 환경변수를 직접 추가할 수 없었습니다.

해결 방법:

• 필요한 환경변수를 문서화하고 프로젝트 관리자에게 필요한 변수 추가를 요청드릴 예정입니다.

2. 환경변수 정의하기

Alpha Vantage API를 사용하기 위해 새로운 환경변수가 필요했습니다.

docker-compose.yml 추가:

    - ALPHA_VANTAGE_API_KEY=${ALPHA_VANTAGE_API_KEY}

deployment.yml 환경변수 추가:

    ALPHA_VANTAGE_API_KEY=${{ secrets.ALPHA_VANTAGE_API_KEY }}

3. 파이프라인 코드 추가

LangGraph 기반 멀티 에이전트 시스템에 수익성 & 안정성 분석 파이프라인을 추가했습니다. 이 파이프라인은 OpenWebUI와 통합되어 사용자가 웹 인터페이스를 통해 금융 분석 서비스에 접근할 수 있도록 해줍니다.

파이프라인 설계 원칙

1. 사용자 친화적 인터페이스: 복잡한 재무 분석을 간단한 질의로 요청할 수 있습니다.
2. 오류 처리 강화: 네트워크 문제, API 제한, 데이터 누락 등 다양한 예외 상황에 대응합니다.
3. 유연성: 티커 심볼뿐만 아니라 회사 이름으로도 검색할 수 있도록 했습니다.

파이프라인 코드 상세 분석

import os
from typing import List, Union, Generator, Iterator
from pydantic import BaseModel
import requests

APISERVER_HOST = os.getenv("APISERVER_HOST")

환경변수로부터 API 서버 호스트를 가져오는 부분입니다. 이 변수는 Docker 컴포즈에서 설정됩니다.

class RequestBody(BaseModel):
    query: str
    model: str
    temperature: float

class ResponseBody(BaseModel):
    answer: str

Pydantic 모델을 사용하여 요청과 응답의 구조를 정의합니다. 타입 안정성과 검증 기능을 제공합니다.

class Pipeline:
    class Valves(BaseModel):
        pass

    def __init__(self):
        self.name = "Market Analysis - Profitability & Stability Analyzer"
        self.agent_name = "usfinancialstatementanalyzer"
        self.endpoint = f"http://{APISERVER_HOST}/api/{self.agent_name}"
        pass

파이프라인 클래스 초기화 부분입니다. name은 OpenWebUI에 표시될 모델 이름이고, agent_name은 API 엔드포인트의 일부로 사용됩니다.

    async def on_startup(self):
        print(f"on_startup:{__name__}")
        pass

    async def on_shutdown(self):
        print(f"on_shutdown:{__name__}")
        pass

서버 시작 및 종료 시 호출되는 생명주기 메소드입니다. 필요한 경우 리소스 초기화/정리 코드를 추가할 수 있습니다.

    def pipe(
        self, user_message: str, model_id: str, messages: List[dict], body: dict
    ) -> Union[str, Generator, Iterator]:
        print(f"pipe:{__name__}")

        print("messages: ", messages)
        print("user_message: ", user_message)
        print("body: ", body)

        # Extract stock ticker or company name from user message
        query = user_message.strip()
        
        # Check if the query is valid
        if not query:
            return "Please provide a company name or stock ticker symbol (e.g., Apple, AAPL, Microsoft, MSFT)"

사용자 메시지를 처리하는 핵심 메소드입니다. 입력값을 검증하고, 빈 입력에 대한 사용자 친화적인 피드백을 제공합니다.

        headers = {}
        headers["accept"] = "application/json"
        headers["Content-Type"] = "application/json"

        try:
            r = requests.post(
                url=f"{self.endpoint}?query={query}",
                json={},
                headers=headers,
            )

            r.raise_for_status()
            return ResponseBody(**r.json()).answer

HTTP 요청을 통해 백엔드 API 서버와 통신합니다. 사용자 쿼리는 URL 파라미터로 전달됩니다. 응답은 Pydantic 모델로 파싱되어 타입 안전성을 보장합니다.

        except Exception as e:
            error_message = str(e)
            if "404" in error_message:
                return f"Error: The US Stock Profitability & Stability Analysis service is not available. Please check if the service is running."
            elif "Connection" in error_message:
                return f"Error: Could not connect to the analysis service. Please check your network connection."
            else:
                return f"Error analyzing profitability and stability metrics: {e}"

상세한 오류 처리 로직이 구현되어 있습니다. 서비스 불가, 연결 실패, 기타 오류에 대해 사용자 친화적인 메시지를 제공합니다.

파이프라인 통합 과정

1. 파일 생성: pipelines/profitability_stability_pipeline.py 파일을 생성했습니다.
2. Docker 볼륨 마운트: docker-compose.yml에서 파이프라인 디렉토리가 컨테이너에 마운트되도록 설정했습니다.
3. 자동 로드: OpenWebUI의 Pipelines 컴포넌트가 시작될 때 파이프라인이 자동으로 로드됩니다.
4. 웹 인터페이스 연동: 파이프라인이 등록되면 OpenWebUI의 모델 선택 드롭다운에 표시됩니다.

이 파이프라인 덕분에 사용자는 "Apple의 수익성과 안정성 지표 분석해줘" 또는 단순히 "AAPL"과 같은 간단한 쿼리로 복잡한 재무 분석을 요청할 수 있습니다.

4. 리포트 양식 정의

미국 주식의 수익성과 안정성 지표를 체계적으로 분석하고 시각적으로 효과적인 보고서를 생성하기 위해 다음과 같은 리포트 양식을 정의했습니다.

리포트 설계 원칙

1. 명확한 구조화: 정보를 논리적으로 구조화하여 투자자가 쉽게 이해할 수 있도록 했습니다.
2. 지표별 평가 제공: 단순한 수치 나열을 넘어, 각 지표의 값이 좋은지 나쁜지 평가합니다.
3. 시각적 계층구조: 제목, 부제목, 목록을 활용하여 정보 계층을 시각화했습니다.
4. 종합 평가: 개별 지표 외에도 수익성과 안정성에 대한 종합 평가를 제공합니다.

리포트에 표시되는 평가들은 alpha_vantage_profitability.py와 alpha_vantage_stability.py 파일에서 정의한 평가 로직에 기반합니다.

# ROE 평가 로직 - alpha_vantage_profitability.py에서 발췌
if roe_value > 20:
    analysis["roe_evaluation"] = "Exceptional ROE - Top tier profitability"
elif roe_value > 15:
    analysis["roe_evaluation"] = "Excellent ROE - Strong profitability"
elif roe_value > 10:
    analysis["roe_evaluation"] = "Good ROE - Above average profitability"
elif roe_value > 5:
    analysis["roe_evaluation"] = "Average ROE - Moderate profitability"
else:
    analysis["roe_evaluation"] = "Below average ROE - May indicate profitability concerns"

# 유동비율 평가 로직 - alpha_vantage_stability.py에서 발췌
if current_ratio > 3:
    analysis["current_ratio_evaluation"] = "Exceptional liquidity - Very conservative"
elif current_ratio > 2:
    analysis["current_ratio_evaluation"] = "Excellent liquidity - Strong financial stability"
elif current_ratio > 1.5:
    analysis["current_ratio_evaluation"] = "Good liquidity - Solid short-term stability"
elif current_ratio > 1:
    analysis["current_ratio_evaluation"] = "Adequate liquidity - Minimal short-term risk"
elif current_ratio > 0.8:
    analysis["current_ratio_evaluation"] = "Borderline liquidity - Potential short-term concerns"
else:
    analysis["current_ratio_evaluation"] = "Liquidity risk - Potential short-term obligations issues"

# 종합 수익성 평가 - calculate_overall_profitability_assessment 함수에서 발췌
if avg_score > 1.5:
    analysis["overall_profitability_assessment"] = "Exceptional profitability - Industry leading performance"
elif avg_score > 0.75:
    analysis["overall_profitability_assessment"] = "Strong profitability - Above industry average performance"
elif avg_score > 0:
    analysis["overall_profitability_assessment"] = "Good profitability - Competitive performance"
elif avg_score > -0.5:
    analysis["overall_profitability_assessment"] = "Adequate profitability - Room for improvement"
else:
    analysis["overall_profitability_assessment"] = "Weak profitability - Significant concerns"

5. 구체적인 리포트 양식

수익성 지표 분석 섹션

### 수익성 지표 분석
- **수익률 지표**
  - ROE(자기자본이익률): [값] ([평가])
  - ROA(총자산이익률): [값] ([평가])

- **마진 분석**
  - 매출총이익률(Gross Margin): [값] ([평가])
  - 영업이익률(Operating Margin): [값] ([평가])
  - 순이익률(Net Profit Margin): [값] ([평가])
  - EBITDA 마진: [값] ([평가])

- **수익성 추세**
  - 순이익 성장률: [값] ([평가])
  - 매출 성장률: [값] ([평가])

- **종합 수익성 평가**: [우수/양호/보통/취약/위험]
  - [주요 수익성 강점 및 약점에 대한 간략한 분석]

이 섹션에서는 수익성 지표를 다음 세 가지 카테고리로 구분했습니다:

1. 수익률 지표: 자본 및 자산 효율성을 측정하는 ROE와 ROA
2. 마진 분석: 매출 대비 이익률을 측정하는 다양한 마진 지표
3. 수익성 추세: 시간에 따른 성장률 분석

각 지표는 단순한 수치 외에도 "(우수)", "(양호)", "(보통)", "(취약)", "(위험)" 등의 평가를 함께 제공하여 해당 수치가 어떤 의미를 갖는지 직관적으로 이해할 수 있게 했습니다.

안정성 지표 분석 섹션

### 안정성 지표 분석
- **유동성 지표**
  - 유동비율(Current Ratio): [값] ([평가])
  - 당좌비율(Quick Ratio): [값] ([평가])
  - 현금비율(Cash Ratio): [값] ([평가])

- **부채 & 레버리지 분석**
  - 부채비율(Debt-to-Equity): [값] ([평가])
  - 부채/자산 비율(Debt-to-Assets): [값] ([평가])
  - 이자보상배율(Interest Coverage): [값] ([평가])

- **현금흐름 안정성**
  - 잉여현금흐름(FCF): [값]
  - FCF 마진: [값] ([평가])
  - 순이익 대비 FCF 비율: [값] ([평가])

- **종합 안정성 평가**: [우수/양호/보통/취약/위험]
  - [주요 안정성 강점 및 약점에 대한 간략한 분석]

안정성 분석 섹션은 다음 세 가지 하위 카테고리로 구성했습니다:

1. 유동성 지표: 단기 채무 상환 능력을 측정하는 다양한 비율
2. 부채 & 레버리지 분석: 장기적인 재무 안정성과 위험 수준을 평가
3. 현금흐름 안정성: 실제 현금 창출 능력과 관련된 지표

결론 및 향후 계획

이번 작업을 통해 FinAgent-Lab의 시장 분석 에이전트 프로젝트에 수익성과 안정성 지표 분석 기능을 추가했습니다. 이 기능은 투자자들이 기업의 재무 건전성을 평가하는 데 유용한 정보를 제공할 것입니다.