qql-cli 0.1.0__py3-none-any.whl

qql/__init__.py

@@ -0,0 +1,45 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("qql-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+from .config import DEFAULT_MODEL, QQLConfig, load_config
+from .exceptions import QQLError, QQLRuntimeError, QQLSyntaxError
+from .executor import ExecutionResult, Executor
+from .lexer import Lexer
+from .parser import Parser
+
+__all__ = [
+    "__version__",
+    "QQLConfig",
+    "QQLError",
+    "QQLRuntimeError",
+    "QQLSyntaxError",
+    "ExecutionResult",
+    "Executor",
+    "Lexer",
+    "Parser",
+    "run_query",
+]
+
+
+def run_query(
+    query: str,
+    url: str = "http://localhost:6333",
+    secret: str | None = None,
+    default_model: str | None = None,
+) -> ExecutionResult:
+    """Convenience function for programmatic use."""
+    from qdrant_client import QdrantClient
+
+    cfg = QQLConfig(
+        url=url,
+        secret=secret,
+        default_model=default_model or DEFAULT_MODEL,
+    )
+    client = QdrantClient(url=url, api_key=secret)
+    tokens = Lexer().tokenize(query)
+    node = Parser(tokens).parse()
+    return Executor(client, cfg).execute(node)

qql/ast_nodes.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class InsertStmt:
+    collection: str
+    values: dict[str, Any]  # must contain "text" key
+    model: str | None  # None → use default
+
+
+@dataclass(frozen=True)
+class CreateCollectionStmt:
+    collection: str
+
+
+@dataclass(frozen=True)
+class DropCollectionStmt:
+    collection: str
+
+
+@dataclass(frozen=True)
+class ShowCollectionsStmt:
+    pass
+
+
+@dataclass(frozen=True)
+class SearchStmt:
+    collection: str
+    query_text: str
+    limit: int
+    model: str | None
+
+
+@dataclass(frozen=True)
+class DeleteStmt:
+    collection: str
+    point_id: str | int
+
+
+# Union type for all statement nodes
+ASTNode = (
+    InsertStmt
+    | CreateCollectionStmt
+    | DropCollectionStmt
+    | ShowCollectionsStmt
+    | SearchStmt
+    | DeleteStmt
+)

qql/cli.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.console import Console
+from rich.prompt import Prompt
+from rich.table import Table
+
+from .config import delete_config, load_config, save_config, QQLConfig
+from .exceptions import QQLError
+from .executor import Executor
+from .lexer import Lexer
+from .parser import Parser
+
+console = Console()
+err_console = Console(stderr=True)
+
+HELP_TEXT = """
+[bold cyan]QQL — Qdrant Query Language[/bold cyan]
+
+Available statements:
+
+  [yellow]INSERT INTO COLLECTION[/yellow] <name> [yellow]VALUES[/yellow] {[yellow]'text'[/yellow]: '...', ...}
+      Insert a point. 'text' is required and auto-vectorized.
+      Optional: [yellow]USING MODEL[/yellow] '<model>'
+
+  [yellow]CREATE COLLECTION[/yellow] <name>
+      Create a new collection (uses default model dimensions).
+
+  [yellow]DROP COLLECTION[/yellow] <name>
+      Delete a collection and all its points.
+
+  [yellow]SHOW COLLECTIONS[/yellow]
+      List all collections in the connected Qdrant instance.
+
+  [yellow]SEARCH[/yellow] <name> [yellow]SIMILAR TO[/yellow] '<text>' [yellow]LIMIT[/yellow] <n>
+      Semantic search by vector similarity.
+      Optional: [yellow]USING MODEL[/yellow] '<model>'
+
+  [yellow]DELETE FROM[/yellow] <name> [yellow]WHERE id =[/yellow] '<id>'
+      Delete a point by its ID.
+
+Type [bold]exit[/bold] or [bold]quit[/bold] to leave the shell.
+"""
+
+
+# ── CLI entry point ────────────────────────────────────────────────────────────
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def main(ctx: click.Context) -> None:
+    """QQL — Qdrant Query Language CLI."""
+    ctx.ensure_object(dict)
+    if ctx.invoked_subcommand is None:
+        # No subcommand → load saved config and launch REPL
+        cfg = load_config()
+        if cfg is None:
+            err_console.print(
+                "[bold red]Not connected.[/bold red] "
+                "Run: [bold]qql connect --url <url>[/bold]"
+            )
+            sys.exit(1)
+        _launch_repl(cfg)
+
+
+# ── connect ────────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.option("--url", required=True, help="Qdrant instance URL, e.g. http://localhost:6333")
+@click.option("--secret", default=None, help="API key / secret (optional)")
+def connect(url: str, secret: str | None) -> None:
+    """Connect to a Qdrant instance and launch the QQL shell."""
+    from qdrant_client import QdrantClient
+
+    console.print(f"Connecting to [bold]{url}[/bold]...")
+
+    try:
+        client = QdrantClient(url=url, api_key=secret)
+        client.get_collections()  # validate connection
+    except Exception as e:
+        err_console.print(f"[bold red]Connection failed:[/bold red] {e}")
+        sys.exit(1)
+
+    cfg = QQLConfig(url=url, secret=secret)
+    save_config(cfg)
+    console.print(f"[bold green]Connected.[/bold green] Config saved to ~/.qql/config.json\n")
+    _launch_repl(cfg)
+
+
+# ── disconnect ─────────────────────────────────────────────────────────────────
+
+@main.command()
+def disconnect() -> None:
+    """Remove saved connection config."""
+    delete_config()
+    console.print("Disconnected. Config removed.")
+
+
+# ── REPL ───────────────────────────────────────────────────────────────────────
+
+def _launch_repl(cfg: QQLConfig) -> None:
+    from qdrant_client import QdrantClient
+
+    try:
+        client = QdrantClient(url=cfg.url, api_key=cfg.secret)
+        client.get_collections()
+    except Exception as e:
+        err_console.print(f"[bold red]Could not connect to {cfg.url}:[/bold red] {e}")
+        err_console.print("Run [bold]qql connect --url <url>[/bold] to update your connection.")
+        sys.exit(1)
+
+    executor = Executor(client, cfg)
+
+    console.print(f"[bold cyan]QQL Interactive Shell[/bold cyan]  •  {cfg.url}")
+    console.print("Type [bold]help[/bold] for available commands or [bold]exit[/bold] to quit.\n")
+
+    while True:
+        try:
+            query = Prompt.ask("[bold green]qql>[/bold green]").strip()
+        except (EOFError, KeyboardInterrupt):
+            console.print("\nBye.")
+            break
+
+        if not query:
+            continue
+
+        low = query.lower()
+        if low in ("exit", "quit", "\\q", ":q"):
+            console.print("Bye.")
+            break
+        if low in ("help", "\\h", "?"):
+            console.print(HELP_TEXT)
+            continue
+
+        _run_and_print(executor, query)
+
+
+def _run_and_print(executor: Executor, query: str) -> None:
+    try:
+        tokens = Lexer().tokenize(query)
+        node = Parser(tokens).parse()
+        result = executor.execute(node)
+    except QQLError as e:
+        err_console.print(f"[bold red]Error:[/bold red] {e}")
+        return
+    except Exception as e:
+        err_console.print(f"[bold red]Unexpected error:[/bold red] {e}")
+        return
+
+    if not result.success:
+        err_console.print(f"[bold red]Failed:[/bold red] {result.message}")
+        return
+
+    console.print(f"[bold green]✓[/bold green] {result.message}")
+
+    if result.data is None:
+        return
+
+    # Pretty-print collections list
+    if isinstance(result.data, list) and all(isinstance(x, str) for x in result.data):
+        if result.data:
+            table = Table(show_header=True, header_style="bold cyan")
+            table.add_column("Collection")
+            for name in result.data:
+                table.add_row(name)
+            console.print(table)
+        return
+
+    # Pretty-print search results
+    if isinstance(result.data, list) and result.data and isinstance(result.data[0], dict) and "score" in result.data[0]:
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("Score", justify="right")
+        table.add_column("ID")
+        table.add_column("Payload")
+        for hit in result.data:
+            table.add_row(
+                str(hit["score"]),
+                hit["id"],
+                str(hit["payload"]),
+            )
+        console.print(table)
+        return
+
+    # Fallback: print data as-is
+    console.print(result.data)

qql/config.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".qql"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+DEFAULT_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+
+
+@dataclass
+class QQLConfig:
+    url: str
+    secret: str | None = None
+    default_model: str = DEFAULT_MODEL
+
+
+def save_config(cfg: QQLConfig) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    with CONFIG_PATH.open("w") as f:
+        json.dump(asdict(cfg), f, indent=2)
+
+
+def load_config() -> QQLConfig | None:
+    """Return saved config, or None if not yet connected."""
+    if not CONFIG_PATH.exists():
+        return None
+    with CONFIG_PATH.open() as f:
+        data = json.load(f)
+    return QQLConfig(
+        url=data["url"],
+        secret=data.get("secret"),
+        default_model=data.get("default_model", DEFAULT_MODEL),
+    )
+
+
+def delete_config() -> None:
+    if CONFIG_PATH.exists():
+        CONFIG_PATH.unlink()

qql/embedder.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+
+class Embedder:
+    DEFAULT_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+
+    # Class-level cache: model_name → TextEmbedding instance
+    # Avoids reloading the same model across multiple Embedder() calls in one session.
+    _cache: dict[str, object] = {}
+
+    def __init__(self, model_name: str = DEFAULT_MODEL) -> None:
+        self._model_name = model_name
+        if model_name not in Embedder._cache:
+            # Import here so the module loads even without fastembed installed
+            # (the error surfaces only when embedding is actually attempted)
+            from fastembed import TextEmbedding
+
+            Embedder._cache[model_name] = TextEmbedding(model_name)
+        self._model = Embedder._cache[model_name]
+
+    def embed(self, text: str) -> list[float]:
+        """Embed a single string and return a plain list[float]."""
+        result = next(iter(self._model.embed([text])))  # type: ignore[attr-defined]
+        return result.tolist()
+
+    def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Embed multiple strings."""
+        return [v.tolist() for v in self._model.embed(texts)]  # type: ignore[attr-defined]
+
+    @property
+    def dimensions(self) -> int:
+        """Return the vector dimensionality by embedding a dummy string."""
+        return len(self.embed("probe"))

qql/exceptions.py

@@ -0,0 +1,15 @@
+class QQLError(Exception):
+    """Base for all QQL errors."""
+
+
+class QQLSyntaxError(QQLError):
+    """Raised by Lexer or Parser for malformed input."""
+
+    def __init__(self, message: str, pos: int | None = None) -> None:
+        self.pos = pos
+        suffix = f" (at position {pos})" if pos is not None else ""
+        super().__init__(f"{message}{suffix}")
+
+
+class QQLRuntimeError(QQLError):
+    """Raised by Executor when the operation fails."""

qql/executor.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+from qdrant_client import QdrantClient
+from qdrant_client.http.exceptions import UnexpectedResponse
+from qdrant_client.models import Distance, PointStruct, VectorParams
+
+from .ast_nodes import (
+    ASTNode,
+    CreateCollectionStmt,
+    DeleteStmt,
+    DropCollectionStmt,
+    InsertStmt,
+    SearchStmt,
+    ShowCollectionsStmt,
+)
+from .config import QQLConfig
+from .embedder import Embedder
+from .exceptions import QQLRuntimeError
+
+
+@dataclass
+class ExecutionResult:
+    success: bool
+    message: str
+    data: Any = None
+
+
+class Executor:
+    def __init__(self, client: QdrantClient, config: QQLConfig) -> None:
+        self._client = client
+        self._config = config
+
+    def execute(self, node: ASTNode) -> ExecutionResult:
+        if isinstance(node, InsertStmt):
+            return self._execute_insert(node)
+        if isinstance(node, CreateCollectionStmt):
+            return self._execute_create(node)
+        if isinstance(node, DropCollectionStmt):
+            return self._execute_drop(node)
+        if isinstance(node, ShowCollectionsStmt):
+            return self._execute_show(node)
+        if isinstance(node, SearchStmt):
+            return self._execute_search(node)
+        if isinstance(node, DeleteStmt):
+            return self._execute_delete(node)
+        raise QQLRuntimeError(f"Unknown AST node type: {type(node)}")
+
+    # ── Statement executors ───────────────────────────────────────────────
+
+    def _execute_insert(self, node: InsertStmt) -> ExecutionResult:
+        if "text" not in node.values:
+            raise QQLRuntimeError("INSERT requires a 'text' field in VALUES")
+
+        model_name = node.model or self._config.default_model
+        embedder = Embedder(model_name)
+        vector = embedder.embed(node.values["text"])
+
+        self._ensure_collection(node.collection, len(vector))
+
+        point_id = str(uuid.uuid4())
+        payload = dict(node.values)
+
+        try:
+            self._client.upsert(
+                collection_name=node.collection,
+                points=[PointStruct(id=point_id, vector=vector, payload=payload)],
+            )
+        except UnexpectedResponse as e:
+            raise QQLRuntimeError(f"Qdrant error during INSERT: {e}") from e
+
+        return ExecutionResult(
+            success=True,
+            message=f"Inserted 1 point [{point_id}]",
+            data={"id": point_id, "collection": node.collection},
+        )
+
+    def _execute_create(self, node: CreateCollectionStmt) -> ExecutionResult:
+        if self._client.collection_exists(node.collection):
+            return ExecutionResult(
+                success=True,
+                message=f"Collection '{node.collection}' already exists",
+            )
+        # Create with default model dimensions
+        embedder = Embedder(self._config.default_model)
+        dims = embedder.dimensions
+        self._client.create_collection(
+            collection_name=node.collection,
+            vectors_config=VectorParams(size=dims, distance=Distance.COSINE),
+        )
+        return ExecutionResult(
+            success=True,
+            message=f"Collection '{node.collection}' created ({dims}-dimensional vectors, cosine distance)",
+        )
+
+    def _execute_drop(self, node: DropCollectionStmt) -> ExecutionResult:
+        if not self._client.collection_exists(node.collection):
+            raise QQLRuntimeError(f"Collection '{node.collection}' does not exist")
+        self._client.delete_collection(node.collection)
+        return ExecutionResult(
+            success=True,
+            message=f"Collection '{node.collection}' dropped",
+        )
+
+    def _execute_show(self, node: ShowCollectionsStmt) -> ExecutionResult:
+        response = self._client.get_collections()
+        names = [c.name for c in response.collections]
+        return ExecutionResult(
+            success=True,
+            message=f"{len(names)} collection(s) found",
+            data=names,
+        )
+
+    def _execute_search(self, node: SearchStmt) -> ExecutionResult:
+        if not self._client.collection_exists(node.collection):
+            raise QQLRuntimeError(f"Collection '{node.collection}' does not exist")
+
+        model_name = node.model or self._config.default_model
+        embedder = Embedder(model_name)
+        vector = embedder.embed(node.query_text)
+
+        try:
+            response = self._client.query_points(
+                collection_name=node.collection,
+                query=vector,
+                limit=node.limit,
+            )
+        except UnexpectedResponse as e:
+            raise QQLRuntimeError(f"Qdrant error during SEARCH: {e}") from e
+
+        results = [
+            {"id": str(h.id), "score": round(h.score, 4), "payload": h.payload}
+            for h in response.points
+        ]
+        return ExecutionResult(
+            success=True,
+            message=f"Found {len(results)} result(s)",
+            data=results,
+        )
+
+    def _execute_delete(self, node: DeleteStmt) -> ExecutionResult:
+        if not self._client.collection_exists(node.collection):
+            raise QQLRuntimeError(f"Collection '{node.collection}' does not exist")
+
+        from qdrant_client.models import PointIdsList
+
+        try:
+            self._client.delete(
+                collection_name=node.collection,
+                points_selector=PointIdsList(points=[node.point_id]),
+            )
+        except UnexpectedResponse as e:
+            raise QQLRuntimeError(f"Qdrant error during DELETE: {e}") from e
+
+        return ExecutionResult(
+            success=True,
+            message=f"Deleted point '{node.point_id}' from '{node.collection}'",
+        )
+
+    # ── Helpers ───────────────────────────────────────────────────────────
+
+    def _ensure_collection(self, name: str, vector_size: int) -> None:
+        """Create the collection if it doesn't exist. Raises on dimension mismatch."""
+        if self._client.collection_exists(name):
+            info = self._client.get_collection(name)
+            existing_size = info.config.params.vectors.size  # type: ignore[union-attr]
+            if existing_size != vector_size:
+                raise QQLRuntimeError(
+                    f"Vector dimension mismatch: collection '{name}' expects "
+                    f"{existing_size} dims, but model produces {vector_size} dims. "
+                    f"Specify a compatible model with USING MODEL '<model>'."
+                )
+        else:
+            self._client.create_collection(
+                collection_name=name,
+                vectors_config=VectorParams(size=vector_size, distance=Distance.COSINE),
+            )