Skip to content

armgit / LEANN

Public Imported from GitHub
0

[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.

feat(cli): add --metadata-filters flag to leann ask (#316)

Leoyd99714d0327f
diff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.py
index 65dbca6..15a8a18 100644
--- a/packages/leann-core/src/leann/cli.py
+++ b/packages/leann-core/src/leann/cli.py
@@ -562,6 +562,17 @@ Examples:
default=None,
help="API key for cloud LLM providers (OpenAI, Anthropic)",
)
+ ask_parser.add_argument(
+ "--metadata-filters",
+ type=str,
+ default=None,
+ help=(
+ "Filter retrieved chunks by metadata fields before answering (JSON string). "
+ 'Format: \'{"field": {"operator": value}}\'. '
+ "Operators: ==, !=, <, <=, >, >=, in, not_in, contains, starts_with, ends_with. "
+ 'Example: \'{"chapter": {"<=": 5}, "genre": {"==": "fiction"}}\''
+ ),
+ )
# React command (multiturn retrieval agent)
react_parser = subparsers.add_parser(
@@ -2840,6 +2851,24 @@ Examples:
if resolved_api_key:
llm_config["api_key"] = resolved_api_key
+ # Parse --metadata-filters JSON string (mirrors `leann search`).
+ # Run before constructing LeannChat so invalid filters fail fast without
+ # spinning up an embedding server.
+ metadata_filters = None
+ raw_filters = getattr(args, "metadata_filters", None)
+ if raw_filters:
+ try:
+ metadata_filters = json.loads(raw_filters)
+ if not isinstance(metadata_filters, dict):
+ print(
+ "Error: --metadata-filters must be a JSON object, "
+ 'e.g. \'{"chapter": {"<=": 5}}\''
+ )
+ return
+ except json.JSONDecodeError as e:
+ print(f"Error: --metadata-filters is not valid JSON: {e}")
+ return
+
chat = LeannChat(index_path=index_path, llm_config=llm_config)
llm_kwargs: dict[str, Any] = {}
@@ -2856,6 +2885,7 @@ Examples:
prune_ratio=args.prune_ratio,
recompute_embeddings=args.recompute_embeddings,
pruning_strategy=args.pruning_strategy,
+ metadata_filters=metadata_filters,
llm_kwargs=llm_kwargs,
)
query_completion_time = time.time() - query_start_time
diff --git a/tests/test_cli_ask.py b/tests/test_cli_ask.py
index 6f71e89..6cac456 100644
--- a/tests/test_cli_ask.py
+++ b/tests/test_cli_ask.py
@@ -1,3 +1,6 @@
+import asyncio
+import json
+
from leann.cli import LeannCLI
@@ -12,3 +15,66 @@ def test_cli_ask_accepts_positional_query(tmp_path, monkeypatch):
assert args.command == "ask"
assert args.index_name == "my-docs"
assert args.query == "Where are prompts configured?"
+
+
+def test_cli_ask_parses_metadata_filters_flag():
+ cli = LeannCLI()
+ parser = cli.create_parser()
+
+ filters_json = '{"chapter": {"<=": 5}, "genre": {"==": "fiction"}}'
+ args = parser.parse_args(
+ ["ask", "my-docs", "Summarize early chapters", "--metadata-filters", filters_json]
+ )
+
+ assert args.command == "ask"
+ assert args.metadata_filters == filters_json
+ # The raw string parses to the expected dict so downstream consumers can rely on it.
+ assert json.loads(args.metadata_filters) == {
+ "chapter": {"<=": 5},
+ "genre": {"==": "fiction"},
+ }
+
+
+def test_cli_ask_metadata_filters_default_is_none():
+ cli = LeannCLI()
+ parser = cli.create_parser()
+
+ args = parser.parse_args(["ask", "my-docs", "any query"])
+
+ assert args.metadata_filters is None
+
+
+def test_cli_ask_rejects_invalid_metadata_filters_json(tmp_path, monkeypatch, capsys):
+ monkeypatch.chdir(tmp_path)
+
+ cli = LeannCLI()
+ parser = cli.create_parser()
+ # Set up an empty index dir so the existence check passes and we reach the JSON parser.
+ index_dir = tmp_path / ".leann" / "indexes" / "my-docs"
+ index_dir.mkdir(parents=True)
+ (index_dir / "documents.leann.meta.json").write_text("{}")
+
+ args = parser.parse_args(["ask", "my-docs", "any query", "--metadata-filters", "not-json"])
+
+ asyncio.run(cli.ask_questions(args))
+
+ captured = capsys.readouterr()
+ assert "--metadata-filters is not valid JSON" in captured.out
+
+
+def test_cli_ask_rejects_non_object_metadata_filters(tmp_path, monkeypatch, capsys):
+ monkeypatch.chdir(tmp_path)
+
+ cli = LeannCLI()
+ parser = cli.create_parser()
+ index_dir = tmp_path / ".leann" / "indexes" / "my-docs"
+ index_dir.mkdir(parents=True)
+ (index_dir / "documents.leann.meta.json").write_text("{}")
+
+ # A valid JSON value that is not an object (dict) — must be rejected.
+ args = parser.parse_args(["ask", "my-docs", "any query", "--metadata-filters", "[1, 2, 3]"])
+
+ asyncio.run(cli.ask_questions(args))
+
+ captured = capsys.readouterr()
+ assert "--metadata-filters must be a JSON object" in captured.out