fix(core): skip empty/invalid chunks before embedding; guard OpenAI embeddings

Avoid 400 errors from OpenAI when chunker yields empty strings by filtering
invalid texts in LeannBuilder.build_index. Add validation fail-fast in
OpenAI embedding path to surface upstream issues earlier. Keeps passages and
embeddings aligned during build.

Refs #54

README.md

@@ -426,21 +426,21 @@ Once the index is built, you can ask questions like:
 **The future of code assistance is here.** Transform your development workflow with LEANN's native MCP integration for Claude Code. Index your entire codebase and get intelligent code assistance directly in your IDE.
 
 **Key features:**
-- 🔍 **Semantic code search** across your entire project
+- 🔍 **Semantic code search** across your entire project, fully local index and lightweight
 - 📚 **Context-aware assistance** for debugging and development
 - 🚀 **Zero-config setup** with automatic language detection
 
 ```bash
 # Install LEANN globally for MCP integration
-uv tool install leann-core
+uv tool install leann-core --with leann
-
+claude mcp add --scope user leann-server -- leann_mcp
 # Setup is automatic - just start using Claude Code!
 ```
 Try our fully agentic pipeline with auto query rewriting, semantic search planning, and more:
 
 ![LEANN MCP Integration](assets/mcp_leann.png)
 
-**Ready to supercharge your coding?** [Complete Setup Guide →](packages/leann-mcp/README.md)
+**🔥 Ready to supercharge your coding?** [Complete Setup Guide →](packages/leann-mcp/README.md)
 
 ## 🖥️ Command Line Interface
 
