Metadata-Version: 2.5
Name: ollama-advisor
Version: 0.1.0
Summary: Recommend, download, and run Ollama models based on your system specs and use case
Project-URL: Homepage, https://github.com/evanjung/ollama-advisor
Project-URL: Repository, https://github.com/evanjung/ollama-advisor
Author: evanjung
License-Expression: MIT
License-File: LICENSE
Keywords: gpu,llm,machine-learning,model-recommendation,ollama
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: ollama>=0.4.0
Requires-Dist: pandas>=2.0
Requires-Dist: psutil>=5.9
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# ollama-advisor

컴퓨터 사양(RAM, GPU VRAM)과 용도(코딩/추론/비전/임베딩/오디오/일반)를 기반으로, 현재 환경에서 실행 가능한 [Ollama](https://ollama.com) 모델을 추천하고 다운로드·실행·중지까지 지원하는 Python 라이브러리입니다.

Mac, Windows, Linux, Google Colab에서 동작합니다.

## 설치

```bash
pip install ollama-advisor
```

개발(로컬) 설치:

```bash
git clone https://github.com/evanjung/ollama-advisor.git
cd ollama-advisor
pip install -e ".[dev]"
```

## Quick Start

```python
import ollama_advisor as oa

oa.recommend()                       # 전체 추천 (DataFrame 반환)
oa.recommend(purpose="coding")       # 코딩용만 필터링
oa.pull_model("qwen2.5-coder:7b")    # 모델 다운로드
oa.run_model("qwen2.5-coder:7b", prompt="hello")  # 비대화식 실행
oa.stop_model("qwen2.5-coder:7b")    # 실행 중지
oa.list_installed()                  # 로컬에 설치된 모델 목록
```

CLI:

```bash
ollama-advisor recommend --purpose coding
ollama-advisor pull qwen2.5-coder:7b
ollama-advisor run qwen2.5-coder:7b --prompt "hello"
ollama-advisor stop qwen2.5-coder:7b
ollama-advisor list
ollama-advisor ps
ollama-advisor specs
```

## 전제 조건: Ollama 설치

`recommend()`와 `get_system_specs()`는 Ollama 없이도 동작합니다.  
`pull_model`, `run_model`, `stop_model`, `list_installed` 등은 **로컬 Ollama 서버**가 필요합니다.

- 다운로드: [https://ollama.com/download](https://ollama.com/download)
- macOS: `brew install ollama` 후 `ollama serve` (또는 앱 실행)
- Windows: 설치 프로그램 실행 후 트레이 앱 기동
- Linux: `curl -fsSL https://ollama.com/install.sh | sh`

Ollama가 꺼져 있으면 한국어 안내 메시지와 함께 `OllamaError`가 발생합니다.

## Google Colab 제약

Colab에서는 Ollama가 **공식적으로 백그라운드 서비스 지속 실행을 지원하지 않습니다**. 임시로 아래처럼 실행할 수 있지만, **런타임 종료 시 모델과 서버 상태가 초기화**됩니다.

```python
!curl -fsSL https://ollama.ai/install.sh | sh
!nohup ollama serve > ollama.log 2>&1 &
```

노트북/Colab에서는 `recommend()` 호출 시 스크롤 가능한 HTML 테이블이 자동으로 표시됩니다.

## 동작 방식

| 모듈 | 역할 |
|------|------|
| `system.py` | RAM/GPU/플랫폼 감지, usable 메모리(80%) 계산 |
| `catalog.py` | [ollama.com/library](https://ollama.com/library) 크롤링 + `~/.ollama_advisor_cache.json` 캐시 (TTL 6시간) |
| `purpose.py` | coding/reasoning/vision/embedding/audio/general 분류 |
| `core.py` | `recommend()` — 사양·카탈로그·용도 조합 |
| `ctl.py` | 공식 `ollama` Python 클라이언트 래핑 |

메모리 추정식(4bit 양자화 근사): `required_gb = billions × 0.6 + 1.0`

## 개발 & 테스트

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

CI(`test.yml`)는 Ubuntu / Windows / macOS × Python 3.9 / 3.11에서 실행되며, 네트워크 크롤링은 mock 처리합니다.

## PyPI 배포 (메인테이너용)

### 1. PyPI 프로젝트 등록

1. [pypi.org](https://pypi.org) 계정 생성
2. 프로젝트 이름 `ollama-advisor` 사용 가능 여부 확인 (이미 사용 중이면 `ollama-model-advisor` 등 대체)
3. 빈 프로젝트를 웹에서 미리 생성하거나, 첫 Trusted Publisher 배포 시 자동 생성될 수 있음

### 2. Trusted Publisher (OIDC) 연결

1. PyPI → Account settings → Publishing → Add a new pending publisher
2. 설정:
   - **PyPI project name**: `ollama-advisor`
   - **Owner**: GitHub 사용자/조직
   - **Repository name**: `ollama-advisor`
   - **Workflow name**: `publish.yml`
   - **Environment name**: `pypi` (GitHub repo Settings → Environments에서 `pypi` 환경 생성 권장)
3. GitHub 저장소 Settings → Environments → `pypi` → Deployment protection rules 설정(선택)

API 토큰 없이 `.github/workflows/publish.yml`의 `pypa/gh-action-pypi-publish`가 OIDC로 배포합니다.

### 3. 릴리스 발행

```bash
git tag v0.1.0
git push origin v0.1.0
```

GitHub Releases에서 태그 `v0.1.0`으로 Release를 **Publish**하면:

1. `publish.yml`이 `pytest` 게이트 실행
2. 통과 시 PyPI에 wheel/sdist 업로드

로컬 수동 배포(비권장, 디버깅용):

```bash
python -m build
twine upload dist/*
```

## 라이선스

MIT — [LICENSE](LICENSE)
