Metadata-Version: 2.4
Name: juricode-retrieval
Version: 0.1.0
Summary: Dense-retrieval core for JuriCode-JP: artefact loading, query embedding, cosine top-k, and article-level dedup as the single source of truth
Project-URL: Homepage, https://github.com/JuriCode-JP/JuriCode-JP
Author-email: "CHOKAI Co.,Ltd." <sato@chokaijp.com>
License: MIT
Keywords: embedding,japan,juricode-jp,legal,rag,retrieval
Requires-Python: >=3.11
Requires-Dist: google-genai>=0.3.0
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# juricode-retrieval

Dense-retrieval core for JuriCode-JP, packaged (MIT) as the single source of
truth for the parity-critical primitives.

## What it provides

| primitive | purpose |
|---|---|
| `_load_artefacts` | Load the embedding matrix (`.npy`), records (`.meta.jsonl`), and provider state (`.vec.json`, `.vec.pkl` fallback). Missing artefacts fail loudly. |
| `_encode_queries` | Embed query strings via the artefact's provider (gemini / openai / tfidf). The openai and gemini clients are imported lazily. |
| `_cosine_topk` | Cosine-similarity top-k of a query matrix against the corpus matrix. |
| `dedup_by_article` | Collapse duplicate segments of the same article to the top-ranked one. |

## Why a package

`tools/embed/retrieve.py` re-imports these four objects, so every eval and
service caller runs the *identical* function objects rather than a copy. The
retrieval math is therefore unchanged by construction, and a test asserts the
object identity (`retrieve._load_artefacts is juricode_retrieval._load_artefacts`).

## Dependencies

`numpy` is required (imported lazily inside each primitive, so importing the
package itself needs no numpy). `google-genai` is the production embedding
provider; the `openai` and `tfidf` branches are optional and imported only when
selected.
