Metadata-Version: 2.5
Name: ragking
Version: 2.0.0
Summary: LlamaIndex 기반 RAG All-In-One 라이브러리
Project-URL: Homepage, https://github.com/JunseoKR/ragking
Project-URL: Repository, https://github.com/JunseoKR/ragking
Project-URL: Documentation, https://github.com/JunseoKR/ragking/tree/master/docs
Project-URL: Issues, https://github.com/JunseoKR/ragking/issues
Author-email: JunseoKR <JunseoKR@icloud.com>
License-Expression: MIT
License-File: LICENSE
Keywords: korean,legal,llamaindex,minio,qdrant,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Korean
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: celery>=5.3
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.28
Requires-Dist: langchain-text-splitters>=1.1
Requires-Dist: llama-index-core>=0.14.12
Requires-Dist: llama-index-embeddings-openai>=0.5.1
Requires-Dist: llama-index-llms-openai>=0.6.10
Requires-Dist: llama-index-postprocessor-jinaai-rerank>=0.4.1
Requires-Dist: llama-index-storage-docstore-redis>=0.5
Requires-Dist: llama-index-vector-stores-qdrant>=0.9.1
Requires-Dist: minio>=7.2.14
Requires-Dist: pydantic-settings>=2.9
Requires-Dist: pymupdf>=1.24.3
Requires-Dist: qdrant-client<1.19,>=1.16.2
Requires-Dist: redis>=5.2
Requires-Dist: selectolax>=0.4
Requires-Dist: tokenizers>=0.22.2
Requires-Dist: tqdm>=4.66
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=1; extra == 'dev'
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Description-Content-Type: text/markdown

# ragking

**LlamaIndex 기반 한국어(법령·규정) RAG 라이브러리.** 파일을 계층적으로 청킹·임베딩해
저장하고, auto-merging 검색 + 리랭크 + LLM으로 답한다.

앱이 아니라 라이브러리다 — 서버 진입점이 없고, 호스트 앱(FastAPI 등)에 임포트해서 쓴다.

```
인제스트:  File ──▶ Converter ──▶ Processor ──▶ connector.upload ──▶ (벡터 스토어 + docstore)
                  bytes→markdown    청킹(parent/leaf)   Small-to-Big 저장

조회:      RAGRetriever ──▶ AutoMergingRetriever ──▶ (리랭커) ──▶ LLM
                            leaf 검색→부모로 병합
```

## 특징

- **한국어 법령 문서용 파서** — `장/절/조/부칙` 헤더 트리를 세워 조문 단위로 청킹하고
  `section_path`·`page_start`/`page_end`를 메타데이터로 남긴다(인용 앵커).
- **Small-to-Big 저장** — leaf만 임베딩해 벡터 스토어에, 부모는 docstore에. 검색은 좁은
  leaf로 하고 답변 컨텍스트는 부모로 넓힌다.
- **레지스트리 한 번 초기화** — `rag_registry.initialize(config)` 이후 컴포넌트 배선이 없다.
- **내부망 전제** — 임베딩·LLM 모두 OpenAI 호환 엔드포인트(vLLM, TEI 등)를 가리키고,
  PDF 변환은 내부 Marker API에 위임한다.
- **하이브리드 검색(opt-in)** — dense + BM25 sparse로 조문 번호·법령명 정확 매칭을 살린다.
- **FastAPI/Celery 연동 제공** — lifespan, 요청 의존성, `/health` 라우터, 인제스트 태스크.

## 설치

```bash
pip install ragking
# 또는 저장소에서 직접
pip install git+https://github.com/JunseoKR/ragking.git
```

Python 3.10+ (CI는 3.10/3.11/3.12). 설치 한 번으로 전부 들어온다 — celery(비동기 인제스트),
redis docstore, pymupdf(2-up PDF 분리)까지 기본 의존성이며 기능별 extra는 없다. 하이브리드
검색(`fastembed`)만 예외로 별도 설치가 필요하다. 폐쇄망 설치는
[offline-install](docs/offline-install.md) 참고.

필요한 외부 서비스: 임베딩 서버·LLM 서버(OpenAI 호환)·Qdrant는 필수, MinIO·Marker API·
리랭크 서버는 용도에 따라 선택이다. 자세한 표는
[getting-started](docs/getting-started.md#설치) 참고.

## 30초 사용법

```python
from ragking.fastapi.registry import rag_registry
from ragking.tasks import run_ingest
from ragking.retrievers.retriever import RAGRetriever

rag_registry.initialize()                                             # env/.env → 설정 로드
run_ingest(bucket="docs", object_name="법령.pdf", file_type="legal")   # 인제스트
print(RAGRetriever().query("제12조의 내용은?"))                        # 조회
```

FastAPI 호스트 앱에 붙일 때:

```python
from fastapi import FastAPI, Depends
from ragking.fastapi import ragking_lifespan, get_retriever, health_router

app = FastAPI(lifespan=ragking_lifespan(settings))
app.include_router(health_router)


@app.post("/query")
async def query(q: str, retriever=Depends(get_retriever)):
    return {"answer": await retriever.aquery(q)}
```

## 문서

전체 문서는 [`docs/`](docs/README.md)에 있다.

| 문서 | 내용 |
|------|------|
| [getting-started](docs/getting-started.md) | 설치, 최소 설정, 인제스트/조회 quickstart, FastAPI·Celery 연동 |
| [architecture](docs/architecture.md) | 설계 — 4계층 분리, Small-to-Big, 레지스트리, 문서 아이덴티티 |
| [configuration](docs/configuration.md) | `RagConfig` 전 필드, 설정 주입 3가지 방법 |
| [connectors](docs/connectors.md) | MinIO 로드, Qdrant 저장·검색·삭제, docstore 샤딩, 하이브리드 |
| [converters](docs/converters.md) | bytes→markdown, PDF→Marker API, 포맷 추가 |
| [parsers](docs/parsers.md) | `Processor`(file_type 라우팅, `run`/`arun`) + parent/leaf 트리, `HierarchicalParser`·`LegalParser` |
| [retrievers](docs/retrievers.md) | auto-merging, 리랭크, 필터, 프롬프트, 스트리밍 |
| [api-reference](docs/api-reference.md) | 공개 심볼 시그니처 목록 |
| [troubleshooting](docs/troubleshooting.md) | 증상별 원인·확인·조치 |

## 개발

```bash
python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest tests/unit      # 단위 테스트(외부 서비스 불필요)
ruff check .
```

`tests/integration/`은 벡터 스토어 등 외부 서비스를 전제한다. 기여 규약과 저장소 관례는
[AGENTS.md](AGENTS.md)와 [`.agents/`](.agents/) 참고.

## 라이선스

[MIT](LICENSE)
