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

ai_lls_lib/cli/commands/test_stack.py

@@ -0,0 +1,216 @@
+"""
+Test stack management commands
+"""
+import click
+import subprocess
+import os
+import time
+from ai_lls_lib.cli.aws_client import AWSClient
+
+@click.group(name="test-stack")
+def test_stack_group():
+    """Test stack management"""
+    pass
+
+@test_stack_group.command(name="deploy")
+@click.option("--stack-name", default="ai-lls-lib-test", help="Test stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def deploy_test_stack(stack_name, profile, region):
+    """Deploy the test stack"""
+    template_path = os.path.join(
+        os.path.dirname(__file__),
+        "..", "..", "..", "..", "template.yaml"
+    )
+
+    if not os.path.exists(template_path):
+        click.echo(f"Test stack template not found at {template_path}")
+        click.echo("Creating minimal test stack template...")
+
+        # Create a minimal test stack
+        template_content = """AWSTemplateFormatVersion: '2010-09-09'
+Description: Minimal test stack for ai-lls-lib integration testing
+
+Resources:
+  TestPhoneCache:
+    Type: AWS::DynamoDB::Table
+    Properties:
+      TableName: !Sub "${AWS::StackName}-phone-cache"
+      BillingMode: PAY_PER_REQUEST
+      AttributeDefinitions:
+        - AttributeName: phone_number
+          AttributeType: S
+      KeySchema:
+        - AttributeName: phone_number
+          KeyType: HASH
+      TimeToLiveSpecification:
+        AttributeName: ttl
+        Enabled: true
+
+  TestUploadBucket:
+    Type: AWS::S3::Bucket
+    Properties:
+      BucketName: !Sub "${AWS::StackName}-uploads-${AWS::AccountId}"
+      LifecycleConfiguration:
+        Rules:
+          - Id: DeleteOldTestFiles
+            Status: Enabled
+            ExpirationInDays: 1
+
+  TestQueue:
+    Type: AWS::SQS::Queue
+    Properties:
+      QueueName: !Sub "${AWS::StackName}-test-queue"
+      MessageRetentionPeriod: 3600  # 1 hour for test
+
+Outputs:
+  CacheTableName:
+    Value: !Ref TestPhoneCache
+  BucketName:
+    Value: !Ref TestUploadBucket
+  QueueUrl:
+    Value: !Ref TestQueue
+"""
+
+        os.makedirs(os.path.dirname(template_path), exist_ok=True)
+        with open(template_path, 'w') as f:
+            f.write(template_content)
+        click.echo(f"Created {template_path}")
+
+    # Deploy using AWS CLI
+    cmd = [
+        "aws", "cloudformation", "deploy",
+        "--template-file", template_path,
+        "--stack-name", stack_name,
+        "--capabilities", "CAPABILITY_IAM"
+    ]
+
+    if profile:
+        cmd.extend(["--profile", profile])
+    if region:
+        cmd.extend(["--region", region])
+
+    click.echo(f"Deploying test stack '{stack_name}'...")
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode == 0:
+            click.echo("Test stack deployed successfully!")
+
+            # Show outputs
+            aws = AWSClient(region=region, profile=profile)
+            outputs = aws.get_stack_outputs(stack_name)
+            if outputs:
+                click.echo("\nStack Outputs:")
+                for key, value in outputs.items():
+                    click.echo(f"  {key}: {value}")
+        else:
+            click.echo(f"Deployment failed: {result.stderr}", err=True)
+    except Exception as e:
+        click.echo(f"Error deploying test stack: {e}", err=True)
+
+@test_stack_group.command(name="delete")
+@click.option("--stack-name", default="ai-lls-lib-test", help="Test stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+@click.confirmation_option(prompt="Delete test stack and all resources?")
+def delete_test_stack(stack_name, profile, region):
+    """Delete the test stack"""
+    aws = AWSClient(region=region, profile=profile)
+
+    try:
+        # Empty S3 bucket first
+        outputs = aws.get_stack_outputs(stack_name)
+        if 'BucketName' in outputs:
+            bucket_name = outputs['BucketName']
+            click.echo(f"Emptying bucket {bucket_name}...")
+
+            # List and delete all objects
+            try:
+                objects = aws.s3.list_objects_v2(Bucket=bucket_name)
+                if 'Contents' in objects:
+                    for obj in objects['Contents']:
+                        aws.s3.delete_object(Bucket=bucket_name, Key=obj['Key'])
+            except:
+                pass  # Bucket might not exist
+
+        # Delete stack
+        click.echo(f"Deleting stack '{stack_name}'...")
+        aws.cloudformation.delete_stack(StackName=stack_name)
+
+        # Wait for deletion
+        click.echo("Waiting for stack deletion...")
+        waiter = aws.cloudformation.get_waiter('stack_delete_complete')
+        waiter.wait(StackName=stack_name)
+
+        click.echo("Test stack deleted successfully!")
+
+    except Exception as e:
+        click.echo(f"Error deleting test stack: {e}", err=True)
+
+@test_stack_group.command(name="status")
+@click.option("--stack-name", default="ai-lls-lib-test", help="Test stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def test_stack_status(stack_name, profile, region):
+    """Show test stack status"""
+    aws = AWSClient(region=region, profile=profile)
+
+    try:
+        response = aws.cloudformation.describe_stacks(StackName=stack_name)
+        stack = response['Stacks'][0]
+
+        click.echo(f"\nTest Stack: {stack_name}")
+        click.echo("=" * 50)
+        click.echo(f"Status: {stack['StackStatus']}")
+        click.echo(f"Created: {stack.get('CreationTime', 'N/A')}")
+
+        if 'Outputs' in stack:
+            click.echo("\nOutputs:")
+            for output in stack['Outputs']:
+                click.echo(f"  {output['OutputKey']}: {output['OutputValue']}")
+
+    except aws.cloudformation.exceptions.ClientError as e:
+        if 'does not exist' in str(e):
+            click.echo(f"Test stack '{stack_name}' does not exist")
+        else:
+            click.echo(f"Error: {e}", err=True)
+
+@test_stack_group.command(name="test")
+@click.option("--stack-name", default="ai-lls-lib-test", help="Test stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def run_integration_tests(stack_name, profile, region):
+    """Run integration tests against test stack"""
+    aws = AWSClient(region=region, profile=profile)
+
+    try:
+        # Check stack exists
+        outputs = aws.get_stack_outputs(stack_name)
+        if not outputs:
+            click.echo(f"Test stack '{stack_name}' not found. Deploy it first.")
+            return
+
+        # Set environment variables for tests
+        os.environ['TEST_STACK_NAME'] = stack_name
+        os.environ['TEST_CACHE_TABLE'] = outputs.get('CacheTableName', '')
+        os.environ['TEST_BUCKET'] = outputs.get('BucketName', '')
+        os.environ['TEST_QUEUE_URL'] = outputs.get('QueueUrl', '')
+
+        if profile:
+            os.environ['AWS_PROFILE'] = profile
+        if region:
+            os.environ['AWS_REGION'] = region
+
+        click.echo(f"Running integration tests against '{stack_name}'...")
+
+        # Run pytest
+        cmd = ["pytest", "tests/integration", "-v"]
+        result = subprocess.run(cmd, cwd=os.path.dirname(template_path))
+
+        if result.returncode == 0:
+            click.echo("\nIntegration tests passed!")
+        else:
+            click.echo("\nSome tests failed", err=True)
+
+    except Exception as e:
+        click.echo(f"Error running tests: {e}", err=True)

ai_lls_lib/cli/commands/verify.py

@@ -0,0 +1,111 @@
+"""
+Verification commands - direct phone verification bypassing API
+"""
+import click
+import json
+from datetime import datetime
+from ai_lls_lib.core.verifier import PhoneVerifier
+from ai_lls_lib.core.cache import DynamoDBCache
+from ai_lls_lib.cli.aws_client import AWSClient
+
+@click.group(name="verify")
+def verify_group():
+    """Phone verification commands"""
+    pass
+
+@verify_group.command(name="phone")
+@click.argument("phone_number")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--skip-cache", is_flag=True, help="Skip cache lookup")
+@click.option("--profile", help="AWS profile to use")
+@click.option("--region", help="AWS region")
+def verify_phone(phone_number, stack, skip_cache, profile, region):
+    """Verify a single phone number"""
+    aws = AWSClient(region=region, profile=profile)
+
+    # Get cache table name from stack
+    cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+    click.echo(f"Using cache table: {cache_table}")
+
+    # Initialize cache and verifier
+    cache = DynamoDBCache(table_name=cache_table)
+    verifier = PhoneVerifier(cache=cache)
+
+    try:
+        if skip_cache:
+            # Force fresh lookup
+            normalized = verifier.normalize_phone(phone_number)
+            line_type = verifier._check_line_type_sync(normalized)
+            dnc = verifier._check_dnc_sync(normalized)
+            result = {
+                "phone_number": normalized,
+                "line_type": line_type,
+                "dnc": dnc,
+                "cached": False,
+                "verified_at": datetime.utcnow().isoformat(),
+                "source": "cli-direct"
+            }
+        else:
+            result = verifier.verify_sync(phone_number)
+            result = result.dict() if hasattr(result, 'dict') else result
+
+        # Display results
+        click.echo("\n" + "=" * 40)
+        click.echo(f"Phone: {result['phone_number']}")
+        click.echo(f"Line Type: {result['line_type']}")
+        click.echo(f"DNC Status: {'Yes' if result['dnc'] else 'No'}")
+        click.echo(f"From Cache: {'Yes' if result.get('cached') else 'No'}")
+        click.echo(f"Verified: {result.get('verified_at', 'Unknown')}")
+        click.echo("=" * 40)
+
+        if click.confirm("\nShow JSON output?"):
+            click.echo(json.dumps(result, indent=2, default=str))
+
+    except ValueError as e:
+        click.echo(f"Error: {e}", err=True)
+    except Exception as e:
+        click.echo(f"Verification failed: {e}", err=True)
+
+@verify_group.command(name="bulk")
+@click.argument("csv_file", type=click.Path(exists=True))
+@click.option("--output", "-o", help="Output CSV file")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile to use")
+@click.option("--region", help="AWS region")
+def verify_bulk(csv_file, output, stack, profile, region):
+    """Process a CSV file for bulk verification"""
+    from ai_lls_lib.core.processor import BulkProcessor
+
+    aws = AWSClient(region=region, profile=profile)
+    cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+
+    cache = DynamoDBCache(table_name=cache_table)
+    verifier = PhoneVerifier(cache=cache)
+    processor = BulkProcessor(verifier=verifier)
+
+    click.echo(f"Processing {csv_file}...")
+
+    try:
+        # Process CSV
+        results = processor.process_csv_sync(csv_file)
+        click.echo(f"\nProcessed {len(results)} phone numbers")
+
+        # Show summary
+        mobile_count = sum(1 for r in results if r.line_type == "mobile")
+        landline_count = sum(1 for r in results if r.line_type == "landline")
+        dnc_count = sum(1 for r in results if r.dnc)
+        cached_count = sum(1 for r in results if r.cached)
+
+        click.echo("\nSummary:")
+        click.echo(f"  Mobile: {mobile_count}")
+        click.echo(f"  Landline: {landline_count}")
+        click.echo(f"  On DNC: {dnc_count}")
+        click.echo(f"  From Cache: {cached_count}")
+
+        # Generate output if requested
+        if output:
+            processor.generate_results_csv(csv_file, results, output)
+            click.echo(f"\nResults saved to: {output}")
+
+    except Exception as e:
+        click.echo(f"Bulk processing failed: {e}", err=True)

ai_lls_lib/core/__init__.py

@@ -0,0 +1,3 @@
+"""
+Core business logic modules
+"""

ai_lls_lib/core/cache.py

@@ -0,0 +1,106 @@
+"""
+DynamoDB cache implementation for phone verifications
+"""
+import os
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+import boto3
+from aws_lambda_powertools import Logger
+from .models import PhoneVerification, CacheEntry
+
+logger = Logger()
+
+
+class DynamoDBCache:
+    """Cache for phone verification results using DynamoDB with TTL"""
+
+    def __init__(self, table_name: str, ttl_days: int = 30):
+        self.table_name = table_name
+        self.ttl_days = ttl_days
+        self.dynamodb = boto3.resource("dynamodb")
+        self.table = self.dynamodb.Table(table_name)
+
+    def get(self, phone_number: str) -> Optional[PhoneVerification]:
+        """Get cached verification result"""
+        try:
+            response = self.table.get_item(Key={"phone_number": phone_number})
+
+            if "Item" not in response:
+                logger.info(f"Cache miss for {phone_number[:6]}***")
+                return None
+
+            item = response["Item"]
+            logger.info(f"Cache hit for {phone_number[:6]}***")
+
+            return PhoneVerification(
+                phone_number=item["phone_number"],
+                line_type=item["line_type"],
+                dnc=item["dnc"],
+                cached=True,
+                verified_at=datetime.fromisoformat(item["verified_at"]),
+                source="cache"
+            )
+
+        except Exception as e:
+            logger.error(f"Cache get error: {str(e)}")
+            return None
+
+    def set(self, phone_number: str, verification: PhoneVerification) -> None:
+        """Store verification result in cache"""
+        try:
+            ttl = int((datetime.now(timezone.utc) + timedelta(days=self.ttl_days)).timestamp())
+
+            self.table.put_item(
+                Item={
+                    "phone_number": phone_number,
+                    "line_type": verification.line_type,
+                    "dnc": verification.dnc,
+                    "verified_at": verification.verified_at.isoformat(),
+                    "source": verification.source,
+                    "ttl": ttl
+                }
+            )
+
+            logger.info(f"Cached result for {phone_number[:6]}***")
+
+        except Exception as e:
+            logger.error(f"Cache set error: {str(e)}")
+            # Don't fail the request if cache write fails
+
+    def batch_get(self, phone_numbers: list[str]) -> dict[str, Optional[PhoneVerification]]:
+        """Get multiple cached results"""
+        results = {}
+
+        # DynamoDB batch get (max 100 items per request)
+        for i in range(0, len(phone_numbers), 100):
+            batch = phone_numbers[i:i+100]
+
+            try:
+                response = self.dynamodb.batch_get_item(
+                    RequestItems={
+                        self.table_name: {
+                            "Keys": [{"phone_number": phone} for phone in batch]
+                        }
+                    }
+                )
+
+                for item in response.get("Responses", {}).get(self.table_name, []):
+                    phone = item["phone_number"]
+                    results[phone] = PhoneVerification(
+                        phone_number=phone,
+                        line_type=item["line_type"],
+                        dnc=item["dnc"],
+                        cached=True,
+                        verified_at=datetime.fromisoformat(item["verified_at"]),
+                        source="cache"
+                    )
+
+            except Exception as e:
+                logger.error(f"Batch cache get error: {str(e)}")
+
+        # Fill in None for misses
+        for phone in phone_numbers:
+            if phone not in results:
+                results[phone] = None
+
+        return results

ai_lls_lib/core/models.py

@@ -0,0 +1,77 @@
+"""
+Data models for phone verification
+"""
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class LineType(str, Enum):
+    """Phone line type enumeration"""
+    MOBILE = "mobile"
+    LANDLINE = "landline"
+    VOIP = "voip"
+    UNKNOWN = "unknown"
+
+
+class VerificationSource(str, Enum):
+    """Source of verification data"""
+    API = "api"
+    CACHE = "cache"
+    BULK_IMPORT = "bulk_import"
+
+
+class JobStatus(str, Enum):
+    """Bulk job status enumeration"""
+    PENDING = "pending"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class PhoneVerification(BaseModel):
+    """Result of phone number verification"""
+    phone_number: str = Field(..., description="E.164 formatted phone number")
+    line_type: LineType = Field(
+        ..., description="Type of phone line"
+    )
+    dnc: bool = Field(..., description="Whether number is on DNC list")
+    cached: bool = Field(..., description="Whether result came from cache")
+    verified_at: datetime = Field(..., description="When verification occurred")
+    source: VerificationSource = Field(
+        ..., description="Source of verification data"
+    )
+
+    class Config:
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+
+class BulkJob(BaseModel):
+    """Bulk processing job metadata"""
+    job_id: str = Field(..., description="Unique job identifier")
+    status: JobStatus = Field(
+        ..., description="Current job status"
+    )
+
+
+class BulkJobStatus(BulkJob):
+    """Extended bulk job status with progress info"""
+    total_rows: Optional[int] = Field(None, description="Total rows to process")
+    processed_rows: Optional[int] = Field(None, description="Rows processed so far")
+    result_url: Optional[str] = Field(None, description="S3 URL of results")
+    created_at: datetime = Field(..., description="Job creation time")
+    completed_at: Optional[datetime] = Field(None, description="Job completion time")
+    error: Optional[str] = Field(None, description="Error message if failed")
+
+
+class CacheEntry(BaseModel):
+    """DynamoDB cache entry"""
+    phone_number: str
+    line_type: str  # Stored as string in DynamoDB
+    dnc: bool
+    verified_at: str  # ISO format string
+    source: str  # Stored as string in DynamoDB
+    ttl: int  # Unix timestamp for DynamoDB TTL

ai_lls_lib/core/processor.py

@@ -0,0 +1,135 @@
+"""
+Bulk CSV processing for phone verification
+"""
+import csv
+from typing import List, Optional
+from aws_lambda_powertools import Logger
+from .models import PhoneVerification
+from .verifier import PhoneVerifier
+
+logger = Logger()
+
+
+class BulkProcessor:
+    """Process CSV files for bulk phone verification"""
+
+    def __init__(self, verifier: PhoneVerifier):
+        self.verifier = verifier
+
+    def process_csv_sync(self, file_path: str, phone_column: str = "phone") -> List[PhoneVerification]:
+        """
+        Process CSV file synchronously.
+        Returns list of verification results.
+        """
+        results = []
+
+        try:
+            with open(file_path, 'r', encoding='utf-8-sig') as f:
+                reader = csv.DictReader(f)
+
+                # Find phone column (case-insensitive)
+                headers = reader.fieldnames or []
+                phone_col = self._find_phone_column(headers, phone_column)
+
+                if not phone_col:
+                    raise ValueError(f"Phone column '{phone_column}' not found in CSV")
+
+                for row_num, row in enumerate(reader, start=2):  # Start at 2 (header is 1)
+                    try:
+                        phone = row.get(phone_col, "").strip()
+                        if not phone:
+                            logger.warning(f"Empty phone at row {row_num}")
+                            continue
+
+                        # Verify phone
+                        result = self.verifier.verify_sync(phone)
+                        results.append(result)
+
+                        # Log progress every 100 rows
+                        if len(results) % 100 == 0:
+                            logger.info(f"Processed {len(results)} phones")
+
+                    except ValueError as e:
+                        logger.warning(f"Invalid phone at row {row_num}: {str(e)}")
+                        continue
+                    except Exception as e:
+                        logger.error(f"Error processing row {row_num}: {str(e)}")
+                        continue
+
+                logger.info(f"Completed processing {len(results)} valid phones")
+
+        except Exception as e:
+            logger.error(f"CSV processing failed: {str(e)}")
+            raise
+
+        return results
+
+    def _find_phone_column(self, headers: List[str], preferred: str) -> Optional[str]:
+        """Find phone column in headers (case-insensitive)"""
+        # First try exact match
+        for header in headers:
+            if header.lower() == preferred.lower():
+                return header
+
+        # Common phone column names
+        phone_patterns = [
+            "phone", "phone_number", "phonenumber", "mobile",
+            "cell", "telephone", "tel", "number", "contact"
+        ]
+
+        for header in headers:
+            header_lower = header.lower()
+            for pattern in phone_patterns:
+                if pattern in header_lower:
+                    logger.info(f"Using column '{header}' as phone column")
+                    return header
+
+        return None
+
+    def generate_results_csv(
+        self,
+        original_path: str,
+        results: List[PhoneVerification],
+        output_path: str
+    ) -> None:
+        """
+        Generate CSV with original data plus verification results.
+        Adds columns: line_type, dnc, cached
+        """
+        # Create lookup dict
+        results_map = {r.phone_number: r for r in results}
+
+        with open(original_path, 'r', encoding='utf-8-sig') as infile:
+            reader = csv.DictReader(infile)
+            headers = reader.fieldnames or []
+
+            # Add new columns
+            output_headers = headers + ["line_type", "dnc", "cached"]
+
+            with open(output_path, 'w', newline='', encoding='utf-8') as outfile:
+                writer = csv.DictWriter(outfile, fieldnames=output_headers)
+                writer.writeheader()
+
+                phone_col = self._find_phone_column(headers, "phone")
+
+                for row in reader:
+                    phone = row.get(phone_col, "").strip()
+
+                    # Try to normalize for lookup
+                    try:
+                        normalized = self.verifier.normalize_phone(phone)
+                        if normalized in results_map:
+                            result = results_map[normalized]
+                            row["line_type"] = result.line_type
+                            row["dnc"] = "true" if result.dnc else "false"
+                            row["cached"] = "true" if result.cached else "false"
+                        else:
+                            row["line_type"] = "unknown"
+                            row["dnc"] = ""
+                            row["cached"] = ""
+                    except:
+                        row["line_type"] = "invalid"
+                        row["dnc"] = ""
+                        row["cached"] = ""
+
+                    writer.writerow(row)