refactor: comprehensive type safety and mypy compliance pass

- Standardized imports: Moved many method-level imports to the top-level across service.py, orchestrator.py, and monitor.py.
- Mypy resolution: Fixed numerous typing errors, including missing return types, Any annotations, and cast operations.
- Watchdog integration: Refined monitor.py to gracefully handle watchdog imports and type callbacks.
- Logic refinements: Updated evaluation scripts and added explicit assertions for VoyageAI clients.

Author: deepakdgupta1

.DS_Store

@@ -53,7 +53,7 @@ def create_app(store_path: str = ".", watch: bool = False) -> FastAPI:
 
     return app
 
-def start_server(host: str = "127.0.0.1", port: int = 8000, store_path: str = ".", watch: bool = False):  # type: ignore
+def start_server(host: str = "127.0.0.1", port: int = 8000, store_path: str = ".", watch: bool = False) -> None:
     """Start the uvicorn server with the configured app.
 
     Args:

src/knowcode/api/main.py

@@ -4,15 +4,16 @@
 
 from pathlib import Path
 from knowcode.indexing.scanner import Scanner
-from typing import Optional, TYPE_CHECKING
+from typing import Optional, TYPE_CHECKING, Any
 
 
 try:
     from watchdog.observers import Observer
     from watchdog.events import FileSystemEventHandler
 except ImportError:
-    Observer = None  # type: ignore
-    FileSystemEventHandler = object  # type: ignore
+    Observer = None  # type: ignore[assignment]
+    class FileSystemEventHandler: 
+        pass  # type: ignore[no-redef]
 
 if TYPE_CHECKING:
     from knowcode.indexing.background_indexer import BackgroundIndexer
@@ -30,7 +31,7 @@ def __init__(self, root_dir: str | Path, background_indexer: Optional["Backgroun
         """
         self.root_dir = Path(root_dir)
         self.background_indexer = background_indexer
-        self.observer = None
+        self.observer: Any = None
 
     def start(self) -> None:
         """Start watching the directory for changes."""
@@ -39,9 +40,9 @@ def start(self) -> None:
             return
 
         event_handler = IndexingHandler(self.background_indexer)
-        self.observer = Observer()  # type: ignore
-        self.observer.schedule(event_handler, str(self.root_dir), recursive=True)  # type: ignore
-        self.observer.start()  # type: ignore
+        self.observer = Observer()
+        self.observer.schedule(event_handler, str(self.root_dir), recursive=True)
+        self.observer.start()
 
     def stop(self) -> None:
         """Stop watching and join the observer thread."""
@@ -61,17 +62,17 @@ def __init__(self, background_indexer: Optional["BackgroundIndexer"]) -> None:
         """
         self.background_indexer = background_indexer
 
-    def on_modified(self, event):   # type: ignore
+    def on_modified(self, event: Any) -> None:
         """Handle modified file events."""
         if not event.is_directory:
             self._handle_change(event.src_path)
 
-    def on_created(self, event):   # type: ignore
+    def on_created(self, event: Any) -> None:
         """Handle created file events."""
         if not event.is_directory:
             self._handle_change(event.src_path)
 
-    def on_deleted(self, event):   # type: ignore
+    def on_deleted(self, event: Any) -> None:
         """Handle deleted file events."""
         if not event.is_directory and self.background_indexer:
             path = Path(event.src_path)
@@ -81,7 +82,7 @@ def on_deleted(self, event):   # type: ignore
                 else:
                     self._handle_change(event.src_path)
 
-    def on_moved(self, event):   # type: ignore
+    def on_moved(self, event: Any) -> None:
         """Handle moved file events."""
         if not event.is_directory and self.background_indexer:
             src_path = Path(event.src_path)

src/knowcode/indexing/monitor.py

@@ -6,7 +6,7 @@
 import hashlib
 import math
 import os
-from typing import Any
+from typing import Any, cast
 
 from knowcode.config import AppConfig
 from knowcode.data_models import EmbeddingConfig
@@ -135,14 +135,14 @@ def __init__(
         """
         super().__init__(config)
         self.api_key_env = api_key_env
-        self.client = None
+        self.client: Any = None
 
-    def _get_client(self):  # type: ignore
+    def _get_client(self) -> Any:  
         """Return an initialized VoyageAI client, loading credentials if needed."""
         if self.client is None:
             from knowcode.llm.voyageai_client import get_voyageai_client
 
