Phone Intelligence System - Developer Documentation

'phone': r'(?:phone|phonenumber):(?:"([^"]+)"|([^\s]+(?:[\s/\-][^\s]+)*))'

# Extract phone operator
phone_match = re.search(self.OPERATORS['phone'], remaining)
if phone_match:
    # Handle both quoted and unquoted phone
    phone_string = phone_match.group(1) if phone_match.group(1) else phone_match.group(2)

    # Split by common separators for multiple phones
    phones = [p.strip() for p in re.split(r'[,;]', phone_string) if p.strip()]

    if phones:
        parsed.phone = phones[0]  # Primary phone
        parsed.phones = phones     # All phones

def _detect_region(self, normalized: str) -> Optional[str]:
    """Auto-detect country from national format number."""

    # Numbers starting with 0 (European national format)
    if normalized.startswith('0') and not normalized.startswith('00'):
        regions_to_try = [
            'DE',  # Germany
            'GB',  # UK
            'PL',  # Poland
            'FR',  # France
            'IT',  # Italy
            'ES',  # Spain
            'AT',  # Austria
            'CH',  # Switzerland
            'NL',  # Netherlands
            'BE',  # Belgium
        ]

        for region in regions_to_try:
            try:
                parsed = phonenumbers.parse(normalized, region)
                if phonenumbers.is_valid_number(parsed):
                    return region
            except:
                continue

    # Numbers without leading 0 (US/CA 10-digit format)
    elif normalized.isdigit() and len(normalized) == 10:
        try:
            parsed = phonenumbers.parse(normalized, 'US')
            if phonenumbers.is_valid_number(parsed):
                return 'US'
        except:
            pass

    return None

def _normalize_phone(self, phone: str) -> str:
    """Normalize phone to E.164 format."""
    try:
        import phonenumbers

        # Remove all non-digit characters except +
        cleaned = re.sub(r'[^\d+]', '', phone)

        # Try to parse with auto-detection
        try:
            parsed = phonenumbers.parse(cleaned, None)
        except:
            # Try common regions
            for region in ['DE', 'US', 'GB']:
                try:
                    parsed = phonenumbers.parse(cleaned, region)
                    if phonenumbers.is_valid_number(parsed):
                        break
                except:
                    continue
            else:
                # Fallback: just digits
                return re.sub(r'\D', '', phone)

        # Format to E164
        return phonenumbers.format_number(
            parsed,
            phonenumbers.PhoneNumberFormat.E164
        )
    except ImportError:
        # Fallback: remove all non-digits
        return re.sub(r'\D', '', phone)

def remember_phone(self, phone: str, metadata: Optional[Dict] = None) -> bool:
    # Normalize phone
    normalized_phone = self._normalize_phone(phone)

    entry = {
        'value': normalized_phone,      # E.164 format for comparison
        'original': phone.strip(),      # Original format preserved
        'added_at': datetime.now().isoformat(),
        'metadata': metadata or {}
    }

    # Check if already exists (compare normalized values)
    if any(self._normalize_phone(p['value']) == normalized_phone
           for p in self.data['phones']):
        logger.info(f"Phone already in memory")
        return False  # Duplicate detected

    # Store new phone
    self.data['phones'].append(entry)
    return True

# All these variations are recognized as the SAME number:
remember_phone("04167/21 60 111")    # → +4941672160111
remember_phone("041672160111")       # → +4941672160111 (duplicate!)
remember_phone("+4941672160111")     # → +4941672160111 (duplicate!)
remember_phone("+49 4167 2160111")   # → +4941672160111 (duplicate!)

# Result: Only 1 phone stored

# 1. Parse query
parsed = parser.parse(query)  # phone:04167/21 60 111

# 2. Check if phone intelligence enabled
if parsed.phone and phone_intel:
    phone_parts = self._process_phone_intelligence(
        parsed.phone,
        phone_intel
    )

# 3. Analyze phone
def _process_phone_intelligence(self, phone: str, phone_intel) -> list:
    # Analyze with PhoneIntelligence
    phone_result = phone_intel.analyze_phone(phone)

    # Format results
    response_parts = ["\n═══ Phone Intelligence ═══\n"]
    response_parts.append(f"**Phone:** {phone_result['input']}")
    response_parts.append(f"**Valid:** {'✓' if phone_result['valid'] else '✗'}")

    if phone_result['valid']:
        # Add analysis results
        response_parts.extend(self._format_phone_results(phone_result))

        # Generate AI suggestions
        ai_queries = self._generate_phone_ai_suggestions(phone_result)
        if ai_queries:
            response_parts.append("\n═══ AI Analysis ═══\n")
            response_parts.append("**Alternative Queries:**")
            for query in ai_queries:
                response_parts.append(f"  • {query}")

        # Search online
        online_parts = self._search_phone_online(phone_result)
        response_parts.extend(online_parts)

    return response_parts

