bps-kit 1.0.1 → 1.0.2

package/templates/vault/notebooklm/scripts/setup_environment.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""
+Environment Setup for NotebookLM Skill
+Manages virtual environment and dependencies automatically
+"""
+
+import os
+import sys
+import subprocess
+import venv
+from pathlib import Path
+
+
+class SkillEnvironment:
+    """Manages skill-specific virtual environment"""
+
+    def __init__(self):
+        # Skill directory paths
+        self.skill_dir = Path(__file__).parent.parent
+        self.venv_dir = self.skill_dir / ".venv"
+        self.requirements_file = self.skill_dir / "requirements.txt"
+
+        # Python executable in venv
+        if os.name == 'nt':  # Windows
+            self.venv_python = self.venv_dir / "Scripts" / "python.exe"
+            self.venv_pip = self.venv_dir / "Scripts" / "pip.exe"
+        else:  # Unix/Linux/Mac
+            self.venv_python = self.venv_dir / "bin" / "python"
+            self.venv_pip = self.venv_dir / "bin" / "pip"
+
+    def ensure_venv(self) -> bool:
+        """Ensure virtual environment exists and is set up"""
+
+        # Check if we're already in the correct venv
+        if self.is_in_skill_venv():
+            print("✅ Already running in skill virtual environment")
+            return True
+
+        # Create venv if it doesn't exist
+        if not self.venv_dir.exists():
+            print(f"🔧 Creating virtual environment in {self.venv_dir.name}/")
+            try:
+                venv.create(self.venv_dir, with_pip=True)
+                print("✅ Virtual environment created")
+            except Exception as e:
+                print(f"❌ Failed to create venv: {e}")
+                return False
+
+        # Install/update dependencies
+        if self.requirements_file.exists():
+            print("📦 Installing dependencies...")
+            try:
+                # Upgrade pip first
+                subprocess.run(
+                    [str(self.venv_pip), "install", "--upgrade", "pip"],
+                    check=True,
+                    capture_output=True,
+                    text=True
+                )
+
+                # Install requirements
+                result = subprocess.run(
+                    [str(self.venv_pip), "install", "-r", str(self.requirements_file)],
+                    check=True,
+                    capture_output=True,
+                    text=True
+                )
+                print("✅ Dependencies installed")
+
+                # Install Chrome for Patchright (not Chromium!)
+                # Using real Chrome ensures cross-platform reliability and consistent browser fingerprinting
+                # See: https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-python#anti-detection
+                print("🌐 Installing Google Chrome for Patchright...")
+                try:
+                    subprocess.run(
+                        [str(self.venv_python), "-m", "patchright", "install", "chrome"],
+                        check=True,
+                        capture_output=True,
+                        text=True
+                    )
+                    print("✅ Chrome installed")
+                except subprocess.CalledProcessError as e:
+                    print(f"⚠️ Warning: Failed to install Chrome: {e}")
+                    print("   You may need to run manually: python -m patchright install chrome")
+                    print("   Chrome is required (not Chromium) for reliability!")
+
+                return True
+            except subprocess.CalledProcessError as e:
+                print(f"❌ Failed to install dependencies: {e}")
+                print(f"   Output: {e.output if hasattr(e, 'output') else 'No output'}")
+                return False
+        else:
+            print("⚠️ No requirements.txt found, skipping dependency installation")
+            return True
+
+    def is_in_skill_venv(self) -> bool:
+        """Check if we're already running in the skill's venv"""
+        if hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix):
+            # We're in a venv, check if it's ours
+            venv_path = Path(sys.prefix)
+            return venv_path == self.venv_dir
+        return False
+
+    def get_python_executable(self) -> str:
+        """Get the correct Python executable to use"""
+        if self.venv_python.exists():
+            return str(self.venv_python)
+        return sys.executable
+
+    def run_script(self, script_name: str, args: list = None) -> int:
+        """Run a script with the virtual environment"""
+        script_path = self.skill_dir / "scripts" / script_name
+
+        if not script_path.exists():
+            print(f"❌ Script not found: {script_path}")
+            return 1
+
+        # Ensure venv is set up
+        if not self.ensure_venv():
+            print("❌ Failed to set up environment")
+            return 1
+
+        # Build command
+        cmd = [str(self.venv_python), str(script_path)]
+        if args:
+            cmd.extend(args)
+
+        print(f"🚀 Running: {script_name} with venv Python")
+
+        try:
+            # Run the script with venv Python
+            result = subprocess.run(cmd)
+            return result.returncode
+        except Exception as e:
+            print(f"❌ Failed to run script: {e}")
+            return 1
+
+    def activate_instructions(self) -> str:
+        """Get instructions for manual activation"""
+        if os.name == 'nt':
+            activate = self.venv_dir / "Scripts" / "activate.bat"
+            return f"Run: {activate}"
+        else:
+            activate = self.venv_dir / "bin" / "activate"
+            return f"Run: source {activate}"
+
+
+def main():
+    """Main entry point for environment setup"""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description='Setup NotebookLM skill environment'
+    )
+
+    parser.add_argument(
+        '--check',
+        action='store_true',
+        help='Check if environment is set up'
+    )
+
+    parser.add_argument(
+        '--run',
+        help='Run a script with the venv (e.g., --run ask_question.py)'
+    )
+
+    parser.add_argument(
+        'args',
+        nargs='*',
+        help='Arguments to pass to the script'
+    )
+
+    args = parser.parse_args()
+
+    env = SkillEnvironment()
+
+    if args.check:
+        if env.venv_dir.exists():
+            print(f"✅ Virtual environment exists: {env.venv_dir}")
+            print(f"   Python: {env.get_python_executable()}")
+            print(f"   To activate manually: {env.activate_instructions()}")
+        else:
+            print(f"❌ No virtual environment found")
+            print(f"   Run setup_environment.py to create it")
+        return
+
+    if args.run:
+        # Run a script with venv
+        return env.run_script(args.run, args.args)
+
+    # Default: ensure environment is set up
+    if env.ensure_venv():
+        print("\n✅ Environment ready!")
+        print(f"   Virtual env: {env.venv_dir}")
+        print(f"   Python: {env.get_python_executable()}")
+        print(f"\nTo activate manually: {env.activate_instructions()}")
+        print(f"Or run scripts directly: python setup_environment.py --run script_name.py")
+    else:
+        print("\n❌ Environment setup failed")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)

package/templates/vault/pdf/scripts/check_bounding_boxes.py

@@ -0,0 +1,70 @@
+from dataclasses import dataclass
+import json
+import sys
+
+
+# Script to check that the `fields.json` file that Claude creates when analyzing PDFs
+# does not have overlapping bounding boxes. See forms.md.
+
+
+@dataclass
+class RectAndField:
+    rect: list[float]
+    rect_type: str
+    field: dict
+
+
+# Returns a list of messages that are printed to stdout for Claude to read.
+def get_bounding_box_messages(fields_json_stream) -> list[str]:
+    messages = []
+    fields = json.load(fields_json_stream)
+    messages.append(f"Read {len(fields['form_fields'])} fields")
+
+    def rects_intersect(r1, r2):
+        disjoint_horizontal = r1[0] >= r2[2] or r1[2] <= r2[0]
+        disjoint_vertical = r1[1] >= r2[3] or r1[3] <= r2[1]
+        return not (disjoint_horizontal or disjoint_vertical)
+
+    rects_and_fields = []
+    for f in fields["form_fields"]:
+        rects_and_fields.append(RectAndField(f["label_bounding_box"], "label", f))
+        rects_and_fields.append(RectAndField(f["entry_bounding_box"], "entry", f))
+
+    has_error = False
+    for i, ri in enumerate(rects_and_fields):
+        # This is O(N^2); we can optimize if it becomes a problem.
+        for j in range(i + 1, len(rects_and_fields)):
+            rj = rects_and_fields[j]
+            if ri.field["page_number"] == rj.field["page_number"] and rects_intersect(ri.rect, rj.rect):
+                has_error = True
+                if ri.field is rj.field:
+                    messages.append(f"FAILURE: intersection between label and entry bounding boxes for `{ri.field['description']}` ({ri.rect}, {rj.rect})")
+                else:
+                    messages.append(f"FAILURE: intersection between {ri.rect_type} bounding box for `{ri.field['description']}` ({ri.rect}) and {rj.rect_type} bounding box for `{rj.field['description']}` ({rj.rect})")
+                if len(messages) >= 20:
+                    messages.append("Aborting further checks; fix bounding boxes and try again")
+                    return messages
+        if ri.rect_type == "entry":
+            if "entry_text" in ri.field:
+                font_size = ri.field["entry_text"].get("font_size", 14)
+                entry_height = ri.rect[3] - ri.rect[1]
+                if entry_height < font_size:
+                    has_error = True
+                    messages.append(f"FAILURE: entry bounding box height ({entry_height}) for `{ri.field['description']}` is too short for the text content (font size: {font_size}). Increase the box height or decrease the font size.")
+                    if len(messages) >= 20:
+                        messages.append("Aborting further checks; fix bounding boxes and try again")
+                        return messages
+
+    if not has_error:
+        messages.append("SUCCESS: All bounding boxes are valid")
+    return messages
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: check_bounding_boxes.py [fields.json]")
+        sys.exit(1)
+    # Input file should be in the `fields.json` format described in forms.md.
+    with open(sys.argv[1]) as f:
+        messages = get_bounding_box_messages(f)
+    for msg in messages:
+        print(msg)

package/templates/vault/pdf/scripts/check_bounding_boxes_test.py

@@ -0,0 +1,226 @@
+import unittest
+import json
+import io
+from check_bounding_boxes import get_bounding_box_messages
+
+
+# Currently this is not run automatically in CI; it's just for documentation and manual checking.
+class TestGetBoundingBoxMessages(unittest.TestCase):
+    
+    def create_json_stream(self, data):
+        """Helper to create a JSON stream from data"""
+        return io.StringIO(json.dumps(data))
+    
+    def test_no_intersections(self):
+        """Test case with no bounding box intersections"""
+        data = {
+            "form_fields": [
+                {
+                    "description": "Name",
+                    "page_number": 1,
+                    "label_bounding_box": [10, 10, 50, 30],
+                    "entry_bounding_box": [60, 10, 150, 30]
+                },
+                {
+                    "description": "Email",
+                    "page_number": 1,
+                    "label_bounding_box": [10, 40, 50, 60],
+                    "entry_bounding_box": [60, 40, 150, 60]
+                }
+            ]
+        }
+        
+        stream = self.create_json_stream(data)
+        messages = get_bounding_box_messages(stream)
+        self.assertTrue(any("SUCCESS" in msg for msg in messages))
+        self.assertFalse(any("FAILURE" in msg for msg in messages))
+    
+    def test_label_entry_intersection_same_field(self):
+        """Test intersection between label and entry of the same field"""
+        data = {
+            "form_fields": [
+                {
+                    "description": "Name",
+                    "page_number": 1,
+                    "label_bounding_box": [10, 10, 60, 30],
+                    "entry_bounding_box": [50, 10, 150, 30]  # Overlaps with label
+                }
+            ]
+        }
+        
+        stream = self.create_json_stream(data)
+        messages = get_bounding_box_messages(stream)
+        self.assertTrue(any("FAILURE" in msg and "intersection" in msg for msg in messages))
+        self.assertFalse(any("SUCCESS" in msg for msg in messages))
+    
+    def test_intersection_between_different_fields(self):
+        """Test intersection between bounding boxes of different fields"""
+        data = {
+            "form_fields": [
+                {
+                    "description": "Name",
+                    "page_number": 1,
+                    "label_bounding_box": [10, 10, 50, 30],
+                    "entry_bounding_box": [60, 10, 150, 30]
+                },
+                {
+                    "description": "Email",
+                    "page_number": 1,
+                    "label_bounding_box": [40, 20, 80, 40],  # Overlaps with Name's boxes
+                    "entry_bounding_box": [160, 10, 250, 30]
+                }
+            ]
+        }
+        
+        stream = self.create_json_stream(data)
+        messages = get_bounding_box_messages(stream)
+        self.assertTrue(any("FAILURE" in msg and "intersection" in msg for msg in messages))
+        self.assertFalse(any("SUCCESS" in msg for msg in messages))
+    
+    def test_different_pages_no_intersection(self):
+        """Test that boxes on different pages don't count as intersecting"""
+        data = {
+            "form_fields": [
+                {
+                    "description": "Name",
+                    "page_number": 1,
+                    "label_bounding_box": [10, 10, 50, 30],
+                    "entry_bounding_box": [60, 10, 150, 30]
+                },
+                {
+                    "description": "Email",
+                    "page_number": 2,
+                    "label_bounding_box": [10, 10, 50, 30],  # Same coordinates but different page
+                    "entry_bounding_box": [60, 10, 150, 30]
+                }
+            ]
+        }
+        
+        stream = self.create_json_stream(data)
+        messages = get_bounding_box_messages(stream)
+        self.assertTrue(any("SUCCESS" in msg for msg in messages))
+        self.assertFalse(any("FAILURE" in msg for msg in messages))
+    
+    def test_entry_height_too_small(self):
+        """Test that entry box height is checked against font size"""
+        data = {
+            "form_fields": [
+                {
+                    "description": "Name",
+                    "page_number": 1,
+                    "label_bounding_box": [10, 10, 50, 30],
+                    "entry_bounding_box": [60, 10, 150, 20],  # Height is 10
+                    "entry_text": {
+                        "font_size": 14  # Font size larger than height
+                    }
+                }
+            ]
+        }
+        
+        stream = self.create_json_stream(data)
+        messages = get_bounding_box_messages(stream)
+        self.assertTrue(any("FAILURE" in msg and "height" in msg for msg in messages))
+        self.assertFalse(any("SUCCESS" in msg for msg in messages))
+    
+    def test_entry_height_adequate(self):
+        """Test that adequate entry box height passes"""
+        data = {
+            "form_fields": [
+                {
+                    "description": "Name",
+                    "page_number": 1,
+                    "label_bounding_box": [10, 10, 50, 30],
+                    "entry_bounding_box": [60, 10, 150, 30],  # Height is 20
+                    "entry_text": {
+                        "font_size": 14  # Font size smaller than height
+                    }
+                }
+            ]
+        }
+        
+        stream = self.create_json_stream(data)
+        messages = get_bounding_box_messages(stream)
+        self.assertTrue(any("SUCCESS" in msg for msg in messages))
+        self.assertFalse(any("FAILURE" in msg for msg in messages))
+    
+    def test_default_font_size(self):
+        """Test that default font size is used when not specified"""
+        data = {
+            "form_fields": [
+                {
+                    "description": "Name",
+                    "page_number": 1,
+                    "label_bounding_box": [10, 10, 50, 30],
+                    "entry_bounding_box": [60, 10, 150, 20],  # Height is 10
+                    "entry_text": {}  # No font_size specified, should use default 14
+                }
+            ]
+        }
+        
+        stream = self.create_json_stream(data)
+        messages = get_bounding_box_messages(stream)
+        self.assertTrue(any("FAILURE" in msg and "height" in msg for msg in messages))
+        self.assertFalse(any("SUCCESS" in msg for msg in messages))
+    
+    def test_no_entry_text(self):
+        """Test that missing entry_text doesn't cause height check"""
+        data = {
+            "form_fields": [
+                {
+                    "description": "Name",
+                    "page_number": 1,
+                    "label_bounding_box": [10, 10, 50, 30],
+                    "entry_bounding_box": [60, 10, 150, 20]  # Small height but no entry_text
+                }
+            ]
+        }
+        
+        stream = self.create_json_stream(data)
+        messages = get_bounding_box_messages(stream)
+        self.assertTrue(any("SUCCESS" in msg for msg in messages))
+        self.assertFalse(any("FAILURE" in msg for msg in messages))
+    
+    def test_multiple_errors_limit(self):
+        """Test that error messages are limited to prevent excessive output"""
+        fields = []
+        # Create many overlapping fields
+        for i in range(25):
+            fields.append({
+                "description": f"Field{i}",
+                "page_number": 1,
+                "label_bounding_box": [10, 10, 50, 30],  # All overlap
+                "entry_bounding_box": [20, 15, 60, 35]   # All overlap
+            })
+        
+        data = {"form_fields": fields}
+        
+        stream = self.create_json_stream(data)
+        messages = get_bounding_box_messages(stream)
+        # Should abort after ~20 messages
+        self.assertTrue(any("Aborting" in msg for msg in messages))
+        # Should have some FAILURE messages but not hundreds
+        failure_count = sum(1 for msg in messages if "FAILURE" in msg)
+        self.assertGreater(failure_count, 0)
+        self.assertLess(len(messages), 30)  # Should be limited
+    
+    def test_edge_touching_boxes(self):
+        """Test that boxes touching at edges don't count as intersecting"""
+        data = {
+            "form_fields": [
+                {
+                    "description": "Name",
+                    "page_number": 1,
+                    "label_bounding_box": [10, 10, 50, 30],
+                    "entry_bounding_box": [50, 10, 150, 30]  # Touches at x=50
+                }
+            ]
+        }
+        
+        stream = self.create_json_stream(data)
+        messages = get_bounding_box_messages(stream)
+        self.assertTrue(any("SUCCESS" in msg for msg in messages))
+        self.assertFalse(any("FAILURE" in msg for msg in messages))
+    
+
+if __name__ == '__main__':
+    unittest.main()