-            self.client = get_voyageai_client(self.api_key_env)  # type: ignore
+            self.client = get_voyageai_client(self.api_key_env)  
 
         if self.client is None:
             raise ValueError(
@@ -157,7 +157,7 @@ def embed(self, texts: list[str]) -> list[list[float]]:
         if not texts:
             return []
 
-        client = self._get_client()  # type: ignore
+        client = self._get_client()  
         embeddings = client.embed(
             texts=texts,
             model=self.config.model_name,
@@ -169,11 +169,11 @@ def embed(self, texts: list[str]) -> list[list[float]]:
         if self.config.normalize:
             embeddings = [self._normalize(e) for e in embeddings]
 
-        return embeddings  # type: ignore
+        return cast(list[list[float]], embeddings)  
 
     def embed_single(self, text: str) -> list[float]:
         """Generate a query embedding for a single text input."""
-        client = self._get_client()  # type: ignore
+        client = self._get_client()  
         embeddings = client.embed(
             texts=[text],
             model=self.config.model_name,

src/knowcode/llm/embedding.py

@@ -80,7 +80,7 @@ def classify_query(query: str) -> Tuple[TaskType, float]:
     if max_score == 0:
         return TaskType.GENERAL, 0.0
 
-    best_type = max(scores, key=scores.get)  # type: ignore
+    best_type = max(scores, key=scores.__getitem__)  
 
     # Calculate confidence based on score relative to maximum possible
     # and gap to second-best

src/knowcode/llm/query_classifier.py

@@ -5,9 +5,8 @@
 - rerank-2.5: Cross-encoder reranking for improved relevance
 """
 
-from typing import Any
+from typing import Any, Optional, cast
 import os
-from typing import Optional
 
 # VoyageAI imports - requires: pip install voyageai
 try:
@@ -42,7 +41,7 @@ def __init__(
                 f"VoyageAI API key not found. Set {api_key_env} or pass api_key."
             )
 
-        self.client = voyageai.Client(api_key=self.api_key)  # type: ignore
+        self.client = voyageai.Client(api_key=self.api_key)  # type: ignore[attr-defined]  
 
     def embed(
         self,
@@ -65,7 +64,7 @@ def embed(
             model=model,
             input_type=input_type,
         )
-        return result.embeddings  # type: ignore
+        return cast(list[list[float]], result.embeddings)  
 
     def rerank(
         self,

src/knowcode/llm/voyageai_client.py

@@ -131,7 +131,7 @@ def _extract_entities(
 
     def _get_text(self, node: Any) -> str:
         """Get text content of a node."""
-        return node.text.decode("utf8")  # type: ignore
+        return str(node.text.decode("utf8"))  
 
     def _get_location(self, node: Any, file_path: Path) -> Location:
         """Get location object for a node."""

src/knowcode/parsers/base.py

@@ -173,7 +173,7 @@ def _parse_method(
 
         return entities, rels
 
-    def _walk_for_calls(self, node, source_id) -> Any:  # type: ignore
+    def _walk_for_calls(self, node: Any, source_id: str) -> Any:  
         rels = []
         cursor = node.walk()
         visited_children = False

src/knowcode/parsers/java_parser.py

@@ -289,7 +289,7 @@ def _parse_arrow_function(
 
         return entity, relationships
 
-    def _walk_for_calls(self, node, source_id) -> Any:  # type: ignore
+    def _walk_for_calls(self, node: Any, source_id: str) -> Any:  
         """Recursive walk to find call_expression.
         
         Note: We use a cursor walk here which is significantly more performant 
@@ -325,7 +325,7 @@ def _walk_for_calls(self, node, source_id) -> Any:  # type: ignore
 
         return rels
 
-    def _extract_call(self, node, source_id) -> Any:  # type: ignore
+    def _extract_call(self, node: Any, source_id: str) -> Any:  
         # call_expression: function: (identifier) arguments: (arguments)
         func_node = node.child_by_field_name("function")
         if not func_node:

src/knowcode/parsers/javascript_parser.py

@@ -3,10 +3,10 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Protocol, Optional, TYPE_CHECKING
+from typing import Protocol, TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from knowcode.retrieval.orchestrator import SearchEngineProtocol
+    pass
 
 
 from knowcode.data_models import EmbeddingConfig, Entity