ai-lls-lib 1.0.0__py3-none-any.whl

ai_lls_lib/core/verifier.py

@@ -0,0 +1,95 @@
+"""
+Phone verification logic - checks line type and DNC status
+"""
+import os
+import re
+from datetime import datetime, timezone
+from typing import Optional
+import httpx
+import phonenumbers
+from aws_lambda_powertools import Logger
+from .models import PhoneVerification, LineType, VerificationSource
+from .cache import DynamoDBCache
+
+logger = Logger()
+
+
+class PhoneVerifier:
+    """Verifies phone numbers for line type and DNC status"""
+
+    def __init__(self, cache: DynamoDBCache):
+        self.cache = cache
+        self.dnc_api_key = os.environ.get("DNC_API_KEY", "")
+        self.phone_api_key = os.environ.get("PHONE_VERIFY_API_KEY", "")
+        self.http_client = httpx.Client(timeout=10.0)
+
+    def normalize_phone(self, phone: str) -> str:
+        """Normalize phone to E.164 format"""
+        try:
+            # Parse with US as default country
+            parsed = phonenumbers.parse(phone, "US")
+            if not phonenumbers.is_valid_number(parsed):
+                raise ValueError(f"Invalid phone number: {phone}")
+
+            # Format as E.164
+            return phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.E164)
+        except Exception as e:
+            logger.error(f"Phone normalization failed: {str(e)}")
+            raise ValueError(f"Invalid phone format: {phone}")
+
+    def verify_sync(self, phone: str) -> PhoneVerification:
+        """Synchronous verification for Lambda handlers"""
+        normalized = self.normalize_phone(phone)
+
+        # Check cache first
+        cached = self.cache.get(normalized)
+        if cached:
+            return cached
+
+        # Call external APIs
+        line_type = self._check_line_type_sync(normalized)
+        dnc_status = self._check_dnc_sync(normalized)
+
+        result = PhoneVerification(
+            phone_number=normalized,
+            line_type=line_type,
+            dnc=dnc_status,
+            cached=False,
+            verified_at=datetime.now(timezone.utc),
+            source=VerificationSource.API
+        )
+
+        # Store in cache
+        self.cache.set(normalized, result)
+
+        return result
+
+    def _check_line_type_sync(self, phone: str) -> LineType:
+        """Check if phone is mobile/landline/voip"""
+        # TODO: Implement actual API call to phone verification service
+        # Would use self.phone_api_key to authenticate
+        logger.info(f"Checking line type for {phone[:6]}***")
+
+        # Stub implementation based on last digit
+        last_digit = phone[-1] if phone else '5'
+        if last_digit in ['2', '0']:
+            return LineType.LANDLINE
+        else:
+            return LineType.MOBILE
+
+    def _check_dnc_sync(self, phone: str) -> bool:
+        """Check if phone is on DNC list"""
+        # TODO: Implement actual DNC API call
+        # Would use self.dnc_api_key or os.environ.get("DNC_CHECK_API_KEY")
+        logger.info(f"Checking DNC status for {phone[:6]}***")
+
+        # Stub implementation based on last digit:
+        # - Ends in 1 or 0: on DNC list
+        # - Otherwise: not on DNC
+        last_digit = phone[-1] if phone else '5'
+        return last_digit in ['1', '0']
+
+    def __del__(self):
+        """Cleanup HTTP client"""
+        if hasattr(self, 'http_client'):
+            self.http_client.close()

ai_lls_lib/testing/__init__.py

@@ -0,0 +1,3 @@
+"""
+Testing utilities and fixtures
+"""

ai_lls_lib/testing/fixtures.py

