ifcraftcorpus 1.2.0__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ifcraftcorpus
-Version: 1.2.0
+Version: 1.3.0
 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.3.0}/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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ifcraftcorpus"
-version = "1.2.0"
+version = "1.3.0"
 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.3.0}/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
@@ -95,7 +125,10 @@ def cmd_embeddings_status(args: argparse.Namespace) -> int:
         status = "✓ Available" if available else "✗ Not available"
         print(f"{name:20} {status}")
         if available:
-            print(f"{'':20} Model: {provider.model} ({provider.dimension}d)")
+            extra_info = ""
+            if hasattr(provider, "cpu_only") and provider.cpu_only:
+                extra_info = " [CPU-only]"
+            print(f"{'':20} Model: {provider.model} ({provider.dimension}d){extra_info}")
 
     # Auto-detect
     print("\n=== Auto-Detection ===\n")
@@ -134,9 +167,10 @@ def cmd_embeddings_build(args: argparse.Namespace) -> int:
 
     # Get provider
     provider: EmbeddingProvider | None = None
+    cpu_only = getattr(args, "cpu_only", False)
     if args.provider:
         if args.provider == "ollama":
-            provider = OllamaEmbeddings(model=args.model, host=args.ollama_host)
+            provider = OllamaEmbeddings(model=args.model, host=args.ollama_host, cpu_only=cpu_only)
         elif args.provider == "openai":
             provider = OpenAIEmbeddings(model=args.model, api_key=args.openai_key)
         elif args.provider in ("sentence-transformers", "st", "local"):
@@ -145,7 +179,7 @@ def cmd_embeddings_build(args: argparse.Namespace) -> int:
             print(f"Unknown provider: {args.provider}", file=sys.stderr)
             return 1
     else:
-        provider = get_embedding_provider(model=args.model)
+        provider = get_embedding_provider(model=args.model, cpu_only=cpu_only)
 
     if not provider:
         print("No embedding provider available.", file=sys.stderr)
@@ -156,12 +190,25 @@ def cmd_embeddings_build(args: argparse.Namespace) -> int:
         print(f"Provider {provider.provider_name} is not available.", file=sys.stderr)
         return 1
 
-    print(f"Using provider: {provider.provider_name}")
+    # Show CPU-only status for Ollama
+    cpu_only_status = ""
+    if hasattr(provider, "cpu_only") and provider.cpu_only:
+        cpu_only_status = " (CPU-only)"
+
+    logger.info(
+        "CLI embeddings build provider=%s model=%s output=%s cpu_only=%s",
+        provider.provider_name,
+        provider.model,
+        args.output,
+        getattr(provider, "cpu_only", False),
+    )
+    print(f"Using provider: {provider.provider_name}{cpu_only_status}")
     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 +265,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}")
 
@@ -265,6 +318,12 @@ def main() -> int:
     )
     emb_build.add_argument("--ollama-host", help="Ollama host URL")
     emb_build.add_argument("--openai-key", help="OpenAI API key")
+    emb_build.add_argument(
+        "--cpu-only",
+        action="store_true",
+        help="Force CPU-only inference for Ollama (num_gpu=0). "
+        "Useful when GPU is under VRAM pressure.",
+    )
     emb_build.set_defaults(func=cmd_embeddings_build)
 
     args = parser.parse_args()
@@ -277,6 +336,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.3.0}/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.3.0/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