cd1-agent 0.1.0__py3-none-any.whl

cd1_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,429 @@
+Metadata-Version: 2.4
+Name: cd1-agent
+Version: 0.1.0
+Summary: AWS Lambda-based intelligent log analysis and auto-remediation system
+Author: CD1 Team
+License: MIT
+Project-URL: Homepage, https://github.com/lks21c/cd1-agent
+Project-URL: Documentation, https://github.com/lks21c/cd1-agent#readme
+Project-URL: Repository, https://github.com/lks21c/cd1-agent
+Keywords: aws,lambda,langgraph,anomaly-detection,remediation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: langchain-core>=0.1.0
+Requires-Dist: langgraph>=0.0.30
+Requires-Dist: boto3>=1.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Provides-Extra: vllm
+Requires-Dist: openai>=1.0.0; extra == "vllm"
+Requires-Dist: httpx>=0.25.0; extra == "vllm"
+Provides-Extra: victoria
+Requires-Dist: requests>=2.31.0; extra == "victoria"
+Provides-Extra: rds
+Requires-Dist: pymysql>=1.1.0; extra == "rds"
+Requires-Dist: cryptography>=41.0.0; extra == "rds"
+Provides-Extra: pyod
+Requires-Dist: pyod>=2.0.0; extra == "pyod"
+Requires-Dist: numpy>=1.24.0; extra == "pyod"
+Requires-Dist: scipy>=1.10.0; extra == "pyod"
+Provides-Extra: bdp-cost
+Requires-Dist: cd1-agent[pyod,server]; extra == "bdp-cost"
+Provides-Extra: gcp
+Requires-Dist: google-cloud-bigquery>=3.0.0; extra == "gcp"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115.0; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == "server"
+Requires-Dist: pydantic-settings>=2.0.0; extra == "server"
+Requires-Dist: prometheus-client>=0.21.0; extra == "server"
+Requires-Dist: httpx>=0.27.0; extra == "server"
+Requires-Dist: jinja2>=3.1.0; extra == "server"
+Requires-Dist: weasyprint>=62.0; extra == "server"
+Requires-Dist: kubernetes>=28.1.0; extra == "server"
+Requires-Dist: apscheduler<4,>=3.10; extra == "server"
+Requires-Dist: cairosvg>=2.7.0; extra == "server"
+Requires-Dist: pymupdf>=1.25.0; extra == "server"
+Provides-Extra: portal
+Requires-Dist: cd1-agent[rds,server]; extra == "portal"
+Requires-Dist: authlib>=1.3.0; extra == "portal"
+Requires-Dist: itsdangerous>=2.1.0; extra == "portal"
+Requires-Dist: python-multipart>=0.0.6; extra == "portal"
+Provides-Extra: lambda-layer
+Requires-Dist: pydantic>=2.0.0; extra == "lambda-layer"
+Requires-Dist: langchain-core>=0.1.0; extra == "lambda-layer"
+Requires-Dist: langgraph>=0.0.30; extra == "lambda-layer"
+Requires-Dist: boto3>=1.28.0; extra == "lambda-layer"
+Provides-Extra: all
+Requires-Dist: cd1-agent[pyod,rds,server,victoria,vllm]; extra == "all"
+
+# CD1 Agent
+
+AWS Lambda 기반 서버리스 멀티 에이전트 이상 탐지 및 자동 복구 플랫폼
+
+## Overview
+
+CD1 Agent는 **4개의 독립적인 서브 에이전트**로 구성된 이상 탐지 플랫폼입니다. 각 에이전트는 MWAA(Airflow)에서 5분 주기로 호출되며, 독립적인 Step Functions 워크플로우를 통해 탐지 → 분석 → 복구 조치를 수행합니다.
+
+### 서브 에이전트 구성
+
+| Agent | 대상 | 탐지 방식 | 설명 |
+|-------|------|----------|------|
+| **BDP Agent** | AWS 인프라 | CloudWatch Logs/Metrics | 로그 패턴, 메트릭 이상, 에러 스파이크 감지 |
+| **HDSP Agent** | On-Prem K8s | Prometheus 메트릭 | Pod/Node 상태, CPU/Memory 이상, OOMKill 감지 |
+| **Cost Agent** | AWS 비용 | Cost Explorer + Luminol | 비용 이상, 서비스별 급증, 근본 원인 분석 |
+| **Drift Agent** | AWS 설정 | Git Baseline 비교 | 구성 드리프트, 보안 설정 변경 감지 |
+
+### Provider 구성
+
+#### LLM Provider
+
+| 환경 | Provider | 모델 | 용도 |
+|------|----------|------|------|
+| **On-Premise** | vLLM | 자체 호스팅 LLM | 프로덕션 분석 |
+| **Public (Mock)** | Google Gemini | Gemini 2.5 Pro/Flash | 개발/테스트 |
+| **로컬 테스트** | Mock LLM | 내장 Mock | AWS/LLM 없이 로직 테스트 |
+
+#### AWS Provider
+
+| 환경 | Provider | 용도 |
+|------|----------|------|
+| **Production** | AWS | 실제 AWS 서비스 호출 |
+| **Public/로컬** | Mock | AWS 없이 전체 로직 테스트 |
+
+### 주요 기능
+
+- **LangGraph Agent**: 동적 ReAct 루프 기반 분석 에이전트
+- **주기적 로그 감지**: 5-10분 간격으로 CloudWatch 및 RDS 통합 로그 분석
+- **AI 기반 근본 원인 분석**: vLLM 또는 Gemini를 활용한 ReAct 패턴 분석
+- **승인 기반 실행**:
+  - 0.5+ : 승인 요청 후 실행
+  - <0.5 : 담당자 에스컬레이션
+- **AWS 리소스 조정**: Lambda 재시작, RDS 파라미터 변경, Auto Scaling 조정
+- **EventBridge 알림**: 외부 시스템 연동 (Slack, Teams 등)
+
+## Architecture
+
+### Multi-Agent Orchestration
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         MWAA (Airflow DAGs) - 5분 주기                    │
+└────────┬────────────────┬────────────────┬────────────────┬─────────────┘
+         │                │                │                │
+         ▼                ▼                ▼                ▼
+┌────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
+│ BDP Agent      │ │ HDSP Agent     │ │ Cost Agent     │ │ Drift Agent    │
+│ (AWS 로그)     │ │ (Prometheus)   │ │ (Cost Explorer)│ │ (Git Baseline) │
+├────────────────┤ ├────────────────┤ ├────────────────┤ ├────────────────┤
+│ Detection      │ │ Detection      │ │ Detection      │ │ Detection      │
+│      ↓         │ │      ↓         │ │      ↓         │ │      ↓         │
+│ Step Functions │ │ Step Functions │ │ Step Functions │ │ Step Functions │
+│ (개별 WF)      │ │ (개별 WF)      │ │ (개별 WF)      │ │ (개별 WF)      │
+│      ↓         │ │      ↓         │ │      ↓         │ │      ↓         │
+│ Analysis       │ │ Analysis       │ │ Analysis       │ │ Analysis       │
+│      ↓         │ │      ↓         │ │      ↓         │ │      ↓         │
+│ Action         │ │ Action         │ │ Action         │ │ Action         │
+└────────────────┘ └────────────────┘ └────────────────┘ └────────────────┘
+         │                │                │                │
+         └────────────────┴────────────────┴────────────────┘
+                                   │
+                                   ▼
+                    ┌──────────────────────────┐
+                    │ 공통 컴포넌트            │
+                    │ - Analysis Agent (LLM)   │
+                    │ - Action Engine          │
+                    │ - EventBridge 알림       │
+                    └──────────────────────────┘
+```
+
+**핵심 설계 원칙**:
+- **독립적 워크플로우**: 각 에이전트는 개별 Step Functions 워크플로우 실행
+- **공통 분석 엔진**: LangGraph 기반 ReAct 루프를 모든 에이전트가 공유
+- **유연한 스케줄링**: MWAA DAG별 독립적인 실행 주기 설정 가능
+
+### 워크플로우 상세
+
+```mermaid
+stateDiagram-v2
+    [*] --> DetectAnomalies
+    DetectAnomalies --> CheckAnomalies
+
+    CheckAnomalies --> NoAnomalies: No Issues
+    CheckAnomalies --> AnalyzeRootCause: Issues Found
+
+    NoAnomalies --> [*]
+
+    AnalyzeRootCause --> EvaluateConfidence
+
+    EvaluateConfidence --> RequestApproval: >= 0.5
+    EvaluateConfidence --> Escalate: < 0.5
+
+    RequestApproval --> CheckApproval
+    CheckApproval --> ExecuteApproved: Approved
+    CheckApproval --> Rejected: Rejected
+    ExecuteApproved --> Reflect
+
+    Reflect --> Success: Resolved
+    Reflect --> Replan: Needs Retry
+    Replan --> AnalyzeRootCause: Attempt < 3
+    Replan --> Escalate: Max Attempts
+
+    Escalate --> [*]
+    Rejected --> [*]
+    Success --> [*]
+```
+
+## Project Structure
+
+```
+cd1-agent/
+├── docs/
+│   ├── ARCHITECTURE.md           # 상세 아키텍처 문서
+│   ├── PROMPTS.md                # 프롬프트 템플릿 설계
+│   ├── COST_OPTIMIZATION.md      # 비용 최적화 전략
+│   ├── IMPLEMENTATION_GUIDE.md   # 구현 가이드
+│   ├── HDSP_DETECTION.md         # HDSP Agent 문서
+│   ├── COST_ANOMALY_DETECTION.md # Cost Agent 문서
+│   └── CONFIG_DRIFT_DETECTION.md # Drift Agent 문서
+├── src/
+│   ├── common/                   # 공통 코드
+│   │   ├── handlers/             # 공통 핸들러 (base, analysis, remediation)
+│   │   ├── services/             # 공통 서비스 (llm_client, aws_client, rds_client)
+│   │   ├── models/               # 데이터 모델
+│   │   ├── prompts/              # 프롬프트 템플릿
+│   │   ├── agent/                # LangGraph Agent
+│   │   └── chat/                 # Interactive Chat
+│   └── agents/                   # Agent별 코드
+│       ├── bdp/                  # BDP Agent (AWS CloudWatch)
+│       │   └── handler.py
+│       ├── hdsp/                 # HDSP Agent (Prometheus/K8s)
+│       │   ├── handler.py
+│       │   └── services/         # prometheus_client, anomaly_detector
+│       ├── cost/                 # Cost Agent (AWS Cost Explorer)
+│       │   ├── handler.py
+│       │   └── services/         # cost_explorer_client, anomaly_detector
+│       └── drift/                # Drift Agent (GitLab Baseline)
+│           ├── handler.py
+│           └── services/         # config_fetcher, drift_detector, gitlab_client
+├── tests/
+│   ├── common/                   # 공통 코드 테스트
+│   │   ├── agent/                # LangGraph 테스트
+│   │   └── chat/                 # Chat 테스트
+│   └── agents/                   # Agent별 테스트
+│       ├── bdp/
+│       ├── hdsp/
+│       ├── cost/
+│       └── drift/
+└── dags/                         # Airflow DAG 파일
+```
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- AWS CLI configured
+
+### Installation
+
+```bash
+# 1. Clone repository
+git clone https://github.com/lks21c/cd1-agent.git
+cd cd1-agent
+
+# 2. Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+# .venv\Scripts\activate   # Windows
+
+# 3. Install dependencies
+pip install -r requirements.txt
+```
+
+### Configuration
+
+#### Environment Variables
+
+**Mock Mode (Public/Local Testing)**
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AWS_MOCK` | AWS Mock 모드 활성화 (`true`/`false`) | `false` |
+| `LLM_MOCK` | LLM Mock 모드 활성화 (`true`/`false`) | `false` |
+
+**LLM Configuration**
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LLM_PROVIDER` | LLM 제공자 (`vllm` 또는 `gemini`) | `vllm` |
+| `VLLM_BASE_URL` | vLLM 서버 엔드포인트 (On-Prem) | `http://localhost:8000/v1` |
+| `VLLM_MODEL_NAME` | vLLM 모델 이름 | Required (vllm 사용 시) |
+| `GEMINI_API_KEY` | Gemini API 키 (Public Mock) | Required (gemini 사용 시) |
+| `GEMINI_MODEL_ID` | Gemini 모델 ID | `gemini-2.5-flash` |
+
+**AWS Configuration**
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RDS_CLUSTER_ARN` | RDS Aurora Serverless 클러스터 ARN | Required (AWS 모드) |
+| `RDS_SECRET_ARN` | RDS 접속 정보가 담긴 Secrets Manager ARN | Required (AWS 모드) |
+| `RDS_DATABASE` | 데이터베이스 이름 | `unified_logs` |
+| `DEDUP_TABLE` | DynamoDB 중복 제거 테이블 이름 | `bdp-anomaly-tracking` |
+
+**Quick Start for Mock Mode**
+
+```bash
+# AWS와 LLM 없이 로컬에서 로직 테스트
+export AWS_MOCK=true
+export LLM_MOCK=true
+python -m examples.services.aws_client  # AWS Mock 테스트
+python -m examples.services.llm_client  # LLM Mock 테스트
+```
+
+#### DynamoDB Tables
+
+| Table | Purpose | Key |
+|-------|---------|-----|
+| `bdp-anomaly-tracking` | 중복 제거 (TTL 7일) | `signature` |
+| `bdp-workflow-state` | 워크플로우 상태 | `workflow_id`, `timestamp` |
+| `bdp-action-history` | 복구 조치 감사 로그 | `action_id` |
+
+## Lambda Functions
+
+### Detection Lambda (에이전트별)
+
+| Function | Memory | Timeout | Trigger | Description |
+|----------|--------|---------|---------|-------------|
+| `bdp-detection` | 512MB | 60s | MWAA DAG | AWS CloudWatch 로그/메트릭 이상 감지 |
+| `bdp-hdsp-detection` | 512MB | 60s | MWAA DAG | On-Prem K8s Prometheus 메트릭 감지 |
+| `bdp-cost-detection` | 512MB | 60s | MWAA DAG | AWS Cost Explorer 비용 이상 감지 |
+| `bdp-drift-detection` | 512MB | 120s | MWAA DAG | AWS 설정 Git Baseline 드리프트 감지 |
+
+### 공통 Lambda
+
+| Function | Memory | Timeout | Trigger | Description |
+|----------|--------|---------|---------|-------------|
+| `bdp-analysis` | 1024MB | 120s | Step Functions | LLM 기반 근본 원인 분석 |
+| `bdp-action` | 512MB | 60s | Step Functions | 복구 조치 실행 |
+| `bdp-approval` | 256MB | 30s | API Gateway | 승인 요청 처리 |
+
+## MWAA DAG 구성
+
+| DAG | Schedule | Target Lambda | Description |
+|-----|----------|---------------|-------------|
+| `bdp_detection_dag` | `*/5 * * * *` | bdp-detection | AWS 로그/메트릭 감지 |
+| `bdp_hdsp_detection_dag` | `*/5 * * * *` | bdp-hdsp-detection | K8s 장애 감지 |
+| `bdp_cost_detection_dag` | `*/5 * * * *` | bdp-cost-detection | 비용 이상 감지 |
+| `bdp_drift_detection_dag` | `*/5 * * * *` | bdp-drift-detection | 설정 드리프트 감지 |
+
+## Cost Estimation
+
+### Monthly Cost (~$11/month for 1M events, excluding LLM)
+
+| Component | Cost |
+|-----------|------|
+| Lambda (ARM64) | ~$5 |
+| Step Functions | ~$3 |
+| DynamoDB (On-demand) | ~$2 |
+| EventBridge | ~$1 |
+
+### LLM 비용
+
+| Provider | 환경 | 비용 모델 |
+|----------|------|----------|
+| **vLLM (On-Prem)** | 프로덕션 | 자체 인프라 비용 (GPU 서버) |
+| **Gemini 2.5 Pro** | Mock/개발 | ~$0.00125/1K input, ~$0.005/1K output |
+| **Gemini 2.5 Flash** | Mock/개발 | ~$0.00015/1K input, ~$0.0006/1K output |
+
+### Cost Optimization Strategies
+
+1. **CloudWatch Field Indexing**: 67% 스캔 비용 감소
+2. **Hierarchical Summarization**: 80-90% 토큰 절감
+3. **ARM64/Graviton2**: 20-34% Lambda 비용 절감
+4. **Provisioned Concurrency**: Cold start 제거 (MWAA 트리거 사용 시)
+
+## Decision Flow
+
+모든 복구 조치는 **승인 후 실행** 방식으로 동작합니다.
+
+| Confidence | Action | Use Case |
+|------------|--------|----------|
+| >= 0.5 | Request Approval | 분석 완료, 승인 요청 |
+| < 0.5 | Escalate | 추가 분석 필요, 담당자 에스컬레이션 |
+
+> **Note**: 자동 실행(Auto Execute) 기능은 현재 비활성화되어 있습니다. 모든 조치는 담당자 승인 후 실행됩니다.
+
+## 지원 복구 조치 (Supported Actions)
+
+- `lambda_restart`: Lambda 함수 재시작
+- `rds_parameter`: RDS 파라미터 변경
+- `auto_scaling`: Auto Scaling 설정 조정
+- `eventbridge_event`: 이벤트 발행 (알림)
+- `investigate`: 추가 정보 수집 요청
+
+## Documentation
+
+### 시스템 문서
+- [Architecture Guide](docs/ARCHITECTURE.md) - 상세 시스템 아키텍처
+- [Prompt Templates](docs/PROMPTS.md) - AI 프롬프트 설계
+- [Cost Optimization](docs/COST_OPTIMIZATION.md) - 비용 최적화 전략
+- [Implementation Guide](docs/IMPLEMENTATION_GUIDE.md) - 단계별 구현 가이드
+
+### 에이전트별 문서
+- [HDSP Detection](docs/HDSP_DETECTION.md) - On-Prem K8s 장애 감지 (HDSP Agent)
+- [Cost Anomaly Detection](docs/COST_ANOMALY_DETECTION.md) - 비용 이상 탐지 (Cost Agent)
+- [Config Drift Detection](docs/CONFIG_DRIFT_DETECTION.md) - 설정 드리프트 감지 (Drift Agent)
+
+## Development
+
+### Running Tests
+
+```bash
+# Unit tests
+pytest tests/unit/
+
+# Integration tests
+pytest tests/integration/
+
+# All tests with coverage
+pytest --cov=src tests/
+```
+
+### Code Quality
+
+```bash
+# Linting
+ruff check src/
+
+# Type checking
+mypy src/
+
+# Formatting
+black src/
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.