mim-cli 0.1.0__tar.gz

mim_cli-0.1.0/.env.sample

@@ -0,0 +1,65 @@
+# mim-cli 환경변수 샘플. 이 파일을 `.env`로 복사 후 값을 채워 사용하세요.
+#   cp .env.sample .env
+
+# ────────────────────────────────────────────────────────────
+# 저장소 경로 (선택)
+# ────────────────────────────────────────────────────────────
+# 기본: ~/.mim-cli
+# MIM_CLI_DIR=/path/to/storage
+
+# ────────────────────────────────────────────────────────────
+# CLI 동작 기본값 (선택)
+# ────────────────────────────────────────────────────────────
+# MIM_CLI_PRETTY=1            # 사람용 Rich 출력 기본 활성화 (기본은 JSON)
+# MIM_CLI_TIMEOUT=120         # HTTP 타임아웃 (초)
+# MIM_CLI_ASSUME_YES=1        # 확인 프롬프트 자동 승인
+
+# ────────────────────────────────────────────────────────────
+# 생성 프로바이더 (이미지 생성 API)
+# ────────────────────────────────────────────────────────────
+
+# Google Gemini — 쉼표로 여러 키 지정 가능 (429 시 자동 다음 키로 전환)
+# 발급: https://aistudio.google.com/apikey
+GEMINI_API_KEYS=
+
+# Replicate — FLUX, SD 3.5, Ideogram, Imagen 등 16종 모델 지원
+# 발급: https://replicate.com/account/api-tokens
+# (결제 수단 등록 필수 — 무료 크레딧도 카드 등록 후 사용 가능)
+REPLICATE_API_TOKEN=
+
+# Leonardo.ai — Phoenix, FLUX, Anime XL 등 10종 모델. 무료 150 토큰/일
+# 발급: https://app.leonardo.ai/settings
+LEONARDO_API_KEY=
+
+# ────────────────────────────────────────────────────────────
+# 가져오기 프로바이더 (온라인 무료 미디어 API)
+# ────────────────────────────────────────────────────────────
+
+# Giphy — GIF 밈의 핵심 소스. 개발자 키 하루 100회 무료
+# 발급: https://developers.giphy.com/dashboard/
+GIPHY_API_KEY=
+
+# Unsplash — 고품질 사진. 데모 앱 시간당 50회 무료
+# 발급: https://unsplash.com/developers
+UNSPLASH_ACCESS_KEY=
+
+# Pexels — 사진/비디오. 월 20,000회 무료
+# 발급: https://www.pexels.com/api/new/
+PEXELS_API_KEY=
+
+# Pixabay — 사진/일러스트/벡터/비디오. 시간당 100회 무료
+# 발급: https://pixabay.com/api/docs/  (계정 생성 후 문서 페이지에서 키 확인)
+PIXABAY_API_KEY=
+
+# Openverse — CC 라이선스 이미지. API 키 불필요 (환경변수 없음)
+#   mim fetch "cute cat" -p openverse
+
+# Reddit — 밈 밀집도 최고. 기본 무인증 동작 (분당 10회). OAuth는 선택.
+#   mim fetch "surprised pikachu" -p reddit --subreddit memes
+# OAuth 자격증명 (선택, 분당 100회로 상승):
+#   1) https://www.reddit.com/prefs/apps 에서 "create another app"
+#   2) script 타입 선택 → client_id + secret 발급
+# REDDIT_CLIENT_ID=
+# REDDIT_CLIENT_SECRET=
+# REDDIT_USER_AGENT=my-app/0.1 (by /u/yourname)     # 권장: 고유한 UA
+# REDDIT_DEFAULT_SUBREDDIT=memes                    # --subreddit 기본값

mim_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  build-and-publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mim-cli
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Verify tag matches project version
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          PROJECT_VERSION=$(python -c "import tomllib,sys; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$PROJECT_VERSION" ]; then
+            echo "::error::Tag ($TAG) does not match pyproject.toml version ($PROJECT_VERSION)"
+            exit 1
+          fi
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mim_cli-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# 환경변수 (민감 정보)
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+*.egg-info/
+dist/
+build/
+
+# uv
+.uv/
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# 프로젝트 로컬
+downloads/
+scripts/
+.claude/
+*.pyc

