[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.
Python aifaissgpt-osslangchainllama-indexllmlocalstorageoffline-firstollamaprivacypythonragretrieval-augmented-generationvector-databasevector-searchvectors
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.pyindex 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_timediff --git a/tests/test_cli_ask.py b/tests/test_cli_ask.pyindex 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