package/templates/vault/pdf/scripts/check_fillable_fields.py

@@ -0,0 +1,12 @@
+import sys
+from pypdf import PdfReader
+
+
+# Script for Claude to run to determine whether a PDF has fillable form fields. See forms.md.
+
+
+reader = PdfReader(sys.argv[1])
+if (reader.get_fields()):
+    print("This PDF has fillable form fields")
+else:
+    print("This PDF does not have fillable form fields; you will need to visually determine where to enter data")

package/templates/vault/pdf/scripts/convert_pdf_to_images.py

@@ -0,0 +1,35 @@
+import os
+import sys
+
+from pdf2image import convert_from_path
+
+
+# Converts each page of a PDF to a PNG image.
+
+
+def convert(pdf_path, output_dir, max_dim=1000):
+    images = convert_from_path(pdf_path, dpi=200)
+
+    for i, image in enumerate(images):
+        # Scale image if needed to keep width/height under `max_dim`
+        width, height = image.size
+        if width > max_dim or height > max_dim:
+            scale_factor = min(max_dim / width, max_dim / height)
+            new_width = int(width * scale_factor)
+            new_height = int(height * scale_factor)
+            image = image.resize((new_width, new_height))
+        
+        image_path = os.path.join(output_dir, f"page_{i+1}.png")
+        image.save(image_path)
+        print(f"Saved page {i+1} as {image_path} (size: {image.size})")
+
+    print(f"Converted {len(images)} pages to PNG images")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 3:
+        print("Usage: convert_pdf_to_images.py [input pdf] [output directory]")
+        sys.exit(1)
+    pdf_path = sys.argv[1]
+    output_directory = sys.argv[2]
+    convert(pdf_path, output_directory)