mim_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Run
+
+```bash
+uv sync                    # 의존성 설치
+uv run mim --help         # CLI 실행
+pytest tests/              # 전체 테스트
+pytest tests/test_store.py # 단일 파일 테스트
+pytest tests/test_store.py::test_save_and_get -v  # 단일 테스트
+```
+
+## Architecture
+
+밈 미디어 관리 CLI. Typer + Rich 기반. **AI-first 설계** — 기본 출력이 **JSON** (stdout), 진행/에러는 stderr. 사람이 직접 쓸 때는 `--pretty` 플래그로 Rich UI 활성화.
+
+**AI 사용 규칙:**
+- **이미지 생성**: 전용 프로바이더 API (Gemini / Leonardo / Replicate)
+- **그 외 모든 AI 작업 (이미지 분석, 메타데이터 추출 등)**: `claude --print` subprocess만 사용 (`ai.py:MetadataGenerator`)
+
+**3가지 미디어 입수 경로 → 단일 저장 흐름:**
+1. **`add <file>`** (수동 업로드) — 로컬 파일 복사 → 해시 중복 체크 → `saver.save_media(source="upload")`
+2. **`generate <prompt>`** (AI 생성) — 프로바이더 API 호출 → `saver.save_media(source="generated", prompt=..., model=...)`
+3. **`fetch <query> -p <provider>`** (온라인 무료 API) — 검색 → 다운로드 → 중복 체크 → `saver.save_media(source="fetched", source_url=..., source_id=..., prompt=<query>, attribution=..., license=...)`
+
+**중복 감지 (자동):**
+- 1차: `(source_provider, source_id)` 인덱스 조회 — 온라인 API 재호출 시 빠른 스킵
+- 2차: `content_hash` (SHA256) 조회 — 같은 바이트면 provider가 달라도 스킵
+- 중복 시 기존 아이템 반환 + `{"skipped": true, "existing_id": "..."}`
+- `add --force`로 해시 중복 우회 가능
+
+**데이터 흐름:**
+- **Search**: FTS5 trigram 매칭 (3자 미만은 LIKE 폴백) 또는 `--semantic` 플래그로 벡터 유사도 검색. `--source upload|generated|fetched`, `--from-provider <name>` 필터
+- **Generate**: 프롬프트 → Provider API → PNG 저장 → (옵션) `saver.save_media`. `--no-save`로 DB 스킵, `--skip-metadata`로 AI 분석 스킵
+- **Fetch**: 쿼리 → 프로바이더 search API → 이미지 바이트 다운로드 → `saver.save_media` (중복 스킵)
+
+**핵심 모듈:**
+- `store.py` — SQLite CRUD + FTS5 전문검색. `PRAGMA user_version` 기반 선형 마이그레이션 프레임워크 (`MIGRATIONS` 리스트). `find_by_source`, `find_by_hash`로 중복 판별. `get_many()`는 999개 변수 제한 우회를 위해 청크 처리
+- `embeddings.py` — ChromaDB + BAAI/bge-m3 (lazy load). 테스트에서는 mock 처리
+- `ai.py` — **유일한 non-생성 AI 경로**. `claude --print` subprocess로 이미지 분석 후 JSON 메타데이터 파싱
+- `output.py` — 글로벌 `--pretty`/`--timeout`/`--yes` 상태 관리, 시크릿 마스킹 (`AIzaSy*`, `r8_*`, UUID, Bearer), 구조화 에러 분류 (`rate_limited`, `payment_required`, `unauthorized`, `not_found`, `timeout`, `request_failed`), stdout/stderr 분리
+- `saver.py` — **3가지 저장 진입점의 통합 흐름**. `save_media(data, suffix, media_type, source, ...)` → `(MediaItem, is_new)`. tempfile → 해시 → 중복 체크 → AI 메타(claude --print, 부분 override 지원) → store.save + embedding upsert
+- `providers/` — 두 종류 ABC:
+  - `ImageProvider` (생성): Gemini/Leonardo/Replicate. `generate()`, `balance()`, `list_models()`
+  - `FetchProvider` (온라인 API): `providers/fetch/` 서브패키지. `search(query, limit, media_type) → list[FetchedMedia]`
+- `cli.py` — 두 레지스트리 분리: `GEN_PROVIDERS`, `FETCH_PROVIDERS`. `_build_gen_provider` / `_build_fetch_provider` 분기
+
+**저장소 구조** (`~/.mim-cli/`, `MIM_CLI_DIR` 환경변수로 오버라이드):
+- `memes.db` — SQLite (media_items + FTS5 가상 테이블). `PRAGMA user_version` 현재 버전 1
+- `media/` — 원본/가져온/생성된 미디어 파일 (UUID 파일명, 확장자는 mime에서 추론)
+- `chroma/` — ChromaDB 벡터 저장소
+
+**MediaItem 스키마 (v1):**
+- 기본: `id`, `path`, `media_type`, `name`, `description`, `tags`, `emotions`, `context`, `created_at`, `updated_at`
+- 출처/계보: `source` (upload|generated|fetched), `source_provider`, `source_url`, `source_id`, `prompt`, `model`, `content_hash`, `attribution`, `license`, `license_url`, `width`, `height`
+- `from_dict()`는 **unknown-field 필터** — DB에 향후 새 컬럼 생겨도 역직렬화 안 깨짐
+
+## 글로벌 옵션 (서브커맨드 앞에 배치)
+
+- `--pretty` — 사람용 Rich 출력 (환경변수 `MIM_CLI_PRETTY`). 미지정 시 JSON (AI 친화 기본)
+- `--timeout N` — HTTP 타임아웃 초 (환경변수 `MIM_CLI_TIMEOUT`)
+- `--yes`/`-y` — 확인 프롬프트 자동 승인 (환경변수 `MIM_CLI_ASSUME_YES`)
+
+## 환경변수
+
+- `MIM_CLI_DIR` — 저장소 루트 경로 (기본: `~/.mim-cli`)
+- **생성 프로바이더:**
+  - `GEMINI_API_KEYS` — Gemini (쉼표로 여러 키 구분, 429 시 자동 전환)
+  - `REPLICATE_API_TOKEN` (또는 `REPLICATE_API_KEY`) — Replicate
+  - `LEONARDO_API_KEY` — Leonardo.ai
+- **가져오기 프로바이더:**
+  - `GIPHY_API_KEY` — https://developers.giphy.com/dashboard/
+  - `UNSPLASH_ACCESS_KEY` — https://unsplash.com/developers
+  - `PEXELS_API_KEY` — https://www.pexels.com/api/new/
+  - `PIXABAY_API_KEY` — https://pixabay.com/api/docs/
+  - Openverse는 키 불필요
+  - Reddit은 기본 무인증 (분당 10회). 선택: `REDDIT_CLIENT_ID`/`REDDIT_CLIENT_SECRET` (OAuth, 분당 100회), `REDDIT_USER_AGENT` (권장), `REDDIT_DEFAULT_SUBREDDIT`
+
+## 테스트 패턴
+
+- `conftest.py`의 `tmp_store_dir` fixture로 테스트별 격리된 DB/미디어 디렉토리 생성
+- EmbeddingStore는 모델 로딩이 느리므로 테스트에서 mock 처리
+- **Fetch 프로바이더**: `respx` + `httpx.MockTransport`로 네트워크 mock (실제 API 호출 없음)
+- **MetadataGenerator** (claude --print): 테스트에서 `@patch("mim_cli.saver.MetadataGenerator")` 로 mock
+- 한국어 메타데이터 (이름, 태그, 감정, 맥락)

