docs: update provider behavior and optional dependency documentation (#48)

* docs: fix trailing whitespace in README (pre-commit)

* chore: remove local test artifacts and fix trailing whitespace in docs

---------

Co-authored-by: Ben De Cock <[email protected]>

Author: VirtualAgentics

README.md

@@ -108,8 +108,19 @@ pip install -e ".[openai]"
 
 # Development tools (linting, testing, formatting)
 pip install -e ".[dev]"
+
+# Sentence-Transformers support (install separately)
+pip install sentence-transformers
 ```
 
+Notes:
+
+- If `sentence-transformers` is not installed, constructing the
+  `SentenceTransformersProvider` raises:
+  `RuntimeError: Optional dependency 'sentence-transformers' is not installed`.
+- In non-strict mode, missing optional dependencies for providers cause a
+  fallback to the hash provider and emit an ERROR log; strict mode raises.
+
 **Prerequisites for type checking:**
 
 - Node.js and npm must be installed for `make type-check` (pyright is Node.js-based)

docs/api-reference.md

@@ -564,6 +564,15 @@ ______________________________________________________________________
 - `CF_OPENAI_EMBED_MODEL`: OpenAI embedding model (default: text-embedding-3-small)
 - `CF_ST_MODEL`: Sentence Transformers model (default: sentence-transformers/all-MiniLM-L6-v2)
 
+### Embeddings Provider Behavior
+
+- `CF_EMBEDDINGS_PROVIDER=st` requires `sentence-transformers` to be installed.
+  - Missing dependency: in non-strict mode the system falls back to hash provider and emits an ERROR log.
+  - In strict mode, initialization fails.
+- `CF_EMBEDDINGS_PROVIDER=openai` requires `CF_OPENAI_API_KEY` or `OPENAI_API_KEY`.
+  - Missing API key: in non-strict mode the system falls back to hash provider and emits an ERROR log.
+  - In strict mode, initialization fails.
+
 ### Security best practices
 
 ⚠️ **CRITICAL SECURITY WARNINGS** ⚠️

docs/architecture.md

@@ -113,9 +113,17 @@ class EmbeddingsProvider(ABC):
 
 1. **FallbackHashEmbeddings**
    - Deterministic hash-based embeddings
-   - 32-dimensional vectors
+   - 32-dimensional vectors (default)
    - No external dependencies
    - Used as fallback when other providers fail
+   - Dimension validation:
+     - Type validation:
+       - Non-integer types (including `bool`) → TypeError
+       - Error messages:
+         - "dimension must be an integer, not a boolean" (for `bool`)
+         - "dimension must be an integer" (for other non-int types)
+     - Range validation:
+       - `< 2` or `> 32` → ValueError
 
 2. **OpenAIEmbeddingsProvider**
    - Uses OpenAI's embedding API

docs/configuration.md

@@ -281,11 +281,20 @@ pip install -e ".[dev]"
 
 Includes testing, linting, and development tools.
 
-### Automatic Optional Dependencies
+### Sentence-Transformers (standalone)
 
-These are installed automatically when needed:
+Install separately when using the SentenceTransformers provider:
 
-- `sentence-transformers` - For sentence transformer embeddings
+```bash
+pip install sentence-transformers
+```
+
+Notes:
+
+- If `sentence-transformers` is not installed, constructing
+  `SentenceTransformersProvider` raises:
+  `RuntimeError: Optional dependency 'sentence-transformers' is not installed`.
+- Model names are validated; invalid names raise `ValueError`.
 
 ### Development Dependencies
 

scripts/apply_cr_suggestions.py

@@ -19,10 +19,22 @@
 import subprocess
 import sys
 import time
+from enum import Enum
 from typing import Any
 
 from re import Pattern
 
+# Import handlers
+try:
+    from handlers import (
+        apply_json_suggestion, validate_json_suggestion,
+        apply_yaml_suggestion, validate_yaml_suggestion,
+        apply_toml_suggestion, validate_toml_suggestion
+    )
+    HANDLERS_AVAILABLE = True
+except ImportError:
+    HANDLERS_AVAILABLE = False
+
 CR_DIR = pathlib.Path(".cr")
 COMMENTS_JSON = CR_DIR / "pr-review-comments.json"
 PATCH_DIR = CR_DIR / "patches"
@@ -40,6 +52,89 @@
 RE_OPTION_HEADER = re.compile(r'\*\*([^*]+)\*\*\s*$', re.MULTILINE)
 
 
+class FileType(Enum):
+    """File type enumeration for routing suggestions to appropriate handlers."""
+    PYTHON = "python"
+    TYPESCRIPT = "typescript"
+    JSON = "json"
+    YAML = "yaml"
+    TOML = "toml"
+    PLAINTEXT = "plaintext"
+
+
+def detect_file_type(path: str) -> FileType:
+    """Detect file type from extension."""
+    suffix = pathlib.Path(path).suffix.lower()
+    mapping = {
+        ".py": FileType.PYTHON,
+        ".ts": FileType.TYPESCRIPT,
+        ".tsx": FileType.TYPESCRIPT,
+        ".js": FileType.TYPESCRIPT,
+        ".jsx": FileType.TYPESCRIPT,
+        ".json": FileType.JSON,
+        ".yaml": FileType.YAML,
+        ".yml": FileType.YAML,
+        ".toml": FileType.TOML,
+    }
+    return mapping.get(suffix, FileType.PLAINTEXT)
+
+
+def route_suggestion(file_type: FileType, path: str, suggestion: str,
+                     start_line: int, end_line: int) -> bool:
+    """Route suggestion to appropriate handler."""
+    if not HANDLERS_AVAILABLE:
+        print(f"Warning: Handlers not available, using plaintext fallback for {path}")
+        return apply_plaintext_suggestion(path, suggestion, start_line, end_line)
+
+    if file_type == FileType.JSON:
+        return apply_json_suggestion(path, suggestion, start_line, end_line)
+    elif file_type == FileType.YAML:
+        return apply_yaml_suggestion(path, suggestion, start_line, end_line)
+    elif file_type == FileType.TOML:
+        return apply_toml_suggestion(path, suggestion, start_line, end_line)
+    else:
+        return apply_plaintext_suggestion(path, suggestion, start_line, end_line)
+
+
+def validate_suggestion(file_type: FileType, path: str, suggestion: str,
+                        start_line: int, end_line: int) -> tuple[bool, str]:
+    """Validate suggestion without applying it."""
+    if not HANDLERS_AVAILABLE:
+        return True, "No validation available"
+
+    if file_type == FileType.JSON:
+        return validate_json_suggestion(path, suggestion, start_line, end_line)
+    elif file_type == FileType.YAML:
+        return validate_yaml_suggestion(path, suggestion, start_line, end_line)
+    elif file_type == FileType.TOML:
+        return validate_toml_suggestion(path, suggestion, start_line, end_line)
+    else:
+        return True, "No validation available"
+
+
+def apply_plaintext_suggestion(path: str, suggestion: str,
+                               start_line: int, end_line: int) -> bool:
+    """Apply suggestion using the original plaintext method."""
+    file_path = pathlib.Path(path)
+    if not file_path.exists():
+        return False
+
+    original = read_lines(file_path)
+    replacement = suggestion.split("\n")
+    a = max(0, start_line - 1)
+    b = max(0, end_line)
+
+    if a > len(original):
+        return False
+    if b > len(original):
+        b = len(original)
+
+    new = original[:]
+    new[a:b] = replacement
+    write_lines(file_path, new)
+    return True
+
+
 def load_review_comments() -> list[dict[str, Any]]:
     """Load review comments from JSON file."""
     if not COMMENTS_JSON.exists():
@@ -583,16 +678,37 @@ def main() -> None:
                 report.append(f"- SKIPPED overlapping change at L{start}-{end} (conflicts with earlier change)")
                 continue
 
-            replacement = text.split("\n")
-            a = max(0, start - 1); b = max(0, end)
-            if a > len(new):
-                report.append(f"- Skip suggestion at L{start}-{end}: out of bounds.")
-                continue
-            if b > len(new):
-                b = len(new)
-            before = new[:]
-            new[a:b] = replacement
-            changed = (before != new)
+            # Detect file type and route to appropriate handler
+            file_type = detect_file_type(path)
+
+            # Validate suggestion first if in validation mode
+            if args.validate:
+                is_valid, validation_msg = validate_suggestion(file_type, path, text, start, end)
+                if not is_valid:
+                    report.append(f"- VALIDATION FAILED at L{start}-{end}: {validation_msg}")
+                    continue
+                else:
+                    report.append(f"- VALIDATION PASSED at L{start}-{end}: {validation_msg}")
+
+            # Apply suggestion using appropriate handler
+            if file_type in [FileType.JSON, FileType.YAML, FileType.TOML]:
+                # Use specialized handler for structured files
+                changed = route_suggestion(file_type, path, text, start, end)
+                if changed:
+                    # Reload file content after handler modification
+                    new = read_lines(file_path)
+            else:
+                # Use original plaintext method for other files
+                replacement = text.split("\n")
+                a = max(0, start - 1); b = max(0, end)
+                if a > len(new):
+                    report.append(f"- Skip suggestion at L{start}-{end}: out of bounds.")
+                    continue
+                if b > len(new):
+                    b = len(new)
+                before = new[:]
+                new[a:b] = replacement
+                changed = (before != new)
             url = meta.get("url", "")
             who = meta.get("author", "")
             src = meta.get("source", "suggestion")