ifcraftcorpus 1.2.0__tar.gz → 1.2.1__tar.gz

{ifcraftcorpus-1.2.0 → ifcraftcorpus-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ifcraftcorpus
-Version: 1.2.0
+Version: 1.2.1
 Summary: Interactive fiction craft corpus with search library and MCP server
 Project-URL: Homepage, https://pvliesdonk.github.io/if-craft-corpus
 Project-URL: Repository, https://github.com/pvliesdonk/if-craft-corpus
@@ -124,6 +124,23 @@ results = corpus.search(
 | agent-design | 2 | Multi-agent patterns, prompt engineering |
 | game-design | 1 | Mechanics design patterns |
 
+## Verbose Logging
+
+Set `LOG_LEVEL` (e.g., `INFO`, `DEBUG`) or the convenience flag `VERBOSE=1`
+before launching `ifcraftcorpus`, `ifcraftcorpus-mcp`, or the Docker image to
+emit detailed logs to stderr. Example:
+
+```bash
+LOG_LEVEL=DEBUG ifcraftcorpus-mcp
+
+# Docker
+docker run -p 8000:8000 \
+  -e LOG_LEVEL=DEBUG \
+  ghcr.io/pvliesdonk/if-craft-corpus
+```
+
+Logs never touch stdout, so stdio transports remain compatible.
+
 ## Documentation
 
 Full documentation: https://pvliesdonk.github.io/if-craft-corpus

{ifcraftcorpus-1.2.0 → ifcraftcorpus-1.2.1}/README.md

@@ -71,6 +71,23 @@ results = corpus.search(
 | agent-design | 2 | Multi-agent patterns, prompt engineering |
 | game-design | 1 | Mechanics design patterns |
 
+## Verbose Logging
+
+Set `LOG_LEVEL` (e.g., `INFO`, `DEBUG`) or the convenience flag `VERBOSE=1`
+before launching `ifcraftcorpus`, `ifcraftcorpus-mcp`, or the Docker image to
+emit detailed logs to stderr. Example:
+
+```bash
+LOG_LEVEL=DEBUG ifcraftcorpus-mcp
+
+# Docker
+docker run -p 8000:8000 \
+  -e LOG_LEVEL=DEBUG \
+  ghcr.io/pvliesdonk/if-craft-corpus
+```
+
+Logs never touch stdout, so stdio transports remain compatible.
+
 ## Documentation
 
 Full documentation: https://pvliesdonk.github.io/if-craft-corpus

{ifcraftcorpus-1.2.0 → ifcraftcorpus-1.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ifcraftcorpus"
-version = "1.2.0"
+version = "1.2.1"
 description = "Interactive fiction craft corpus with search library and MCP server"
 readme = "README.md"
 license = {text = "MIT"}
@@ -103,6 +103,17 @@ strict = true
 warn_return_any = true
 warn_unused_ignores = true
 
+[[tool.mypy.overrides]]
+module = [
+    "fastmcp",
+    "fastmcp.prompts",
+    "mcp.*",
+    "sentence_transformers",
+    "numpy",
+    "httpx",
+]
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-v --tb=short"

{ifcraftcorpus-1.2.0 → ifcraftcorpus-1.2.1}/src/ifcraftcorpus/cli.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import logging
 import sys
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -24,18 +25,38 @@ 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:
     """Show corpus information."""
     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)")
 
@@ -47,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,
@@ -55,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
 
@@ -69,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
 
 
@@ -81,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
@@ -156,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)
@@ -218,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}")
 
@@ -277,6 +320,7 @@ def main() -> int:
         emb_parser.print_help()
         return 0
 
+    logger.debug("CLI command executed: %s", args.command)
     result: int = args.func(args)
     return result
 

{ifcraftcorpus-1.2.0 → ifcraftcorpus-1.2.1}/src/ifcraftcorpus/index.py

@@ -53,6 +53,26 @@ 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.
@@ -380,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 = ""

ifcraftcorpus-1.2.1/src/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

{ifcraftcorpus-1.2.0 → ifcraftcorpus-1.2.1}/src/ifcraftcorpus/mcp_server.py

@@ -64,17 +64,33 @@ Prompts:
 
 from __future__ import annotations
 
+import logging
 import os
 import sys
+from collections.abc import Callable
 from pathlib import Path
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Any, Literal, TypeVar
 
 from fastmcp import FastMCP
 from fastmcp.prompts import Message
 from mcp.types import PromptMessage
 
+from ifcraftcorpus.logging_utils import configure_logging
 from ifcraftcorpus.search import Corpus
 
+_CONFIGURED_LOG_LEVEL = configure_logging()
+logger = logging.getLogger(__name__)
+if _CONFIGURED_LOG_LEVEL is not None:
+    logger.info("MCP logging enabled at %s", logging.getLevelName(_CONFIGURED_LOG_LEVEL))
+
+
+def _truncate(value: str, limit: int = 200) -> str:
+    """Truncate long strings for safe structured logging."""
+
+    if len(value) <= limit:
+        return value
+    return f"{value[:limit]}..."
+
 
 def _get_subagents_dir() -> Path:
     """Get the path to the subagents directory.
@@ -88,15 +104,19 @@ def _get_subagents_dir() -> Path:
         # We're in a virtual environment
         installed_path = Path(sys.prefix) / "share" / "ifcraftcorpus" / "subagents"
         if installed_path.exists():
+            logger.debug("Using installed subagents directory: %s", installed_path)
             return installed_path
 
     # Try development location (relative to this file)
     dev_path = Path(__file__).parent.parent.parent.parent / "subagents"
     if dev_path.exists():
+        logger.debug("Using development subagents directory: %s", dev_path)
         return dev_path
 
     # Fallback to current directory
-    return Path("subagents")
+    fallback = Path("subagents")
+    logger.debug("Using fallback subagents directory: %s", fallback)
+    return fallback
 
 
 def _load_subagent_template(name: str) -> str:
@@ -114,7 +134,9 @@ def _load_subagent_template(name: str) -> str:
     subagents_dir = _get_subagents_dir()
     template_path = subagents_dir / f"{name}.md"
     if not template_path.exists():
+        logger.error("Subagent template missing: %s", template_path)
         raise FileNotFoundError(f"Subagent template not found: {template_path}")
+    logger.debug("Loaded subagent template %s", template_path.name)
     return template_path.read_text(encoding="utf-8")
 
 
@@ -129,6 +151,16 @@ mcp = FastMCP(
     """,
 )
 