mim_cli-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: mim-cli
+Version: 0.1.0
+Summary: 밈 미디어 관리 및 검색 CLI
+Requires-Python: >=3.11
+Requires-Dist: chromadb>=0.5
+Requires-Dist: google-genai>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pytest>=9.0.3
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: respx>=0.21
+Requires-Dist: rich>=13
+Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: typer>=0.12

mim_cli-0.1.0/README.md

@@ -0,0 +1,175 @@
+# mim-cli
+
+> **AI 에이전트를 위한 밈 미디어 관리 CLI.**
+> 기본 출력이 **JSON (stdout)**, 진행/에러는 stderr로 분리 — AI가 파싱하기 쉬운 형태로 설계됨. 사람이 직접 쓸 때는 `--pretty` 플래그로 Rich UI.
+
+MCP 서버를 띄울 필요 없이, Claude Code·Cursor·Codex 같은 코딩 에이전트가 셸을 통해 바로 호출할 수 있는 밈 저장소. 한 번의 `mim fetch`로 온라인에서 밈을 가져오고, `mim search`로 의미 기반 검색까지 한 번에 된다.
+
+---
+
+## AI-first 설계 규칙
+
+- **기본은 JSON**. 터미널 예쁨은 opt-in (`--pretty`).
+- **stdout은 결과만**, 진행/경고/에러는 **stderr**. 파이프 체이닝 안전.
+- **구조화된 에러 분류**: `rate_limited` / `payment_required` / `unauthorized` / `not_found` / `timeout` / `request_failed` — 에이전트가 코드로 분기 가능.
+- **시크릿 자동 마스킹**: API 키, UUID, Bearer 토큰은 출력에서 가려짐.
+- **중복 감지 자동**: `(provider, source_id)` + SHA256 콘텐츠 해시. 재호출 시 API 낭비 없음.
+- **이미지 생성만 전용 API**, 나머지 AI 작업(이미지 분석, 메타데이터 추출)은 `claude --print` subprocess로 위임.
+
+---
+
+## 설치
+
+```bash
+uv sync
+cp .env.sample .env   # API 키 채우기 (선택)
+uv run mim --help
+```
+
+Python 3.11+ 필요. `uv tool install .` 하면 `mim` 명령이 전역으로 설치된다.
+
+---
+
+## 세 가지 미디어 입수 경로
+
+모두 **동일한 저장 흐름** (해시 중복 체크 → AI 메타 추출 → DB + 벡터 upsert) 을 통과한다.
+
+### 1. `add` — 로컬 파일 업로드
+
+```bash
+mim add ./pepe.png
+mim add ./pepe.png --name "페페" --tags "frog,sad" --force
+```
+
+### 2. `generate` — AI로 이미지 생성
+
+```bash
+mim generate "수학 풀다 지친 강아지" -p gemini
+mim generate "surprised pikachu" -p replicate --model flux-dev --no-save
+```
+
+지원 프로바이더: `gemini`, `replicate`, `leonardo`.
+
+### 3. `fetch` — 온라인 무료 API에서 가져오기
+
+```bash
+mim fetch "surprised pikachu" -p giphy --limit 5
+mim fetch "cute cat"          -p openverse     # API 키 불필요
+mim fetch "happy dog"         -p reddit --subreddit aww
+```
+
+지원 프로바이더: `giphy`, `unsplash`, `pexels`, `pixabay`, `openverse`, `reddit`.
+
+---
+
+## 검색
+
+```bash
+mim search "페페"                           # FTS5 trigram (키워드)
+mim search "슬픈 개구리" --semantic         # bge-m3 벡터 유사도
+mim search "cat" --source fetched --from-provider giphy
+```
+
+- 3자 이상은 trigram FTS5, 미만은 LIKE 폴백.
+- `--semantic`은 ChromaDB + `BAAI/bge-m3` 임베딩 (최초 1회 모델 다운로드).
+
+---
+
+## 글로벌 옵션
+
+| 플래그 | 환경변수 | 설명 |
+|---|---|---|
+| `--pretty` | `MIM_CLI_PRETTY` | 사람용 Rich 출력 활성화 |
+| `--timeout N` | `MIM_CLI_TIMEOUT` | HTTP 타임아웃 (초, 기본 120) |
+| `--yes` / `-y` | `MIM_CLI_ASSUME_YES` | 확인 프롬프트 자동 승인 |
+| — | `MIM_CLI_DIR` | 저장소 루트 (기본 `~/.mim-cli`) |
+
+글로벌 옵션은 **서브커맨드 앞에** 둔다: `mim --pretty search "pepe"`.
+
+---
+
+## 전체 커맨드
+
+| 커맨드 | 설명 |
+|---|---|
+| `add <file>` | 로컬 파일 업로드 + AI 메타 자동 생성 |
+| `generate <prompt>` | AI 이미지 생성 (자동 저장, `--no-save`로 스킵) |
+| `fetch <query> -p <provider>` | 온라인 API에서 검색·다운로드·저장 |
+| `search <query>` | 키워드/시맨틱 검색 |
+| `list` | 전체 목록 |
+| `get <id>` | 상세 조회 |
+| `edit <id>` | 메타데이터 수정 (AI 재분석도 가능) |
+| `remove <id>` | 삭제 |
+| `balance -p <provider>` | 생성 프로바이더 크레딧 조회 |
+| `providers` | 등록된 프로바이더 + 인증 상태 |
+| `models -p <provider>` | 지원 모델 별명 |
+| `info` | 저장소 경로·상태 덤프 |
+
+---
+
+## 환경변수
+
+### 생성 프로바이더
+
+| 키 | 용도 |
+|---|---|
+| `GEMINI_API_KEYS` | Gemini (쉼표 여러 키, 429 시 자동 전환) |
+| `REPLICATE_API_TOKEN` | Replicate (FLUX / SD / Imagen 등) |
+| `LEONARDO_API_KEY` | Leonardo.ai (Phoenix / FLUX 등) |
+
+### 가져오기 프로바이더
+
+| 키 | 용도 |
+|---|---|
+| `GIPHY_API_KEY` | Giphy (GIF 밈 핵심 소스) |
+| `UNSPLASH_ACCESS_KEY` | Unsplash (고품질 사진) |
+| `PEXELS_API_KEY` | Pexels (사진/비디오) |
+| `PIXABAY_API_KEY` | Pixabay (사진/일러스트/벡터/비디오) |
+| — | Openverse는 키 불필요 |
+| `REDDIT_CLIENT_ID` / `REDDIT_CLIENT_SECRET` | Reddit OAuth (선택, 분당 100회). 없으면 무인증 10회/분 |
+| `REDDIT_USER_AGENT` / `REDDIT_DEFAULT_SUBREDDIT` | Reddit 추가 설정 (선택) |
+
+`.env` 파일은 자동 로드된다 (python-dotenv).
+
+---
+
+## 저장소 구조
+
+```
+~/.mim-cli/
+├── memes.db    # SQLite + FTS5 (PRAGMA user_version으로 마이그레이션)
+├── media/      # 원본 바이너리 (UUID 파일명)
+└── chroma/     # 벡터 임베딩 (bge-m3)
+```
+
+`MIM_CLI_DIR`로 경로 오버라이드 가능.
+
+---
+
+## 아키텍처 한눈에
+
+```
+┌─ add ────┐
+├─ generate┼─► saver.save_media() ──► hash dedup ──► AI 메타 ──► store.save + embedding upsert
+└─ fetch ──┘                                       (claude --print)
+```
+
+- `store.py` — SQLite + FTS5, `PRAGMA user_version` 기반 선형 마이그레이션
+- `embeddings.py` — ChromaDB + bge-m3 (lazy load)
+- `saver.py` — 3가지 입수 경로의 단일 통합 진입점
+- `ai.py` — 비-생성 AI의 유일한 경로 (`claude --print` subprocess)
+- `output.py` — `--pretty` 라우팅, 시크릿 마스킹, 에러 분류
+- `providers/` — 생성 (`ImageProvider`) / 가져오기 (`FetchProvider`) ABC 두 종
+
+---
+
+## 개발
+
+```bash
+pytest tests/                                      # 전체 테스트
+pytest tests/test_store.py::test_save_and_get -v   # 단일 테스트
+```
+
+테스트는 `conftest.py:tmp_store_dir` fixture로 DB/미디어 디렉토리 격리. EmbeddingStore와 `claude --print`는 mock 처리. Fetch 프로바이더는 `respx` + `httpx.MockTransport`로 네트워크 없이 검증.
+
+자세한 내부 규칙과 컨벤션은 [`CLAUDE.md`](./CLAUDE.md) 참고.