ai-lls-lib 2.0.0rc2__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,204 @@
+"""
+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
+from ai_lls_lib.providers import StubProvider, ExternalAPIProvider
+
+@click.group(name="verify")
+def verify_group():
+    """Phone verification commands"""
+    pass
+
+@verify_group.command(name="phone")
+@click.argument("phone_number")
+@click.option("--output", type=click.Choice(["json", "text"], case_sensitive=False), default="json", help="Output format")
+@click.option("--provider", type=click.Choice(["external", "stub"], case_sensitive=False), default="external", help="Verification provider to use")
+@click.option("--no-cache", is_flag=True, help="Disable caching even if AWS is available")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name (for caching)")
+@click.option("--profile", help="AWS profile to use (for caching)")
+@click.option("--region", help="AWS region (for caching)")
+@click.option("--verbose", is_flag=True, help="Show detailed output")
+def verify_phone(phone_number, output, provider, no_cache, stack, profile, region, verbose):
+    """
+    Verify a phone number (works with or without AWS).
+
+    Accepts phone numbers in various formats:
+      - 6197966726 (10 digits)
+      - 16197966726 (11 digits with 1)
+      - +16197966726 (E.164 format)
+      - 619-796-6726 (with dashes)
+      - (619) 796-6726 (with parentheses)
+    """
+
+    # Select provider based on parameter
+    if provider == "stub":
+        provider_instance = StubProvider()
+        if verbose:
+            click.echo("Using StubProvider (deterministic test mode)")
+    else:
+        provider_instance = ExternalAPIProvider()
+        if verbose:
+            click.echo("Using ExternalAPIProvider (real API calls)")
+
+    # Try to set up caching if not explicitly disabled
+    cache = None
+    cache_status = ""
+
+    if not no_cache:
+        try:
+            aws = AWSClient(region=region, profile=profile)
+            cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+            cache = DynamoDBCache(table_name=cache_table)
+            cache_status = "(Using cache)"
+            if verbose:
+                click.echo(f"Using DynamoDB cache table: {cache_table}")
+        except Exception as e:
+            cache_status = "(No cache - direct API call)"
+            if verbose:
+                click.echo(f"Cache not available: {e}")
+                click.echo("Continuing without cache (direct API calls)")
+    else:
+        cache_status = "(Cache disabled)"
+        if verbose:
+            click.echo("Cache explicitly disabled with --no-cache")
+
+    # Initialize verifier (works with or without cache)
+    verifier = PhoneVerifier(cache=cache, provider=provider_instance)
+
+    try:
+        # Verify the phone number
+        result = verifier.verify(phone_number)
+        result_dict = result.dict() if hasattr(result, 'dict') else result
+
+        # Prepare clean output
+        # Extract line type value if it's an enum
+        line_type = result_dict['line_type']
+        if hasattr(line_type, 'value'):
+            line_type = line_type.value
+
+        # Build clean output dictionary
+        output_data = {
+            "phone": result_dict['phone_number'],
+            "line_type": line_type,
+            "dnc": result_dict['dnc'],
+            "cached": result_dict.get('cached', False),
+            "verified_at": str(result_dict.get('verified_at', 'Unknown'))
+        }
+
+        if output == "json":
+            # JSON output (default for composability)
+            click.echo(json.dumps(output_data, indent=2))
+        else:
+            # Text output (human-readable)
+            click.echo(f"Phone: {output_data['phone']}")
+            click.echo(f"Line Type: {output_data['line_type']}")
+            click.echo(f"DNC: {output_data['dnc']}")
+            click.echo(f"Cached: {output_data['cached']}")
+            click.echo(f"Verified: {output_data['verified_at']}")
+
+    except ValueError as e:
+        if output == "json":
+            error_data = {"error": str(e)}
+            click.echo(json.dumps(error_data), err=True)
+        else:
+            click.echo(f"Error: {e}", err=True)
+            click.echo("\nSupported formats:", err=True)
+            click.echo("  6197966726      (10 digits)", err=True)
+            click.echo("  16197966726     (11 digits)", err=True)
+            click.echo("  +16197966726    (E.164)", err=True)
+            click.echo("  619-796-6726    (with dashes)", err=True)
+            click.echo("  (619) 796-6726  (with parentheses)", err=True)
+        import sys
+        sys.exit(1)
+    except Exception as e:
+        if output == "json":
+            error_data = {"error": str(e)}
+            click.echo(json.dumps(error_data), err=True)
+        else:
+            click.echo(f"Verification failed: {e}", err=True)
+            if verbose:
+                import traceback
+                click.echo(traceback.format_exc(), err=True)
+        import sys
+        sys.exit(1)
+
+@verify_group.command(name="bulk")
+@click.argument("csv_file", type=click.Path(exists=True))
+@click.option("--output", "-o", help="Output CSV file")
+@click.option("--provider", type=click.Choice(["external", "stub"], case_sensitive=False), default="external", help="Verification provider to use")
+@click.option("--no-cache", is_flag=True, help="Disable caching even if AWS is available")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name (for caching)")
+@click.option("--profile", help="AWS profile to use (for caching)")
+@click.option("--region", help="AWS region (for caching)")
+@click.option("--verbose", is_flag=True, help="Show detailed output")
+def verify_bulk(csv_file, output, provider, no_cache, stack, profile, region, verbose):
+    """Process a CSV file for bulk verification"""
+    from ai_lls_lib.core.processor import BulkProcessor
+
+    # Select provider based on parameter
+    if provider == "stub":
+        provider_instance = StubProvider()
+        if verbose:
+            click.echo("Using StubProvider (deterministic test mode)")
+    else:
+        provider_instance = ExternalAPIProvider()
+        if verbose:
+            click.echo("Using ExternalAPIProvider (real API calls)")
+
+    # Try to set up caching if not explicitly disabled
+    cache = None
+
+    if not no_cache:
+        try:
+            aws = AWSClient(region=region, profile=profile)
+            cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+            cache = DynamoDBCache(table_name=cache_table)
+            if verbose:
+                click.echo(f"Using DynamoDB cache table: {cache_table}")
+        except Exception as e:
+            if verbose:
+                click.echo(f"Cache not available: {e}")
+                click.echo("Continuing without cache (direct API calls)")
+    else:
+        if verbose:
+            click.echo("Cache explicitly disabled with --no-cache")
+
+    # Initialize verifier (works with or without cache)
+    verifier = PhoneVerifier(cache=cache, provider=provider_instance)
+    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}")
+        if cache:
+            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)
+        if verbose:
+            import traceback
+            click.echo(traceback.format_exc(), err=True)

ai_lls_lib/cli/env_loader.py

@@ -0,0 +1,129 @@
+"""Environment variable loader for CLI commands."""
+
+import os
+from pathlib import Path
+from typing import Optional, Dict
+import click
+
+
+def load_env_file(env_path: Path, verbose: bool = False) -> Dict[str, str]:
+    """Load environment variables from a .env file."""
+    env_vars = {}
+    if env_path.exists():
+        try:
+            with open(env_path, 'r') as f:
+                for line in f:
+                    line = line.strip()
+                    if line and not line.startswith('#') and '=' in line:
+                        key, value = line.split('=', 1)
+                        # Remove quotes if present
+                        value = value.strip().strip('"').strip("'")
+                        env_vars[key.strip()] = value
+        except Exception as e:
+            if verbose:
+                click.echo(f"Warning: Could not read {env_path}: {e}", err=True)
+    return env_vars
+
+
+def load_environment_config() -> Dict[str, str]:
+    """
+    Load environment variables from multiple sources in order:
+    1. ~/.lls/.env (user global config)
+    2. ./.env (project local config)
+    3. System environment variables (highest priority)
+
+    Returns merged dictionary with system env taking precedence.
+    """
+    env_vars = {}
+
+    # Load from ~/.lls/.env
+    home_env = Path.home() / '.lls' / '.env'
+    if home_env.exists():
+        home_vars = load_env_file(home_env)
+        env_vars.update(home_vars)
+        click.echo(f"Loaded {len(home_vars)} variables from {home_env}", err=True)
+
+    # Load from ./.env
+    local_env = Path('.env')
+    if local_env.exists():
+        local_vars = load_env_file(local_env)
+        env_vars.update(local_vars)
+        click.echo(f"Loaded {len(local_vars)} variables from {local_env}", err=True)
+
+    # System environment variables override file-based ones
+    env_vars.update(os.environ)
+
+    return env_vars
+
+
+def get_stripe_key(environment: str, env_vars: Optional[Dict[str, str]] = None) -> Optional[str]:
+    """
+    Get Stripe API key for the specified environment.
+
+    Looks for keys in this order:
+    1. STAGING_STRIPE_SECRET_KEY or PROD_STRIPE_SECRET_KEY (based on environment)
+    2. STRIPE_SECRET_KEY (fallback)
+
+    Args:
+        environment: 'staging' or 'production'
+        env_vars: Optional pre-loaded environment variables
+
+    Returns:
+        Stripe API key or None if not found
+    """
+    if env_vars is None:
+        env_vars = load_environment_config()
+
+    # Map environment names to prefixes
+    env_prefix_map = {
+        'staging': 'STAGING',
+        'production': 'PROD'
+    }
+    if environment not in env_prefix_map:
+        raise ValueError(f"Invalid environment '{environment}'. Must be 'staging' or 'production'")
+    env_prefix = env_prefix_map[environment]
+
+    # Try environment-specific key first
+    env_key = f"{env_prefix}_STRIPE_SECRET_KEY"
+    if env_key in env_vars:
+        return env_vars[env_key]
+
+    # Fall back to generic key
+    if 'STRIPE_SECRET_KEY' in env_vars:
+        return env_vars['STRIPE_SECRET_KEY']
+
+    return None
+
+
+def get_env_variable(key: str, environment: Optional[str] = None,
+                     env_vars: Optional[Dict[str, str]] = None) -> Optional[str]:
+    """
+    Get an environment variable, optionally with environment prefix.
+
+    Args:
+        key: Variable name (e.g., 'API_URL')
+        environment: Optional environment ('staging' or 'production')
+        env_vars: Optional pre-loaded environment variables
+
+    Returns:
+        Variable value or None if not found
+    """
+    if env_vars is None:
+        env_vars = load_environment_config()
+
+    if environment:
+        env_prefix_map = {
+            'staging': 'STAGING',
+            'production': 'PROD'
+        }
+        if environment not in env_prefix_map:
+            raise ValueError(f"Invalid environment '{environment}'. Must be 'staging' or 'production'")
+        env_prefix = env_prefix_map[environment]
+
+        # Try environment-specific key first
+        env_key = f"{env_prefix}_{key}"
+        if env_key in env_vars:
+            return env_vars[env_key]
+
+    # Fall back to non-prefixed key
+    return env_vars.get(key)

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