Metadata-Version: 2.4
Name: pyqql-edge
Version: 0.1.1
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Typing :: Typed
License-File: LICENSE
Summary: Local QQL execution for Python with qdrant-edge and FastEmbed
Keywords: qql,qdrant,vector-search,embeddings,edge
Home-Page: https://github.com/srimon12/qql-rs
Author-email: Srimon Danguria <srimon12mckv@gmail.com>
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/srimon12/qql-rs/tree/main/crates/pyqql-edge
Project-URL: Homepage, https://github.com/srimon12/qql-rs
Project-URL: Issues, https://github.com/srimon12/qql-rs/issues
Project-URL: Repository, https://github.com/srimon12/qql-rs

# pyqql-edge

Local QQL execution for Python — qdrant-edge + fastembed, zero network.

```python
import pyqql_edge

# Parser (same API as pyqql)
stmt = pyqql_edge.parse("QUERY 'hello' FROM docs LIMIT 10")[0]
tokens = pyqql_edge.tokenize("QUERY 'test' FROM docs")

# Discover local ONNX models
models = pyqql_edge.list_embedding_models()
# [{'name': 'BGESmallENV15', 'model_code': 'Xenova/bge-small-en-v1.5', 'dim': 384, ...}, ...]

# Edge execution — pick model (default BGESmallENV15 / 384-d)
exec = pyqql_edge.local_executor(
    "./qdrant_data",
    on_disk_payload=False,
    model="bge-small-en-v1.5",        # enum name, HF code, or short alias
    cache_dir="/var/cache/fastembed", # optional
)

# Schema-aware text auto-embed (dense-only, sparse-only, and hybrid)
exec.execute("CREATE COLLECTION docs HYBRID")
exec.execute(
    'UPSERT INTO docs VALUES {id: "550e8400-e29b-41d4-a716-446655440001", text: "hello"}'
)
result = exec.execute("QUERY 'hello' FROM docs USING dense LIMIT 10", on_error="stop")
```

`execute()` and `execute_async()` return the same `ExecutionReport` dict as
`pyqql`: `ok`, ordered `results`, `succeeded`, and `failed`.

Prebuilt wheels are provided for Linux x64, Windows x64, and Apple Silicon
macOS. ONNX Runtime does not provide the required macOS Intel artifact, so
`pyqql-edge` does not publish a Darwin x64 wheel.

## Edge gotchas

| Gotcha | Reality |
|--------|---------|
| Point IDs | Integers or UUIDs only — `"doc-1"` is rejected |
| Text UPSERT into an existing collection | Auto-embedding follows the schema: dense-only gets dense, sparse-only gets sparse, hybrid gets both |
| `QUERY 'text'` on HYBRID | Dense+sparse topology is ambiguous, so specify the target with `USING <vector_name>` |
| `GROUP BY` / shard keys | Rejected clearly; never silently ignored in edge mode |
| Model locked at `local_executor()` | `USING MODEL 'other'` mismatches fail |
| Client lifetime | Call `close()` (or use Python `with Client`) before deleting `data_dir` |

