multilingual-dev-rag 0.1.0rc1__tar.gz

multilingual_dev_rag-0.1.0rc1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

multilingual_dev_rag-0.1.0rc1/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: multilingual-dev-rag
+Version: 0.1.0rc1
+Summary: Local-first multilingual RAG for code and technical docs. In-process hybrid retrieval (vector + full-text) with FTS for Cyrillic and other non-ASCII scripts.
+Author: Aleksandr Dragunkin
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/AlexandrDragunkin/multilingual-dev-rag
+Project-URL: Repository, https://github.com/AlexandrDragunkin/multilingual-dev-rag
+Project-URL: Issues, https://github.com/AlexandrDragunkin/multilingual-dev-rag/issues
+Keywords: rag,vector-search,full-text-search,hybrid-search,multilingual,cyrillic,code-search,zvec,local-first
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Natural Language :: Russian
+Classifier: Natural Language :: English
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: zvec>=0.5.1
+Requires-Dist: sentence-transformers>=2.0
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.7; extra == "qdrant"
+Requires-Dist: httpx>=0.24; extra == "qdrant"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# multilingual-dev-rag
+
+Local-first multilingual RAG for code and technical docs. In-process hybrid retrieval (vector + full-text) with FTS for Cyrillic and other non-ASCII scripts.
+
+[Русская версия](README_RU.md) · Apache-2.0
+
+---
+
+## Why this exists
+
+Most local RAG setups pair a multilingual embedding model with a full-text index and call it hybrid search. That works — until your corpus is not in English.
+
+The embedded engine this is built on ([zvec](https://github.com/alibaba/zvec)) ships a `standard` tokenizer that **drops non-ASCII tokens entirely** (on Windows and Linux — on macOS, curiously, it does not), and a `lowercase` filter that **only folds ASCII**. The result is not an error. A query for `воркер` returns zero rows, a query for `RabbitMQ` returns rows, and the hybrid quietly degrades to vector-only for half your corpus. Nothing in the logs says so.
+
+The platform split is the nastier half of the story. A package that relied on `standard` alone would *appear* to work on a developer's Mac and silently break the moment it shipped to a Linux server — same code, same engine, different tokenizer behaviour per OS. The fix below does not depend on which side of that split you are on: it works everywhere, and is merely redundant where `standard` already handles Cyrillic.
+
+## How the fix works
+
+Swapping the tokenizer does not save you. The engine ships exactly three, and each breaks differently:
+
+| Tokenizer | Cyrillic | Identifiers | Punctuation |
+| --- | --- | --- | --- |
+| `standard` | **discards it**¹ | splits correctly: `obj_k3_gab3` → `obj`, `k3`, `gab3` | separates correctly |
+| `whitespace` | keeps it | **never splits** | **glues**: `RabbitMQ.` is one token |
+| `jieba` | **shreds it** | splits | separates |
+
+¹ On Windows and Linux. On macOS, `standard` *does* match Cyrillic — the only platform of the three where it does (verified across the CI matrix on zvec 0.5.1). The `text_fts` workaround below is therefore redundant on macOS but harmless: its lanes never double-count because Latin is excluded from `text_fts`.
+
+`jieba` looks like the answer right up until you measure it at scale: 7 of 9 correct on a five-document probe, pure noise on a real 837-chunk corpus — a query for the exact title word of one document returned three unrelated ones, a different wrong answer per letter case. Worse than `standard`, which at least stayed honestly silent.
+
+Hence the design: **do not pick the best tokenizer — use two**, each for what it is good at. The index carries two fields, and every query goes only to the field that can answer it:
+
+| Field | Content | Tokenizer | Answers |
+| --- | --- | --- | --- |
+| `text` | original, verbatim | `standard` | ASCII words and identifiers — `obj_k3_gab3` is findable as `obj`, `k3`, `gab3` |
+| `text_fts` | non-ASCII tokens only, casefolded, punctuation stripped | `whitespace` | Cyrillic, Greek, accented Latin, Arabic — in any letter case |
+
+`text` stays byte-for-byte the original: it is what search returns to you. `text_fts` is derived and internal.
+
+Latin is deliberately **excluded** from `text_fts`. If both fields matched `RabbitMQ`, a document containing it would score twice in the Reciprocal Rank Fusion and outrank documents that match the query's Russian half. Keeping the two lanes disjoint keeps the fusion honest.
+
+Case folding happens in Python, not in the engine: `casefold()` handles `ß`/`SS` and Greek final sigma, which the engine's ASCII-only `lowercase` filter does not.
+
+## What you get
+
+- **Hybrid retrieval** — vector + full-text, fused with Reciprocal Rank Fusion.
+- **FTS that survives non-ASCII** — verified end-to-end on Russian, German, Greek, French, Arabic.
+- **No servers** — zvec runs in your process. No Qdrant, no Ollama, no Docker.
+- **Profiles** — describe your corpus in JSON; the package stays generic.
+- **MCP server** — exposes `rag_search` to Claude Code and other MCP clients.
+
+## Requirements
+
+**Python 3.10–3.14, 64-bit.** Everything else follows from zvec's wheels — it ships **no sdist**, so if there is no wheel for your platform there is no fallback to building from source.
+
+| Platform | Wheel | Status |
+| --- | --- | --- |
+| Windows x86_64 | `win_amd64` | **tested** — this is where it was built |
+| Linux x86_64 / aarch64 | `manylinux_2_28` | **tested** — CI green (Python 3.10–3.13) |
+| macOS Apple Silicon (11+) | `macosx_11_0_arm64` | **tested** — CI green (Python 3.10–3.13) |
+| macOS Intel | — | **will not install** |
+| Any 32-bit Python | — | **will not install** |
+
+All three wheel-bearing platforms run the full suite in CI, including the seven integration tests that hit the live zvec engine.
+
+On a platform without a wheel, `pip install` fails with `from versions: none`. That message means *wrong platform*, not *missing package* — no amount of build tooling will help.
+
+Other requirements:
+
+- **457 MB** of disk for the embedding model, downloaded on first index into `~/.cache/huggingface/`. Shared across projects; separate from the index.
+- On macOS the index goes to `~/.local/share/dev-rag/` (the XDG path), not `~/Library/Application Support`. Set `ZVEC_DB_PATH` if you want the native location.
+
+## Install
+
+```bash
+pip install multilingual-dev-rag
+```
+
+The default embedding model (`paraphrase-multilingual-MiniLM-L12-v2`, Apache-2.0) is downloaded from Hugging Face on first use and is not bundled.
+
+## Configure
+
+Two environment variables:
+
+```bash
+# Required: the repository you want to index.
+export DEV_RAG_ROOT=/path/to/your/repo
+
+# Optional: which files count. Built-in: generic (default), k3_mebel.
+# Or a path to your own profile JSON.
+export DEV_RAG_PROFILE=generic
+```
+
+`DEV_RAG_ROOT` is **not** guessed from the package location, deliberately. An earlier version defaulted to a path near the install directory; when that guess was wrong, globs matched nothing, indexing reported `0 chunks` and exited `0`.
+
+Two guards replace that guess. A missing root, or one that is not a directory, raises before anything runs. A root that exists but matches no file under the profile's patterns makes `dev-rag-index` **exit 2** with both values printed — an empty index built "successfully" looks healthy right up until a search returns nothing and also says nothing.
+
+### Where the index lives
+
+Per user, per corpus — never inside the package:
+
+```text
+Linux/macOS   ${XDG_DATA_HOME:-~/.local/share}/dev-rag/<repo>-<hash>/zvec_data
+Windows       %LOCALAPPDATA%\dev-rag\<repo>-<hash>\zvec_data
+```
+
+The `<hash>` is derived from the corpus root's absolute path, so **one installation serves several repositories** without them colliding. Point `DEV_RAG_ROOT` somewhere else and you get a separate index, not an overwritten one — otherwise a search would answer confidently from the wrong corpus.
+
+Set `ZVEC_DB_PATH` to override the location entirely.
+
+The index is derived data: it holds chunks of whatever you indexed, it is rebuilt by `dev-rag-index`, and it does not belong in version control.
+
+## Use
+
+```bash
+# Index the whole corpus
+dev-rag-index --category all --force
+
+# Index one collection
+dev-rag-index --category docs --force
+
+# Search from the shell
+dev-rag-search "ферма воркеров" --collection docs
+```
+
+> **The first run is slower than the rest.** The embedding model is not bundled:
+> `sentence-transformers` fetches it from Hugging Face on first use — 457 MB into
+> `~/.cache/huggingface/hub/` (on Windows, `C:\Users\<you>\.cache\huggingface\hub\`).
+> That is **not** where the index lives: the model is shared across projects, the
+> index is per corpus. Later runs load it from cache.
+>
+> For an offline environment, copy the cache from a machine where it is already
+> warm, or point `HF_HOME` somewhere prepared.
+
+```python
+from dev_rag import search
+
+for r in search('усталость воркера', collection='docs', n=5):
+    print(f"{r['score']:.4f}  {r['path']}")
+```
+
+### As an MCP server
+
+```json
+{
+  "mcpServers": {
+    "dev-rag": {
+      "command": "dev-rag-mcp",
+      "env": {
+        "DEV_RAG_ROOT": "/absolute/path/to/your/repo",
+        "DEV_RAG_PROFILE": "generic"
+      }
+    }
+  }
+}
+```
+
+MCP servers are child processes of the client, not daemons: `env` is read once at startup. After editing the config, restart the client.
+
+## Profiles
+
+A profile says which files belong to which collection. `generic` indexes markdown and Python anywhere; `k3_mebel` is a worked example for a CAD codebase with `.mac` macros.
+
+```json
+{
+  "name": "my_project",
+  "collections": { "docs": "my_docs", "code": "my_code", "plans": "my_plans" },
+  "index_patterns": {
+    "docs":  ["docs/**/*.md"],
+    "code":  ["src/**/*.py"],
+    "plans": ["rfcs/*.md"]
+  }
+}
+```
+
+```bash
+export DEV_RAG_PROFILE=/path/to/my_project.json
+```
+
+## Backends
+
+| Backend | Model | Servers needed |
+| --- | --- | --- |
+| **zvec** (default) | `paraphrase-multilingual-MiniLM-L12-v2` (384d) | none — in-process |
+| qdrant (legacy) | `nomic-embed-text` via Ollama (768d) | Qdrant + Ollama |
+
+The Qdrant path predates zvec and is kept only as a fallback: `nomic-embed-text` is English-centric and recalls poorly on Russian. Install it with `pip install multilingual-dev-rag[qdrant]` and set `RAG_BACKEND=qdrant` if you need it.
+
+## Known limits
+
+- **CJK is not supported.** Chinese and Japanese have no whitespace between words, so the `whitespace` tokenizer swallows a sentence as one token. zvec ships a `jieba` tokenizer for exactly this — it would need a separate field. (Do not reach for `jieba` on Cyrillic: it indexes it, but shreds it into fragments that match everything. Measured on a real corpus, it ranked worse than returning nothing.)
+- **Turkish `İ`/`ı` is not supported.** Caseless matching there is locale-dependent and neither `lower()` nor `casefold()` resolves it.
+- **Indexing is manual.** Incremental indexing (`--changed-only`) is not implemented for the zvec backend; after changing your corpus, re-run a full index.
+- **One writer.** zvec allows many readers but a single writer: do not index while another process holds the collection open for writing.
+
+## Origins
+
+Originally built for [K3-Мебель](https://k3-mebel.ru/) — a furniture-design CAD — to give semantic and full-text search over a Russian-language codebase and its documentation. That is where the non-ASCII FTS problem surfaced, and why the fix is measured against a real corpus rather than a toy example.
+
+The `k3_mebel` profile is that original corpus, kept as a worked example of a hand-tuned profile: Python prototypes, `.mac` macros, API reference and plans.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

multilingual_dev_rag-0.1.0rc1/README.md

@@ -0,0 +1,204 @@
+# multilingual-dev-rag
+
+Local-first multilingual RAG for code and technical docs. In-process hybrid retrieval (vector + full-text) with FTS for Cyrillic and other non-ASCII scripts.
+
+[Русская версия](README_RU.md) · Apache-2.0
+
+---
+
+## Why this exists
+
+Most local RAG setups pair a multilingual embedding model with a full-text index and call it hybrid search. That works — until your corpus is not in English.
+
+The embedded engine this is built on ([zvec](https://github.com/alibaba/zvec)) ships a `standard` tokenizer that **drops non-ASCII tokens entirely** (on Windows and Linux — on macOS, curiously, it does not), and a `lowercase` filter that **only folds ASCII**. The result is not an error. A query for `воркер` returns zero rows, a query for `RabbitMQ` returns rows, and the hybrid quietly degrades to vector-only for half your corpus. Nothing in the logs says so.
+
+The platform split is the nastier half of the story. A package that relied on `standard` alone would *appear* to work on a developer's Mac and silently break the moment it shipped to a Linux server — same code, same engine, different tokenizer behaviour per OS. The fix below does not depend on which side of that split you are on: it works everywhere, and is merely redundant where `standard` already handles Cyrillic.
+
+## How the fix works
+
+Swapping the tokenizer does not save you. The engine ships exactly three, and each breaks differently:
+
+| Tokenizer | Cyrillic | Identifiers | Punctuation |
+| --- | --- | --- | --- |
+| `standard` | **discards it**¹ | splits correctly: `obj_k3_gab3` → `obj`, `k3`, `gab3` | separates correctly |
+| `whitespace` | keeps it | **never splits** | **glues**: `RabbitMQ.` is one token |
+| `jieba` | **shreds it** | splits | separates |
+
+¹ On Windows and Linux. On macOS, `standard` *does* match Cyrillic — the only platform of the three where it does (verified across the CI matrix on zvec 0.5.1). The `text_fts` workaround below is therefore redundant on macOS but harmless: its lanes never double-count because Latin is excluded from `text_fts`.
+
+`jieba` looks like the answer right up until you measure it at scale: 7 of 9 correct on a five-document probe, pure noise on a real 837-chunk corpus — a query for the exact title word of one document returned three unrelated ones, a different wrong answer per letter case. Worse than `standard`, which at least stayed honestly silent.
+
+Hence the design: **do not pick the best tokenizer — use two**, each for what it is good at. The index carries two fields, and every query goes only to the field that can answer it:
+
+| Field | Content | Tokenizer | Answers |
+| --- | --- | --- | --- |
+| `text` | original, verbatim | `standard` | ASCII words and identifiers — `obj_k3_gab3` is findable as `obj`, `k3`, `gab3` |
+| `text_fts` | non-ASCII tokens only, casefolded, punctuation stripped | `whitespace` | Cyrillic, Greek, accented Latin, Arabic — in any letter case |
+
+`text` stays byte-for-byte the original: it is what search returns to you. `text_fts` is derived and internal.
+
+Latin is deliberately **excluded** from `text_fts`. If both fields matched `RabbitMQ`, a document containing it would score twice in the Reciprocal Rank Fusion and outrank documents that match the query's Russian half. Keeping the two lanes disjoint keeps the fusion honest.
+
+Case folding happens in Python, not in the engine: `casefold()` handles `ß`/`SS` and Greek final sigma, which the engine's ASCII-only `lowercase` filter does not.
+
+## What you get
+
+- **Hybrid retrieval** — vector + full-text, fused with Reciprocal Rank Fusion.
+- **FTS that survives non-ASCII** — verified end-to-end on Russian, German, Greek, French, Arabic.
+- **No servers** — zvec runs in your process. No Qdrant, no Ollama, no Docker.
+- **Profiles** — describe your corpus in JSON; the package stays generic.
+- **MCP server** — exposes `rag_search` to Claude Code and other MCP clients.
+
+## Requirements
+
+**Python 3.10–3.14, 64-bit.** Everything else follows from zvec's wheels — it ships **no sdist**, so if there is no wheel for your platform there is no fallback to building from source.
+
+| Platform | Wheel | Status |
+| --- | --- | --- |
+| Windows x86_64 | `win_amd64` | **tested** — this is where it was built |
+| Linux x86_64 / aarch64 | `manylinux_2_28` | **tested** — CI green (Python 3.10–3.13) |
+| macOS Apple Silicon (11+) | `macosx_11_0_arm64` | **tested** — CI green (Python 3.10–3.13) |
+| macOS Intel | — | **will not install** |
+| Any 32-bit Python | — | **will not install** |
+
+All three wheel-bearing platforms run the full suite in CI, including the seven integration tests that hit the live zvec engine.
+
+On a platform without a wheel, `pip install` fails with `from versions: none`. That message means *wrong platform*, not *missing package* — no amount of build tooling will help.
+
+Other requirements:
+
+- **457 MB** of disk for the embedding model, downloaded on first index into `~/.cache/huggingface/`. Shared across projects; separate from the index.
+- On macOS the index goes to `~/.local/share/dev-rag/` (the XDG path), not `~/Library/Application Support`. Set `ZVEC_DB_PATH` if you want the native location.
+
+## Install
+
+```bash
+pip install multilingual-dev-rag
+```
+
+The default embedding model (`paraphrase-multilingual-MiniLM-L12-v2`, Apache-2.0) is downloaded from Hugging Face on first use and is not bundled.
+
+## Configure
+
+Two environment variables:
+
+```bash
+# Required: the repository you want to index.
+export DEV_RAG_ROOT=/path/to/your/repo
+
+# Optional: which files count. Built-in: generic (default), k3_mebel.
+# Or a path to your own profile JSON.
+export DEV_RAG_PROFILE=generic
+```
+
+`DEV_RAG_ROOT` is **not** guessed from the package location, deliberately. An earlier version defaulted to a path near the install directory; when that guess was wrong, globs matched nothing, indexing reported `0 chunks` and exited `0`.
+
+Two guards replace that guess. A missing root, or one that is not a directory, raises before anything runs. A root that exists but matches no file under the profile's patterns makes `dev-rag-index` **exit 2** with both values printed — an empty index built "successfully" looks healthy right up until a search returns nothing and also says nothing.
+
+### Where the index lives
+
+Per user, per corpus — never inside the package:
+
+```text
+Linux/macOS   ${XDG_DATA_HOME:-~/.local/share}/dev-rag/<repo>-<hash>/zvec_data
+Windows       %LOCALAPPDATA%\dev-rag\<repo>-<hash>\zvec_data
+```
+
+The `<hash>` is derived from the corpus root's absolute path, so **one installation serves several repositories** without them colliding. Point `DEV_RAG_ROOT` somewhere else and you get a separate index, not an overwritten one — otherwise a search would answer confidently from the wrong corpus.
+
+Set `ZVEC_DB_PATH` to override the location entirely.
+
+The index is derived data: it holds chunks of whatever you indexed, it is rebuilt by `dev-rag-index`, and it does not belong in version control.
+
+## Use
+
+```bash
+# Index the whole corpus
+dev-rag-index --category all --force
+
+# Index one collection
+dev-rag-index --category docs --force
+
+# Search from the shell
+dev-rag-search "ферма воркеров" --collection docs
+```
+
+> **The first run is slower than the rest.** The embedding model is not bundled:
+> `sentence-transformers` fetches it from Hugging Face on first use — 457 MB into
+> `~/.cache/huggingface/hub/` (on Windows, `C:\Users\<you>\.cache\huggingface\hub\`).
+> That is **not** where the index lives: the model is shared across projects, the
+> index is per corpus. Later runs load it from cache.
+>
+> For an offline environment, copy the cache from a machine where it is already
+> warm, or point `HF_HOME` somewhere prepared.
+
+```python
+from dev_rag import search
+
+for r in search('усталость воркера', collection='docs', n=5):
+    print(f"{r['score']:.4f}  {r['path']}")
+```
+
+### As an MCP server
+
+```json
+{
+  "mcpServers": {
+    "dev-rag": {
+      "command": "dev-rag-mcp",
+      "env": {
+        "DEV_RAG_ROOT": "/absolute/path/to/your/repo",
+        "DEV_RAG_PROFILE": "generic"
+      }
+    }
+  }
+}
+```
+
+MCP servers are child processes of the client, not daemons: `env` is read once at startup. After editing the config, restart the client.
+
+## Profiles
+
+A profile says which files belong to which collection. `generic` indexes markdown and Python anywhere; `k3_mebel` is a worked example for a CAD codebase with `.mac` macros.
+
+```json
+{
+  "name": "my_project",
+  "collections": { "docs": "my_docs", "code": "my_code", "plans": "my_plans" },
+  "index_patterns": {
+    "docs":  ["docs/**/*.md"],
+    "code":  ["src/**/*.py"],
+    "plans": ["rfcs/*.md"]
+  }
+}
+```
+
+```bash
+export DEV_RAG_PROFILE=/path/to/my_project.json
+```
+
+## Backends
+
+| Backend | Model | Servers needed |
+| --- | --- | --- |
+| **zvec** (default) | `paraphrase-multilingual-MiniLM-L12-v2` (384d) | none — in-process |
+| qdrant (legacy) | `nomic-embed-text` via Ollama (768d) | Qdrant + Ollama |
+
+The Qdrant path predates zvec and is kept only as a fallback: `nomic-embed-text` is English-centric and recalls poorly on Russian. Install it with `pip install multilingual-dev-rag[qdrant]` and set `RAG_BACKEND=qdrant` if you need it.
+
+## Known limits
+
+- **CJK is not supported.** Chinese and Japanese have no whitespace between words, so the `whitespace` tokenizer swallows a sentence as one token. zvec ships a `jieba` tokenizer for exactly this — it would need a separate field. (Do not reach for `jieba` on Cyrillic: it indexes it, but shreds it into fragments that match everything. Measured on a real corpus, it ranked worse than returning nothing.)
+- **Turkish `İ`/`ı` is not supported.** Caseless matching there is locale-dependent and neither `lower()` nor `casefold()` resolves it.
+- **Indexing is manual.** Incremental indexing (`--changed-only`) is not implemented for the zvec backend; after changing your corpus, re-run a full index.
+- **One writer.** zvec allows many readers but a single writer: do not index while another process holds the collection open for writing.
+
+## Origins
+
+Originally built for [K3-Мебель](https://k3-mebel.ru/) — a furniture-design CAD — to give semantic and full-text search over a Russian-language codebase and its documentation. That is where the non-ASCII FTS problem surfaced, and why the fix is measured against a real corpus rather than a toy example.
+
+The `k3_mebel` profile is that original corpus, kept as a worked example of a hand-tuned profile: Python prototypes, `.mac` macros, API reference and plans.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).