mkd-retriever 0.1.0__tar.gz

mkd_retriever-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented here. The format loosely
+follows [Keep a Changelog](https://keepachangelog.com/); versions follow
+[SemVer](https://semver.org/).
+
+## [0.1.0] — 2026-07-22
+
+First public release.
+
+### Added
+- **`retrieval.core`** — the small, stable shared surface every module depends
+  on: `RetrievalResult`, the async `Retriever` protocol (+ `run_sync`),
+  `IntentLabel` (9 classes) / `IntentResult`, and the ingestion-contract
+  pydantic schemas (`ChunkFile`/`ChunkNode`, `ProductFile`/`ProductNode`,
+  `DocumentFile`/`DocumentNode`) with file loaders.
+- **`retrieval.eval`** — golden-set format, hand-written metrics
+  (accuracy / macro-micro F1 / confusion, recall@k / MRR) and an async runner.
+- **`intent_classification`** module (extra `intent_classification`) — an
+  LLM-prompt classifier over any `langchain-core` `BaseChatModel`, returning a
+  single `IntentResult`. Provider-agnostic; a factory wires a real
+  OpenAI-compatible endpoint. Defensive label parsing, graceful
+  logprobs→confidence.
+- **`db_query`** module (extra `db_query`) — retrieval by generating SQL
+  (via the `text2sql-engine` package) and running it against a ready-made
+  database. Two injected seams: `SqlGenerator` (NL→SQL) and `SqlExecutor`
+  (`SQLiteExecutor`, read-only). Rows map to `RetrievalResult` with a constant
+  score of `1.0`.
+
+### Notes
+- Every module depends only on `retrieval.core`, never on another module.
+- Model inference is expected behind a remote OpenAI-compatible endpoint; the
+  library only sends requests and never runs local inference. The default test
+  run is fully mocked and never touches a network endpoint.

mkd_retriever-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mehmet Kaan Durupunar
+
+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.

mkd_retriever-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+recursive-include src/retrieval py.typed

mkd_retriever-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: mkd-retriever
+Version: 0.1.0
+Summary: Modular, project-agnostic RAG retrieval layer: independent retrieval strategies behind a small shared core.
+Author: Mehmet Kaan Durupunar
+License: MIT
+Project-URL: Homepage, https://pypi.org/project/mkd-retriever/
+Keywords: rag,retrieval,information-retrieval,intent-classification,text-to-sql,llm,nlp,modular
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dotenv>=1
+Requires-Dist: langchain-core>=0.3
+Provides-Extra: top-n
+Provides-Extra: query-rewriting
+Provides-Extra: intent-classification
+Requires-Dist: langchain-openai>=0.2; extra == "intent-classification"
+Provides-Extra: raptor
+Provides-Extra: agentic
+Provides-Extra: db-query
+Requires-Dist: text2sql-engine[openai]>=0.2; extra == "db-query"
+Provides-Extra: eval
+Provides-Extra: all
+Requires-Dist: langchain-openai>=0.2; extra == "all"
+Requires-Dist: text2sql-engine[openai]>=0.2; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# mkd-retriever
+
+A **modular, project-agnostic RAG retrieval layer**. Several retrieval
+strategies — intent classification, text-to-SQL database query, and more to
+come (top-N vector search, query rewriting, RAPTOR, agentic flows) — live side
+by side in one package **without depending on one another**.
+
+The PyPI name is `mkd-retriever`; the import name is `retrieval`
+(`import retrieval`).
+
+```bash
+pip install mkd-retriever                        # core only
+pip install "mkd-retriever[intent_classification]"
+pip install "mkd-retriever[db_query]"
+pip install "mkd-retriever[all]"                 # everything implemented so far
+```
+
+## Why it is built this way
+
+Building retrieval methods on top of one another is a Jenga tower: changing or
+removing one piece topples the rest. Instead, every method is an **independent
+module**. The hard rules (enforced, see [`ARCHITECTURE.md`](./ARCHITECTURE.md)):
+
+1. **A module never imports another module.** Cross-module communication is the
+   consuming project's job, not this library's.
+2. **Everything shared lives in `retrieval.core`, and core stays small.** Only
+   minimal interfaces and common data schemas — never a module's implementation
+   detail. The dependency arrow is always *module → core*.
+3. **Dependencies are isolated per module.** Each module has its own
+   optional-dependency group; a library one module needs never leaks into
+   another module's environment.
+4. **Each module is understandable and testable on its own.**
+5. **Intent classification only returns a label — it does not route.** Mapping a
+   label to a retrieval method is the consuming project's decision.
+
+## What's inside
+
+```
+retrieval/
+  core/        shared interfaces + ingestion-contract schemas (small, stable)
+  eval/        golden-set format + metrics + async runner (cross-cutting)
+  modules/
+    intent_classification/   query -> intent label   (usable)
+    db_query/                query -> SQL -> rows     (usable)
+    top_n/                   vector search            (planned)
+    query_rewriting/         rewriting / expansion    (planned)
+    raptor/                  hierarchical retrieval   (planned)
+    agentic/                 multi-step flows         (planned)
+```
+
+### `retrieval.core`
+
+The whole surface every module shares:
+
+- `RetrievalResult` — a single scored item, returned identically by every
+  backend (`id`, `score`, `text`, `metadata`).
+- `Retriever` — the one async method a backend implements:
+  `async def retrieve(query, k) -> list[RetrievalResult]`. `run_sync` is a thin
+  convenience for synchronous callers.
+- `IntentLabel` (9 classes) / `IntentResult`.
+- Ingestion-contract schemas — pydantic models for the JSON an upstream
+  ingestion/parsing project emits (chunks, product graph, document metadata).
+  The contract is defined by *shape*, not by importing the producer, so any
+  project emitting these shapes can feed this layer. Models set `extra="ignore"`
+  to stay resilient to upstream format drift.
+
+### `intent_classification`
+
+A prompt-based classifier over any `langchain-core` `BaseChatModel`. It returns
+one `IntentResult` and nothing more — the label → strategy mapping is the
+consuming project's job.
+
+```python
+from retrieval.modules.intent_classification import (
+    LLMIntentClassifier, build_default_chat_model,
+)
+
+clf = LLMIntentClassifier(build_default_chat_model())
+result = await clf.classify("de1000 fiyati ne kadar")   # -> IntentResult
+```
+
+In tests, inject a fake `BaseChatModel` instead of the factory — no network,
+no model download.
+
+### `db_query`
+
+Retrieval by generating SQL and running it. A natural-language query is turned
+into a SQL string by the [`text2sql-engine`](https://pypi.org/project/text2sql-engine/)
+package (a 2-stage LLM pipeline), that SQL runs against a **ready-made**
+database, and the rows come back as `RetrievalResult` items.
+
+```python
+from retrieval.modules.db_query import build_default_retriever
+
+retriever = build_default_retriever(db_path="specs.db")
+results = await retriever.retrieve("operating temperature of DE9001", k=5)
+```
+
+Two injected seams keep it testable and dependency-isolated:
+
+- `SqlGenerator` (NL → SQL) — the production impl wraps a `text2sql` engine
+  hitting a remote endpoint; unit tests inject a fake returning canned SQL.
+- `SqlExecutor` (SQL → rows) — the shipped `SQLiteExecutor` uses only stdlib
+  `sqlite3` and opens the database **read-only** by default, so a stray write in
+  generated SQL fails at the engine level.
+
+The score is a constant `1.0` (a SQL result is an exact match set, not a
+similarity ranking; ordering is the query's own `ORDER BY`). The full row is in
+`RetrievalResult.metadata`. This module connects to an existing database — it
+does not build one.
+
+## Inference & the GPU rule
+
+Model inference (LLM/embedding) is expected to run on a **separate machine
+behind an OpenAI-compatible endpoint**. This library only sends requests to that
+endpoint; it never downloads models or runs local inference. The default test
+run (`pytest`) is fully mocked and never reaches a network endpoint — tests that
+hit a live endpoint are marked `integration` and skipped by default.
+
+## Development
+
+```bash
+pip install -e ".[all,dev]"
+pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

mkd_retriever-0.1.0/README.md

@@ -0,0 +1,129 @@
+# mkd-retriever
+
+A **modular, project-agnostic RAG retrieval layer**. Several retrieval
+strategies — intent classification, text-to-SQL database query, and more to
+come (top-N vector search, query rewriting, RAPTOR, agentic flows) — live side
+by side in one package **without depending on one another**.
+
+The PyPI name is `mkd-retriever`; the import name is `retrieval`
+(`import retrieval`).
+
+```bash
+pip install mkd-retriever                        # core only
+pip install "mkd-retriever[intent_classification]"
+pip install "mkd-retriever[db_query]"
+pip install "mkd-retriever[all]"                 # everything implemented so far
+```
+
+## Why it is built this way
+
+Building retrieval methods on top of one another is a Jenga tower: changing or
+removing one piece topples the rest. Instead, every method is an **independent
+module**. The hard rules (enforced, see [`ARCHITECTURE.md`](./ARCHITECTURE.md)):
+
+1. **A module never imports another module.** Cross-module communication is the
+   consuming project's job, not this library's.
+2. **Everything shared lives in `retrieval.core`, and core stays small.** Only
+   minimal interfaces and common data schemas — never a module's implementation
+   detail. The dependency arrow is always *module → core*.
+3. **Dependencies are isolated per module.** Each module has its own
+   optional-dependency group; a library one module needs never leaks into
+   another module's environment.
+4. **Each module is understandable and testable on its own.**
+5. **Intent classification only returns a label — it does not route.** Mapping a
+   label to a retrieval method is the consuming project's decision.
+
+## What's inside
+
+```
+retrieval/
+  core/        shared interfaces + ingestion-contract schemas (small, stable)
+  eval/        golden-set format + metrics + async runner (cross-cutting)
+  modules/
+    intent_classification/   query -> intent label   (usable)
+    db_query/                query -> SQL -> rows     (usable)
+    top_n/                   vector search            (planned)
+    query_rewriting/         rewriting / expansion    (planned)
+    raptor/                  hierarchical retrieval   (planned)
+    agentic/                 multi-step flows         (planned)
+```
+
+### `retrieval.core`
+
+The whole surface every module shares:
+
+- `RetrievalResult` — a single scored item, returned identically by every
+  backend (`id`, `score`, `text`, `metadata`).
+- `Retriever` — the one async method a backend implements:
+  `async def retrieve(query, k) -> list[RetrievalResult]`. `run_sync` is a thin
+  convenience for synchronous callers.
+- `IntentLabel` (9 classes) / `IntentResult`.
+- Ingestion-contract schemas — pydantic models for the JSON an upstream
+  ingestion/parsing project emits (chunks, product graph, document metadata).
+  The contract is defined by *shape*, not by importing the producer, so any
+  project emitting these shapes can feed this layer. Models set `extra="ignore"`
+  to stay resilient to upstream format drift.
+
+### `intent_classification`
+
+A prompt-based classifier over any `langchain-core` `BaseChatModel`. It returns
+one `IntentResult` and nothing more — the label → strategy mapping is the
+consuming project's job.
+
+```python
+from retrieval.modules.intent_classification import (
+    LLMIntentClassifier, build_default_chat_model,
+)
+
+clf = LLMIntentClassifier(build_default_chat_model())
+result = await clf.classify("de1000 fiyati ne kadar")   # -> IntentResult
+```
+
+In tests, inject a fake `BaseChatModel` instead of the factory — no network,
+no model download.
+
+### `db_query`
+
+Retrieval by generating SQL and running it. A natural-language query is turned
+into a SQL string by the [`text2sql-engine`](https://pypi.org/project/text2sql-engine/)
+package (a 2-stage LLM pipeline), that SQL runs against a **ready-made**
+database, and the rows come back as `RetrievalResult` items.
+
+```python
+from retrieval.modules.db_query import build_default_retriever
+
+retriever = build_default_retriever(db_path="specs.db")
+results = await retriever.retrieve("operating temperature of DE9001", k=5)
+```
+
+Two injected seams keep it testable and dependency-isolated:
+
+- `SqlGenerator` (NL → SQL) — the production impl wraps a `text2sql` engine
+  hitting a remote endpoint; unit tests inject a fake returning canned SQL.
+- `SqlExecutor` (SQL → rows) — the shipped `SQLiteExecutor` uses only stdlib
+  `sqlite3` and opens the database **read-only** by default, so a stray write in
+  generated SQL fails at the engine level.
+
+The score is a constant `1.0` (a SQL result is an exact match set, not a
+similarity ranking; ordering is the query's own `ORDER BY`). The full row is in
+`RetrievalResult.metadata`. This module connects to an existing database — it
+does not build one.
+
+## Inference & the GPU rule
+
+Model inference (LLM/embedding) is expected to run on a **separate machine
+behind an OpenAI-compatible endpoint**. This library only sends requests to that
+endpoint; it never downloads models or runs local inference. The default test
+run (`pytest`) is fully mocked and never reaches a network endpoint — tests that
+hit a live endpoint are marked `integration` and skipped by default.
+
+## Development
+
+```bash
+pip install -e ".[all,dev]"
+pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

mkd_retriever-0.1.0/pyproject.toml

@@ -0,0 +1,116 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name on PyPI. The IMPORT name stays `retrieval`:
+#     pip install mkd-retriever   ->   import retrieval
+name = "mkd-retriever"
+version = "0.1.0"
+description = "Modular, project-agnostic RAG retrieval layer: independent retrieval strategies behind a small shared core."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Mehmet Kaan Durupunar" }]
+keywords = [
+    "rag",
+    "retrieval",
+    "information-retrieval",
+    "intent-classification",
+    "text-to-sql",
+    "llm",
+    "nlp",
+    "modular",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Text Processing :: Linguistic",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    # Kept minimal on purpose: only what core/ (shared interfaces + schemas)
+    # actually needs. Anything a specific retrieval method needs goes into
+    # that method's own extra below, never here.
+    "pydantic>=2",
+    "python-dotenv>=1",
+    # Thin abstraction layer only (Embeddings/VectorStore/chat interfaces).
+    # Heavy integrations (langchain-openai, langgraph, store clients, ...)
+    # belong in module extras below — never here. See ARCHITECTURE.md #8.
+    "langchain-core>=0.3",
+]
+
+# Each retrieval method is an installable extra. A consumer (or a dev working
+# on one method) installs only what that method needs:
+#   pip install "mkd-retriever[intent_classification]"
+#   pip install "mkd-retriever[db_query]"
+# No extra should ever depend on another extra — that dependency belongs in
+# `dependencies` above (shared/core) instead, or the boundary is wrong.
+[project.optional-dependencies]
+top_n = []
+query_rewriting = []
+intent_classification = [
+    # v1 backend calls a remote OpenAI-compatible endpoint (e.g. Ollama /v1)
+    # via LangChain's ChatOpenAI. langchain-core is in base deps; only the
+    # heavy integration lives here (ARCHITECTURE.md #8).
+    "langchain-openai>=0.2",
+]
+raptor = []
+agentic = []
+db_query = [
+    # SQL is generated by the text2sql-engine package (import name: text2sql):
+    # a 2-stage LLM pipeline that produces a SQL string and never touches a DB.
+    # We run that SQL locally with the stdlib sqlite3 (no dep). The [openai]
+    # extra pulls the OpenAI SDK to talk to a remote OpenAI-compatible endpoint
+    # (e.g. Ollama /v1) — the only heavy piece, isolated here (ARCHITECTURE.md #3).
+    "text2sql-engine[openai]>=0.2",
+]
+eval = []
+
+# Everything the implemented modules need, in one shot.
+all = [
+    "langchain-openai>=0.2",
+    "text2sql-engine[openai]>=0.2",
+]
+
+dev = [
+    "pytest>=8",
+    "ruff>=0.6",
+    "build>=1",
+    "twine>=5",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/mkd-retriever/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# Ship the PEP 561 marker so downstream type-checkers see this as a typed package.
+"retrieval" = ["py.typed"]
+
+[tool.setuptools]
+license-files = ["LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# GPU/inference rule (CLAUDE.md): the default run never touches a real endpoint.
+# Integration tests that hit a live inference endpoint are marked `integration`
+# and skipped by default — run them only on the GPU machine with `-m integration`.
+addopts = "-m 'not integration'"
+markers = [
+    "integration: hits a real inference endpoint; run only on the GPU machine",
+]
+
+[tool.ruff]
+line-length = 100
+src = ["src"]

mkd_retriever-0.1.0/setup.cfg

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

mkd_retriever-0.1.0/src/mkd_retriever.egg-info/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: mkd-retriever
+Version: 0.1.0
+Summary: Modular, project-agnostic RAG retrieval layer: independent retrieval strategies behind a small shared core.
+Author: Mehmet Kaan Durupunar
+License: MIT
+Project-URL: Homepage, https://pypi.org/project/mkd-retriever/
+Keywords: rag,retrieval,information-retrieval,intent-classification,text-to-sql,llm,nlp,modular
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dotenv>=1
+Requires-Dist: langchain-core>=0.3
+Provides-Extra: top-n
+Provides-Extra: query-rewriting
+Provides-Extra: intent-classification
+Requires-Dist: langchain-openai>=0.2; extra == "intent-classification"
+Provides-Extra: raptor
+Provides-Extra: agentic
+Provides-Extra: db-query
+Requires-Dist: text2sql-engine[openai]>=0.2; extra == "db-query"
+Provides-Extra: eval
+Provides-Extra: all
+Requires-Dist: langchain-openai>=0.2; extra == "all"
+Requires-Dist: text2sql-engine[openai]>=0.2; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# mkd-retriever
+
+A **modular, project-agnostic RAG retrieval layer**. Several retrieval
+strategies — intent classification, text-to-SQL database query, and more to
+come (top-N vector search, query rewriting, RAPTOR, agentic flows) — live side
+by side in one package **without depending on one another**.
+
+The PyPI name is `mkd-retriever`; the import name is `retrieval`
+(`import retrieval`).
+
+```bash
+pip install mkd-retriever                        # core only
+pip install "mkd-retriever[intent_classification]"
+pip install "mkd-retriever[db_query]"
+pip install "mkd-retriever[all]"                 # everything implemented so far
+```
+
+## Why it is built this way
+
+Building retrieval methods on top of one another is a Jenga tower: changing or
+removing one piece topples the rest. Instead, every method is an **independent
+module**. The hard rules (enforced, see [`ARCHITECTURE.md`](./ARCHITECTURE.md)):
+
+1. **A module never imports another module.** Cross-module communication is the
+   consuming project's job, not this library's.
+2. **Everything shared lives in `retrieval.core`, and core stays small.** Only
+   minimal interfaces and common data schemas — never a module's implementation
+   detail. The dependency arrow is always *module → core*.
+3. **Dependencies are isolated per module.** Each module has its own
+   optional-dependency group; a library one module needs never leaks into
+   another module's environment.
+4. **Each module is understandable and testable on its own.**
+5. **Intent classification only returns a label — it does not route.** Mapping a
+   label to a retrieval method is the consuming project's decision.
+
+## What's inside
+
+```
+retrieval/
+  core/        shared interfaces + ingestion-contract schemas (small, stable)
+  eval/        golden-set format + metrics + async runner (cross-cutting)
+  modules/
+    intent_classification/   query -> intent label   (usable)
+    db_query/                query -> SQL -> rows     (usable)
+    top_n/                   vector search            (planned)
+    query_rewriting/         rewriting / expansion    (planned)
+    raptor/                  hierarchical retrieval   (planned)
+    agentic/                 multi-step flows         (planned)
+```
+
+### `retrieval.core`
+
+The whole surface every module shares:
+
+- `RetrievalResult` — a single scored item, returned identically by every
+  backend (`id`, `score`, `text`, `metadata`).
+- `Retriever` — the one async method a backend implements:
+  `async def retrieve(query, k) -> list[RetrievalResult]`. `run_sync` is a thin
+  convenience for synchronous callers.
+- `IntentLabel` (9 classes) / `IntentResult`.
+- Ingestion-contract schemas — pydantic models for the JSON an upstream
+  ingestion/parsing project emits (chunks, product graph, document metadata).
+  The contract is defined by *shape*, not by importing the producer, so any
+  project emitting these shapes can feed this layer. Models set `extra="ignore"`
+  to stay resilient to upstream format drift.
+
+### `intent_classification`
+
+A prompt-based classifier over any `langchain-core` `BaseChatModel`. It returns
+one `IntentResult` and nothing more — the label → strategy mapping is the
+consuming project's job.
+
+```python
+from retrieval.modules.intent_classification import (
+    LLMIntentClassifier, build_default_chat_model,
+)
+
+clf = LLMIntentClassifier(build_default_chat_model())
+result = await clf.classify("de1000 fiyati ne kadar")   # -> IntentResult
+```
+
+In tests, inject a fake `BaseChatModel` instead of the factory — no network,
+no model download.
+
+### `db_query`
+
+Retrieval by generating SQL and running it. A natural-language query is turned
+into a SQL string by the [`text2sql-engine`](https://pypi.org/project/text2sql-engine/)
+package (a 2-stage LLM pipeline), that SQL runs against a **ready-made**
+database, and the rows come back as `RetrievalResult` items.
+
+```python
+from retrieval.modules.db_query import build_default_retriever
+
+retriever = build_default_retriever(db_path="specs.db")
+results = await retriever.retrieve("operating temperature of DE9001", k=5)
+```
+
+Two injected seams keep it testable and dependency-isolated:
+
+- `SqlGenerator` (NL → SQL) — the production impl wraps a `text2sql` engine
+  hitting a remote endpoint; unit tests inject a fake returning canned SQL.
+- `SqlExecutor` (SQL → rows) — the shipped `SQLiteExecutor` uses only stdlib
+  `sqlite3` and opens the database **read-only** by default, so a stray write in
+  generated SQL fails at the engine level.
+
+The score is a constant `1.0` (a SQL result is an exact match set, not a
+similarity ranking; ordering is the query's own `ORDER BY`). The full row is in
+`RetrievalResult.metadata`. This module connects to an existing database — it
+does not build one.
+
+## Inference & the GPU rule
+
+Model inference (LLM/embedding) is expected to run on a **separate machine
+behind an OpenAI-compatible endpoint**. This library only sends requests to that
+endpoint; it never downloads models or runs local inference. The default test
+run (`pytest`) is fully mocked and never reaches a network endpoint — tests that
+hit a live endpoint are marked `integration` and skipped by default.
+
+## Development
+
+```bash
+pip install -e ".[all,dev]"
+pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).