Metadata-Version: 2.4
Name: maru-deep-pro-search
Version: 0.29.0
Summary: Universal AI search MCP server — Perplexity-level quality with zero API keys. Multi-engine web scraping, intelligent ranking, and citation-native answers.
Author-email: claudianus <claudianus@engineer.com>
License-Expression: MIT
Project-URL: Homepage, https://claudianus.github.io/maru-deep-pro-search/
Project-URL: Documentation, https://claudianus.github.io/maru-deep-pro-search/
Project-URL: Repository, https://github.com/claudianus/maru-deep-pro-search
Project-URL: Issues, https://github.com/claudianus/maru-deep-pro-search/issues
Keywords: mcp,model-context-protocol,web-search,deep-research,perplexity,ai-search,scraping,llm-tools,trafilatura,citations,cursor,claude,agent,coding-assistant,semantic-search,bm25
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: htmldate>=1.9.4
Requires-Dist: huggingface-hub>=0.20.0
Requires-Dist: llama-cpp-python>=0.3.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: pygments>=2.20.0
Requires-Dist: scrapling[fetchers]>=0.2.99
Requires-Dist: trafilatura>=2.0.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: urllib3>=2.7.0
Provides-Extra: semantic
Provides-Extra: stealth
Requires-Dist: cloakbrowser>=0.1.0; extra == "stealth"
Provides-Extra: gpu
Requires-Dist: llama-cpp-python>=0.3.0; platform_system != "Darwin" and extra == "gpu"
Provides-Extra: metal
Requires-Dist: llama-cpp-python>=0.3.0; platform_system == "Darwin" and extra == "metal"
Dynamic: license-file

# maru-deep-pro-search

<div align="center">

**AI 에이전트를 위한 evidence-grade agent research infrastructure — 멀티 엔진 검색, 증거 원장, provider doctor JSON**

[🇺🇸 English](./README.en.md)

