python-nlql 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

nlql/__init__.py

@@ -2,10 +2,10 @@
 
 Quick start::
 
-    import nlql
+    from nlql import Engine
+    from nlql.embed import FakeEmbedder   # or OpenAIEmbedder(base_url=..., api_key=...)
 
-    # The embedder is injected — any OpenAI-compatible channel is one class + a base_url.
-    engine = nlql.Engine(nlql.FakeEmbedder())   # or Engine(OpenAIEmbedder(base_url=..., api_key=...))
+    engine = Engine(FakeEmbedder())
     engine.add_text("AI agents plan, use memory, and call tools.", metadata={"status": "published"})
 
     results = engine.search('''
@@ -17,9 +17,12 @@ Quick start::
     ''')
     for unit in results:
         print(unit.scores.get("rel"), unit.content)
+
+Backend implementations (embedders, stores, concrete rerankers) live in their
+submodules: `from nlql.embed import OpenAIEmbedder`, `from nlql.store import
+LocalStore`, `from nlql.rerank import CrossEncoderReranker`.
 """
 
-from nlql.embed import CachedEmbedder, EmbeddingCache, FakeEmbedder, OpenAIEmbedder
 from nlql.errors import (
     NLQLError,
     NLQLExecutionError,
@@ -33,7 +36,7 @@ from nlql.ir import Query, query_json_schema
 from nlql.lang import parse
 from nlql.model import Document, Modality, Payload, Unit
 from nlql.registry import GLOBAL_REGISTRY, Registry, register_function, register_splitter
-from nlql.rerank import CrossEncoderReranker, FakeReranker, Reranker
+from nlql.rerank import Reranker
 from nlql.sdk import (
     Engine,
     F,
@@ -46,7 +49,6 @@ from nlql.sdk import (
     select,
     similarity,
 )
-from nlql.store import LocalStore
 from nlql.types import Signature, TypeTag
 
 __version__ = "0.2.0"
@@ -72,17 +74,9 @@ __all__ = [
     "parse",
     "Query",
     "query_json_schema",
-    # embedders
-    "FakeEmbedder",
-    "OpenAIEmbedder",
-    "EmbeddingCache",
-    "CachedEmbedder",
-    # rerank
+    # rerank protocol (concrete rerankers in nlql.rerank)
     "Reranker",
-    "FakeReranker",
-    "CrossEncoderReranker",
-    # store & registry
-    "LocalStore",
+    # registry
     "Registry",
     "GLOBAL_REGISTRY",
     "register_function",

nlql/sdk/CLAUDE.md

@@ -13,7 +13,7 @@
 
 ```python
 import nlql
-engine = nlql.Engine(nlql.FakeEmbedder())        # 或 OpenAIEmbedder(base_url=..., api_key=...)
+engine = nlql.Engine(nlql.embed.FakeEmbedder())        # 或 OpenAIEmbedder(base_url=..., api_key=...)
 engine.add_text("...", metadata={"status": "published"})
 results = engine.search('SELECT SENTENCE LET rel = SIMILARITY(content, "x") WHERE rel >= 0.2 LIMIT 5')
 ```

nlql/sdk/engine.py

@@ -39,7 +39,8 @@ class Engine:
     :class:`~nlql.embed.OpenAIEmbedder` parameterized by ``base_url``; any other provider
     is just another :class:`~nlql.embed.base.Embedder` implementation::
 
-        from nlql import Engine, OpenAIEmbedder, FakeEmbedder
+        from nlql import Engine
+        from nlql.embed import FakeEmbedder, OpenAIEmbedder
 
         Engine(OpenAIEmbedder(base_url="https://your-gateway/v1", api_key="sk-..."))
         Engine(FakeEmbedder())                       # deterministic, offline (tests/demos)

{python_nlql-0.2.0.dist-info → python_nlql-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-nlql
-Version: 0.2.0
+Version: 0.3.0
 Summary: SQL-style semantic query language and retrieval middleware for Agents & RAG
 Project-URL: Repository, https://github.com/natural-language-query-language/python-nlql
 Author: Okysu
@@ -57,16 +57,18 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://natural-language-query-language.github.io/python-nlql/)
 
-NLQL 让你用类似 SQL 的语句做语义检索。把"从文本里找相关内容"这件事，变得像查数据库一样直接——相关度计算、过滤、排序写在一条查询里，不再需要拼凑 embedding 调用和后处理代码。
+**English** · [简体中文](README.zh-CN.md) · [在线文档](https://natural-language-query-language.github.io/python-nlql/)
 
-适合 Agent 与 RAG 应用：查询本身就是结构化数据，可以直接作为大模型的工具调用载体。
+NLQL lets you do semantic search with SQL-style statements. Relevance scoring, filtering, and sorting live in one query — no more scattered embedding calls and post-processing code.
 
-## 它长什么样
+Built for Agent and RAG applications: the query itself is structured data, usable directly as an LLM tool-call payload.
+
+## What it looks like
 
 ```python
 import nlql
 
-engine = nlql.Engine(nlql.FakeEmbedder())  # 或 OpenAIEmbedder，以及任意 Embedder 实现
+engine = nlql.Engine(nlql.embed.FakeEmbedder())  # or OpenAIEmbedder, or any Embedder
 engine.add_text("AI agents plan tasks and call tools.", metadata={"status": "published"})
 engine.add_text("Banana bread needs flour and sugar.", metadata={"status": "draft"})
 
@@ -80,54 +82,54 @@ for unit in engine.search('''
     print(f"{unit.scores['rel']:+.3f}  {unit.content}")
 ```
 
-语句和 SQL 几乎一样：`SELECT` 指定返回粒度，`LET` 算相关度，`WHERE` 过滤，`ORDER BY` / `LIMIT` 排序限量。
+The statement reads almost like SQL: `SELECT` sets the return granularity, `LET` computes relevance, `WHERE` filters, `ORDER BY` / `LIMIT` sort and cap.
 
-## 特性
+## Features
 
-- **一条语句表达完整意图** —— 相关度、过滤、排序集中在一处，不再散在业务代码里
-- **三种写法，结果一致** —— SQL 语句、Python 链式构造、JSON IR，都编译到同一份内部表示
-- **后端可插拔** —— 内置存储开箱即用；切换 Qdrant / Faiss / Chroma / HnswLib / pgvector 只需改一行
-- **召回 + 重排两段式** —— 向量召回后挂重排器，提升结果准确性
-- **多模态** —— 文本与图像在同一向量空间，用文字检索图像
-- **可解释** —— `engine.explain()` 输出查询的执行计划
+- **One statement, full intent** — relevance, filtering, and sorting in one place, not scattered across business code
+- **Three ways to write, identical results** — SQL statement, Python chained builder, or JSON IR; all compile to the same internal representation
+- **Pluggable backends** — built-in store works out of the box; switch to Qdrant / Faiss / Chroma / HnswLib / pgvector with one line
+- **Two-stage retrieval** — attach a reranker after recall for higher accuracy
+- **Multimodal** — text and images share one vector space; retrieve images with text
+- **Explainable** — `engine.explain()` prints the query plan
 
-## 安装
+## Installation
 
 ```bash
 pip install python-nlql
 ```
 
-可选依赖：
+Optional extras:
 
-| 命令 | 用途 |
+| Command | Purpose |
 |---|---|
-| `pip install "python-nlql[faiss]"` | Faiss 后端 |
-| `pip install "python-nlql[hnsw]"` | HnswLib 后端（适合大数据量） |
-| `pip install "python-nlql[qdrant]"` | Qdrant 后端 |
-| `pip install "python-nlql[chroma]"` | Chroma 后端 |
-| `pip install "python-nlql[pgvector]"` | Postgres + pgvector 后端 |
-| `pip install "python-nlql[local]"` | 本地 sentence-transformers / CLIP / cross-encoder |
-| `pip install "python-nlql[loaders]"` | 加载 DOCX / PDF 文件 |
+| `pip install "python-nlql[faiss]"` | Faiss backend |
+| `pip install "python-nlql[hnsw]"` | HnswLib backend (for large-scale data) |
+| `pip install "python-nlql[qdrant]"` | Qdrant backend |
+| `pip install "python-nlql[chroma]"` | Chroma backend |
+| `pip install "python-nlql[pgvector]"` | Postgres + pgvector backend |
+| `pip install "python-nlql[local]"` | local sentence-transformers / CLIP / cross-encoder |
+| `pip install "python-nlql[loaders]"` | DOCX / PDF file loaders |
 
-## 切换后端
+## Switching backends
 
-切换存储后端只需一行，写入与查询代码完全不变：
+One line; ingestion and query code stay the same:
 
 ```python
 from nlql.store.qdrant_store import QdrantStore
 engine = nlql.Engine(embedder, store=QdrantStore(location=":memory:"))
 ```
 
-## 文档
+## Documentation
 
-完整文档、教程与 API 参考：**https://natural-language-query-language.github.io/python-nlql/**
+Full docs, tutorials, and API reference: **https://natural-language-query-language.github.io/python-nlql/en/**
 
-- [快速开始](https://natural-language-query-language.github.io/python-nlql/content/tutorials/quickstart/)
-- [设计思路](https://natural-language-query-language.github.io/python-nlql/content/concepts/overview/)
-- [API 参考](https://natural-language-query-language.github.io/python-nlql/reference/sdk/)
-- [English docs](https://natural-language-query-language.github.io/python-nlql/en/)
+- [Quick start](https://natural-language-query-language.github.io/python-nlql/en/content/tutorials/quickstart/)
+- [Design](https://natural-language-query-language.github.io/python-nlql/en/content/concepts/overview/)
+- [API reference](https://natural-language-query-language.github.io/python-nlql/en/reference/sdk/)
+- [中文文档](https://natural-language-query-language.github.io/python-nlql/)
 
-更多示例见 [`examples/`](examples/) 目录。
+More examples in the [`examples/`](examples/) directory.
 
 ## License
 

{python_nlql-0.2.0.dist-info → python_nlql-0.3.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 nlql/CLAUDE.md,sha256=ozLOpVSZKBKdIGRTmW3-Z0s1lRg2x5M-MXcym2SGz4s,2588
-nlql/__init__.py,sha256=_kcLGw6cvBoyruungWPgy_YGMUoaCou-aEbVTe6FK60,2379
+nlql/__init__.py,sha256=sHsoP0lUOEq_wPi8SiT0XkyEI3AgVs6dfo5SpanRNfA,2253
 nlql/errors.md,sha256=a8GWN-09pkhu8VFEDT5BsfLH1sN_8kDULH6YljfMiOw,304
 nlql/errors.py,sha256=2qg39dYWL5SGtGNND6grj5ppOjqfcm1HtHKuopZ2ewY,1811
 nlql/embed/CLAUDE.md,sha256=l7li7CdGcRsGAdbuJv15Jequ_yfvZRKYzpiUMs3UIs0,3434
@@ -56,10 +56,10 @@ nlql/rerank/CLAUDE.md,sha256=dEvFU7vREJB1_CTemomGkIQGtYPJpMlvWoGIV1RYqDE,1716
 nlql/rerank/__init__.py,sha256=usS5iDG0xTi9koQraFdV2sM3p3LgiCBTtw8EcKMh0L0,273
 nlql/rerank/base.py,sha256=Xo19JVIei1EgcCE8jmSA1-qJ_4KSnM3hV9PaH-i9tns,1997
 nlql/rerank/cross_encoder.py,sha256=cunbcTFn-aWaAebEBj8gIVmOwT4lf9Sm4EWyOk-DaxI,1730
-nlql/sdk/CLAUDE.md,sha256=QM9PoHRXkKgkJ4TDeKzzQ7o_EZzwftSXIyNF7G371Ss,3579
+nlql/sdk/CLAUDE.md,sha256=MZ1X4K1qW3bz6iSMjJ9mPpYspkNHobxcSGBKtkq10co,3585
 nlql/sdk/__init__.py,sha256=mzXS75JVpyqvfQFXePycm6J_W5WiFoinRGJzGRBka4M,414
 nlql/sdk/builder.py,sha256=SPadR5a1HndofzekqlS32KHhVmWF1899iwI9pY-mQQM,5315
-nlql/sdk/engine.py,sha256=5QEQUYMukJi305zCg8YrHeDxbzgwuWNHF-wx62Ey9IE,12607
+nlql/sdk/engine.py,sha256=3YGoVEmRMbijne2bfYz5lbz9MypGhQLaLO0IqM6Q2NY,12637
 nlql/store/CLAUDE.md,sha256=ehnr8eJ2Icd2JH2pS5lwtHjH7sVY7Ie5Nb6DuOAKVMo,4681
 nlql/store/__init__.py,sha256=YdV-Io_dJovRYKz83GXoUUaell_EcfdPeK_B6FJEVlQ,266
 nlql/store/base.py,sha256=Vm4UIcLK_UfvvSr1_gbWVI1y8RJewttuY4c9WkBLxiY,2189
@@ -76,7 +76,7 @@ nlql/types/CLAUDE.md,sha256=U4_D5F54BtsxpKq67rX2z7PUJD26M4gs5GPUF_rFWnU,1721
 nlql/types/__init__.py,sha256=36nkQVDZ22qdR0HdWKPb06kkUByX1voRYFVyA2QxVU0,143
 nlql/types/coerce.py,sha256=lksqQekqyxBDRsxZkjBr77yp0-aZibKM-YDXmgtZwao,4039
 nlql/types/core.py,sha256=XJxbWTZplCTOfzVmS7LTokyVnuk-4HEj3N5ZLNPgppM,1290
-python_nlql-0.2.0.dist-info/METADATA,sha256=nA8Qj9v2h3UjKrILMUsiDsx4QifNAO4X45eyHQiW0V4,5618
-python_nlql-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-python_nlql-0.2.0.dist-info/licenses/LICENSE,sha256=9YZVpGmnIp5KhayjWX5DGOjhSZz_ap_iTZe4mRC4nSY,1062
-python_nlql-0.2.0.dist-info/RECORD,,
+python_nlql-0.3.0.dist-info/METADATA,sha256=nkgYLUK1gZkQW9YeBI8Bd0QILc1Mia9y8EwGeUJoRTc,5747
+python_nlql-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+python_nlql-0.3.0.dist-info/licenses/LICENSE,sha256=9YZVpGmnIp5KhayjWX5DGOjhSZz_ap_iTZe4mRC4nSY,1062
+python_nlql-0.3.0.dist-info/RECORD,,