@@ -457,7 +457,8 @@ leann --help
 **To make it globally available:**
 ```bash
 # Install the LEANN CLI globally using uv tool
-uv tool install leann-core
+uv tool install leann-core --with leann
+
 
 # Now you can use leann from anywhere without activating venv
 leann --help

packages/leann-core/src/leann/api.py

@@ -306,6 +306,23 @@ class LeannBuilder:
     def build_index(self, index_path: str):
         if not self.chunks:
             raise ValueError("No chunks added.")
+
+        # Filter out invalid/empty text chunks early to keep passage and embedding counts aligned
+        valid_chunks: list[dict[str, Any]] = []
+        skipped = 0
+        for chunk in self.chunks:
+            text = chunk.get("text", "")
+            if isinstance(text, str) and text.strip():
+                valid_chunks.append(chunk)
+            else:
+                skipped += 1
+        if skipped > 0:
+            print(
+                f"Warning: Skipping {skipped} empty/invalid text chunk(s). Processing {len(valid_chunks)} valid chunks"
+            )
+            self.chunks = valid_chunks
+            if not self.chunks:
+                raise ValueError("All provided chunks are empty or invalid. Nothing to index.")
         if self.dimensions is None:
             self.dimensions = len(
                 compute_embeddings(

packages/leann-core/src/leann/cli.py

@@ -148,12 +148,6 @@ Examples:
             type=str,
             help="Comma-separated list of file extensions to include (e.g., '.txt,.pdf,.pptx'). If not specified, uses default supported types.",
         )
-        build_parser.add_argument(
-            "--include-hidden",
-            action=argparse.BooleanOptionalAction,
-            default=False,
-            help="Include hidden files and directories (paths starting with '.') during indexing (default: false)",
-        )
         build_parser.add_argument(
             "--doc-chunk-size",
             type=int,
@@ -417,10 +411,7 @@ Examples:
                     print(f"  leann ask {example_name} --interactive")
 
     def load_documents(
-        self,
+        self, docs_paths: Union[str, list], custom_file_types: Union[str, None] = None
-        docs_paths: Union[str, list],
-        custom_file_types: Union[str, None] = None,
-        include_hidden: bool = False,
     ):
         # Handle both single path (string) and multiple paths (list) for backward compatibility
         if isinstance(docs_paths, str):
@@ -464,10 +455,6 @@ Examples:
 
         all_documents = []
 
-        # Helper to detect hidden path components
-        def _path_has_hidden_segment(p: Path) -> bool:
-            return any(part.startswith(".") and part not in [".", ".."] for part in p.parts)
-
         # First, process individual files if any
         if files:
             print(f"\n🔄 Processing {len(files)} individual file{'s' if len(files) > 1 else ''}...")
@@ -480,12 +467,8 @@ Examples:
 
                 files_by_dir = defaultdict(list)
                 for file_path in files:
-                    file_path_obj = Path(file_path)
+                    parent_dir = str(Path(file_path).parent)
-                    if not include_hidden and _path_has_hidden_segment(file_path_obj):
+                    files_by_dir[parent_dir].append(file_path)
-                        print(f"  ⚠️  Skipping hidden file: {file_path}")
-                        continue
-                    parent_dir = str(file_path_obj.parent)
-                    files_by_dir[parent_dir].append(str(file_path_obj))
 
                 # Load files from each parent directory
                 for parent_dir, file_list in files_by_dir.items():
@@ -496,7 +479,6 @@ Examples:
                         file_docs = SimpleDirectoryReader(
                             parent_dir,
                             input_files=file_list,
-                            # exclude_hidden only affects directory scans; input_files are explicit
                             filename_as_id=True,
                         ).load_data()
                         all_documents.extend(file_docs)
@@ -595,8 +577,6 @@ Examples:
                     # Check if file matches any exclude pattern
                     try:
                         relative_path = file_path.relative_to(docs_path)
-                        if not include_hidden and _path_has_hidden_segment(relative_path):
-                            continue
                         if self._should_exclude_file(relative_path, gitignore_matches):
                             continue
                     except ValueError:
@@ -624,7 +604,6 @@ Examples:
                         try:
                             default_docs = SimpleDirectoryReader(
                                 str(file_path.parent),
-                                exclude_hidden=not include_hidden,
                                 filename_as_id=True,
                                 required_exts=[file_path.suffix],
                             ).load_data()
@@ -653,7 +632,6 @@ Examples:
                     encoding="utf-8",
                     required_exts=code_extensions,
                     file_extractor={},  # Use default extractors
-                    exclude_hidden=not include_hidden,
                     filename_as_id=True,
                 ).load_data(show_progress=True)
 
@@ -803,9 +781,7 @@ Examples:
             paragraph_separator="\n\n",
         )
 
-        all_texts = self.load_documents(
+        all_texts = self.load_documents(docs_paths, args.file_types)
-            docs_paths, args.file_types, include_hidden=args.include_hidden
-        )
         if not all_texts:
             print("No documents found")
             return

packages/leann-core/src/leann/embedding_compute.py

@@ -244,6 +244,16 @@ def compute_embeddings_openai(texts: list[str], model_name: str) -> np.ndarray:
     except ImportError as e:
         raise ImportError(f"OpenAI package not installed: {e}")
 
+    # Validate input list
+    if not texts:
+        raise ValueError("Cannot compute embeddings for empty text list")
+    # Extra validation: abort early if any item is empty/whitespace
+    invalid_count = sum(1 for t in texts if not isinstance(t, str) or not t.strip())
+    if invalid_count > 0:
+        raise ValueError(
+            f"Found {invalid_count} empty/invalid text(s) in input. Upstream should filter before calling OpenAI."
+        )
+
     api_key = os.getenv("OPENAI_API_KEY")
     if not api_key:
         raise RuntimeError("OPENAI_API_KEY environment variable not set")

packages/leann-mcp/README.md

@@ -92,7 +92,7 @@ leann build docs-and-configs --docs $(git ls-files "*.md" "*.yml" "*.yaml" "*.js
 ```
 
 
-**Try this in Claude Code:**
+## **Try this in Claude Code:**
 ```
 Help me understand this codebase. List available indexes and search for authentication patterns.
 ```