ifcraftcorpus 1.1.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

ifcraftcorpus/cli.py

@@ -17,8 +17,26 @@ from __future__ import annotations
 
 import argparse
 import json
+import logging
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ifcraftcorpus.providers import EmbeddingProvider
+
+from ifcraftcorpus.logging_utils import configure_logging
+
+configure_logging()
+logger = logging.getLogger(__name__)
+
+
+def _truncate(value: str, limit: int = 120) -> str:
+    """Shorten long log values to keep CLI logs readable."""
+
+    if len(value) <= limit:
+        return value
+    return f"{value[:limit]}..."
 
 
 def cmd_info(args: argparse.Namespace) -> int:
@@ -26,12 +44,19 @@ def cmd_info(args: argparse.Namespace) -> int:
     from ifcraftcorpus import Corpus, __version__
 
     corpus = Corpus()
+    clusters = corpus.list_clusters()
+    logger.info(
+        "CLI info command: version=%s docs=%s clusters=%s",
+        __version__,
+        corpus.document_count(),
+        len(clusters),
+    )
 
     print(f"\nIF Craft Corpus v{__version__}")
     print(f"Documents: {corpus.document_count()}")
-    print(f"Clusters: {len(corpus.list_clusters())}")
+    print(f"Clusters: {len(clusters)}")
     print("\nClusters:")
-    for cluster in corpus.list_clusters():
+    for cluster in clusters:
         docs = [d for d in corpus.list_documents() if d["cluster"] == cluster]
         print(f"  {cluster}: {len(docs)} file(s)")
 
@@ -43,6 +68,12 @@ def cmd_search(args: argparse.Namespace) -> int:
     from ifcraftcorpus import Corpus
 
     corpus = Corpus()
+    logger.info(
+        "CLI search query=%r cluster=%s limit=%s",
+        _truncate(args.query),
+        args.cluster,
+        args.limit,
+    )
     results = corpus.search(
         args.query,
         limit=args.limit,
@@ -51,6 +82,7 @@ def cmd_search(args: argparse.Namespace) -> int:
     )
 
     if not results:
+        logger.info("CLI search returned no matches")
         print("No results found.")
         return 0
 
@@ -65,6 +97,7 @@ def cmd_search(args: argparse.Namespace) -> int:
             content += "..."
         print(f"    {content}")
 
+    logger.info("CLI search returned %s results", len(results))
     return 0
 
 
@@ -77,6 +110,7 @@ def cmd_embeddings_status(args: argparse.Namespace) -> int:
         get_embedding_provider,
     )
 
+    logger.debug("CLI embeddings status requested")
     print("\n=== Embedding Providers ===\n")
 
     # Check each provider
@@ -129,7 +163,7 @@ def cmd_embeddings_build(args: argparse.Namespace) -> int:
     )
 
     # Get provider
-    provider = None
+    provider: EmbeddingProvider | None = None
     if args.provider:
         if args.provider == "ollama":
             provider = OllamaEmbeddings(model=args.model, host=args.ollama_host)
@@ -152,12 +186,19 @@ def cmd_embeddings_build(args: argparse.Namespace) -> int:
         print(f"Provider {provider.provider_name} is not available.", file=sys.stderr)
         return 1
 
+    logger.info(
+        "CLI embeddings build provider=%s model=%s output=%s",
+        provider.provider_name,
+        provider.model,
+        args.output,
+    )
     print(f"Using provider: {provider.provider_name}")
     print(f"Model: {provider.model} ({provider.dimension}d)")
 
     # Build embeddings
     corpus = Corpus()
-    print(f"\nBuilding embeddings for {corpus.document_count()} documents...")
+    doc_total = corpus.document_count()
+    print(f"\nBuilding embeddings for {doc_total} documents...")
 
     # Use the corpus's internal index
     embedding_index = EmbeddingIndex(provider=provider)
@@ -214,6 +255,12 @@ def cmd_embeddings_build(args: argparse.Namespace) -> int:
     output_path = Path(args.output)
     embedding_index.save(output_path)
 
+    logger.info(
+        "CLI embeddings build completed docs=%s sections=%s output=%s",
+        doc_count,
+        section_count,
+        output_path,
+    )
     print(f"\nDone! Embedded {section_count} sections from {doc_count} documents.")
     print(f"Saved to: {output_path}")
 
@@ -273,7 +320,9 @@ def main() -> int:
         emb_parser.print_help()
         return 0
 
-    return args.func(args)
+    logger.debug("CLI command executed: %s", args.command)
+    result: int = args.func(args)
+    return result
 
 
 if __name__ == "__main__":

ifcraftcorpus/embeddings.py

@@ -44,10 +44,13 @@ from __future__ import annotations
 import json
 import logging
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
+if TYPE_CHECKING:
+    from sentence_transformers import SentenceTransformer
+
 if TYPE_CHECKING:
     from ifcraftcorpus.index import CorpusIndex
     from ifcraftcorpus.providers import EmbeddingProvider