def _generate_phone_ai_suggestions(self, phone_result: dict) -> list:
    """Generate context-aware alternative queries."""
    queries = []

    country = phone_result.get('country', '')
    phone_type = phone_result.get('type', 'unknown')
    carrier = phone_result.get('carrier', '')
    formatted = phone_result.get('formatted', '')

    # Map phone types to readable text
    type_map = {
        'fixed_line': 'landline',
        'mobile': 'mobile',
        'fixed_line_or_mobile': 'phone',
        'toll_free': 'toll-free number',
        'voip': 'VoIP number'
    }
    type_text = type_map.get(phone_type, 'phone number')

    # Generate queries
    if country and formatted:
        # Query 1: Country + Type + Number
        queries.append(f"{country} {type_text} {formatted}")

    if carrier and formatted:
        # Query 2: Carrier + Number
        queries.append(f"{carrier} {formatted}")

    # Query 3: Alternative format
    if phone_result.get('variations'):
        for var in phone_result['variations'][:2]:
            if var != phone_result['input'] and var != formatted:
                queries.append(f'"{var}" contact')
                break

    # Deduplicate and limit to 3
    queries = list(dict.fromkeys(queries))[:3]
    return queries

def generate_variations(self, phone: str) -> List[str]:
    """Generate format variations for search."""
    normalized = self._normalize_phone(phone)
    variations = [phone, normalized]

    # Country-specific formats
    if normalized.startswith('+49'):
        # German formats
        national = '0' + normalized[3:]
        variations.append(national)
        variations.append(f"+49 {normalized[3:6]} {normalized[6:]}")
        variations.append(f"0{normalized[3:6]} {normalized[6:]}")

    elif normalized.startswith('+44'):
        # UK formats
        national = '0' + normalized[3:]
        variations.append(national)
        variations.append(f"+44 {normalized[3:5]} {normalized[5:9]} {normalized[9:]}")

    elif normalized.startswith('+1'):
        # US/Canada formats
        area = normalized[2:5]
        exchange = normalized[5:8]
        number = normalized[8:]
        variations.append(f"({area}) {exchange}-{number}")
        variations.append(f"{area}-{exchange}-{number}")
        variations.append(f"{area}.{exchange}.{number}")

    # ... (more countries)

    # Remove duplicates
    variations = list(set(variations))
    return variations

class PhoneIntelligence:
    """Phone number OSINT capabilities."""

    def __init__(self):
        """Initialize with phonenumbers library if available."""

    def analyze_phone(self, phone: str, region: str = None) -> Dict:
        """
        Comprehensive phone number analysis.

        Args:
            phone: Phone number in any format
            region: Optional country code (e.g., 'DE', 'US')

        Returns:
            {
                'input': str,           # Original input
                'valid': bool,          # Is valid phone number
                'formatted': str,       # International format
                'country': str,         # Country/location name
                'region': str,          # Region code (e.g., 'DE')
                'carrier': str,         # Carrier name (if available)
                'type': str,           # mobile/fixed_line/voip/etc.
                'variations': List[str], # Format variations
                'confidence': float     # 0.0 - 1.0
            }
        """

class MemoryStore:

    def _normalize_phone(self, phone: str) -> str:
        """Normalize phone to E.164 format."""

    def remember_phone(self, phone: str,
                      metadata: Optional[Dict] = None,
                      user_id: str = "anonymous") -> bool:
        """
        Store phone number (with duplicate detection).

        Args:
            phone: Phone number in any format
            metadata: Optional metadata (country, type, etc.)
            user_id: User identifier

        Returns:
            True if added, False if duplicate
        """

try:
    import openai
    HAS_OPENAI = True
except ImportError:
    HAS_OPENAI = False

@pytest.mark.skipif(not HAS_OPENAI, reason="openai package not installed")
class TestOpenAIClient:
    # Tests only run if openai is installed
    pass

# Input: phone:123
# Output: Valid: ✗ False
# Reason: Too short, doesn't match any pattern

# Input: phone:99999999
# Output: Uses basic validation (7-15 digits)
# Type: unknown
# Country: None

# Falls back to basic validation
# Pattern: ^\+?\d{7,15}$
# No carrier/type detection
# Simple country detection based on prefix