jodie 0.1.0__py3-none-any.whl

jodie/input/signature.py

@@ -0,0 +1,57 @@
+import re
+from typing import List
+
+class SignaturePreprocessor:
+    """Preprocess email signatures before parsing."""
+
+    # Noise patterns to filter out
+    NOISE_PATTERNS = [
+        r'^>.*$',           # Quoted replies
+        r'^On .* wrote:$',  # Forwarded headers
+        r'^-+\s*Original Message\s*-+$',
+        r'^From:.*$',
+        r'^Sent:.*$',
+        r'^To:.*$',
+        r'^Subject:.*$',
+    ]
+
+    # Pronouns to strip from names
+    PRONOUNS = r'\s*\([^)]*(?:he|she|they|him|her|them)[^)]*\)\s*'
+
+    # Common separators
+    SEPARATORS = r'[•·|–—]'
+
+    @classmethod
+    def preprocess(cls, text: str) -> List[str]:
+        """Clean and split signature text into parseable tokens."""
+        if not text:
+            return []
+
+        lines = []
+        for line in text.strip().split('\n'):
+            line = line.strip()
+
+            # Skip empty lines
+            if not line:
+                continue
+
+            # Skip noise patterns
+            skip = False
+            for pattern in cls.NOISE_PATTERNS:
+                if re.match(pattern, line, re.IGNORECASE):
+                    skip = True
+                    break
+            if skip:
+                continue
+
+            # Strip pronouns
+            line = re.sub(cls.PRONOUNS, '', line, flags=re.IGNORECASE)
+
+            # Split by common separators
+            parts = re.split(cls.SEPARATORS, line)
+            for part in parts:
+                part = part.strip()
+                if part:
+                    lines.append(part)
+
+        return lines

jodie/input/stdin.py

@@ -0,0 +1,7 @@
+import sys
+
+def read_stdin() -> str:
+    """Read from stdin (for heredoc/pipe)."""
+    if sys.stdin.isatty():
+        raise RuntimeError("No input provided via stdin")
+    return sys.stdin.read()

jodie/parsers/__init__.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+# jodie/parsers/__init__.py
+from jodie.parsers.parsers import (
+    BaseParser,
+    EmailParser,
+    NameParser,
+    WebsiteParser,
+    TitleParser,
+    PhoneParser
+)
+from jodie.parsers.base import ParseResult
+from jodie.parsers.pipeline import ParserPipeline
+
+__all__ = (
+    "BaseParser",
+    "EmailParser",
+    "NameParser",
+    "WebsiteParser",
+    "TitleParser",
+    "PhoneParser",
+    "ParseResult",
+    "ParserPipeline"
+)

