# PlanitAI KPI

AI가 당신의 KPI를 계획하고 분석합니다.

KPI 트리를 시각화하고, AI가 자동으로 병목을 분석하여 개선안을 제시하는 도구입니다.

## Features

- **KPI Tree Visualization**: 전사 KPI를 하나의 트리로 시각화
- **AI Analysis**: Gemini AI가 자동으로 트렌드와 병목 분석
- **Bottleneck Detection**: 목표 미달 KPI 자동 식별
- **Executive Summary**: 경영진 보고용 요약 자동 생성
- **HTML Reports**: 아름다운 HTML 보고서 출력

## Installation

```bash
# Clone repository
git clone https://github.com/planitai/planitai-kpi.git
cd planitai-kpi

# Install with pip
pip install -e .

# Or with poetry
poetry install
```

## Quick Start

### 1. Create Configuration

```bash
planitai-kpi init -o config.yaml
```

### 2. Set Environment Variables

```bash
export GEMINI_API_KEY="your-api-key"
```

### 3. Configure Google Sheets

1. Create a Google Cloud project
2. Enable Google Sheets API
3. Create a service account and download `credentials.json`
4. Share your Google Sheet with the service account email

### 4. Run Analysis

```bash
planitai-kpi analyze -c config.yaml -p "2024-11"
```

## Configuration

### config.yaml

```yaml
# Google Sheets Settings
sheet:
  sheet_id: "1ABC123xyz..."
  data_range: "Monthly Data!A1:Z100"
  target_range: "Targets!A1:Z100"  # Optional
  period_column: "period"

# Gemini API
gemini_api_key: "${GEMINI_API_KEY}"

# KPI Tree Definition
tree:
  - id: revenue
    name: 月間売上
    type: kgi
    formula: "{contracts} * {avg_price}"
    unit: 円
    category: finance
    children: [contracts, avg_price]

  - id: contracts
    name: 契約数
    type: kpi
    formula: "{meetings} * {close_rate}"
    unit: 件
    category: sales
    children: [meetings, close_rate]

  # ... more nodes
```

### Node Types

| Type | Description |
|------|-------------|
| `kgi` | Key Goal Indicator (top-level, usually one) |
| `kpi` | Key Performance Indicator (calculated) |
| `input` | Input values (leaf nodes) |

### Categories

- `finance` - 재무
- `sales` - 영업
- `marketing` - 마케팅
- `hr` - 인사
- `product` - 제품
- `customer` - 고객
- `operation` - 운영

## Commands

### analyze

Run KPI analysis and generate report.

```bash
planitai-kpi analyze -c config.yaml -p "2024-11" -o ./output
```

Options:
- `-c, --config`: Configuration file path
- `-p, --period`: Analysis period (required)
- `-o, --output`: Output directory
- `--skip-ai`: Skip AI analysis
- `--mock-data`: Use mock data JSON instead of Google Sheets

### validate

Validate configuration file.

```bash
planitai-kpi validate -c config.yaml
```

### tree

Display KPI tree structure.

```bash
planitai-kpi tree -c config.yaml
```

### init

Create example configuration file.

```bash
planitai-kpi init -o config.yaml
```

## Development

### Setup

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Format code
black src tests
ruff check src tests
```

### Project Structure

```
planitai-kpi/
├── src/
│   ├── __init__.py
│   ├── main.py              # CLI entry point
│   ├── config.py            # Configuration management
│   ├── sheets/
│   │   ├── __init__.py
│   │   └── client.py        # Google Sheets client
│   ├── kpi/
│   │   ├── __init__.py
│   │   ├── tree.py          # KPI tree structure
│   │   ├── calculator.py    # Calculation engine
│   │   └── analyzer.py      # Bottleneck analyzer
│   ├── ai/
│   │   ├── __init__.py
│   │   ├── client.py        # Gemini client
│   │   ├── prompts.py       # Prompt templates
│   │   └── analyzer.py      # AI analyzer
│   └── output/
│       ├── __init__.py
│       └── html.py          # HTML generator
├── templates/
│   └── report.html          # Report template
├── config/
│   ├── example.yaml         # Example config
│   └── mock_data.json       # Test data
├── tests/
│   ├── test_tree.py
│   └── test_calculator.py
├── pyproject.toml
└── README.md
```

## Example Output

The tool generates HTML reports like this:

```
📊 KPI Report - 2024年11月

KGI: 月間売上
├── 実績: ¥28,080,000
├── 目標: ¥32,000,000
└── 達成率: 87.8%

⚠️ Bottlenecks:
1. 成約率 - 達成率 72% (Impact: High)
2. 商談化率 - 達成率 87.5% (Impact: Medium)

🤖 AI Insights:
- 성약률이 전월 대비 10% 하락
- 신규 영업 담당자 온보딩 필요
- 상담 스크립트 개선 추천
```

## License

MIT License

## Author

PlanitAI - hello@planitai.co.jp