@@ -0,0 +1,104 @@
+"""
+Test fixtures and utilities for ai-lls-lib
+"""
+from datetime import datetime, timedelta, timezone
+from typing import List, Dict, Any
+from ai_lls_lib.core.models import PhoneVerification, LineType, VerificationSource
+
+# Sample phone numbers for testing
+# Using 201-555-01XX format which is designated for testing
+TEST_PHONES = {
+    "valid_mobile": "+12015550153",  # Ends in 3 - mobile, not on DNC
+    "valid_landline": "+12015550152",  # Ends in 2 - landline, not on DNC
+    "dnc_mobile": "+12015550151",  # Ends in 1 - mobile, on DNC
+    "dnc_landline": "+12015550150",  # Ends in 0 - landline, on DNC
+    "invalid": "not-a-phone",
+    "missing_country": "2015550123",
+    "international": "+442071234567",
+}
+
+def create_test_verification(
+    phone: str = TEST_PHONES["valid_mobile"],
+    line_type: LineType = LineType.MOBILE,
+    dnc: bool = False,
+    cached: bool = False,
+    source: VerificationSource = VerificationSource.API
+) -> PhoneVerification:
+    """Create a test PhoneVerification object"""
+    return PhoneVerification(
+        phone_number=phone,
+        line_type=line_type,
+        dnc=dnc,
+        cached=cached,
+        verified_at=datetime.now(timezone.utc),
+        source=source
+    )
+
+def create_test_csv_content(phones: List[str] = None) -> str:
+    """Create CSV content for testing bulk processing"""
+    if phones is None:
+        phones = [
+            TEST_PHONES["valid_mobile"],
+            TEST_PHONES["valid_landline"],
+            TEST_PHONES["dnc_mobile"],
+        ]
+
+    lines = ["name,phone,email"]
+    for i, phone in enumerate(phones):
+        lines.append(f"Test User {i},{phone},test{i}@example.com")
+
+    return "\n".join(lines)
+
+def create_dynamodb_item(phone: str, line_type: LineType = LineType.MOBILE, dnc: bool = False) -> Dict[str, Any]:
+    """Create a DynamoDB item for testing"""
+    ttl = int((datetime.now(timezone.utc) + timedelta(days=30)).timestamp())
+
+    return {
+        "phone_number": phone,
+        "line_type": line_type.value,  # Store as string in DynamoDB
+        "dnc": dnc,
+        "cached": True,
+        "verified_at": datetime.now(timezone.utc).isoformat(),
+        "source": VerificationSource.CACHE.value,  # Store as string in DynamoDB
+        "ttl": ttl
+    }
+
+def create_sqs_message(file_id: str, bucket: str, key: str, user_id: str) -> Dict[str, Any]:
+    """Create an SQS message for bulk processing"""
+    return {
+        "file_id": file_id,
+        "bucket": bucket,
+        "key": key,
+        "user_id": user_id,
+        "created_at": datetime.now(timezone.utc).isoformat()
+    }
+
+def create_api_gateway_event(
+    phone: str = None,
+    user_id: str = "test-user",
+    method: str = "GET",
+    path: str = "/verify"
+) -> Dict[str, Any]:
+    """Create an API Gateway event for Lambda testing"""
+    event = {
+        "httpMethod": method,
+        "path": path,
+        "headers": {
+            "Authorization": "Bearer test-token"
+        },
+        "requestContext": {
+            "authorizer": {
+                "lambda": {
+                    "principal_id": user_id,
+                    "claims": {
+                        "email": f"{user_id}@example.com"
+                    }
+                }
+            }
+        }
+    }
+
+    if phone:
+        event["queryStringParameters"] = {"p": phone}
+
+    return event