jodie/parsers/base.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# jodie/parsers/base.py
+"""Base classes for parser plugin architecture."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional, Any
+
+
+@dataclass
+class ParseResult:
+    """Result from a parser."""
+    value: Any
+    confidence: float  # 0.0 to 1.0
+    consumed_text: str
+    source: str = "parsed"  # "parsed", "inferred", "explicit"
+
+    def __repr__(self) -> str:
+        """Developer-friendly representation showing value and confidence."""
+        conf_pct = f"{self.confidence:.0%}"
+        return f"ParseResult({self.value!r}, {conf_pct}, source={self.source!r})"
+
+    def __str__(self) -> str:
+        """User-friendly representation showing value with confidence indicator."""
+        conf_pct = f"{self.confidence:.0%}"
+        return f"{self.value} ({conf_pct})"
+
+
+class BaseParser(ABC):
+    """Abstract base class for all parsers.
+
+    To create a new parser:
+    1. Create a new file in jodie/parsers/
+    2. Subclass BaseParser
+    3. Set name, priority, and field_name class attributes
+    4. Implement the parse() classmethod
+
+    Parsers are auto-discovered by the Pipeline.
+    """
+    name: str = ""
+    priority: int = 0  # Higher = runs first
+    field_name: str = ""
+
+    @classmethod
+    @abstractmethod
+    def parse(cls, text: str) -> Optional[ParseResult]:
+        """Parse text and return result or None if no match.
+
+        Args:
+            text: Input text to parse
+
+        Returns:
+            ParseResult if match found, None otherwise
+        """
+        pass
+
+    @staticmethod
+    def find_matches(pattern: str, text: str) -> list:
+        """Find all regex matches in text.
+
+        Args:
+            pattern: Regex pattern
+            text: Text to search
+
+        Returns:
+            List of matches
+        """
+        import re
+        return re.findall(pattern, text)

jodie/parsers/parsers.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+# jodie/parsers/parsers.py
+import re
+from nameparser import HumanName
+
+class BaseParser:
+    """
+    Base class for parsing text into specific contact properties.
+    """
+
+    def __init__(self):
+        pass
+
+    @staticmethod
+    def find_matches(pattern, text):
+        """
+        Find all matches of a regex pattern in the given text.
+
+        :param pattern: Regex pattern to match against the text.
+        :param text: The text to search in.
+        :return: A list of all matches.
+        """
+        return re.findall(pattern, text)
+
+    @classmethod
+    def parse(cls, text):
+        """
+        Parse the given text to extract information.
+        This method should be implemented by subclasses.
+
+        :param text: The text to parse.
+        :return: Extracted information.
+        """
+        raise NotImplementedError("Subclasses must implement this method.")
+
+
+class EmailParser(BaseParser):
+    @classmethod
+    def parse(cls, text):
+        """
+        Extracts a single email from the text.
+        Returns the first valid match or None.
+        """
+        email_pattern = r'<(\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b)>' \
+                        r'|(\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b)'
+        matches = cls.find_matches(email_pattern, text)
+        for match in matches:
+            # Return the first non-empty match
+            if isinstance(match, tuple):
+                return next((item for item in match if item), None)
+            return match
+        return None
+
+
+class TitleParser(BaseParser):
+    # Common job titles and their variations
+    COMMON_TITLES = {
+        # C-level
+        "ceo", "cto", "cfo", "coo", "chief executive officer", "chief technology officer",
+        "chief financial officer", "chief operating officer",
+        
+        # Founder/Leadership
+        "founder", "co-founder", "cofounder", "president", "vice president", "vp",
+        "director", "head", "lead", "principal",
+        
+        # Engineering
+        "engineer", "developer", "architect", "scientist", "researcher",
+        "software engineer", "senior engineer", "staff engineer", "full stack engineer",
+        "senior full stack engineer", "senior software engineer",
+        
+        # Management
+        "manager", "supervisor", "coordinator", "specialist", "analyst",
+        "project manager", "product manager", "program manager",
+        
+        # Business
+        "consultant", "advisor", "partner", "associate", "representative",
+        "business development", "sales", "marketing",
+        
+        # Academic
+        "professor", "lecturer", "researcher", "fellow", "scholar",
+        
+        # Creative
+        "designer", "artist", "writer", "editor", "producer",
+        
+        # Other
+        "intern", "assistant", "coordinator", "specialist"
+    }
+
+    # Acronyms that should stay uppercase
+    ACRONYMS = {"CEO", "CTO", "CFO", "COO", "VP"}
+
+    # Common title prefixes
+    PREFIXES = {
+        "senior", "lead", "principal", "staff", "associate", "junior",
+        "full stack", "front end", "back end", "full-stack", "front-end", "back-end"
+    }
+
+    @classmethod
+    def parse(cls, text):
+        """
+        Enhanced title parsing:
+        - Standardizes capitalization for common titles
+        - Handles variations and compound titles
+        - Returns None for non-title text
+        - Preserves acronym case (e.g., CEO stays as CEO)
+        """
+        if not isinstance(text, str) or not text.strip():
+            return None
+
+        # Normalize text for comparison
+        cleaned_text = text.strip().lower()
+        
+        # Direct match against common titles
+        if cleaned_text in cls.COMMON_TITLES:
+            # Preserve original case for acronyms
+            if text.upper() in cls.ACRONYMS:
+                return text.upper()
+            # Preserve original case for the entire title
+            return text
+
+        # Check for compound titles with prefixes
+        words = cleaned_text.split()
+        if len(words) >= 2:
+            # First check if the entire phrase is a known title
+            if cleaned_text in cls.COMMON_TITLES:
+                return text
+            
+            # Then check for prefix + title combinations
+            for i in range(len(words)):
+                prefix = " ".join(words[:i+1])
+                if prefix in cls.PREFIXES:
+                    remaining = " ".join(words[i+1:])
+                    if remaining in cls.COMMON_TITLES:
+                        return text
+            
+            # Finally check if any part matches a known title
+            for i in range(len(words)):
+                for j in range(i + 1, len(words) + 1):
+                    phrase = " ".join(words[i:j])
+                    if phrase in cls.COMMON_TITLES:
+                        return text
+
+        return None
+
+
+class WebsiteParser(BaseParser):
+    @classmethod
+    def parse(cls, text):
+        # Match typical URL patterns
+        url_pattern = r'https?://[^\s]+|www\.[^\s]+'
+        urls = cls.find_matches(url_pattern, text)
+        return urls[0] if urls else None
+
+
+class PhoneParser(BaseParser):
+    @classmethod
+    def parse(cls, text):
+        """
+        Parse a phone number from the given text.
+        Supports various phone number formats:
+        - 10 digits: 5167763192
+        - With country code: +15167763192, 15167763192
+        - With separators: 516-776-3192, 516.776.3192, (516) 776-3192
+        - International formats: +1 516 776 3192
+        
+        Returns the cleaned phone number or None if no valid phone found.
+        """
+        if not isinstance(text, str) or not text.strip():
+            return None
+            
+        # Remove common non-digit characters for analysis
+        digits_only = ''.join(ch for ch in text if ch.isdigit())
+        
+        # Various phone number patterns
+        phone_patterns = [
+            # US phone numbers with various formatting
+            r'\+?1?[-.\s]?\(?([0-9]{3})\)?[-.\s]?([0-9]{3})[-.\s]?([0-9]{4})\b',
+            # 10 digit number
+            r'\b([0-9]{10})\b',
+            # International format with country code
+            r'\+?([0-9]{1,3})[-.\s]?([0-9]{3,4})[-.\s]?([0-9]{3,4})[-.\s]?([0-9]{3,4})\b'
+        ]
+        
+        for pattern in phone_patterns:
+            matches = cls.find_matches(pattern, text)
+            if matches:
+                # For tuple matches, join the groups
+                if isinstance(matches[0], tuple):
+                    # Remove empty groups and join
+                    phone_digits = ''.join(group for group in matches[0] if group)
+                else:
+                    phone_digits = matches[0]
+                
+                # Validate phone number length
+                if len(phone_digits) == 10:
+                    # US phone number without country code
+                    return phone_digits
+                elif len(phone_digits) == 11 and phone_digits.startswith('1'):
+                    # US phone number with country code
+                    return phone_digits[1:]  # Return without country code
+                elif 7 <= len(phone_digits) <= 15:
+                    # International phone number
+                    return phone_digits
+        
+        # Fallback: if we have exactly 10 or 11 digits, treat as phone
+        if len(digits_only) == 10:
+            return digits_only
+        elif len(digits_only) == 11 and digits_only.startswith('1'):
+            return digits_only[1:]
+            
+        return None
+
+
+class NameParser(BaseParser):
+    @classmethod
+    def parse(cls, text):
+        """
+        Parse a name from the given text.
+        - If an email is present in mailbox format, extract the portion before the email.
+        - Use the `nameparser` package to parse the extracted name.
+
+        :param text: The text to parse.
+        :return: A tuple of (first_name, last_name).
+        """
+        # Check for email in the text.
+        email = EmailParser.parse(text)
+        if email:
+            # Extract the portion of text before the email for name parsing.
+            name_portion_index = text.find(email)
+            name_portion = text[:name_portion_index].strip()
+            name_portion = name_portion.rstrip('<').strip()
+        else:
+            # Use the entire text if no email is found.
+            name_portion = text.strip()
+
+        if not name_portion:
+            return "", ""
+
+        # Use the `HumanName` class to parse the name intelligently.
+        name = HumanName(name_portion)
+
+        # Return the first and last names as a tuple.
+        return name.first, f"{name.middle} {name.last}".strip()

jodie/parsers/pipeline.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+# jodie/parsers/pipeline.py
+"""Parser pipeline for orchestrating field extraction."""
+
+from typing import List, Dict
+from .base import ParseResult
+from jodie.constants import WEBMAIL_DOMAINS
+
+
+class ParserPipeline:
+    """Orchestrates parsers to extract contact fields from text.
+
+    The pipeline:
+    1. Runs parsers in priority order
+    2. Stops processing a line when a parser matches
+    3. Applies cross-field inference after all parsing
+    """
+
+    @classmethod
+    def parse(cls, lines: List[str]) -> Dict[str, ParseResult]:
+        """Run all parsers on input lines.
+
+        Args:
+            lines: List of text lines to parse
+
+        Returns:
+            Dict mapping field names to ParseResults
+        """
+        # Import parsers here to avoid circular imports
+        from .parsers import (
+            EmailParser, PhoneParser, WebsiteParser,
+            TitleParser, NameParser
+        )
+
+        results: Dict[str, ParseResult] = {}
+
+        # Parser configuration: (parser_class, field_name, priority)
+        # Higher priority = runs first
+        parsers = [
+            (EmailParser, "email", 100),
+            (WebsiteParser, "websites", 90),
+            (TitleParser, "job_title", 70),
+            (PhoneParser, "phone", 60),
+            (NameParser, "name", 50),
+        ]
+
+        # Sort by priority (highest first)
+        parsers.sort(key=lambda x: x[2], reverse=True)
+
+        for line in lines:
+            if not line or not line.strip():
+                continue
+
+            for parser_class, field_name, _ in parsers:
+                # Skip if we already have this field
+                if field_name in results:
+                    continue
+
+                # Try to parse
+                try:
+                    result = parser_class.parse(line)
+                    if result is not None:
+                        # Handle NameParser's tuple return
+                        if field_name == "name" and isinstance(result, tuple):
+                            first, last = result
+                            if first or last:
+                                results["first_name"] = ParseResult(
+                                    value=first,
+                                    confidence=0.95,
+                                    consumed_text=line,
+                                    source="parsed"
+                                )
+                                results["last_name"] = ParseResult(
+                                    value=last,
+                                    confidence=0.95,
+                                    consumed_text=line,
+                                    source="parsed"
+                                )
+                        else:
+                            results[field_name] = ParseResult(
+                                value=result,
+                                confidence=0.95,
+                                consumed_text=line,
+                                source="parsed"
+                            )
+                        break  # Line consumed
+                except Exception:
+                    # Parser failed, try next
+                    continue
+
+        # Apply cross-field inference
+        cls._apply_inference(results)
+
+        return results
+
+    @classmethod
+    def _apply_inference(cls, results: Dict[str, ParseResult]) -> None:
+        """Apply cross-field inference after parsing.
+
+        Args:
+            results: Dict of parsed results (modified in place)
+        """
+        # Infer company from email domain
+        if "company" not in results and "email" in results:
+            email = results["email"].value
+            if email and "@" in email:
+                domain = email.split("@")[1].lower()
+                if domain not in WEBMAIL_DOMAINS:
+                    company = domain.split(".")[0].title()
+                    results["company"] = ParseResult(
+                        value=company,
+                        confidence=0.6,
+                        consumed_text=domain,
+                        source="inferred"
+                    )
+
+    @classmethod
+    def to_dict(cls, results: Dict[str, ParseResult]) -> Dict[str, any]:
+        """Convert ParseResults to simple dict of values.
+
+        Args:
+            results: Dict mapping field names to ParseResults
+
+        Returns:
+            Dict mapping field names to values
+        """
+        return {k: v.value for k, v in results.items()}