🧠 spoonAI - Python 기반 소프트웨어 분석 및 자동화 도구

이 프로젝트는 Python을 기반으로 외부 API(GitHub 등)와 LLM(대형 언어 모델) 서비스를 활용하여 코드 저장소를 분석하고, 다양한 자동화 및 분석 결과를 제공하는 시스템입니다. 환경 변수 관리, 외부 명령어(npx) 실행, 서비스 레이어, 그래프 기반 분석 로직, 도구 정의, URL 파싱 등 다양한 유틸리티가 포함되어 있습니다.

🛠 Tech Stack

• Python 3.12
• FastAPI (웹 서버 프레임워크)
• Spoon OS (AI Agent 프레임워크)
• dotenv (환경 변수 관리)
• 외부 API: GitHub, OpenRouter/LLM 등
• npx (Node.js 기반 외부 명령어 실행)
• AWS EC2 (배포 환경)

🏛️ Architecture

System Architecture

spoonAI는 AWS 클라우드 환경에서 FastAPI와 Spoon OS를 활용한 AI 에이전트 기반 아키텍처로 구성되어 있습니다.

주요 구성 요소

1. Client Layer

   • 웹 클라이언트가 HTTP 요청을 통해 시스템과 상호작용
   • Internet Gateway를 통한 안전한 접근

2. API Layer (FastAPI Server)

   • VPC 내 EC2 인스턴스에서 실행
   • Security Group으로 방화벽 보호
   • 워크플로우 트리거 및 응답 처리

3. Spoon OS Environment

   • Agent (AI Task Worker): 실제 AI 작업을 수행하는 에이전트
   • Graph (Workflow Logic): 워크플로우 흐름 제어
   • Nodes (Workflow Steps): 각 분석 단계를 담당하는 노드들

4. External Services

   • GitHub MCP Server: GitHub 저장소 접근 및 분석
   • External LLM Service: OpenAI 등의 LLM API 활용
   • GitHub Repository: 분석 대상 저장소

Analysis Workflow

시스템의 분석 워크플로우는 다음과 같은 순차적 단계로 구성됩니다:

워크플로우 단계

1. fetch_metadata

   • GitHub 저장소의 메타데이터 수집
   • 기본 정보, 통계, 설정 등 추출

2. analyze_structure

   • 프로젝트 구조 분석
   • 디렉토리 구조, 파일 구성 파악

3. llm_summarize

   • LLM을 활용한 코드 요약
   • 주요 기능 및 로직 설명 생성

4. security_check

   • 보안 취약점 검사
   • 민감 정보 노출 여부 확인

5. build_readme

   • 분석 결과 기반 README 생성
   • 프로젝트 문서화

6. generate_report

   • 최종 분석 보고서 작성
   • 통합 결과물 생성

🗂️ 주요 컴포넌트

Core Components

• config/settings.py
  환경 변수 로드 및 검증, 외부 API 토큰 관리

• services/
  GitHub, LLM 등 외부 서비스와의 통신 및 분석 비즈니스 로직 구현

  • GitHub 저장소 분석
  • LLM 기반 코드 리뷰 및 요약
  • 외부 API 통합

• graph/spoon_graph.py
  분석 워크플로우의 그래프 기반 제어 및 데이터 흐름 관리

  • LangGraph를 활용한 상태 관리
  • 분석 파이프라인 정의
  • 노드 간 데이터 전달 및 조정

• tool/tool_defination.py
  분석에 사용되는 도구 및 명령 정의, 외부 명령 실행 로직

  • npx 기반 외부 도구 호출
  • 커스텀 분석 도구 래핑

• utils/url_parser.py
  URL 파싱 등 보조 유틸리티 함수 제공

• api/server.py
  FastAPI 기반 REST API 서버

🚀 Getting Started

Prerequisites

이 프로젝트를 실행하기 위해서는 다음이 필요합니다:

• Python 3.12+
• Node.js (npx 명령어 사용을 위해)
• GitHub Personal Access Token (저장소 분석용)
• OpenRouter API Key 또는 기타 LLM API Key

Installation

1. 저장소 클론

git clone https://github.com/teamKAU/spoonAI.git
cd spoonAI

2. 가상환경 생성 및 활성화

python -m venv venv

# macOS/Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

3. 의존성 설치

pip install -r requirements.txt

4. 환경 변수 설정

프로젝트 루트에 .env 파일을 생성하고 다음 내용을 추가하세요:

# GitHub API
GITHUB_TOKEN=your_github_personal_access_token

# LLM API (OpenRouter 또는 다른 제공자)
OPENROUTER_API_KEY=your_openrouter_api_key
# 또는
OPENAI_API_KEY=your_openai_api_key

# 기타 설정
DEBUG=True
LOG_LEVEL=INFO

📦 Usage

1. FastAPI 서버 실행

웹 API 서버를 시작하려면:

python -m api.server

서버는 기본적으로 http://localhost:8000에서 실행됩니다.

API 문서는 http://localhost:8000/docs에서 확인할 수 있습니다.