ai_lls_lib-1.0.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.3
+Name: ai-lls-lib
+Version: 1.0.0
+Summary: Landline Scrubber core library - phone verification and DNC checking
+Author: LandlineScrubber Team
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aws-lambda-powertools (>=2.30.0,<3.0.0)
+Requires-Dist: boto3 (>=1.34.0,<2.0.0)
+Requires-Dist: click (>=8.1.0,<9.0.0)
+Requires-Dist: httpx (>=0.25.0,<0.26.0)
+Requires-Dist: phonenumbers (>=8.13.0,<9.0.0)
+Requires-Dist: pydantic (>=2.5.0,<3.0.0)
+Requires-Dist: rich (>=14.0,<15.0)
+Description-Content-Type: text/markdown
+
+# AI LLS Library
+
+Core business logic library and CLI tools for Landline Scrubber - phone verification and DNC checking.
+
+## Features
+
+- Phone number normalization (E.164 format)
+- Line type detection (mobile/landline/voip)
+- DNC (Do Not Call) list checking
+- DynamoDB caching with 30-day TTL
+- Bulk CSV processing
+- Infrastructure-aware CLI for admin operations
+- AWS Lambda PowerTools integration
+
+## Installation
+
+```bash
+# Install library with Poetry
+poetry install
+
+# Install CLI globally
+pip install -e .
+```
+
+## Library Usage
+
+### Single Phone Verification
+
+```python
+from ai_lls_lib import PhoneVerifier, DynamoDBCache
+
+cache = DynamoDBCache(table_name="phone-cache")
+verifier = PhoneVerifier(cache)
+
+result = verifier.verify_sync("+15551234567")
+print(f"Line type: {result.line_type}")
+print(f"DNC: {result.dnc}")
+print(f"From cache: {result.cached}")
+```
+
+### Bulk Processing
+
+```python
+from ai_lls_lib import BulkProcessor, PhoneVerifier, DynamoDBCache
+
+cache = DynamoDBCache(table_name="phone-cache")
+verifier = PhoneVerifier(cache)
+processor = BulkProcessor(verifier)
+
+results = processor.process_csv_sync("/path/to/phones.csv")
+processor.generate_results_csv(
+    original_path="/path/to/phones.csv",
+    results=results,
+    output_path="/path/to/results.csv"
+)
+```
+
+## CLI Usage
+
+The `ai-lls` CLI provides infrastructure-aware administrative tools:
+
+### Verification Commands
+```bash
+# Verify single phone
+ai-lls verify phone +15551234567 --stack landline-api
+
+# Bulk verify CSV
+ai-lls verify bulk input.csv -o output.csv --stack landline-api
+```
+
+### Cache Management
+```bash
+# Show cache statistics
+ai-lls cache stats --stack landline-api
+
+# Get cached entry
+ai-lls cache get +15551234567 --stack landline-api
+
+# Invalidate cache entry
+ai-lls cache invalidate +15551234567 --stack landline-api
+
+# Clear old entries
+ai-lls cache clear --older-than 20 --stack landline-api
+```
+
+### Administrative Commands
+```bash
+# Manage user credits
+ai-lls admin user-credits user123 --add 100
+ai-lls admin user-credits user123 --set 500
+
+# List API keys
+ai-lls admin api-keys --user user123
+
+# Check queue status
+ai-lls admin queue-stats
+
+# View secrets (masked)
+ai-lls admin secrets --stack landline-api
+```
+
+### Test Stack Management
+```bash
+# Deploy test stack
+ai-lls test-stack deploy
+
+# Check status
+ai-lls test-stack status
+
+# Run integration tests
+ai-lls test-stack test
+
+# Delete test stack
+ai-lls test-stack delete
+```
+
+## Project Structure
+
+```
+ai-lls-lib/
+├── src/ai_lls_lib/
+│   ├── core/           # Business logic (infrastructure-agnostic)
+│   │   ├── models.py   # Pydantic models
+│   │   ├── verifier.py # Phone verification
+│   │   ├── processor.py # Bulk processing
+│   │   └── cache.py    # DynamoDB cache
+│   ├── cli/            # Infrastructure-aware CLI
+│   │   ├── __main__.py # Entry point
+│   │   ├── commands/   # Command modules
+│   │   └── aws_client.py # AWS operations
+│   └── testing/        # Test utilities
+│       └── fixtures.py # Test data
+├── tests/
+│   ├── unit/          # Mocked tests
+│   └── integration/   # AWS integration tests
+└── test-stack.yaml    # Test infrastructure
+```
+
+## Testing
+
+```bash
+# Run unit tests (mocked AWS)
+poetry run pytest tests/unit -v
+
+# Deploy test stack for integration tests
+ai-lls test-stack deploy
+
+# Run integration tests (requires test stack)
+TEST_STACK_NAME=ai-lls-lib-test poetry run pytest tests/integration -v
+
+# All tests with coverage
+poetry run pytest --cov=src --cov-report=html
+
+# Clean up
+ai-lls test-stack delete
+```
+
+## Development
+
+### Current Stub Implementation
+
+For demo purposes, verification uses stub logic based on last digit:
+- Ends in 3: mobile, not on DNC
+- Ends in 2: landline, not on DNC
+- Ends in 1: mobile, on DNC
+- Ends in 0: landline, on DNC
+- Otherwise: mobile, not on DNC
+
+TODO markers indicate where real API integration will be added.
+
+### Code Quality
+
+```bash
+# Format code
+poetry run black src/ tests/
+poetry run isort src/ tests/
+
+# Type checking
+poetry run mypy src/
+
+# Run pre-commit hooks
+pre-commit run --all-files
+```
+
+## Environment Variables
+
+- `DNC_API_KEY` - DNC verification API key
+- `DNC_CHECK_API_KEY` - Alternative DNC service
+- `PHONE_VERIFY_API_KEY` - Line type verification
+- `AWS_REGION` - AWS region (default: us-east-1)
+- `AWS_PROFILE` - AWS profile for CLI operations
+
+## License
+
+Proprietary - All rights reserved
+
+## Release Process
+
+This library uses semantic versioning and publishes to:
+- TestPyPI on dev branch pushes (pre-release versions)
+- PyPI on main branch pushes (stable releases)
+

ai_lls_lib-1.0.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+ai_lls_lib/__init__.py,sha256=XfIG376ImlT_OH0R75BNpoqcxsx0fIp6cSFpQw_XhL8,584
+ai_lls_lib/cli/__init__.py,sha256=m9qjZTW1jpENwXAUeuRrlP0b66BWRcqSO28MSjvOyCs,74
+ai_lls_lib/cli/__main__.py,sha256=DH9x08k6GWBSqVWspHgWTxGM7NkTBZ2OS2KrVW-XQaA,671
+ai_lls_lib/cli/aws_client.py,sha256=YcCWCpTNOW9JPLxSNLRy5-F5HPKguJJk7dPNrPqhJv0,3952
+ai_lls_lib/cli/commands/__init__.py,sha256=_kROrYuR_p2i110c0OvNeArfEFQbn15zR1c3pdeZOoo,28
+ai_lls_lib/cli/commands/admin.py,sha256=bNBJi2fZBP0J40JQP6HP7NYadNmI214iII1TeLhooyE,6687
+ai_lls_lib/cli/commands/cache.py,sha256=vWt0vy4L9CEgUEWUzfdehU6u43PE8vUvHx7xxg4e5tw,5680
+ai_lls_lib/cli/commands/test_stack.py,sha256=rNq4mhRXX7Ixo67kSoEPWlxqgXCzM9e2PR96qTAG7pE,7378
+ai_lls_lib/cli/commands/verify.py,sha256=tKHkSghrtnqkjAQGvTs-5uDUgstQO0HMW04EddRPgJU,4253
+ai_lls_lib/core/__init__.py,sha256=QUaeQHIyvknkgMxIbfXRo1a5jSQpiJkB84dId5ubuEk,36
+ai_lls_lib/core/cache.py,sha256=MubgyAF3y7BBF9am39Ni98NgikZ9UBZUG-KtbE3XWX4,3711
+ai_lls_lib/core/models.py,sha256=ABRYaeMCWahQh4WdbkCxt3AO0-EvPWZwlL-JITQSnEM,2381
+ai_lls_lib/core/processor.py,sha256=s49fVlZt6lnfWNgboiHsC6ruman4oIXzgVqzuwExKBQ,4916
+ai_lls_lib/core/verifier.py,sha256=fglRDoFgrQyX4UuYknZLYX4t9HlpTS2HMVsfszSNXQ4,3257
+ai_lls_lib/testing/__init__.py,sha256=RUxRYBzzPCPS15Umb6bUrE6rL5BQXBQf4SJM2E3ffrg,39
+ai_lls_lib/testing/fixtures.py,sha256=_n6bbr95LnQf9Dvu1qKs2HsvHEA7AAbe59B75qxE10w,3310
+ai_lls_lib-1.0.0.dist-info/METADATA,sha256=q4xSigc2_m2Jmv45SfXFfH9dBbFOVDcfIBa0Uzaw48w,5344
+ai_lls_lib-1.0.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+ai_lls_lib-1.0.0.dist-info/entry_points.txt,sha256=Pi0V_HBViEKGFbNQKatl5lhhnHHBXlxaom-5gH9gXZ0,55
+ai_lls_lib-1.0.0.dist-info/RECORD,,

ai_lls_lib-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any

ai_lls_lib-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ai-lls=ai_lls_lib.cli.__main__:main
+