+if TYPE_CHECKING:
+    TCallable = TypeVar("TCallable", bound=Callable[..., Any])
+
+    def tool(func: TCallable, /) -> TCallable: ...
+
+    def prompt(*args: Any, **kwargs: Any) -> Callable[[TCallable], TCallable]: ...
+else:  # pragma: no cover - runtime aliases for decorators
+    tool = mcp.tool
+    prompt = mcp.prompt
+
 # Global corpus instance (initialized on first use)
 _corpus: Corpus | None = None
 
@@ -144,11 +176,12 @@ def get_corpus() -> Corpus:
     """
     global _corpus
     if _corpus is None:
+        logger.info("Initializing shared Corpus instance for MCP server")
         _corpus = Corpus()
     return _corpus
 
 
-@mcp.tool
+@tool
 def search_corpus(
     query: str,
     cluster: str | None = None,
@@ -175,8 +208,21 @@ def search_corpus(
     """
     limit = max(1, min(20, limit))
 
+    logger.debug(
+        "search_corpus(query=%r, cluster=%s, limit=%s)",
+        _truncate(query),
+        cluster,
+        limit,
+    )
+
     corpus = get_corpus()
-    results = corpus.search(query, cluster=cluster, limit=limit)
+    try:
+        results = corpus.search(query, cluster=cluster, limit=limit)
+    except Exception:  # pragma: no cover - defensive logging
+        logger.exception("search_corpus failed")
+        raise
+
+    logger.debug("search_corpus returning %s results", len(results))
 
     return [
         {
@@ -190,7 +236,7 @@ def search_corpus(
     ]
 
 
-@mcp.tool
+@tool
 def get_document(name: str) -> dict[str, Any] | None:
     """Get a specific document from the IF Craft Corpus.
 
@@ -204,11 +250,17 @@ def get_document(name: str) -> dict[str, Any] | None:
     Returns:
         Full document with title, summary, cluster, topics, and all sections.
     """
+    logger.debug("get_document(%s)", name)
     corpus = get_corpus()
-    return corpus.get_document(name)
+    document = corpus.get_document(name)
+    if document is None:
+        logger.info("Document not found: %s", name)
+    else:
+        logger.debug("Document %s retrieved", name)
+    return document
 
 
-@mcp.tool
+@tool
 def list_documents(cluster: str | None = None) -> list[dict[str, Any]]:
     """List all documents in the IF Craft Corpus.
 
@@ -220,16 +272,18 @@ def list_documents(cluster: str | None = None) -> list[dict[str, Any]]:
     Returns:
         List of documents with name, title, cluster, and topics.
     """
+    logger.debug("list_documents(cluster=%s)", cluster)
     corpus = get_corpus()
     docs = corpus.list_documents()
 
     if cluster:
         docs = [d for d in docs if d["cluster"] == cluster]
 
+    logger.debug("list_documents returning %s entries", len(docs))
     return docs
 
 
-@mcp.tool
+@tool
 def list_clusters() -> list[dict[str, Any]]:
     """List all topic clusters in the IF Craft Corpus.
 
@@ -239,6 +293,7 @@ def list_clusters() -> list[dict[str, Any]]:
     Returns:
         List of clusters with names and document counts.
     """
+    logger.debug("list_clusters invoked")
     corpus = get_corpus()
     clusters = corpus.list_clusters()
     docs = corpus.list_documents()
@@ -249,26 +304,36 @@ def list_clusters() -> list[dict[str, Any]]:
         c = d["cluster"]
         counts[c] = counts.get(c, 0) + 1
 
-    return [{"name": c, "document_count": counts.get(c, 0)} for c in clusters]
+    cluster_info = [{"name": c, "document_count": counts.get(c, 0)} for c in clusters]
+    logger.debug("list_clusters returning %s clusters", len(cluster_info))
+    return cluster_info
 
 
-@mcp.tool
+@tool
 def corpus_stats() -> dict[str, Any]:
     """Get statistics about the IF Craft Corpus.
 
     Returns:
         Statistics including document count, cluster count, and availability.
     """
+    logger.debug("corpus_stats invoked")
     corpus = get_corpus()
-    return {
+    stats = {
         "document_count": corpus.document_count(),
         "cluster_count": len(corpus.list_clusters()),
         "clusters": corpus.list_clusters(),
         "semantic_search_available": corpus.has_semantic_search,
     }
+    logger.debug(
+        "corpus_stats: docs=%s clusters=%s semantic=%s",
+        stats["document_count"],
+        stats["cluster_count"],
+        stats["semantic_search_available"],
+    )
+    return stats
 
 
-@mcp.tool
+@tool
 def embeddings_status() -> dict[str, Any]:
     """Get status of embedding providers and index.
 
@@ -278,6 +343,7 @@ def embeddings_status() -> dict[str, Any]:
     Returns:
         Dict with provider availability and embedding index status.
     """
+    logger.debug("embeddings_status invoked")
     result: dict[str, Any] = {
         "semantic_search_available": get_corpus().has_semantic_search,
         "providers": {},
@@ -306,13 +372,15 @@ def embeddings_status() -> dict[str, Any]:
                     "model": provider.model if available else None,
                     "dimension": provider.dimension if available else None,
                 }
-            except Exception:
+            except Exception as exc:  # pragma: no cover - defensive logging
+                logger.warning("Failed to inspect embedding provider %s: %s", name, exc)
                 result["providers"][name] = {"available": False, "error": "import_failed"}
 
         # Auto-detect best provider
         auto = get_embedding_provider()
         result["auto_detected_provider"] = auto.provider_name if auto else None
     except ImportError:
+        logger.warning("Embedding providers module not importable for status call")
         result["providers_error"] = "providers module not available"
 
     # Check for saved embeddings
@@ -329,10 +397,16 @@ def embeddings_status() -> dict[str, Any]:
             "count": len(meta.get("metadata", [])),
         }
 
+    logger.debug(
+        "embeddings_status semantic=%s providers=%s saved=%s",
+        result["semantic_search_available"],
+        list(result["providers"].keys()),
+        bool(result["saved_embeddings"]),
+    )
     return result
 
 
-@mcp.tool
+@tool
 def build_embeddings(
     provider: str | None = None,
     force: bool = False,
@@ -358,6 +432,8 @@ def build_embeddings(
     """
     global _corpus
 
+    logger.info("build_embeddings requested provider=%s force=%s", provider, force)
+
     try:
         from ifcraftcorpus.providers import (
             OllamaEmbeddings,
@@ -366,6 +442,7 @@ def build_embeddings(
             get_embedding_provider,
         )
     except ImportError:
+        logger.warning("Embedding provider modules not installed")
         return {
             "error": "Embedding providers not available. "
             "Install with [embeddings-api] or [embeddings] extras."
@@ -380,6 +457,7 @@ def build_embeddings(
             "sentence_transformers": SentenceTransformersEmbeddings,
         }
         if provider not in provider_map:
+            logger.warning("Unknown embeddings provider requested: %s", provider)
             return {
                 "error": f"Unknown provider: {provider}. Use: ollama, openai, sentence_transformers"
             }
@@ -388,12 +466,14 @@ def build_embeddings(
         embedding_provider = get_embedding_provider()
 
     if not embedding_provider:
+        logger.warning("No embedding provider available for build request")
         return {
             "error": "No embedding provider available. "
             "Configure Ollama, set OPENAI_API_KEY, or install sentence-transformers."
         }
 
     if not embedding_provider.check_availability():
+        logger.warning("Embedding provider %s unavailable", embedding_provider.provider_name)
         return {"error": f"Provider {embedding_provider.provider_name} is not available."}
 
     # Configure paths
@@ -401,6 +481,7 @@ def build_embeddings(
 
     # Check if already exists
     if not force and embeddings_path.exists() and (embeddings_path / "metadata.json").exists():
+        logger.info("Embedding build skipped; existing index at %s", embeddings_path)
         return {
             "status": "skipped",
             "message": "Embeddings already exist. Use force=True to rebuild.",
@@ -415,6 +496,12 @@ def build_embeddings(
 
     # Build embeddings
     count = corpus.build_embeddings(force=force)
+    logger.info(
+        "Embedding build complete items=%s provider=%s model=%s",
+        count,
+        embedding_provider.provider_name,
+        embedding_provider.model,
+    )
 
     # Update global corpus to use new embeddings
     _corpus = Corpus(embeddings_path=embeddings_path)
@@ -436,7 +523,7 @@ def build_embeddings(
 # Each agent has a specific role in the IF creation workflow.
 
 
-@mcp.prompt(
+@prompt(
     name="if_story_architect",
     description="System prompt for an IF Story Architect - an orchestrator agent that "
     "plans narrative structure, decomposes IF projects, and coordinates creation.",
@@ -470,7 +557,7 @@ def if_story_architect_prompt(
     return [Message(template, role="user")]
 
 
-@mcp.prompt(
+@prompt(
     name="if_prose_writer",
     description="System prompt for an IF Prose Writer - a specialist agent that "
     "creates narrative content including prose, dialogue, and scene text.",
@@ -504,7 +591,7 @@ def if_prose_writer_prompt(
     return [Message(template, role="user")]
 
 
-@mcp.prompt(
+@prompt(
     name="if_quality_reviewer",
     description="System prompt for an IF Quality Reviewer - a validator agent that "
     "reviews IF content for craft quality, consistency, and standards compliance.",
@@ -530,7 +617,7 @@ def if_quality_reviewer_prompt(
     return [Message(template, role="user")]
 
 
-@mcp.prompt(
+@prompt(
     name="if_genre_consultant",
     description="System prompt for an IF Genre Consultant - a researcher agent that "
     "provides genre-specific guidance on conventions, tropes, and reader expectations.",
@@ -563,7 +650,7 @@ def if_genre_consultant_prompt(
     return [Message(template, role="user")]
 
 
-@mcp.prompt(
+@prompt(
     name="if_world_curator",
     description="System prompt for an IF World Curator - a curator agent that "
     "maintains world consistency, manages canon, and ensures setting coherence.",
@@ -596,7 +683,7 @@ def if_world_curator_prompt(
     return [Message(template, role="user")]
 
 
-@mcp.prompt(
+@prompt(
     name="if_platform_advisor",
     description="System prompt for an IF Platform Advisor - a researcher agent that "
     "provides guidance on tools, platforms, and technical implementation.",
@@ -629,7 +716,7 @@ def if_platform_advisor_prompt(
     return [Message(template, role="user")]
 
 
-@mcp.tool
+@tool
 def list_subagents() -> list[dict[str, Any]]:
     """List all available IF subagent prompts.
 
@@ -639,6 +726,7 @@ def list_subagents() -> list[dict[str, Any]]:
     Returns:
         List of subagents with name, description, and parameters.
     """
+    logger.debug("list_subagents invoked")
     return [
         {
             "name": "if_story_architect",
@@ -706,8 +794,10 @@ def run_server(
         >>> run_server(transport="http", host="0.0.0.0", port=8080)
     """
     if transport == "http":
+        logger.info("Starting MCP server (http) host=%s port=%s", host, port)
         mcp.run(transport="http", host=host, port=port)
     else:
+        logger.info("Starting MCP server (stdio)")
         mcp.run()
 
 

{ifcraftcorpus-1.2.0 → ifcraftcorpus-1.2.1}/src/ifcraftcorpus/providers.py

@@ -283,7 +283,7 @@ class OpenAIEmbeddings(EmbeddingProvider):
                     "https://api.openai.com/v1/models",
                     headers={"Authorization": f"Bearer {self._api_key}"},
                 )
-                return response.status_code == 200
+                return bool(response.status_code == 200)
 
         except httpx.RequestError as e:
             logger.debug(f"OpenAI availability check failed: {e}")

{ifcraftcorpus-1.2.0 → ifcraftcorpus-1.2.1}/src/ifcraftcorpus/search.py

@@ -40,12 +40,24 @@ Classes:
 
 from __future__ import annotations
 
+import logging
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal
 
 from ifcraftcorpus.index import CorpusIndex
 
+logger = logging.getLogger(__name__)
+
+
+def _truncate(value: str, limit: int = 120) -> str:
+    """Trim long query strings for readable logging."""
+
+    if len(value) <= limit:
+        return value
+    return f"{value[:limit]}..."
+
+
 if TYPE_CHECKING:
     from ifcraftcorpus.embeddings import EmbeddingIndex
     from ifcraftcorpus.providers import EmbeddingProvider
@@ -193,6 +205,14 @@ class Corpus:
         self._fts_index: CorpusIndex | None = None
         self._embedding_index: EmbeddingIndex | None = None  # Lazy loaded
 
+        logger.debug(
+            "Corpus init corpus_dir=%s index_path=%s embeddings_path=%s use_bundled=%s",
+            corpus_dir,
+            index_path,
+            embeddings_path,
+            use_bundled,
+        )
+
     def _get_corpus_dir(self) -> Path:
         """Get the corpus directory path.
 
@@ -203,6 +223,7 @@ class Corpus:
             ValueError: If no corpus directory can be found.
         """
         if self._corpus_dir:
+            logger.debug("Using provided corpus directory: %s", self._corpus_dir)
             return self._corpus_dir
 
         if self._use_bundled:
@@ -215,15 +236,17 @@ class Corpus:
                 # Check for installed shared data (pip install)
                 bundled = Path(sys.prefix) / "share" / "ifcraftcorpus" / "corpus"
                 if bundled.exists():
+                    logger.debug("Using bundled corpus directory: %s", bundled)
                     return bundled
 
                 # Check relative to package (development mode / editable install)
                 pkg_dir = Path(ifcraftcorpus.__file__).parent
                 dev_corpus = pkg_dir.parent.parent / "corpus"
                 if dev_corpus.exists():
+                    logger.debug("Using development corpus directory: %s", dev_corpus)
                     return dev_corpus
             except Exception:
-                pass
+                logger.debug("Failed to auto-detect bundled corpus directory", exc_info=True)
 
         raise ValueError(
             "No corpus directory found. Provide corpus_dir or install package with bundled corpus."
@@ -240,11 +263,13 @@ class Corpus:
         """
         if self._fts_index is None:
             if self._index_path and self._index_path.exists():
+                logger.debug("Loading corpus index from %s", self._index_path)
                 self._fts_index = CorpusIndex(self._index_path)
             else:
                 # Build in-memory index
-                self._fts_index = CorpusIndex()
                 corpus_dir = self._get_corpus_dir()
+                logger.debug("Building in-memory corpus index from %s", corpus_dir)
+                self._fts_index = CorpusIndex()
                 self._fts_index.build_from_directory(corpus_dir)
         return self._fts_index
 
@@ -259,6 +284,7 @@ class Corpus:
             EmbeddingIndex instance or None if unavailable.
         """
         if self._embedding_index is None and self._embeddings_path:
+            logger.debug("Attempting to load embeddings from %s", self._embeddings_path)
             try:
                 from ifcraftcorpus.embeddings import EmbeddingIndex
 
@@ -270,7 +296,9 @@ class Corpus:
                         self._embeddings_path, provider=self._embedding_provider
                     )
             except ImportError:
-                pass  # embeddings not available
+                logger.debug("Embedding support not installed", exc_info=True)
+        elif self._embedding_index is None and not self._embeddings_path:
+            logger.debug("No embeddings path configured; semantic search disabled")
         return self._embedding_index
 
     def build_embeddings(self, *, force: bool = False) -> int:
@@ -310,12 +338,14 @@ class Corpus:
             and self._embeddings_path.exists()
             and (self._embeddings_path / "metadata.json").exists()
         ):
+            logger.info("Embeddings already exist at %s; skipping rebuild", self._embeddings_path)
             return 0
 
         from ifcraftcorpus.embeddings import EmbeddingIndex
 
         embedding_index = EmbeddingIndex(provider=self._embedding_provider)
 
+        logger.info("Building embeddings into %s", self._embeddings_path)
         count = 0
         for doc_info in self.list_documents():
             doc = self.get_document(doc_info["name"])
@@ -360,6 +390,7 @@ class Corpus:
         embedding_index.save(self._embeddings_path)
         self._embedding_index = embedding_index
 
+        logger.info("Saved embeddings (%s items) to %s", count, self._embeddings_path)
         return count
 
     def search(
@@ -408,6 +439,14 @@ class Corpus:
             >>> # Semantic search (if embeddings available)
             >>> results = corpus.search("scary atmosphere", mode="semantic")
         """
+        logger.debug(
+            "Corpus.search query=%r cluster=%s limit=%s mode=%s",
+            _truncate(query),
+            cluster,
+            limit,
+            mode,
+        )
+
         results: list[CorpusResult] = []
 
         if mode in ("keyword", "hybrid"):
@@ -458,6 +497,11 @@ class Corpus:
                     unique_results.append(result)
             results = unique_results[:limit]
 
+        logger.debug(
+            "Corpus.search returning %s results (mode=%s)",
+            len(results),
+            mode,
+        )
         return results
 
     def get_document(self, name: str) -> dict[str, Any] | None: