# 🏛️ Athena Vector CLI

> **Stop memorizing complex CLI flags. Let your local AI brain remember them for you.**

[![PyPI version](https://badge.fury.io/py/athena-vector-cli.svg)](https://badge.fury.io/py/athena-vector-cli)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Athena Vector CLI**는 자연어 명령어를 벡터 시스템으로 변환하여 실행하는 AI 기반 CLI 도구입니다. 복잡한 명령어를 외울 필요 없이, 자연어로 명령하면 AI가 기억하고 재사용합니다.

> **💡 Open Core 전략**: 우리는 투명합니다. 소스코드를 자유롭게 확인하고 검토하세요. 안전도 점수 계산 로직이 얼마나 정교한지 직접 확인해 보세요.

---

## 🎬 Demo

![Athena Vector CLI Demo](demo.gif)

**5초 데모**: `athena "undo last git commit"` → AI가 기억한 명령어를 자동으로 실행합니다.

---

## 🚀 Quick Start

### 설치

```bash
pip install athena-vector-cli
```

### 설정

#### 방법 1: 설정 파일 (권장)

설정 파일을 사용하면 환경 변수를 매번 설정할 필요가 없습니다.

**전역 설정** (`~/.athena/config.yaml`):
```yaml
qdrant:
  url: http://localhost:6333
  collection: command_vectors

search:
  similarity_threshold: 0.85
  max_results: 5

execution:
  confirm_by_default: true
  timeout: 30
```

**프로젝트별 설정** (`.athenarc`):
현재 디렉토리에 `.athenarc` 파일을 생성하면 프로젝트별로 다른 설정을 사용할 수 있습니다.

#### 방법 2: 환경 변수

```bash
# Qdrant 서버 URL 설정 (필수)
export VPS_QDRANT_URL="http://your-qdrant-server:6333"
# 또는
export QDRANT_URL="http://your-qdrant-server:6333"
```

**우선순위**: `.athenarc` > `~/.athena/config.yaml` > 환경 변수

### 첫 실행

```bash
# 도움말 확인
athena --help

# 자연어 명령어 실행
athena "서버 상태 보여줘"
athena "Git 저장소 상태 확인"
athena "Docker 컨테이너 목록"
```

---

## ✨ Key Features

### 🧠 **Local Vector DB**
- 데이터가 밖으로 나가지 않습니다 (Privacy First)
- 로컬 또는 자체 호스팅 Qdrant 서버 사용
- 모든 명령어는 벡터화되어 안전하게 저장됩니다

### 🔄 **Vector Command Reuse**
- 한 번 학습한 명령어는 자동으로 재사용
- 유사한 명령어를 자동으로 찾아서 실행
- 시간이 지날수록 더 똑똑해집니다

### 🛡️ **Iron Gate** (Coming Soon)
- 코드 품질 자동 검증
- 보안 취약점 자동 감지
- 배포 전 자동 테스트

### 🎯 **Natural Language Interface**
- 복잡한 CLI 플래그를 외울 필요 없음
- "undo last git commit" → `git reset HEAD~1` 자동 변환
- 한국어와 영어 모두 지원

### 📊 **Usage Tracking**
- 자주 사용하는 명령어 자동 추적
- 효율적인 명령어 우선순위 자동 조정

---

## 📖 사용 예시

### 기본 사용

```bash
# 자연어로 명령어 검색 (실행하지 않음)
athena "서버 상태 보여줘"

# 명령어 검색 및 실행 (실행 전 확인 프롬프트)
athena "undo last git commit" --execute

# 확인 없이 자동 실행
athena "undo last git commit" --yes

# 유사한 명령어 자동 검색 및 재사용
athena "Git 커밋 취소"
# → 이전에 학습한 "undo last git commit" 명령어 자동 검색
```

### 학습 모드

```bash
# 새로운 명령어 학습
athena "새로운 명령어"
# → 유사한 명령어가 없으면 학습 모드로 전환
# → DSL과 결과를 입력하여 저장
```

### 명령어 옵션

```bash
# 도움말
athena --help

# 버전 확인
athena --version
# Athena CLI v0.1.2

# 명령어 실행 (실행 전 확인)
athena "query" --execute

# 확인 없이 자동 실행
athena "query" --yes
```

### 안전 기능

Athena는 위험한 명령어를 자동으로 차단합니다:
- `rm -rf /` (시스템 삭제)
- `format` (포맷팅)
- `shutdown` (시스템 종료)
- 기타 위험한 패턴

차단된 명령어는 실행되지 않으며 경고 메시지가 표시됩니다.

---

## 🧠 Powered by Athena Brain Core

**Athena Vector CLI**는 **`athena-brain-core`** 엔진을 기반으로 구축되었습니다. 이는 단순한 쉘 스크립트 모음이 아닌, **견고한 모듈형 AI 아키텍처**입니다.

### Core Engine Features

- 🧠 **Long-term Memory**: 모든 명령어와 결과를 장기 기억으로 저장
- 🔄 **Self-Evolution**: 실수로부터 학습하고 자동으로 개선
- 👤 **Personalization**: 사용자별 명령어 패턴 학습
- 🔒 **Privacy-First**: 100% 로컬 저장, 데이터는 절대 외부로 전송되지 않음

### Architecture Benefits

- **모듈화**: Core 엔진과 CLI 인터페이스의 명확한 분리
- **확장성**: 다른 Athena 도구들과 동일한 Core 엔진 공유
- **일관성**: 모든 Athena 생태계가 동일한 메모리 시스템 사용

**Learn more**: [athena-brain-core on PyPI](https://pypi.org/project/athena-brain-core/)

---

## 🏗️ 아키텍처

```
┌─────────────────┐
│  자연어 명령어   │
│  "undo commit"  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  벡터 검색      │
│  (유사 명령어)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  명령어 재사용   │
│  또는 학습       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  실행 및 결과   │
└─────────────────┘
```

---

## 🔧 설정

### 설정 파일

**위치**:
- `~/.athena/config.yaml` (전역 설정)
- `.athenarc` (프로젝트별 설정, 우선순위 높음)

**설정 항목**:
```yaml
qdrant:
  url: http://localhost:6333        # Qdrant 서버 URL
  collection: command_vectors        # 컬렉션 이름
  timeout: 3.0                       # 타임아웃 (초)

model:
  name: snunlp/KR-SBERT-V40K-klueNLI-aug-sts  # 임베딩 모델

search:
  similarity_threshold: 0.85        # 유사도 임계값
  max_results: 5                     # 최대 결과 수

execution:
  confirm_by_default: true           # 기본적으로 확인 프롬프트 표시
  timeout: 30                         # 명령어 실행 타임아웃 (초)
```

### 환경 변수

| 변수 | 설명 | 필수 |
|------|------|------|
| `VPS_QDRANT_URL` | Qdrant 서버 URL | ✅ |
| `QDRANT_URL` | Qdrant 서버 URL (대체) | ✅ |
| `ATHENA_DEBUG` | 디버그 모드 (스택 트레이스 출력) | ❌ |

**우선순위**: `.athenarc` > `~/.athena/config.yaml` > 환경 변수

### Qdrant 서버 설정

**로컬 설치**:
```bash
docker run -p 6333:6333 qdrant/qdrant
```

**VPS 사용**:
```bash
export VPS_QDRANT_URL="http://your-vps-ip:6333"
```

---

## 📚 문서

- [설치 가이드](docs/INSTALL.md)
- [사용 가이드](docs/USAGE.md)
- [API 문서](docs/API.md)
- [문제 해결](docs/TROUBLESHOOTING.md)

---

## 🤝 기여하기

기여를 환영합니다! 이슈를 열거나 Pull Request를 보내주세요.

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

---

## 📝 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.

---

## 🙏 감사의 말

- [athena-brain-core](https://pypi.org/project/athena-brain-core/) - Core AI memory and evolution engine
- [Qdrant](https://qdrant.tech/) - 벡터 데이터베이스
- [Sentence Transformers](https://www.sbert.net/) - 임베딩 모델
- [MKM Lab](https://mkmlab.com/) - 프로젝트 후원

---

## 🔗 링크

- **PyPI**: https://pypi.org/project/athena-vector-cli/
- **GitHub**: https://github.com/mkmlab-hq/athena-vector-cli
- **문서**: https://athena-vector-cli.readthedocs.io/
- **이슈**: https://github.com/mkmlab-hq/athena-vector-cli/issues

---

## ⭐ Star History

[![Star History Chart](https://api.star-history.com/svg?repos=mkmlab-hq/athena-vector-cli&type=Date)](https://star-history.com/#mkmlab-hq/athena-vector-cli&Date)

---

**Made with ❤️ by [MKM Lab](https://mkmlab.com/)**