2. Agent 테스트 실행

직접 에이전트를 테스트하려면:

python main.py

3. 주요 기능

GitHub 저장소 분석

from services.github_service import GitHubService

service = GitHubService()
analysis = service.analyze_repository("owner/repo")
print(analysis)

LLM 기반 코드 리뷰

from services.llm_service import LLMService

llm_service = LLMService()
review = llm_service.review_code(code_snippet)
print(review)

그래프 기반 워크플로우 실행

from graph.spoon_graph import run_analysis_workflow

result = run_analysis_workflow(repository_url)
print(result)

🏗️ Project Structure

spoonAI/
├── api/
│   └── server.py          # FastAPI 서버
├── config/
│   └── settings.py        # 환경 변수 및 설정 관리
├── services/
│   ├── github_service.py  # GitHub API 통신
│   └── llm_service.py     # LLM API 통신
├── graph/
│   └── spoon_graph.py     # LangGraph 기반 워크플로우
├── tool/
│   └── tool_defination.py # 도구 정의 및 실행
├── utils/
│   └── url_parser.py      # URL 파싱 유틸리티
├── docs/
│   └── images/            # 아키텍처 다이어그램
│       ├── architecture.png
│       └── workflow.png
├── main.py                # 메인 실행 파일
├── requirements.txt       # Python 의존성
├── .env.example           # 환경 변수 템플릿
└── README.md

⚙️ Configuration

환경 변수

변수명	설명	필수 여부
GITHUB_TOKEN	GitHub Personal Access Token	✅
OPENROUTER_API_KEY	OpenRouter API Key	✅*
OPENAI_API_KEY	OpenAI API Key	✅*
DEBUG	디버그 모드 활성화	❌
LOG_LEVEL	로그 레벨 (INFO, DEBUG, WARNING, ERROR)	❌

*LLM API 키 중 하나는 필수입니다.

⚠️ Risks / Limitations

• 외부 서비스 의존성: GitHub API, LLM API 등 외부 서비스에 대한 의존도가 높아 환경 설정 오류 시 정상 동작하지 않을 수 있습니다.

• 다중 런타임 요구사항: Python과 Node.js 환경이 모두 필요합니다 (npx 명령어 실행을 위해).

• API 레이트 리밋: GitHub API 및 LLM API는 사용량 제한이 있을 수 있습니다. 대량의 저장소 분석 시 주의가 필요합니다.

• 비용: LLM API 사용 시 토큰 기반 과금이 발생할 수 있습니다.

• 코드 커버리지: 일부 분석 로직 및 그래프 처리 방식은 추가 문서화가 필요할 수 있습니다.

🔒 Security Notes

API 키 관리

• ⚠️ 절대 .env 파일을 Git에 커밋하지 마세요
• .gitignore에 .env가 포함되어 있는지 확인하세요
• 프로덕션 환경에서는 환경 변수 관리 서비스(AWS Secrets Manager, Azure Key Vault 등) 사용을 권장합니다

GitHub Token 권한

• GitHub Personal Access Token 생성 시 최소 권한 원칙을 따르세요
• 저장소 분석에 필요한 최소한의 scope만 부여하세요 (예: repo:read)

외부 명령 실행

• npx 및 외부 명령어 실행 시 입력 검증을 철저히 하세요
• 사용자 입력이 직접 명령어로 전달되지 않도록 주의하세요

🧪 Testing

테스트 실행:

# 전체 테스트
pytest

# 특정 모듈 테스트
pytest tests/test_services.py

# 커버리지 확인
pytest --cov=.

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

이 프로젝트의 라이선스 정보는 추후 업데이트될 예정입니다.

📞 Contact & Support

• GitHub Issues: https://github.com/teamKAU/spoonAI/issues
• Team: teamKAU

🗺️ Roadmap

• 추가 코드 분석 메트릭 지원
• 다양한 LLM 제공자 통합
• 웹 UI 대시보드 개발
• CI/CD 파이프라인 자동화 지원
• 더 많은 프로그래밍 언어 지원

📝 기타 참고 사항

아키텍처

• 서비스 레이어 패턴: 각 외부 서비스(GitHub, LLM)는 독립적인 서비스 클래스로 분리되어 있습니다.
• 그래프 기반 워크플로우: Spoon OS를 사용하여 복잡한 분석 파이프라인을 상태 기계로 관리합니다.
• 비동기 처리: FastAPI와 비동기 함수를 활용하여 동시성을 지원합니다.

개발 시 주의사항

• npx 명령어 사용을 위해 Node.js가 설치되어 있어야 합니다
• Python 3.12 이상에서 테스트되었습니다
• 환경 변수 설정이 올바르지 않으면 서비스가 시작되지 않을 수 있습니다

성능 최적화

• LLM API 호출 시 캐싱을 고려하세요
• 대량의 저장소 분석 시 배치 처리를 권장합니다
• GitHub API 레이트 리밋을 고려하여 요청 간격을 조절하세요

---

Made with ❤️ by teamKAU