[![Version](https://img.shields.io/badge/version-v0.29.0-6C5CE7?style=flat-square&logo=github)](https://github.com/claudianus/maru-deep-pro-search)
[![PyPI](https://img.shields.io/pypi/v/maru-deep-pro-search?style=flat-square&color=2D98DA)](https://pypi.org/project/maru-deep-pro-search/)
[![Python](https://img.shields.io/pypi/pyversions/maru-deep-pro-search?style=flat-square&color=00B894)](https://pypi.org/project/maru-deep-pro-search/)
[![License](https://img.shields.io/badge/license-MIT-00B894?style=flat-square)](https://github.com/claudianus/maru-deep-pro-search/blob/main/LICENSE)
[![CI](https://github.com/claudianus/maru-deep-pro-search/actions/workflows/validate.yml/badge.svg)](https://github.com/claudianus/maru-deep-pro-search/actions/workflows/validate.yml)

[🌐 웹사이트](https://claudianus.github.io/maru-deep-pro-search/) · [📦 PyPI](https://pypi.org/project/maru-deep-pro-search/) · [💻 GitHub](https://github.com/claudianus/maru-deep-pro-search)

</div>

---

## 🚀 주요 기능

| 기능 | 설명 |
|:---:|:---|
| 🧠 **내장 경량 LLM 리파이너** | `llama-cpp-python` 기반 Qwen3.5(0.8B~4B)가 웹 콘텐츠를 자동 정제. 호스트 LLM 토큰 **83% 절약**. SHA-256 무결성 검증 + 손상 모델 자동 복구 |
| 🔍 **하이브리드 멀티 엔진 검색** | DuckDuckGo, Bing 등 **9개 엔진** + 자동 페일오버. RetrievalHints 기반 검색 범위 힌트, RRF + BM25 + authority 랭킹 |
| 📄 **trafilatura 정밀 추출** | HTML→Markdown 변환에 trafilatura 사용. 헤딩·코드 블록·리스트 구조 보존, `_evidence` 메타데이터와 CSS 폴백 내장 |
| 📊 **시맨틱 재랭킹** | 로컬 `ibm-granite/granite-embedding-97m-multilingual-r2` 임베딩 모델로 정교한 문서 순위 재조정 |
| 🛡️ **인용 파이프라인** | 모든 정보에 `[N]` 출처 태그를 안정적으로 매핑. 환각 최소화 |
| 🧾 **증거 등급 인프라** | `metadata-only` evidence ledger, `get_evidence`, `list_evidence_runs`, provider doctor JSON, policy-aware stealth 라우팅으로 조사 근거를 보존 |
| 🔗 **34개 에이전트 지원** | Cursor, Claude Code, Cline, Aider, Codex, OpenCode, Kimi 등 주요 AI 개발 도구 전격 대응 |
| 🦊 **정책 인지 브라우저 라우팅** | 기본은 일반 fetch와 Playwright 폴백. 차단 신호가 있을 때만 예산·정책·로봇 설정을 확인한 뒤 policy-aware stealth로 명시적 상승 |
| ⚡ **완전 무료** | 상용 검색 API 키 없이 **$0**로 모든 기능 사용 |

> **💡 Host-led evidence substrate**: 호스트 에이전트가 질의 분해, 도구 순서, 충분성 판단, 최종 종합을 직접 담당합니다. MCP는 `search`, `fetch`, `fetch_bulk`, `verify`로 검색 결과, 본문 증거, 메타데이터, 보안 경계를 안정적으로 제공합니다.
> **🧾 Evidence-grade agent research infrastructure**: 경쟁 포지셔닝과 런타임 주장은 [competitive source ledger](.omo/evidence/competitive-source-ledger.md)와 [competitive moat benchmark](.omo/evidence/competitive-moat/summary.md)에서 확인한 항목만 공개 문서에 싣습니다.

---

## 🛠️ 핵심 도구 (MCP Tools)

### Core Research Pipeline — 4종

| 도구 | 역할 | 파이프라인 |
|:---|:---|:---|
| `search` | 웹 검색 + 랭킹 | RetrievalHints → 엔진 선택 → 병렬 검색 → CandidateResult 정화 → BM25/RRF/Authority → Granite 97M 재랭킹 |
| `fetch` | 단일 URL 본문 수집·정제 | HTTP GET → trafilatura Markdown 추출 → Qwen3.5 Refiner → EvidencePacket metadata |
| `fetch_bulk` | 다중 URL 병렬 fetch | Semaphore 동시성 제어 + query 기반 relevance filter + EvidencePacket metadata |
| `verify` | 증거 정렬·충돌 신호 | 주장 추출 → supporting/contradicting sources → conflict_count → overall_consensus 호환 마커 |

### Evidence & Diagnostics — 2종

| 도구 | 역할 | 증거 계약 |
|:---|:---|:---|
| `get_evidence` | 마지막 또는 지정 run의 metadata-only evidence ledger 조회 | raw HTML/body 없이 `run_id`, `sources`, `warnings`, `access_risk` 반환 |
| `list_evidence_runs` | 최근 evidence run 목록 조회 | 기본 20개 이내, provider doctor JSON과 함께 진단 가능 |

### `search` 3단계 모드

| 모드 | 엔진 수 | 재랭킹 | 리파이너 | 용도 |
|:---|:---:|:---:|:---:|:---|
| `fast` | 1 | — | — | 빠른 조회 (API 시그니처, 단순 팩트체크) |
| `balanced` | 2 | Granite 97M | — | 기본 (버전 체크, 중간 복잡도) |
| `deep` | 3+ | Granite 97M | — | CVE 조사, 아키텍처, 보안 |

`deep` 출력은 `## Research:`, `_engines:`, `### Sources`, `_score:` 계약을 유지하면서 BM25, metadata, RRF, semantic, final score와 간단한 ranking reason을 `_ranking:` 줄에 함께 표시합니다. `fast`/`balanced`는 `Search:`와 번호 결과 형식을 유지합니다.

Qwen3 reranker, BGE-M3, ColBERT/SPLATE 계열 late interaction은 기본 품질 경로가 아니라 **disabled-by-default optional adapter**입니다. 고정 30-query corpus에서 품질 개선과 p95 latency 비회귀를 증명하기 전에는 core dependency나 기본 실행 경로로 올리지 않습니다.

### v0.28.0 Host Delegation + 품질 게이트

- 고정 30-query live corpus로 Precision@5, NDCG@10, MRR, forbidden-domain rate, zero-relevance-visible rate, sanitizer leak rate, p50/p95 latency를 함께 측정합니다.
- benchmark/evaluation/paper/model-card/docs/spec, MCP tool annotations/structured output, latest-version, migration/tutorial, 한국어 소비자 질의, CVE/version/API 질의는 broad expansion과 자동 follow-up retry를 끄고 원 질의를 보존합니다.
- `fetch`/`fetch_bulk`는 기존 `EXTERNAL CONTENT` 보안 경계를 유지하면서 `_evidence:` 줄로 source type, extraction quality/method, access risk, taint status, fragments, citations를 노출합니다.

### 호스트 주도 툴 체인 예시

```
복합 질의: 호스트가 관점/키워드 선택 → search × N → fetch_bulk(선택 URL) → verify(필요 시) → 종합
단순 조회: search(fast) → 호스트 답변
보안 이슈: search(deep) → fetch_bulk(공식/권위 출처) → verify(증거 충돌 확인) → 코드 판단
비교 분석: 호스트가 비교 축 선택 → search × N(+fetch) → verify(증거 정렬 확인) → 종합
```

### 내부 안전장치

| 레이어 | 메커니즘 |
|:---|:---|
| `_with_validation` | 입력 검증 (쿼리 길이, URL scheme, SSRF 가드) |
| `_with_audit` | 모든 호출 → SQLite 감사 로그 |
| `CircuitBreaker` | 엔진별 3연속 실패 → 60초 OPEN |
| `RateLimiter` | 엔진별 슬라이딩 윈도우 (10req/60s) |
| `Semaphore(4)` | 전체 동시 검색 상한 |
| 프롬프트 인젝션 방어 | Zero-width 제거, Chat token 중화 |

### Utility — 3종

| 도구 | 역할 |
|:---|:---|
| `version` | 현재 maru-deep-pro-search 버전 반환 |
| `list_engines` | 등록된 9개 엔진 메타데이터 (quality tier, reliability %, latency) |
| `engine_health` | 실시간 서킷 브레이커 상태 (CLOSED/OPEN/HALF-OPEN, failure count) |

- 🤖 **지원 에이전트 목록**: [웹사이트 에이전트 목록](https://claudianus.github.io/maru-deep-pro-search/#agents)

---

## 🧾 Evidence-Grade 경쟁 근거

Maru의 공개 경쟁 주장은 “더 좋다”는 감상이 아니라 측정 가능한 근거에 묶습니다. 아래 표의 모든 행은 [competitive source ledger](.omo/evidence/competitive-source-ledger.md) 또는 [competitive moat benchmark](.omo/evidence/competitive-moat/summary.md)에 연결됩니다.

| 검증 축 | 근거 | Maru의 측정된 응답 |
|:---|:---|:---|
| 차단 출처 투명성 | [ledger D-03~D-05](.omo/evidence/competitive-source-ledger.md), [benchmark `blocked_source_transparency`](.omo/evidence/competitive-moat/summary.md) | 일반 fetch 우선, bot-wall metadata, policy-aware stealth 결정, `get_evidence`/`list_evidence_runs`로 확인 가능한 run 기록 |
| provider doctor UX | [ledger A-03~A-05](.omo/evidence/competitive-source-ledger.md), [benchmark `provider_doctor_status`](.omo/evidence/competitive-moat/summary.md) | `maru-deep-pro-search-setup setup --check --json`가 provider doctor JSON, browser 상태, evidence 경로, repair hint를 출력 |
| durable evidence | [ledger D-05~D-06](.omo/evidence/competitive-source-ledger.md), [benchmark `evidence_retrieval`](.omo/evidence/competitive-moat/summary.md) | `metadata-only` evidence ledger가 URL, 접근 위험, 추출 품질, 경고, citation metadata만 저장하고 본문·쿠키·토큰은 저장하지 않음 |
| optional browser packaging | [ledger C-02~C-04](.omo/evidence/competitive-source-ledger.md), [packaging decision](.omo/evidence/cloakbrowser-packaging-decision.md) | CloakBrowser는 core dependency가 아니라 `maru-deep-pro-search[stealth]` extra이며 wheel/Docker/package data에 binary를 벤더링하지 않음 |

---

## 📦 설치 및 설정

### 빠른 설치

**macOS / Linux:**
```bash
curl -sSL https://raw.githubusercontent.com/claudianus/maru-deep-pro-search/main/scripts/install.sh | bash
```

**Windows:**
```powershell
irm https://raw.githubusercontent.com/claudianus/maru-deep-pro-search/main/scripts/install.ps1 | iex
```

**Pip / Hatch:**
```bash
pip install --user maru-deep-pro-search
# 선택 사항: CAPTCHA·차단 페이지가 많은 환경에서 스텔스 브라우저 지원을 명시적으로 설치
pip install --user "maru-deep-pro-search[stealth]"
maru-deep-pro-search-setup browsers --check
maru-deep-pro-search-setup setup --check --json
maru-deep-pro-search-setup setup
```

**uv:**
```bash
uv tool install --python 3.12 maru-deep-pro-search
```

> [!NOTE]
> 설치 스크립트가 시스템 하드웨어를 자동 감지하고 최적의 Qwen3.5 모델(0.8B~4B)을 다운로드합니다. GPU(CUDA/Metal)가 있으면 가속 wheel을 자동 설치합니다.

> [!NOTE]
> Granite 97M 가중치 파일(Hugging Face)은 첫 실행 시 다운로드됩니다. 콜드스타트 지연을 방지하려면 사전에 실행하세요:
>
> ```bash
> maru-deep-pro-search-setup warmup-embeddings -q
> maru-deep-pro-search-setup setup --check
> maru-deep-pro-search-setup setup --check --json
> ```

### 에이전트 설정

설치 후 에이전트(예: Cursor)를 **완전히 종료 후 재시작**하세요.

**Claude Code** (`~/.claude/settings.json`):
```json
{
  "mcpServers": {
    "maru-deep-pro-search": {
      "command": "python3",
      "args": ["-m", "maru_deep_pro_search.server"]
    }
  }
}
```

---

## 🎯 사용 방법

에이전트 시스템 프롬프트(User Rules) 또는 첫 대화에 아래 지침을 지정하여 검색 활용 방식을 권장할 수 있습니다:

- `"코드 작성 전에 반드시 웹 검색을 수행하여 최신 명세를 확인하고 [1], [2] 형식으로 명확한 출처를 표기해줘."`
- `"Next.js 15 App Router의 Server Action revalidate 에러 관련 최신 해결 방법을 검색해서 알려줘."`
- `"CVE-2026-40347 취약점 관련 공식 권고(Advisory)를 검색해 현재 프로젝트가 사용하는 버전이 안전한지 검증해줘."`

---

## 📊 Evidence-Backed 운영 계약

| 검증 축 | 공개 계약 | 근거 |
|:---|:---|:---|
| Public tool surface | `search`, `fetch`, `fetch_bulk`, `verify`, `get_evidence`, `list_evidence_runs`는 기존 출력 마커를 유지하며 additive로 확장 | [output-contract artifacts](.omo/evidence/output-contract/), [benchmark summary](.omo/evidence/competitive-moat/summary.md) |
| 차단 출처 투명성 | 일반 fetch 우선, bot-wall metadata 노출, policy-aware stealth 상승 여부 기록 | [source ledger D-03~D-05](.omo/evidence/competitive-source-ledger.md), [benchmark summary](.omo/evidence/competitive-moat/summary.md) |
| provider doctor JSON | `setup --check --json`이 provider/browser/evidence 상태와 repair hint를 read-only로 출력 | [source ledger A-03~A-05](.omo/evidence/competitive-source-ledger.md), [benchmark summary](.omo/evidence/competitive-moat/summary.md) |
| 증거 보존 | `metadata-only` evidence ledger는 raw body, cookies, tokens 없이 run/source metadata만 저장 | [source ledger D-05~D-06](.omo/evidence/competitive-source-ledger.md), [benchmark summary](.omo/evidence/competitive-moat/summary.md) |

---

## 📈 품질 벤치마크

고정 30-query live corpus 기준 (`.omo/evidence/search-quality-gate/metrics.json`)

상세 설명: [`docs/search-quality-improvement-report.md`](docs/search-quality-improvement-report.md)

| 성능 지표 | 단일 엔진 web_search | deep search v3 | 변화 |
|:---|:---:|:---:|:---:|
| **Precision@5** | 0.187 | **0.473** | +154% |
| **NDCG@10** | 0.332 | **0.585** | +76% |
| **MRR** | 0.447 | **0.840** | +88% |

> ⚠️ **트레이드오프**: 30-query live corpus 기준 deep 검색 p50은 약 **9.9초**, p95는 약 **20.9초**이며, 정확 질의는 broad expansion을 끄고 원 질의를 보존합니다.
> 
> ```bash
> # 재현 명령어
> uv run python benchmark/search_quality_benchmark.py --queries .omo/evidence/search-quality-baseline/queries.jsonl --output .omo/evidence/search-quality-gate/metrics.json
> ```

---

## ⚙️ 주요 환경 변수

| 환경 변수 | 기본값 | 설명 |
|:---|:---|:---|
| `MARU_STRICT_QUERY` | `1` | 모호하거나 불완전한 검색어 필터링 및 정규화 |
| `MARU_EMBEDDING_MODEL` | Granite 97M R2 | 문서 재랭킹에 사용할 시맨틱 임베딩 모델 |
| `MARU_EVIDENCE_DB` | `~/.maru/evidence.sqlite3` | metadata-only evidence ledger 저장 위치 |
| `MARU_STEALTH_MODE` | `auto` | `auto`, `always`, `off` 중 policy-aware stealth 동작 |
| `MARU_RESPECT_ROBOTS` | `1` | 스텔스 상승 시 robots 정책 존중 기본값 |
| `MARU_BENCHMARK_SUITE` | — | `stress` 설정 시 부하 테스트 벤치마크 수행 |

- 🔧 **전체 환경 변수 상세**: [웹사이트 설정 페이지](https://claudianus.github.io/maru-deep-pro-search/#config)

---

## 🛠️ 문제 해결 (Troubleshooting)

| 발생 현상 | 해결 방법 |
|:---|:---|
| MCP 서버가 에이전트에 노출되지 않음 | `maru-deep-pro-search-setup setup` 재실행 후 에이전트 완전 재시작 |
| 첫 검색 실행 시 지나치게 느림 | `maru-deep-pro-search-setup warmup-embeddings -q`로 가중치 파일 사전 캐시 |
| provider doctor JSON이 필요함 | `maru-deep-pro-search-setup setup --check --json`으로 provider, browser, evidence 상태 확인 |
| 설정 변경 사항이 반영되지 않음 | `maru-deep-pro-search-update --with-setup` 또는 `setup --repair` 실행 |
| 간헐적인 검색 엔진 에러 발생 | `engine_health` 도구로 실시간 헬스 상태 점검 |

---

## 🤝 기여 및 라이선스

- **기여**: [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요. 버그 리포트와 PR을 환영합니다!
- **라이선스**: MIT License — 자세한 내용은 [LICENSE](LICENSE) 파일을 참고하세요.

<div align="center">

**[⬆️ 맨 위로 돌아가기](#maru-deep-pro-search)**

</div>
