multilingual-dev-rag 0.1.0rc1__py3-none-any.whl

dev_rag/__init__.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""multilingual-dev-rag — local-first RAG over source code and technical docs.
+
+    from dev_rag import search
+    results = search('ферма воркеров', collection='docs', n=5)
+
+Set `DEV_RAG_ROOT` to the repository you want to index, and `DEV_RAG_PROFILE`
+to a profile describing which files count. See `dev_rag.config`.
+"""
+from .config import DEV_RAG_PROFILE, DEV_RAG_ROOT, RAG_BACKEND
+from .searcher import search
+
+__version__ = '0.1.0rc1'
+
+__all__ = [
+    'search',
+    'RAG_BACKEND',
+    'DEV_RAG_ROOT',
+    'DEV_RAG_PROFILE',
+    '__version__',
+]

dev_rag/chunker.py

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+"""Разбиение текста на чанки с учётом типа файла."""
+from __future__ import annotations
+
+import re
+from typing import Generator
+
+from .config import CHUNK_SIZE, CHUNK_OVERLAP
+
+
+def chunk_text(text: str, path: str) -> Generator[dict, None, None]:
+    """Разбить текст на перекрывающиеся чанки с метаданными.
+
+    Стратегия зависит от расширения:
+      .md  — по секциям заголовков (##/###)
+      .mac — по блокам (двойной перевод строки)
+      .py  — по границам class/def
+    """
+    if path.endswith('.md'):
+        sections = re.split(r'\n(?=#{1,3} )', text)
+        for section in sections:
+            if not section.strip():
+                continue
+            title_match = re.match(r'#{1,3} (.+)', section)
+            section_title = title_match.group(1) if title_match else ''
+            yield from _sliding_window(section, path, section_title)
+    elif path.endswith('.mac') or path.endswith('.MAC'):
+        blocks = re.split(r'\n{2,}', text)
+        for block in blocks:
+            if not block.strip():
+                continue
+            name_match = re.match(r'(\w+)\s*\(', block.lstrip())
+            block_name = name_match.group(1) if name_match else ''
+            yield from _sliding_window(block, path, block_name)
+    else:
+        # Python: split by class/def boundaries
+        blocks = re.split(r'\n(?=(?:class |def |\Z))', text)
+        for block in blocks:
+            if not block.strip():
+                continue
+            name_match = re.match(r'(?:class|def)\s+(\w+)', block.lstrip())
+            block_name = name_match.group(1) if name_match else ''
+            yield from _sliding_window(block, path, block_name)
+
+
+def _sliding_window(text: str, path: str, context: str) -> Generator[dict, None, None]:
+    """Скользящее окно по тексту с перекрытием."""
+    start = 0
+    idx = 0
+    while start < len(text):
+        end = min(start + CHUNK_SIZE, len(text))
+        chunk = text[start:end]
+        if chunk.strip():
+            yield {
+                'text': chunk,
+                'path': path,
+                'context': context or '',
+                'chunk_idx': idx,
+            }
+            idx += 1
+        if end >= len(text):
+            break
+        start += CHUNK_SIZE - CHUNK_OVERLAP

dev_rag/cli.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+"""CLI entry points for multilingual-dev-rag.
+
+    dev-rag-index   — build or rebuild the index
+    dev-rag-search  — search from the shell
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .config import RAG_BACKEND
+
+COLLECTION_CHOICES = ('all', 'docs', 'code', 'plans')
+
+
+def main():
+    """Entry point for dev-rag-index. Routes to the configured backend."""
+    if RAG_BACKEND == 'zvec':
+        from .zvec_indexer import main as _zvec_main
+        _zvec_main()
+    else:
+        from .indexer import main as _qdrant_main
+        _qdrant_main()
+
+
+def search_main():
+    """Entry point for dev-rag-search."""
+    parser = argparse.ArgumentParser(
+        prog='dev-rag-search',
+        description='Search the indexed corpus (hybrid vector + full-text).',
+    )
+    parser.add_argument('query', help='what to search for')
+    # Restricted to the known collections on purpose: an unknown name used to
+    # be swallowed silently — the lookup failed, the exception was caught, and
+    # the command printed "No results found" as if the corpus had no match.
+    parser.add_argument(
+        '-c', '--collection',
+        choices=COLLECTION_CHOICES,
+        default='all',
+        help='which collection to search (default: all)',
+    )
+    parser.add_argument(
+        '-n', '--num-results',
+        type=int,
+        default=5,
+        metavar='N',
+        help='how many results to return (default: 5)',
+    )
+    parser.add_argument(
+        '--paths-only',
+        action='store_true',
+        help='print only scores and paths, without the matching text',
+    )
+    args = parser.parse_args()
+
+    from .searcher import search
+
+    results = search(args.query, collection=args.collection, n=args.num_results)
+    if not results:
+        print('No results found.')
+        sys.exit(1)
+
+    for i, r in enumerate(results, 1):
+        ctx = f' [{r["context"]}]' if r.get('context') else ''
+        if args.paths_only:
+            print(f'{r["score"]:.4f}  {r["path"]}{ctx}')
+            continue
+        print(f'--- Result {i} (score={r["score"]:.4f}) ---')
+        print(f'File: {r["path"]}{ctx}')
+        print(r['text'][:300])
+        print()

dev_rag/config.py

@@ -0,0 +1,136 @@
+# -*- coding: utf-8 -*-
+"""Configuration for multilingual-dev-rag.
+
+Two things must be decided before indexing: **what to index** (the corpus root)
+and **which files count** (the profile). Both come from the environment, so the
+same installed package serves several projects.
+
+    DEV_RAG_ROOT     absolute path to the repository being indexed. Required.
+    DEV_RAG_PROFILE  built-in profile name, or a path to a profile JSON.
+                     Default: 'generic'.
+
+`DEV_RAG_ROOT` is deliberately **not** guessed from the package location. An
+earlier version defaulted to `<package>/../..`, which quietly resolved to a
+directory that held none of the corpus: globs matched nothing, indexing reported
+"0 chunks" and exited successfully. A wrong answer that looks like a working one
+is worse than a crash, so a missing root now raises — see `require_root()`.
+
+Profiles keep project-specific knowledge out of the code. `generic` indexes
+markdown and Python anywhere; `k3_mebel` is a hand-tuned example for a CAD
+codebase with `.mac` macros. To describe your own corpus, copy a built-in
+profile, edit the globs, and point `DEV_RAG_PROFILE` at the file.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+
+_PACKAGE_DIR = os.path.dirname(os.path.abspath(__file__))
+_PROFILES_DIR = os.path.join(_PACKAGE_DIR, 'profiles')
+
+# ==================== Corpus root ====================
+# Empty (not a guess) when unset: see require_root().
+DEV_RAG_ROOT = os.environ.get('DEV_RAG_ROOT', '')
+
+
+def require_root() -> str:
+    """Return the corpus root, or raise with an actionable message.
+
+    Called by the indexer and searcher rather than at import time, so that
+    `import dev_rag` stays cheap and testable without a corpus on disk.
+    """
+    if not DEV_RAG_ROOT:
+        raise RuntimeError(
+            'DEV_RAG_ROOT is not set. Point it at the repository you want to '
+            'index, e.g. DEV_RAG_ROOT=/path/to/your/repo. It is not guessed '
+            'from the package location on purpose: a wrong guess indexes '
+            'nothing and reports success.'
+        )
+    if not os.path.isdir(DEV_RAG_ROOT):
+        raise RuntimeError(
+            f'DEV_RAG_ROOT points at {DEV_RAG_ROOT!r}, which is not a '
+            f'directory. Nothing would be indexed.'
+        )
+    return DEV_RAG_ROOT
+
+
+# ==================== Profile ====================
+DEV_RAG_PROFILE = os.environ.get('DEV_RAG_PROFILE', 'generic')
+
+
+def load_profile(name_or_path: str = None) -> dict:
+    """Load a profile by built-in name or by path to a JSON file."""
+    name_or_path = name_or_path or DEV_RAG_PROFILE
+    path = name_or_path
+    if not os.path.isfile(path):
+        path = os.path.join(_PROFILES_DIR, f'{name_or_path}.json')
+    if not os.path.isfile(path):
+        available = sorted(
+            f[:-5] for f in os.listdir(_PROFILES_DIR) if f.endswith('.json')
+        )
+        raise RuntimeError(
+            f'Profile {name_or_path!r} not found. Built-in profiles: '
+            f'{", ".join(available)}. Or pass a path to a profile JSON.'
+        )
+    with open(path, encoding='utf-8') as f:
+        return json.load(f)
+
+
+_profile = load_profile()
+
+# Collection names and glob patterns come from the profile, not from this file.
+COLLECTIONS = _profile['collections']
+INDEX_PATTERNS = _profile['index_patterns']
+
+# ==================== Backend selection ====================
+# zvec   — in-process vector DB + local multilingual embeddings, no servers.
+# qdrant — legacy: needs a Qdrant server and an Ollama embedder.
+RAG_BACKEND = os.getenv('RAG_BACKEND', 'zvec')
+
+# ==================== zvec backend ====================
+
+def _default_db_path() -> str:
+    """Where the index lives: a per-user, per-corpus directory.
+
+    Not inside the package. The index is derived data — rebuilt by
+    `dev-rag-index`, and holding chunks of whatever corpus you pointed at.
+    Writing it into `site-packages/` works for an editable install and breaks
+    for a normal one: on Linux that directory belongs to root.
+
+    Keyed by the corpus root, so one installation can serve several
+    repositories. With a single shared path, pointing DEV_RAG_ROOT at another
+    repository and re-indexing would silently overwrite the previous index —
+    and a search would then answer confidently from the wrong corpus.
+
+    The directory name keeps the root's basename for readability and a short
+    hash of its absolute path for uniqueness. Override wholesale with
+    ZVEC_DB_PATH if you want the index somewhere specific.
+    """
+    if os.name == 'nt':
+        base = os.environ.get('LOCALAPPDATA') or os.path.join(
+            os.path.expanduser('~'), 'AppData', 'Local'
+        )
+    else:
+        base = os.environ.get('XDG_DATA_HOME') or os.path.join(
+            os.path.expanduser('~'), '.local', 'share'
+        )
+    root = os.path.abspath(DEV_RAG_ROOT) if DEV_RAG_ROOT else '_unset'
+    slug = os.path.basename(root.rstrip(os.sep)) or 'root'
+    digest = hashlib.md5(root.encode('utf-8')).hexdigest()[:8]
+    return os.path.join(base, 'dev-rag', f'{slug}-{digest}', 'zvec_data')
+
+
+ZVEC_DB_PATH = os.getenv('ZVEC_DB_PATH') or _default_db_path()
+ZVEC_MODEL = os.getenv('ZVEC_MODEL', 'paraphrase-multilingual-MiniLM-L12-v2')
+ZVEC_EMBED_DIM = 384  # paraphrase-multilingual-MiniLM-L12-v2 output dimension
+
+# ==================== Qdrant + Ollama (legacy backend) ====================
+QDRANT_URL = os.getenv('QDRANT_URL', 'http://localhost:6333')
+OLLAMA_URL = os.getenv('OLLAMA_URL', 'http://localhost:11434')
+EMBED_MODEL = os.getenv('EMBED_MODEL', 'nomic-embed-text')
+EMBED_DIM = 768  # nomic-embed-text output dimension
+
+# ==================== Chunking ====================
+CHUNK_SIZE = 800     # characters per chunk
+CHUNK_OVERLAP = 100  # overlap between consecutive chunks

dev_rag/embedder.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""Эмбеддинги через Ollama nomic-embed-text (legacy-бэкенд).
+
+Используется только при RAG_BACKEND=qdrant.
+Для zvec-бэкенда эмбеддинги генерируются локально (sentence-transformers)
+внутри zvec_searcher.py.
+"""
+from __future__ import annotations
+
+import httpx
+
+from .config import OLLAMA_URL, EMBED_MODEL
+
+
+def embed(text: str) -> list:
+    """Получить вектор эмбеддинга через Ollama API."""
+    r = httpx.post(
+        f'{OLLAMA_URL}/api/embeddings',
+        json={'model': EMBED_MODEL, 'prompt': text},
+        timeout=120.0,
+    )
+    r.raise_for_status()
+    return r.json()['embedding']
+
+
+def embed_batch(texts: list, batch_size: int = 16) -> list:
+    """Эмбеддинги для списка текстов."""
+    vectors = []
+    for i in range(0, len(texts), batch_size):
+        batch = texts[i:i + batch_size]
+        for text in batch:
+            vectors.append(embed(text))
+    return vectors

dev_rag/fts_normalizer.py

@@ -0,0 +1,115 @@
+# -*- coding: utf-8 -*-
+"""Нормализация текста для FTS-поиска по не-ASCII письменностям.
+
+## Зачем это нужно
+
+FTS-движок zvec не умеет искать по тексту вне ASCII, и на то две независимые
+причины (обе проверены зондами на реальном корпусе, а не на игрушечных примерах):
+
+1. **Токенайзер `standard` выбрасывает не-ASCII токены целиком.** Любой русский
+   запрос через `Fts(match_string='воркер')` возвращает 0 результатов, тогда как
+   латиница (`RabbitMQ`, `assembly`) находится. В гибриде FTS+vector это значит,
+   что для русских запросов работал только вектор.
+2. **Фильтр `lowercase` внутри zvec обрабатывает только ASCII.** Он не приводит
+   кириллицу к нижнему регистру, поэтому даже токенайзер, сохраняющий русские
+   токены, находит `Коробка` и не находит `коробка`.
+
+Альтернативы, которые проверены и отвергнуты:
+
+- `tokenizer_name='jieba'` — кириллицу индексирует, но режет её на мелкие
+  фрагменты. На корпусе из 5 документов давал 7/9 верных ответов и выглядел
+  решением; на реальных 837 чанках выродился в шум: `микрорепозитории` →
+  план 022, `воркер` → план 022, а три разных регистра давали три разных
+  неверных ответа. Хуже `standard`: тот хотя бы честно возвращал пусто.
+- Транслитерация в ASCII + hex-ключи — решает проблему, которой нет: коллизии
+  (`ел`/`ель` → `el`) возникают только из-за самой транслитерации. Без неё
+  `ел` и `ель` — разные токены.
+- Другого токенайзера нет: в `_zvec.*.pyd` доступны ровно три (`standard`,
+  `whitespace`, `jieba`) и ровно один фильтр (`lowercase`).
+
+## Решение
+
+`whitespace`-токенайзер сохраняет не-ASCII токены целиком, а привести их к
+нижнему регистру и убрать пунктуацию можно на стороне Python: `str.lower()`
+работает с юникодом, в отличие от ASCII-фильтра zvec.
+
+Нормализованный текст пишется в **отдельное** поле `text_fts`, а поле `text`
+остаётся нетронутым: его отдаёт RAG в выдачу, и на нём работает `standard`,
+который умеет разбивать идентификаторы (`obj_k3_gab3` находится по частям
+`obj`/`k3`/`gab3` — это полезно и терять это нельзя).
+
+В `text_fts` попадают **только токены с не-ASCII символами**. Чистая латиница
+туда не идёт намеренно: она уже проиндексирована в `text`, и дублирование дало
+бы документу двойной вес в RRF при смешанном запросе. Так две FTS-дороги не
+пересекаются: `text` отвечает за ASCII и идентификаторы, `text_fts` — за всё
+остальное.
+
+## Граница применимости
+
+Подход работает для письменностей, где **слова разделены пробелами**: кириллица,
+греческий, латиница с диакритикой, армянский, грузинский, иврит, арабский.
+Проверено сквозным зондом (запрос → FTS → документ) на ru/de/el/fr/ar.
+
+**CJK так не поедет.** В китайском и японском пробелов между словами нет, и
+`whitespace` склеит предложение в один токен. Для них нужен `tokenizer_name='jieba'`
+на отдельном поле — он в zvec есть и для китайского как раз по назначению
+(на кириллице он бесполезен, см. выше).
+
+**Турецкий `İ`/`ı` не поддержан.** Беcрегистровое сравнение там зависит от локали
+(`İstanbul` vs `istanbul`), и ни `lower()`, ни `casefold()` его не решают — нужен
+turkish casing. Для турецкого корпуса потребуется отдельная обработка.
+"""
+from __future__ import annotations
+
+import re
+
+# Версия схемы нормализации. Менять при любой правке make_fts_unicode, иначе
+# старый индекс будет молча искать по правилам, которых больше нет.
+FTS_NORM_VERSION = 'unicode_casefold_v1'
+
+_PUNCT_RE = re.compile(r'[^\w\s]', re.UNICODE)
+_SPACE_RE = re.compile(r'\s+', re.UNICODE)
+_ASCII_WORD_RE = re.compile(r'[a-z0-9]', re.IGNORECASE)
+
+
+def has_non_ascii(text: str) -> bool:
+    """Есть ли в тексте символы вне ASCII (значит, поле text_fts может помочь).
+
+    Именно не-ASCII, а не «кириллица»: токенайзер standard слеп ко всему за
+    пределами ASCII одинаково, поэтому и обход нужен один на все письменности.
+    """
+    return any(ord(ch) > 127 for ch in text)
+
+
+def has_ascii_word(text: str) -> bool:
+    """Есть ли в тексте латиница или цифры (значит, поле text может помочь)."""
+    return bool(_ASCII_WORD_RE.search(text))
+
+
+def make_fts_unicode(text: str) -> str:
+    """Вернуть не-ASCII токены текста, приведённые к виду, пригодному для FTS.
+
+    Складывает регистр через `casefold()`, заменяет пунктуацию пробелами и
+    оставляет только токены, содержащие хотя бы один не-ASCII символ.
+    `ё` → `е` — русская любезность, чтобы «ёлка» и «елка» искались одинаково.
+
+    Именно `casefold()`, а не `lower()`: последний не решает немецкую асимметрию
+    `ß`/`SS` — `'ß'.lower()` остаётся `ß`, а `'SS'.lower()` даёт `ss`, поэтому
+    `TÜRGRÖSSE` не находил `Türgröße`. `casefold()` сводит оба к `türgrösse`.
+    Найдено сквозным зондом; юнит-тесты нормализатора это пропускали, потому что
+    сравнивали функцию с самой собой.
+
+    Результат пишется в поле text_fts с токенайзером whitespace. Пустая строка —
+    нормальный результат для чисто ASCII-текста.
+
+    >>> make_fts_unicode('Коробка двери KSM12.')
+    'коробка двери'
+    >>> make_fts_unicode('def build_door(x): pass')
+    ''
+    >>> make_fts_unicode('Größe Ελλάδα')
+    'grösse ελλάδα'
+    """
+    lowered = text.casefold().replace('ё', 'е')
+    spaced = _PUNCT_RE.sub(' ', lowered)
+    tokens = [t for t in _SPACE_RE.split(spaced) if t and has_non_ascii(t)]
+    return ' '.join(tokens)

dev_rag/indexer.py

@@ -0,0 +1,167 @@
+# -*- coding: utf-8 -*-
+"""Qdrant-индексатор (legacy) — индексация через Qdrant + Ollama.
+
+Используется только при RAG_BACKEND=qdrant.
+Для zvec используйте zvec_indexer.py.
+"""
+from __future__ import annotations
+
+import os
+import glob
+import hashlib
+import argparse
+
+from qdrant_client import QdrantClient
+from qdrant_client.models import (
+    Distance, VectorParams, PointStruct,
+    Filter, FieldCondition, MatchValue,
+)
+
+from .config import (
+    QDRANT_URL, EMBED_DIM, DEV_RAG_ROOT,
+    COLLECTIONS, INDEX_PATTERNS,
+)
+from .embedder import embed
+from .chunker import chunk_text
+from .reader import read_file_text, file_hash
+
+client = QdrantClient(url=QDRANT_URL)
+
+
+def _ensure_collections():
+    existing = {c.name for c in client.get_collections().collections}
+    for name in COLLECTIONS.values():
+        if name not in existing:
+            client.create_collection(
+                collection_name=name,
+                vectors_config=VectorParams(size=EMBED_DIM, distance=Distance.COSINE),
+            )
+            print(f'Created collection: {name}')
+
+
+def _collection_for(path: str) -> str:
+    rel = os.path.relpath(path, DEV_RAG_ROOT).replace('\\', '/')
+    if rel.startswith('plans/'):
+        return COLLECTIONS['plans']
+    if rel.endswith('.py') or rel.endswith('.mac'):
+        return COLLECTIONS['code']
+    return COLLECTIONS['docs']
+
+
+def index_file(path: str, force: bool = False) -> int:
+    abs_path = os.path.abspath(path)
+    rel_path = os.path.relpath(abs_path, DEV_RAG_ROOT).replace('\\', '/')
+    collection = _collection_for(abs_path)
+    fhash = file_hash(abs_path)
+
+    if not force:
+        results = client.scroll(
+            collection_name=collection,
+            scroll_filter=Filter(must=[
+                FieldCondition(key='path', match=MatchValue(value=rel_path)),
+                FieldCondition(key='hash', match=MatchValue(value=fhash)),
+            ]),
+            limit=1,
+        )
+        if results[0]:
+            return 0  # уже актуален
+
+    client.delete(
+        collection_name=collection,
+        points_selector=Filter(must=[
+            FieldCondition(key='path', match=MatchValue(value=rel_path))
+        ]),
+    )
+
+    try:
+        text = read_file_text(abs_path)
+    except Exception as e:
+        print(f'  Skip {rel_path}: {e}')
+        return 0
+
+    chunks = list(chunk_text(text, rel_path))
+    if not chunks:
+        return 0
+
+    points = []
+    for i, chunk in enumerate(chunks):
+        chunk_id = int(hashlib.md5(f'{rel_path}:{i}'.encode()).hexdigest()[:15], 16)
+        vector = embed(chunk['text'])
+        points.append(PointStruct(
+            id=chunk_id,
+            vector=vector,
+            payload={
+                'path': rel_path,
+                'context': chunk['context'],
+                'text': chunk['text'],
+                'hash': fhash,
+                'chunk_index': i,
+            },
+        ))
+
+    client.upsert(collection_name=collection, points=points)
+    return len(chunks)
+
+
+def index_all(force: bool = False) -> int:
+    _ensure_collections()
+    total = 0
+    for group, patterns in INDEX_PATTERNS.items():
+        print(f'\n[{group}]')
+        for pattern in patterns:
+            for path in glob.glob(os.path.join(DEV_RAG_ROOT, pattern), recursive=True):
+                n = index_file(path, force=force)
+                if n:
+                    rel = os.path.relpath(path, DEV_RAG_ROOT)
+                    print(f'  {rel}: {n} chunks')
+                    total += n
+    print(f'\nTotal: {total} chunks indexed')
+    return total
+
+
+def index_changed_files(changed_paths: list, force: bool = False) -> int:
+    _ensure_collections()
+    total = 0
+    for path in changed_paths:
+        abs_path = os.path.join(DEV_RAG_ROOT, path)
+        if not os.path.exists(abs_path):
+            continue
+        if not (path.endswith('.py') or path.endswith('.md') or path.endswith('.mac')):
+            continue
+        n = index_file(abs_path, force=force)
+        if n:
+            print(f'  {path}: {n} chunks')
+            total += n
+    return total
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Qdrant indexer for multilingual-dev-rag')
+    parser.add_argument('--all', action='store_true', help='Index all configured files')
+    parser.add_argument('--changed-only', action='store_true', help='Index files changed in last commit')
+    parser.add_argument('--force', action='store_true', help='Force reindex')
+    parser.add_argument('files', nargs='*', help='Specific files to index')
+    args = parser.parse_args()
+
+    if args.changed_only:
+        import subprocess
+        try:
+            out = subprocess.check_output(
+                ['git', 'diff', 'HEAD~1', 'HEAD', '--name-only'],
+                cwd=DEV_RAG_ROOT, stderr=subprocess.DEVNULL,
+            ).decode().splitlines()
+        except Exception:
+            out = []
+        n = index_changed_files(out, force=args.force)
+        print(f'Indexed {n} chunks from changed files')
+    elif args.files:
+        _ensure_collections()
+        for f in args.files:
+            n = index_file(f, force=args.force)
+            print(f'{f}: {n} chunks')
+    else:
+        index_all(force=args.force)
+
+
+if __name__ == '__main__':
+    main()