@@ -107,7 +110,8 @@ class EmbeddingIndex:
         """
         self._provider = provider
         self._embeddings: np.ndarray | None = None
-        self._metadata: list[dict] = []
+        self._metadata: list[dict[str, Any]] = []
+        self._st_model: SentenceTransformer | None = None
 
         # For backward compatibility / persistence
         if provider:
@@ -117,7 +121,6 @@ class EmbeddingIndex:
             self.model_name = model_name
             self._provider_name = "sentence-transformers"
             # Lazy-load sentence-transformers model
-            self._st_model = None
             if not lazy_load:
                 self._load_st_model()
 
@@ -126,7 +129,7 @@ class EmbeddingIndex:
         """Get the provider name."""
         return self._provider_name
 
-    def _load_st_model(self):
+    def _load_st_model(self) -> SentenceTransformer:
         """Load sentence-transformers model (fallback)."""
         if self._st_model is None:
             try:
@@ -148,12 +151,13 @@ class EmbeddingIndex:
         else:
             # Fallback to sentence-transformers
             model = self._load_st_model()
-            return model.encode(texts, show_progress_bar=False, convert_to_numpy=True)
+            embeddings = model.encode(texts, show_progress_bar=False, convert_to_numpy=True)
+            return np.asarray(embeddings)
 
     def add_texts(
         self,
         texts: list[str],
-        metadata: list[dict],
+        metadata: list[dict[str, Any]],
     ) -> None:
         """Add texts with metadata to the index.
 
@@ -185,7 +189,7 @@ class EmbeddingIndex:
         *,
         top_k: int = 10,
         cluster: str | None = None,
-    ) -> list[tuple[dict, float]]:
+    ) -> list[tuple[dict[str, Any], float]]:
         """Search for semantically similar texts.
 
         Args:

ifcraftcorpus/index.py

@@ -48,10 +48,31 @@ from __future__ import annotations
 import sqlite3
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
 
 from ifcraftcorpus.parser import Document, parse_directory
 
 
+def _sanitize_fts_query(query: str) -> str:
+    """Sanitize a query string for the FTS5 MATCH clause.
+
+    This function replaces hyphens with spaces to prevent FTS5 from
+    interpreting them as the `NOT` operator. This is intended to correctly
+    handle natural language queries with hyphenated words, for example
+    transforming "haunted-house" into a search for "haunted house".
+
+    It also collapses any resulting multiple spaces into a single space.
+
+    Args:
+        query: Raw query string from user input.
+
+    Returns:
+        Sanitized query safe for FTS5 MATCH.
+    """
+    # Replace hyphens and collapse whitespace in one go.
+    return " ".join(query.replace("-", " ").split())
+
+
 @dataclass
 class SearchResult:
     """A search result from the corpus FTS5 index.
@@ -379,8 +400,8 @@ class CorpusIndex:
             ...                        cluster="emotional-design",
             ...                        limit=5)
         """
-        # Build FTS5 query
-        fts_query = query
+        # Build FTS5 query - sanitize to handle special characters
+        fts_query = _sanitize_fts_query(query)
 
         # Add cluster filter if specified
         where_clause = ""
@@ -462,7 +483,7 @@ class CorpusIndex:
         cursor = self.conn.execute("SELECT DISTINCT cluster FROM documents ORDER BY cluster")
         return [row["cluster"] for row in cursor]
 
-    def get_document(self, name: str) -> dict | None:
+    def get_document(self, name: str) -> dict[str, Any] | None:
         """Get a document by name with all its sections.
 
         Retrieves complete document data including metadata and all
@@ -535,7 +556,8 @@ class CorpusIndex:
             Count of documents in the index.
         """
         cursor = self.conn.execute("SELECT COUNT(*) FROM documents")
-        return cursor.fetchone()[0]
+        result = cursor.fetchone()
+        return int(result[0]) if result else 0
 
 
 def build_index(corpus_dir: Path, output_path: Path) -> CorpusIndex:

ifcraftcorpus/logging_utils.py

@@ -0,0 +1,84 @@
+"""Shared logging helpers for the IF Craft Corpus codebase."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Final
+
+LOG_LEVEL_ENV: Final[str] = "LOG_LEVEL"
+VERBOSE_ENV: Final[str] = "VERBOSE"
+
+__all__ = ["configure_logging", "LOG_LEVEL_ENV", "VERBOSE_ENV"]
+
+_TRUTHY_VALUES: Final[set[str]] = {"1", "true", "yes", "on"}
+_configured: bool = False
+_CHATTY_LOGGERS: Final[tuple[str, ...]] = (
+    "httpx",
+    "fakeredis",
+    "docket",
+)
+
+
+def _is_truthy(value: str | None) -> bool:
+    """Return True if the string resembles a truthy flag."""
+
+    if value is None:
+        return False
+    return value.strip().lower() in _TRUTHY_VALUES
+
+
+def _resolve_level(value: str | None) -> int | None:
+    """Convert a logging level string (name or integer) to ``int``."""
+
+    if not value:
+        return None
+    candidate = value.strip()
+    if not candidate:
+        return None
+    if candidate.isdigit():
+        return int(candidate)
+    name = candidate.upper()
+    return getattr(logging, name, None)
+
+
+def configure_logging(
+    *,
+    env_level: str = LOG_LEVEL_ENV,
+    env_verbose: str = VERBOSE_ENV,
+    fmt: str = "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+) -> int | None:
+    """Configure root logging when LOG_LEVEL/VERBOSE are set.
+
+    Returns the configured level when logging is enabled, ``None`` otherwise.
+    """
+
+    global _configured
+
+    raw_level = os.getenv(env_level)
+    level = _resolve_level(raw_level)
+    verbose_flag = os.getenv(env_verbose)
+
+    if raw_level and level is None:
+        print(
+            f"ifcraftcorpus: unknown log level '{raw_level}', defaulting to INFO",
+            file=sys.stderr,
+        )
+        level = logging.INFO
+
+    if level is None and not _is_truthy(verbose_flag):
+        return None
+
+    if level is None:
+        level = logging.DEBUG
+
+    root = logging.getLogger()
+    if not (root.handlers and _configured):
+        logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+        _configured = True
+    root.setLevel(level)
+
+    for name in _CHATTY_LOGGERS:
+        logging.getLogger(name).setLevel(max(logging.WARNING, level))
+    return level