package/templates/vault/pdf/scripts/create_validation_image.py

@@ -0,0 +1,41 @@
+import json
+import sys
+
+from PIL import Image, ImageDraw
+
+
+# Creates "validation" images with rectangles for the bounding box information that
+# Claude creates when determining where to add text annotations in PDFs. See forms.md.
+
+
+def create_validation_image(page_number, fields_json_path, input_path, output_path):
+    # Input file should be in the `fields.json` format described in forms.md.
+    with open(fields_json_path, 'r') as f:
+        data = json.load(f)
+
+        img = Image.open(input_path)
+        draw = ImageDraw.Draw(img)
+        num_boxes = 0
+        
+        for field in data["form_fields"]:
+            if field["page_number"] == page_number:
+                entry_box = field['entry_bounding_box']
+                label_box = field['label_bounding_box']
+                # Draw red rectangle over entry bounding box and blue rectangle over the label.
+                draw.rectangle(entry_box, outline='red', width=2)
+                draw.rectangle(label_box, outline='blue', width=2)
+                num_boxes += 2
+        
+        img.save(output_path)
+        print(f"Created validation image at {output_path} with {num_boxes} bounding boxes")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 5:
+        print("Usage: create_validation_image.py [page number] [fields.json file] [input image path] [output image path]")
+        sys.exit(1)
+    page_number = int(sys.argv[1])
+    fields_json_path = sys.argv[2]
+    input_image_path = sys.argv[3]
+    output_image_path = sys.argv[4]
+    create_validation_image(page_number, fields_json_path, input_image_path, output_image_path)