dormouse-ua 0.3.0__tar.gz

dormouse_ua-0.3.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.db
+*.sqlite3
+.pytest_cache/
+.ruff_cache/
+*.egg
+.DS_Store
+notebooks/.ipynb_checkpoints/
+data/exports/*.jsonl
+data/exports/*.csv
+gemini.json

dormouse_ua-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daria Chuprina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dormouse_ua-0.3.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: dormouse-ua
+Version: 0.3.0
+Summary: Оптимізація українських текстів для LLM: менше токенів, краще розуміння
+Author-email: Daria Chuprina <daria@lazysoft.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ChuprinaDaria/dormouse
+Keywords: ukrainian,nlp,llm,tokenization,optimization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Provides-Extra: morph
+Requires-Dist: pymorphy3>=2.0; extra == "morph"
+Provides-Extra: tokens
+Requires-Dist: tiktoken>=0.7; extra == "tokens"
+Requires-Dist: anthropic>=0.40; extra == "tokens"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=3.0; extra == "embeddings"
+Provides-Extra: compress
+Requires-Dist: llmlingua>=0.2; extra == "compress"
+Provides-Extra: translate
+Requires-Dist: transformers>=4.40; extra == "translate"
+Requires-Dist: sentencepiece>=0.2; extra == "translate"
+Provides-Extra: ml
+Requires-Dist: torch>=2.0; extra == "ml"
+Provides-Extra: style
+Requires-Dist: scikit-learn>=1.3; extra == "style"
+Requires-Dist: numpy>=1.24; extra == "style"
+Provides-Extra: search
+Requires-Dist: sentence-transformers>=3.0; extra == "search"
+Requires-Dist: openpyxl>=3.1; extra == "search"
+Requires-Dist: pymupdf>=1.24; extra == "search"
+Provides-Extra: middleware
+Requires-Dist: openai>=1.0; extra == "middleware"
+Provides-Extra: anthropic-middleware
+Requires-Dist: anthropic>=0.40; extra == "anthropic-middleware"
+Provides-Extra: all
+Requires-Dist: dormouse[anthropic-middleware,compress,embeddings,middleware,ml,morph,search,style,tokens,translate]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: pymorphy3>=2.0; extra == "dev"
+Dynamic: license-file
+
+# dormouse
+
+**Ukrainian text optimizer for LLMs** — fewer tokens, better comprehension.
+
+Normalizes surzhyk, slang, fillers, and maps to English for cloud LLMs. Saves 60-73% tokens while *improving* response quality.
+
+> **UA:** Оптимізація українських текстів для LLM. Нормалізує суржик, сленг, мат — і стискає в англійську для Claude/GPT. Економія 60-73% токенів, якість відповідей зростає зі 67% до 100%.
+
+## Results
+
+Tested on 53,351 texts (Telegram corpus + books), 12 IT prompts across 4 GPT models:
+
+| Metric | Value |
+|--------|-------|
+| Token savings (cloud) | **73%** |
+| Token savings (without seq2seq) | **49%** |
+| Lexicon coverage | **88%** |
+| Seq2seq exact match | **98.2%** |
+| GPT response quality (original UA) | 67% |
+| GPT response quality (squeezed EN) | **100%** |
+| Quality preservation | **150%** (squeezed > original) |
+
+```
+Original UA:  "блін продакшн впав після деплою, що робити першим"
+Squeezed EN:  "damn production crashed after deploy, what do first"
+Tokens:       45 → 12 (-73%)
+GPT accuracy: 67% → 100%
+```
+
+## How it works
+
+```mermaid
+graph LR
+    A[UA text<br/>surzhyk, slang] --> B[crack_open<br/>normalize]
+    B --> C[compress<br/>remove fillers]
+    C --> D[map_to_en<br/>lexicon + seq2seq]
+    D --> E[EN compressed<br/>for LLM]
+
+    style A fill:#fdd,stroke:#c33
+    style E fill:#dfd,stroke:#3a3
+```
+
+| Layer | What it does | How |
+|-------|-------------|-----|
+| **crack_open** | surzhyk, slang, profanity → standard UA | 360 rules + pymorphy3 lemmatization |
+| **compress** | remove fillers, intensifiers, noise | rule-based pattern matching |
+| **map_to_en** | UA → compact English | 47K lexicon + seq2seq (28K expression pairs) |
+
+## Install
+
+```bash
+pip install dormouse
+
+# With morphological analysis (recommended)
+pip install dormouse[morph]
+
+# Everything
+pip install dormouse[all]
+```
+
+## Quick start
+
+```python
+from dormouse import squeeze
+
+# Normalize only (layers 1+2)
+squeeze("шо там по баґу, пофікси плз")
+# → "що там по помилці, виправ"
+
+# Cloud mode — compress for Claude/GPT (layers 1+2+3)
+squeeze("ваще нормально, канєшно зробимо", target="cloud")
+# → "generally ok, sure do"
+```
+
+### SDK Middleware (drop-in)
+
+```python
+from openai import OpenAI
+from dormouse import DormouseClient
+
+client = DormouseClient(OpenAI())  # or Anthropic()
+
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "шо там по деплою, він ваще не робе"}],
+)
+# Prompt: squeeze → EN → GPT → unsqueeze → Ukrainian response
+```
+
+### Semantic search
+
+```python
+from dormouse import stir, mumble, sip
+
+stir("report.pdf")                                    # index
+results = mumble("холодні закуски")                   # search by meaning
+topics = sip("data.xlsx", topics=["HR", "finance"])   # classify
+```
+
+### CLI
+
+```bash
+dormouse squeeze "шо там по баґу" -t cloud
+dormouse stir book.pdf
+dormouse mumble "головний герой"
+```
+
+## Comparison with alternatives
+
+| Tool | Ukrainian | Token savings | Approach | Quality impact |
+|------|:---------:|:------------:|----------|:--------------:|
+| **dormouse** | native | **73%** | normalize + compress + translate | **+50% quality** |
+| [LLMLingua](https://github.com/microsoft/LLMLingua) | no | up to 20x | ML perplexity pruning (GPT-2/LLaMA) | -5-15% |
+| [Selective Context](https://github.com/liyucheng09/Selective_Context) | no | 40-50% | self-information filtering | -10-20% |
+| [token-reducer](https://pypi.org/project/token-reducer/) | no | 50-75% | 6-stage pipeline, AST for code | neutral |
+| [shrink-prompt](https://pypi.org/project/shrink-prompt/) | no | 30-70% | domain-specific rules (<20ms) | neutral |
+| Google Translate → EN | partial | 30-40% | full translation | variable |
+
+**Why dormouse is different:**
+
+The problem: Ukrainian Cyrillic costs [3-4x more tokens](https://www.frontiersin.org/journals/artificial-intelligence/articles/10.3389/frai.2025.1538165/full) than equivalent English text in GPT-4/Claude.
+
+All existing tools (LLMLingua, Selective Context, token-reducer) compress *already English* text by removing information. dormouse solves the problem one level earlier — transforms expensive Ukrainian (3-4 tokens/word) into cheap English (1-1.5 tokens/word) while **preserving all meaning**.
+
+No other tool specifically optimizes Ukrainian for LLMs.
+
+## Use cases
+
+**Cost reduction** — Ukrainian Cyrillic encodes into 2-4x more tokens than equivalent English. dormouse saves 60-73% on input tokens.
+
+**Chatbots & support** — Users write in surzhyk/slang, dormouse normalizes before LLM, GPT gives concrete answers instead of generic responses.
+
+**RAG & document search** — User searches in slang, documents are in literary language. dormouse normalizes both sides → finds by meaning.
+
+**AI agents** — Long chains of actions eat context window. 73% compression = 73% more "memory" for the agent.
+
+**Batch processing** — 10K comments through GPT for sentiment analysis. Squeeze first → cheaper and faster.
+
+## Eval details
+
+Full evaluation ran for 4 days on 53,351 texts:
+
+```
+Corpus: 53,351 texts (Telegram + books)
+Squeeze speed: 606 texts/sec (normalization)
+Seq2seq model: 7.3M params, 28K expression pairs
+Stir/mumble: 8,441 chunks indexed, search ~600ms
+Sip classification: 99% texts classified (8 topics)
+```
+
+### HF Inference API (small models)
+
+| Model | UA score | Squeezed EN score | Delta |
+|-------|:--------:|:-----------------:|:-----:|
+| Qwen2.5-72B | 4.9/5 | 4.5/5 | -0.4 |
+| Qwen2.5-7B | 4.4/5 | 3.6/5 | -0.8 |
+| Llama-3.2-1B | 2.7/5 | 2.8/5 | +0.1 |
+
+> Squeeze works great for cloud models (GPT, Claude, 70B+). For small models (<7B), use `brew()` with native Ukrainian — they understand UA better than squeezed EN.
+
+## Architecture
+
+```
+src/dormouse/
+├── optimizer.py       — squeeze() main pipeline
+├── rule_engine.py     — normalization (360 rules + pymorphy3)
+├── compressor.py      — filler/noise removal
+├── mapper.py          — UA→EN via lexicon + lemma + transliteration
+├── seq2seq.py         — expression translator (GRU encoder-decoder)
+├── teapot.py          — stir/mumble/sip/brew (search + LLM)
+├── embedder.py        — sentence-transformers wrapper
+├── middleware.py      — OpenAI/Anthropic SDK proxy
+├── cli.py             — Click CLI
+└── assets.py          — lazy download of models/data
+```
+
+## Development
+
+```bash
+git clone https://github.com/ChuprinaDaria/dormouse
+cd dormouse
+pip install -e ".[dev,morph]"
+DORMOUSE_DATA_DIR=./data pytest tests/ -v
+```
+
+## License
+
+MIT

dormouse_ua-0.3.0/README.md

@@ -0,0 +1,188 @@
+# dormouse
+
+**Ukrainian text optimizer for LLMs** — fewer tokens, better comprehension.
+
+Normalizes surzhyk, slang, fillers, and maps to English for cloud LLMs. Saves 60-73% tokens while *improving* response quality.
+
+> **UA:** Оптимізація українських текстів для LLM. Нормалізує суржик, сленг, мат — і стискає в англійську для Claude/GPT. Економія 60-73% токенів, якість відповідей зростає зі 67% до 100%.
+
+## Results
+
+Tested on 53,351 texts (Telegram corpus + books), 12 IT prompts across 4 GPT models:
+
+| Metric | Value |
+|--------|-------|
+| Token savings (cloud) | **73%** |
+| Token savings (without seq2seq) | **49%** |
+| Lexicon coverage | **88%** |
+| Seq2seq exact match | **98.2%** |
+| GPT response quality (original UA) | 67% |
+| GPT response quality (squeezed EN) | **100%** |
+| Quality preservation | **150%** (squeezed > original) |
+
+```
+Original UA:  "блін продакшн впав після деплою, що робити першим"
+Squeezed EN:  "damn production crashed after deploy, what do first"
+Tokens:       45 → 12 (-73%)
+GPT accuracy: 67% → 100%
+```
+
+## How it works
+
+```mermaid
+graph LR
+    A[UA text<br/>surzhyk, slang] --> B[crack_open<br/>normalize]
+    B --> C[compress<br/>remove fillers]
+    C --> D[map_to_en<br/>lexicon + seq2seq]
+    D --> E[EN compressed<br/>for LLM]
+
+    style A fill:#fdd,stroke:#c33
+    style E fill:#dfd,stroke:#3a3
+```
+
+| Layer | What it does | How |
+|-------|-------------|-----|
+| **crack_open** | surzhyk, slang, profanity → standard UA | 360 rules + pymorphy3 lemmatization |
+| **compress** | remove fillers, intensifiers, noise | rule-based pattern matching |
+| **map_to_en** | UA → compact English | 47K lexicon + seq2seq (28K expression pairs) |
+
+## Install
+
+```bash
+pip install dormouse
+
+# With morphological analysis (recommended)
+pip install dormouse[morph]
+
+# Everything
+pip install dormouse[all]
+```
+
+## Quick start
+
+```python
+from dormouse import squeeze
+
+# Normalize only (layers 1+2)
+squeeze("шо там по баґу, пофікси плз")
+# → "що там по помилці, виправ"
+
+# Cloud mode — compress for Claude/GPT (layers 1+2+3)
+squeeze("ваще нормально, канєшно зробимо", target="cloud")
+# → "generally ok, sure do"
+```
+
+### SDK Middleware (drop-in)
+
+```python
+from openai import OpenAI
+from dormouse import DormouseClient
+
+client = DormouseClient(OpenAI())  # or Anthropic()
+
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "шо там по деплою, він ваще не робе"}],
+)
+# Prompt: squeeze → EN → GPT → unsqueeze → Ukrainian response
+```
+
+### Semantic search
+
+```python
+from dormouse import stir, mumble, sip
+
+stir("report.pdf")                                    # index
+results = mumble("холодні закуски")                   # search by meaning
+topics = sip("data.xlsx", topics=["HR", "finance"])   # classify
+```
+
+### CLI
+
+```bash
+dormouse squeeze "шо там по баґу" -t cloud
+dormouse stir book.pdf
+dormouse mumble "головний герой"
+```
+
+## Comparison with alternatives
+
+| Tool | Ukrainian | Token savings | Approach | Quality impact |
+|------|:---------:|:------------:|----------|:--------------:|
+| **dormouse** | native | **73%** | normalize + compress + translate | **+50% quality** |
+| [LLMLingua](https://github.com/microsoft/LLMLingua) | no | up to 20x | ML perplexity pruning (GPT-2/LLaMA) | -5-15% |
+| [Selective Context](https://github.com/liyucheng09/Selective_Context) | no | 40-50% | self-information filtering | -10-20% |
+| [token-reducer](https://pypi.org/project/token-reducer/) | no | 50-75% | 6-stage pipeline, AST for code | neutral |
+| [shrink-prompt](https://pypi.org/project/shrink-prompt/) | no | 30-70% | domain-specific rules (<20ms) | neutral |
+| Google Translate → EN | partial | 30-40% | full translation | variable |
+
+**Why dormouse is different:**
+
+The problem: Ukrainian Cyrillic costs [3-4x more tokens](https://www.frontiersin.org/journals/artificial-intelligence/articles/10.3389/frai.2025.1538165/full) than equivalent English text in GPT-4/Claude.
+
+All existing tools (LLMLingua, Selective Context, token-reducer) compress *already English* text by removing information. dormouse solves the problem one level earlier — transforms expensive Ukrainian (3-4 tokens/word) into cheap English (1-1.5 tokens/word) while **preserving all meaning**.
+
+No other tool specifically optimizes Ukrainian for LLMs.
+
+## Use cases
+
+**Cost reduction** — Ukrainian Cyrillic encodes into 2-4x more tokens than equivalent English. dormouse saves 60-73% on input tokens.
+
+**Chatbots & support** — Users write in surzhyk/slang, dormouse normalizes before LLM, GPT gives concrete answers instead of generic responses.
+
+**RAG & document search** — User searches in slang, documents are in literary language. dormouse normalizes both sides → finds by meaning.
+
+**AI agents** — Long chains of actions eat context window. 73% compression = 73% more "memory" for the agent.
+
+**Batch processing** — 10K comments through GPT for sentiment analysis. Squeeze first → cheaper and faster.
+
+## Eval details
+
+Full evaluation ran for 4 days on 53,351 texts:
+
+```
+Corpus: 53,351 texts (Telegram + books)
+Squeeze speed: 606 texts/sec (normalization)
+Seq2seq model: 7.3M params, 28K expression pairs
+Stir/mumble: 8,441 chunks indexed, search ~600ms
+Sip classification: 99% texts classified (8 topics)
+```
+
+### HF Inference API (small models)
+
+| Model | UA score | Squeezed EN score | Delta |
+|-------|:--------:|:-----------------:|:-----:|
+| Qwen2.5-72B | 4.9/5 | 4.5/5 | -0.4 |
+| Qwen2.5-7B | 4.4/5 | 3.6/5 | -0.8 |
+| Llama-3.2-1B | 2.7/5 | 2.8/5 | +0.1 |
+
+> Squeeze works great for cloud models (GPT, Claude, 70B+). For small models (<7B), use `brew()` with native Ukrainian — they understand UA better than squeezed EN.
+
+## Architecture
+
+```
+src/dormouse/
+├── optimizer.py       — squeeze() main pipeline
+├── rule_engine.py     — normalization (360 rules + pymorphy3)
+├── compressor.py      — filler/noise removal
+├── mapper.py          — UA→EN via lexicon + lemma + transliteration
+├── seq2seq.py         — expression translator (GRU encoder-decoder)
+├── teapot.py          — stir/mumble/sip/brew (search + LLM)
+├── embedder.py        — sentence-transformers wrapper
+├── middleware.py      — OpenAI/Anthropic SDK proxy
+├── cli.py             — Click CLI
+└── assets.py          — lazy download of models/data
+```
+
+## Development
+
+```bash
+git clone https://github.com/ChuprinaDaria/dormouse
+cd dormouse
+pip install -e ".[dev,morph]"
+DORMOUSE_DATA_DIR=./data pytest tests/ -v
+```
+
+## License
+
+MIT

dormouse_ua-0.3.0/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["setuptools>=68.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dormouse-ua"
+version = "0.3.0"
+description = "Оптимізація українських текстів для LLM: менше токенів, краще розуміння"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    {name = "Daria Chuprina", email = "daria@lazysoft.dev"},
+]
+keywords = ["ukrainian", "nlp", "llm", "tokenization", "optimization"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+    "click>=8.1",
+]
+
+[project.optional-dependencies]
+morph = [
+    "pymorphy3>=2.0",
+]
+tokens = [
+    "tiktoken>=0.7",
+    "anthropic>=0.40",
+]
+embeddings = [
+    "sentence-transformers>=3.0",
+]
+compress = [
+    "llmlingua>=0.2",
+]
+translate = [
+    "transformers>=4.40",
+    "sentencepiece>=0.2",
+]
+ml = [
+    "torch>=2.0",
+]
+style = [
+    "scikit-learn>=1.3",
+    "numpy>=1.24",
+]
+search = [
+    "sentence-transformers>=3.0",
+    "openpyxl>=3.1",
+    "pymupdf>=1.24",
+]
+middleware = [
+    "openai>=1.0",
+]
+anthropic-middleware = [
+    "anthropic>=0.40",
+]
+all = [
+    "dormouse[morph,tokens,embeddings,compress,translate,ml,style,search,middleware,anthropic-middleware]",
+]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.5",
+    "pymorphy3>=2.0",
+]
+
+[project.scripts]
+dormouse = "dormouse.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ChuprinaDaria/dormouse"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dormouse = ["data/*.json"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E402"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "e2e: end-to-end tests with real API (require API keys)",
+]

dormouse_ua-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dormouse_ua-0.3.0/src/dormouse/__init__.py

@@ -0,0 +1,95 @@
+"""dormouse — оптимізація українських текстів для LLM."""
+
+__version__ = "0.3.0"
+
+from dormouse.optimizer import SqueezedText, squeeze, squeeze_batch
+
+__all__ = [
+    "squeeze",
+    "squeeze_batch",
+    "SqueezedText",
+    "__version__",
+]
+
+
+def nibble(text: str):
+    """Бенчмарк токенізації (потребує pip install dormouse[tokens])."""
+    from dormouse.analyzer import nibble as _nibble
+
+    return _nibble(text)
+
+
+def nibble_batch(texts: list[str]):
+    """Батч-аналіз токенізації."""
+    from dormouse.analyzer import nibble_batch as _nibble_batch
+
+    return _nibble_batch(texts)
+
+
+def sniff(
+    items: list[str],
+    categories: list[str],
+    squeeze_first: bool = False,
+):
+    """Класифікація через embeddings (потребує pip install dormouse[embeddings])."""
+    from dormouse.classifier import sniff as _sniff
+
+    return _sniff(items, categories, squeeze_first=squeeze_first)
+
+
+def DormouseClient(client, **kwargs):
+    """SDK wrapper для OpenAI (потребує pip install dormouse[middleware])."""
+    from dormouse.middleware import DormouseClient as _DormouseClient
+
+    return _DormouseClient(client, **kwargs)
+
+
+def stir(source, **kwargs):
+    """Завантажити і проіндексувати файл (потребує pip install dormouse[search])."""
+    from dormouse.teapot import Teapot
+
+    try:
+        from dormouse.embedder import Embedder
+
+        emb = Embedder()
+    except ImportError:
+        emb = None
+    t = Teapot(embedder=emb)
+    return t.stir(source, **kwargs)
+
+
+def mumble(query, index=None, top_k=10):
+    """Семантичний пошук по проіндексованих даних."""
+    from dormouse.teapot import Teapot
+
+    if index is not None:
+        return index.mumble(query, top_k=top_k)
+    t = Teapot()
+    return t.mumble(query, top_k=top_k)
+
+
+def sip(source, topics, threshold=0.5, **kwargs):
+    """Класифікація тексту по заданих темах."""
+    from dormouse.embedder import Embedder
+    from dormouse.teapot import Teapot
+
+    emb = Embedder()
+    t = Teapot(embedder=emb)
+    return t.sip(source, topics, threshold=threshold)
+
+
+def brew(query, *, llm, index=None, extract=None, strategy="hierarchical", limit=50):
+    """LLM-powered пошук і витягування (потребує pip install dormouse[search])."""
+    from dormouse.teapot import Teapot
+
+    if index is not None:
+        return index.brew(query, llm=llm, extract=extract, strategy=strategy, limit=limit)
+    t = Teapot()
+    return t.brew(query, llm=llm, extract=extract, strategy=strategy, limit=limit)
+
+
+def LocalLLM(model="MamayLM-4B", **kwargs):
+    """Уніфікований інтерфейс до локальної LLM."""
+    from dormouse.local_model import LocalLLM as _LocalLLM
+
+    return _LocalLLM(model, **kwargs)