ai-lls-lib 1.5.0rc3__py3-none-any.whl → 1.5.0rc5__py3-none-any.whl

ai_lls_lib/__init__.py

@@ -17,7 +17,7 @@ from ai_lls_lib.core.verifier import PhoneVerifier
 from ai_lls_lib.core.processor import BulkProcessor
 from ai_lls_lib.core.cache import DynamoDBCache
 
-__version__ = "1.5.0-rc.3"
+__version__ = "1.5.0-rc.5"
 __all__ = [
     "PhoneVerification",
     "BulkJob",

ai_lls_lib/cli/__main__.py

@@ -3,13 +3,45 @@ Landline Scrubber CLI entry point
 """
 import click
 import sys
-from ai_lls_lib.cli.commands import verify, cache, admin, test_stack, stripe
+import os
+from pathlib import Path
+from ai_lls_lib.cli.commands import verify, cache, admin, test_stack, stripe, monitor
+from ai_lls_lib.cli.env_loader import load_env_file
+
+def load_env_files(verbose=False):
+    """Load .env files from ~/.lls and current directory"""
+    # Load from ~/.lls/.env
+    home_env = Path.home() / '.lls' / '.env'
+    if home_env.exists():
+        env_vars = load_env_file(home_env)
+        for key, value in env_vars.items():
+            if key not in os.environ:  # Don't override existing env vars
+                os.environ[key] = value
+        if env_vars and verbose:
+            click.echo(f"Loaded {len(env_vars)} variables from {home_env}", err=True)
+
+    # Load from current directory .env
+    local_env = Path('.env')
+    if local_env.exists():
+        env_vars = load_env_file(local_env)
+        for key, value in env_vars.items():
+            if key not in os.environ:  # Don't override existing env vars
+                os.environ[key] = value
+        if env_vars and verbose:
+            click.echo(f"Loaded {len(env_vars)} variables from {local_env}", err=True)
+
+    # Set default environment to 'prod' if not set
+    if 'ENVIRONMENT' not in os.environ:
+        os.environ['ENVIRONMENT'] = 'prod'
+        if verbose:
+            click.echo(f"Set default ENVIRONMENT=prod", err=True)
 
 @click.group()
 @click.version_option(version="0.1.0", prog_name="ai-lls")
 def cli():
     """Landline Scrubber CLI - Administrative and debugging tools"""
-    pass
+    # Load environment files at startup
+    load_env_files()
 
 # Register command groups
 cli.add_command(verify.verify_group)
@@ -17,6 +49,7 @@ cli.add_command(cache.cache_group)
 cli.add_command(admin.admin_group)
 cli.add_command(test_stack.test_stack_group)
 cli.add_command(stripe.stripe_group)
+cli.add_command(monitor.monitor_group)
 
 def main():
     """Main entry point"""

ai_lls_lib/cli/aws_client.py

@@ -27,6 +27,7 @@ class AWSClient:
         self._sqs = None
         self._secretsmanager = None
         self._cloudformation = None
+        self._logs = None
 
     @property
     def dynamodb(self):
@@ -63,6 +64,13 @@ class AWSClient:
             self._cloudformation = self.session.client('cloudformation')
         return self._cloudformation
 
+    @property
+    def logs(self):
+        """Get CloudWatch Logs client"""
+        if not self._logs:
+            self._logs = self.session.client('logs')
+        return self._logs
+
     def get_stack_outputs(self, stack_name: str) -> Dict[str, str]:
         """Get CloudFormation stack outputs"""
         try:

ai_lls_lib/cli/commands/monitor.py

@@ -0,0 +1,297 @@
+"""
+Real-time CloudWatch log monitoring for Lambda functions
+"""
+import click
+import json
+import time
+from datetime import datetime, timedelta
+from typing import Optional, List, Dict
+from botocore.exceptions import ClientError
+from ai_lls_lib.cli.aws_client import AWSClient
+
+try:
+    from rich.console import Console
+    from rich.syntax import Syntax
+    from rich.table import Table
+    from rich.live import Live
+    from rich.panel import Panel
+    from rich.text import Text
+    from rich import box
+    HAS_RICH = True
+except ImportError:
+    HAS_RICH = False
+    Console = None
+
+
+def get_log_groups(aws_client: AWSClient, environment: str) -> List[str]:
+    """Get relevant CloudWatch log groups for the environment"""
+    # Map environment to stack name pattern
+    stack_prefix = "landline-api-staging" if environment == "staging" else "landline-api"
+
+    # Key Lambda functions to monitor
+    lambda_functions = [
+        "PhoneVerifyHandler",
+        "BulkUploadHandler",
+        "BulkProcessHandler",
+        "PlansHandler",
+        "PaymentHandler",
+        "UserProfileHandler"
+    ]
+
+    log_groups = []
+    for func in lambda_functions:
+        log_group = f"/aws/lambda/{stack_prefix}-{func}"
+        log_groups.append(log_group)
+
+    return log_groups
+
+
+def format_log_event(event: Dict, use_rich: bool = True) -> str:
+    """Format a CloudWatch log event for display"""
+    timestamp = datetime.fromtimestamp(event.get('timestamp', 0) / 1000)
+    message = event.get('message', '')
+
+    # Try to parse JSON message
+    try:
+        if message.strip().startswith('{'):
+            parsed = json.loads(message)
+
+            # Check for external API calls
+            if 'external_api_call' in message.lower() or 'landlineremover.com' in message:
+                if use_rich and HAS_RICH:
+                    return f"[bold green]{timestamp.strftime('%H:%M:%S')}[/bold green] [cyan]EXTERNAL API:[/cyan] {message}"
+                else:
+                    return f"{timestamp.strftime('%H:%M:%S')} EXTERNAL API: {message}"
+
+            # Check for cache events
+            if 'cache' in message.lower():
+                if use_rich and HAS_RICH:
+                    return f"[bold blue]{timestamp.strftime('%H:%M:%S')}[/bold blue] [yellow]CACHE:[/yellow] {message}"
+                else:
+                    return f"{timestamp.strftime('%H:%M:%S')} CACHE: {message}"
+
+            # Check for errors
+            if 'error' in message.lower() or 'exception' in message.lower():
+                if use_rich and HAS_RICH:
+                    return f"[bold red]{timestamp.strftime('%H:%M:%S')}[/bold red] [red]ERROR:[/red] {message}"
+                else:
+                    return f"{timestamp.strftime('%H:%M:%S')} ERROR: {message}"
+
+            # Format structured logs
+            if use_rich and HAS_RICH:
+                message = json.dumps(parsed, indent=2)
+    except (json.JSONDecodeError, ValueError):
+        pass
+
+    # Default formatting
+    if use_rich and HAS_RICH:
+        return f"[dim]{timestamp.strftime('%H:%M:%S')}[/dim] {message}"
+    else:
+        return f"{timestamp.strftime('%H:%M:%S')} {message}"
+
+
+def tail_logs(aws_client: AWSClient, log_groups: List[str], duration: int = 300, follow: bool = True):
+    """Tail CloudWatch logs in real-time"""
+    console = Console() if HAS_RICH else None
+
+    # Calculate start time
+    start_time = int((datetime.utcnow() - timedelta(seconds=duration)).timestamp() * 1000)
+
+    # Track last event time for each log group
+    last_event_times = {group: start_time for group in log_groups}
+
+    if console and HAS_RICH:
+        console.print(Panel.fit(
+            f"[bold cyan]Monitoring {len(log_groups)} Lambda functions[/bold cyan]\n"
+            f"[dim]Press Ctrl+C to stop[/dim]",
+            title="CloudWatch Log Monitor",
+            border_style="cyan"
+        ))
+        console.print()
+    else:
+        click.echo(f"Monitoring {len(log_groups)} Lambda functions")
+        click.echo("Press Ctrl+C to stop\n")
+
+    try:
+        while True:
+            events_found = False
+
+            for log_group in log_groups:
+                try:
+                    # Use filter_log_events for real-time tailing
+                    response = aws_client.logs.filter_log_events(
+                        logGroupName=log_group,
+                        startTime=last_event_times[log_group],
+                        limit=100
+                    )
+
+                    events = response.get('events', [])
+
+                    if events:
+                        events_found = True
+                        # Update last event time
+                        last_event_times[log_group] = events[-1]['timestamp'] + 1
+
+                        # Display log group header
+                        if console and HAS_RICH:
+                            console.print(f"\n[bold magenta]═══ {log_group} ═══[/bold magenta]")
+                        else:
+                            click.echo(f"\n=== {log_group} ===")
+
+                        # Display events
+                        for event in events:
+                            formatted = format_log_event(event, use_rich=(console is not None))
+                            if console and HAS_RICH:
+                                console.print(formatted)
+                            else:
+                                click.echo(formatted)
+
+                except ClientError as e:
+                    if e.response['Error']['Code'] != 'ResourceNotFoundException':
+                        if console and HAS_RICH:
+                            console.print(f"[yellow]Warning: {e}[/yellow]")
+                        else:
+                            click.echo(f"Warning: {e}", err=True)
+
+            if not follow:
+                break
+
+            # Sleep briefly before next poll
+            time.sleep(2 if events_found else 5)
+
+    except KeyboardInterrupt:
+        if console and HAS_RICH:
+            console.print("\n[yellow]Monitoring stopped[/yellow]")
+        else:
+            click.echo("\nMonitoring stopped")
+
+
+def start_live_tail(aws_client: AWSClient, log_groups: List[str]):
+    """Start a CloudWatch Logs Live Tail session (requires AWS SDK v2)"""
+    console = Console() if HAS_RICH else None
+
+    try:
+        # Start live tail session
+        response = aws_client.logs.start_live_tail(
+            logGroupIdentifiers=log_groups,
+            logStreamNamePrefixes=[],
+            logEventFilterPattern=""
+        )
+
+        session_id = response.get('sessionId')
+        session_url = response.get('sessionUrl')
+
+        if console and HAS_RICH:
+            console.print(Panel.fit(
+                f"[bold green]Live Tail session started[/bold green]\n"
+                f"Session ID: {session_id}\n"
+                f"[dim]Note: Live Tail API requires WebSocket support[/dim]",
+                title="CloudWatch Live Tail",
+                border_style="green"
+            ))
+        else:
+            click.echo(f"Live Tail session started")
+            click.echo(f"Session ID: {session_id}")
+            click.echo(f"Note: Live Tail API requires WebSocket support")
+
+        # Note: Full WebSocket implementation would be needed here
+        # For now, fall back to filter_log_events polling
+        click.echo("\nFalling back to standard log polling...")
+        tail_logs(aws_client, log_groups, duration=300, follow=True)
+
+    except ClientError as e:
+        if 'start_live_tail' in str(e):
+            # Fall back to regular tailing if Live Tail not available
+            if console and HAS_RICH:
+                console.print("[yellow]Live Tail API not available, using standard polling[/yellow]")
+            else:
+                click.echo("Live Tail API not available, using standard polling")
+            tail_logs(aws_client, log_groups, duration=300, follow=True)
+        else:
+            raise
+
+
+@click.group(name="monitor")
+def monitor_group():
+    """Monitor CloudWatch logs in real-time"""
+    pass
+
+
+@monitor_group.command()
+@click.option('--staging', is_flag=True, help='Monitor staging environment (default: production)')
+@click.option('--production', is_flag=True, help='Monitor production environment')
+@click.option('--duration', default=300, help='How far back to start (seconds, default: 300)')
+@click.option('--follow', is_flag=True, default=True, help='Follow logs in real-time (default: true)')
+@click.option('--filter', 'filter_pattern', help='CloudWatch filter pattern to apply')
+@click.option('--profile', help='AWS profile to use')
+@click.option('--region', default='us-east-1', help='AWS region')
+def logs(staging, production, duration, follow, filter_pattern, profile, region):
+    """Tail CloudWatch logs for Lambda functions
+
+    Examples:
+        ai-lls monitor logs --staging
+        ai-lls monitor logs --production
+        ai-lls monitor logs --staging --filter "ERROR"
+        ai-lls monitor logs --duration 600 --follow
+    """
+    # Determine environment
+    if staging and production:
+        raise click.ClickException("Cannot specify both --staging and --production")
+
+    environment = "staging" if staging else "production"
+
+    # Show warning if Rich not installed
+    if not HAS_RICH:
+        click.echo("Warning: Install 'rich' library for better output formatting", err=True)
+        click.echo("Run: pip install rich", err=True)
+        click.echo()
+
+    # Initialize AWS client
+    aws_client = AWSClient(region=region, profile=profile)
+
+    # Get log groups
+    log_groups = get_log_groups(aws_client, environment)
+
+    click.echo(f"Monitoring {environment} environment...")
+    click.echo(f"Log groups: {', '.join([g.split('/')[-1] for g in log_groups])}")
+    click.echo()
+
+    # Start tailing logs
+    tail_logs(aws_client, log_groups, duration=duration, follow=follow)
+
+
+@monitor_group.command()
+@click.option('--staging', is_flag=True, help='Monitor staging environment')
+@click.option('--production', is_flag=True, help='Monitor production environment')
+@click.option('--profile', help='AWS profile to use')
+@click.option('--region', default='us-east-1', help='AWS region')
+def live(staging, production, profile, region):
+    """Start CloudWatch Logs Live Tail session (experimental)
+
+    Uses the CloudWatch Logs Live Tail API for real-time streaming.
+    Falls back to standard polling if Live Tail is not available.
+
+    Examples:
+        ai-lls monitor live --staging
+        ai-lls monitor live --production
+    """
+    # Determine environment
+    if staging and production:
+        raise click.ClickException("Cannot specify both --staging and --production")
+
+    environment = "staging" if staging else "production"
+
+    # Initialize AWS client
+    aws_client = AWSClient(region=region, profile=profile)
+
+    # Get log groups
+    log_groups = get_log_groups(aws_client, environment)
+
+    click.echo(f"Starting Live Tail for {environment} environment...")
+
+    # Start live tail
+    start_live_tail(aws_client, log_groups)
+
+
+# Export the group for registration
+__all__ = ['monitor_group']

ai_lls_lib/cli/commands/verify.py

@@ -7,6 +7,7 @@ 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():
@@ -15,72 +16,160 @@ def verify_group():
 
 @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)
+@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:
-        if skip_cache:
-            # Force fresh lookup
-            normalized = verifier.normalize_phone(phone_number)
-            line_type = verifier._check_line_type(normalized)
-            dnc = verifier._check_dnc(normalized)
-            result = {
-                "phone_number": normalized,
-                "line_type": line_type,
-                "dnc": dnc,
-                "cached": False,
-                "verified_at": datetime.utcnow().isoformat(),
-                "source": "cli-direct"
-            }
+        # 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:
-            result = verifier.verify(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))
+            # 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:
-        click.echo(f"Error: {e}", err=True)
+        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:
-        click.echo(f"Verification failed: {e}", err=True)
+        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("--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):
+@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
 
-    aws = AWSClient(region=region, profile=profile)
-    cache_table = aws.get_table_name(stack, "PhoneCacheTable")
-
-    cache = DynamoDBCache(table_name=cache_table)
-    verifier = PhoneVerifier(cache=cache)
+    # 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}...")
@@ -100,7 +189,8 @@ def verify_bulk(csv_file, output, stack, profile, region):
         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}")
+        if cache:
+            click.echo(f"  From Cache: {cached_count}")
 
         # Generate output if requested
         if output:
@@ -109,3 +199,6 @@ def verify_bulk(csv_file, output, stack, profile, region):
 
     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

@@ -6,7 +6,7 @@ from typing import Optional, Dict
 import click
 
 
-def load_env_file(env_path: Path) -> Dict[str, str]:
+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():
@@ -20,7 +20,8 @@ def load_env_file(env_path: Path) -> Dict[str, str]:
                         value = value.strip().strip('"').strip("'")
                         env_vars[key.strip()] = value
         except Exception as e:
-            click.echo(f"Warning: Could not read {env_path}: {e}", err=True)
+            if verbose:
+                click.echo(f"Warning: Could not read {env_path}: {e}", err=True)
     return env_vars
 
 

ai_lls_lib/core/verifier.py

@@ -8,7 +8,7 @@ import phonenumbers
 from aws_lambda_powertools import Logger
 from .models import PhoneVerification, LineType, VerificationSource
 from .cache import DynamoDBCache
-from ..providers import VerificationProvider, StubProvider
+from ..providers import VerificationProvider, StubProvider, ExternalAPIProvider
 
 logger = Logger()
 
@@ -16,16 +16,16 @@ logger = Logger()
 class PhoneVerifier:
     """Verifies phone numbers for line type and DNC status"""
 
-    def __init__(self, cache: DynamoDBCache, provider: Optional[VerificationProvider] = None):
+    def __init__(self, cache: Optional[DynamoDBCache] = None, provider: Optional[VerificationProvider] = None):
         """
         Initialize phone verifier.
 
         Args:
-            cache: DynamoDB cache for storing results
-            provider: Verification provider (defaults to StubProvider)
+            cache: Optional DynamoDB cache for storing results
+            provider: Verification provider (defaults to ExternalAPIProvider)
         """
         self.cache = cache
-        self.provider = provider or StubProvider()
+        self.provider = provider or ExternalAPIProvider()
 
     def normalize_phone(self, phone: str) -> str:
         """Normalize phone to E.164 format"""
@@ -45,10 +45,11 @@ class PhoneVerifier:
         """Verify phone number for line type and DNC status"""
         normalized = self.normalize_phone(phone)
 
-        # Check cache first
-        cached = self.cache.get(normalized)
-        if cached:
-            return cached
+        # Check cache first if available
+        if self.cache:
+            cached = self.cache.get(normalized)
+            if cached:
+                return cached
 
         # Use provider to verify
         line_type, dnc_status = self.provider.verify_phone(normalized)
@@ -62,8 +63,13 @@ class PhoneVerifier:
             source=VerificationSource.API
         )
 
-        # Store in cache
-        self.cache.set(normalized, result)
+        # Store in cache if available
+        if self.cache:
+            try:
+                self.cache.set(normalized, result)
+            except Exception as e:
+                logger.warning(f"Failed to cache result: {e}")
+                # Continue without caching - don't fail the verification
 
         return result
 

ai_lls_lib/providers/__init__.py

@@ -3,5 +3,6 @@ Verification providers for phone number checking
 """
 from .base import VerificationProvider
 from .stub import StubProvider
+from .external import ExternalAPIProvider
 
-__all__ = ["VerificationProvider", "StubProvider"]
+__all__ = ["VerificationProvider", "StubProvider", "ExternalAPIProvider"]

ai_lls_lib/providers/external.py

@@ -13,29 +13,45 @@ logger = Logger()
 class ExternalAPIProvider:
     """
     Production provider that calls external verification APIs.
+    Uses landlineremover.com which returns both line type and DNC status in a single call.
     """
 
     def __init__(
         self,
-        phone_api_key: Optional[str] = None,
-        dnc_api_key: Optional[str] = None,
+        api_key: Optional[str] = None,
         timeout: float = 10.0
     ):
         """
         Initialize external API provider.
 
         Args:
-            phone_api_key: API key for phone line type verification
-            dnc_api_key: API key for DNC list checking
+            api_key: API key for landlineremover.com (if not provided, uses environment)
             timeout: HTTP request timeout in seconds
         """
-        self.phone_api_key = phone_api_key or os.environ.get("PHONE_VERIFY_API_KEY", "")
-        self.dnc_api_key = dnc_api_key or os.environ.get("DNC_API_KEY", "")
+        # Get environment-specific API key
+        # Default to 'prod' if not specified
+        env = os.environ.get("ENVIRONMENT", "prod").upper()
+
+        # Try environment-specific key first, then fall back to provided key
+        self.api_key = (
+            api_key or
+            os.environ.get(f"{env}_LANDLINE_API_KEY") or
+            os.environ.get("PHONE_VERIFY_API_KEY", "")
+        )
+
+        if not self.api_key:
+            logger.warning(f"No API key found for environment {env}")
+
+        self.api_url = "https://app.landlineremover.com/api/check-number"
+        self.timeout = timeout
         self.http_client = httpx.Client(timeout=timeout)
 
     def verify_phone(self, phone: str) -> Tuple[LineType, bool]:
         """
-        Verify phone using external APIs.
+        Verify phone using landlineremover.com API.
+
+        This API returns both line type and DNC status in a single call,
+        which is more efficient than making two separate API calls.
 
         Args:
             phone: E.164 formatted phone number
@@ -47,41 +63,89 @@ class ExternalAPIProvider:
             httpx.HTTPError: For API communication errors
             ValueError: For invalid responses
         """
-        line_type = self._check_line_type(phone)
-        is_dnc = self._check_dnc(phone)
-        return line_type, is_dnc
-
-    def _check_line_type(self, phone: str) -> LineType:
-        """
-        Check line type via external API.
-
-        TODO: Implement actual API call
-        - Use self.phone_api_key for authentication
-        - Parse API response
-        - Map to LineType enum
+        logger.debug(f"Verifying phone {phone[:6]}*** via external API")
+
+        if not self.api_key:
+            raise ValueError("API key not configured")
+
+        try:
+            # Make single API call that returns both line type and DNC status
+            # The API may redirect, so we need to follow redirects
+            response = self.http_client.get(
+                self.api_url,
+                params={
+                    "apikey": self.api_key,
+                    "number": phone
+                },
+                follow_redirects=True
+            )
+
+            # Raise for HTTP errors
+            response.raise_for_status()
+
+            # Parse response
+            json_response = response.json()
+
+            # Extract data from response wrapper
+            if "data" in json_response:
+                data = json_response["data"]
+            else:
+                data = json_response
+
+            # Map line type from API response
+            line_type = self._map_line_type(data)
+
+            # Map DNC status - API uses "DNCType" field
+            # Values can be "dnc", "clean", etc.
+            dnc_type = data.get("DNCType", data.get("dnc_type", "")).lower()
+            is_dnc = dnc_type != "clean" and dnc_type != ""
+
+            logger.debug(
+                f"Verification complete for {phone[:6]}***",
+                extra={
+                    "line_type": line_type.value,
+                    "is_dnc": is_dnc,
+                    "dnc_type": dnc_type
+                }
+            )
+
+            return line_type, is_dnc
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"API error: {e.response.status_code} - {e.response.text}")
+            raise ValueError(f"API request failed with status {e.response.status_code}")
+        except httpx.RequestError as e:
+            logger.error(f"Network error: {str(e)}")
+            raise ValueError(f"Network error during API call: {str(e)}")
+        except Exception as e:
+            logger.error(f"Unexpected error during verification: {str(e)}")
+            raise
+
+    def _map_line_type(self, data: dict) -> LineType:
         """
-        logger.info(f"External line type check for {phone[:6]}***")
+        Map API response to LineType enum.
 
-        # Placeholder implementation
-        # In production, this would make an actual API call
-        raise NotImplementedError("External line type API not yet configured")
+        Args:
+            data: API response dictionary
 
-    def _check_dnc(self, phone: str) -> bool:
+        Returns:
+            LineType enum value
         """
-        Check DNC status via external API.
+        # API uses "LineType" (capitalized) field
+        line_type_str = data.get("LineType", data.get("line_type", "")).lower()
 
-        TODO: Implement actual API call
-        - Use self.dnc_api_key for authentication
-        - Parse API response
-        - Return boolean status
-        """
-        logger.info(f"External DNC check for {phone[:6]}***")
+        # Map common line types
+        line_type_map = {
+            "mobile": LineType.MOBILE,
+            "landline": LineType.LANDLINE,
+            "voip": LineType.VOIP,
+            "wireless": LineType.MOBILE,  # Some APIs return "wireless" for mobile
+            "fixed": LineType.LANDLINE,    # Some APIs return "fixed" for landline
+        }
 
-        # Placeholder implementation
-        # In production, this would make an actual API call
-        raise NotImplementedError("External DNC API not yet configured")
+        return line_type_map.get(line_type_str, LineType.UNKNOWN)
 
     def __del__(self):
         """Cleanup HTTP client"""
         if hasattr(self, 'http_client'):
-            self.http_client.close()
+            self.http_client.close()

ai_lls_lib/providers/stub.py

@@ -32,7 +32,7 @@ class StubProvider:
         Returns:
             Tuple of (line_type, is_on_dnc_list)
         """
-        logger.info(f"Stub verification for {phone[:6]}***")
+        logger.debug(f"Stub verification for {phone[:6]}***")
 
         last_digit = phone[-1] if phone else '5'
 

{ai_lls_lib-1.5.0rc3.dist-info → ai_lls_lib-1.5.0rc5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-lls-lib
-Version: 1.5.0rc3
+Version: 1.5.0rc5
 Summary: Landline Scrubber core library - phone verification and DNC checking
 Author: LandlineScrubber Team
 Requires-Python: >=3.12,<4.0
@@ -186,6 +186,33 @@ ai-lls test-stack test
 ai-lls test-stack delete
 ```
 
+### CloudWatch Log Monitoring
+```bash
+# Monitor staging environment logs in real-time
+ai-lls monitor logs --staging
+
+# Monitor production environment logs
+ai-lls monitor logs --production
+
+# Monitor with custom duration (look back 10 minutes)
+ai-lls monitor logs --staging --duration 600
+
+# Filter logs for errors only
+ai-lls monitor logs --staging --filter "ERROR"
+
+# Use specific AWS profile
+ai-lls monitor logs --staging --profile myprofile
+
+# Experimental: Use CloudWatch Logs Live Tail API
+ai-lls monitor live --staging
+```
+
+The monitor command provides real-time log streaming from Lambda functions with:
+- Color-coded output for different event types (external API calls, cache events, errors)
+- Support for multiple log groups simultaneously
+- Rich formatting when the `rich` library is installed
+- Automatic detection of external API calls to landlineremover.com
+
 ## Project Structure
 
 ```

{ai_lls_lib-1.5.0rc3.dist-info → ai_lls_lib-1.5.0rc5.dist-info}/RECORD

@@ -1,33 +1,34 @@
-ai_lls_lib/__init__.py,sha256=pGHYFGC4SkH9TaaSFWG7qyjwC63DGMx2zZOvHaY5diI,734
+ai_lls_lib/__init__.py,sha256=XPFbxbxGbOhVzGxkFlvmuENvWHUK2AnWUOpRcu29gT8,734
 ai_lls_lib/auth/__init__.py,sha256=ZjwlfTvYUo9A9BaLinaXW2elxYectScmu0XtKAppSFs,198
 ai_lls_lib/auth/context_parser.py,sha256=AWyGWejrFR0jJ7fMhajdA1ABo656Qlvs2YAzz-IfTrs,2290
 ai_lls_lib/cli/__init__.py,sha256=HyjnIBGlrbTlHQ82n_UppjtJbZl4_7QsnAgRqNlXKMU,77
-ai_lls_lib/cli/__main__.py,sha256=wsSjkPdrkqqmcxYZr-_CWmOd1YQAN4fo3cey-P4BQxI,746
-ai_lls_lib/cli/aws_client.py,sha256=lqihYQQtpx8Xb5HcVTbexl1pZdlYYdozPLDEGcen27Q,4067
+ai_lls_lib/cli/__main__.py,sha256=OLpqz78s2nAtib7soqI-WQ2_V9aqa9Cd4NRwvso0IbM,2120
+ai_lls_lib/cli/aws_client.py,sha256=yJ_seXyAOSy1xFqUHD8CScnN5un18b2412a7pUG_UQs,4283
 ai_lls_lib/cli/commands/__init__.py,sha256=yi0bdkZSPIXY33apvJRcuK410-Ta0-_-n31MQYuL_aU,31
 ai_lls_lib/cli/commands/admin.py,sha256=JlFljbblVWJkJ2z2FIM6P0fy3Pmc0VqG62Y3POtvRFw,6861
 ai_lls_lib/cli/commands/cache.py,sha256=1Vm3m5vXJkRagNmQXpT8_YEsQEv92veJUFwA_v9FPb0,5822
+ai_lls_lib/cli/commands/monitor.py,sha256=TLbf5Q_viwF7q_aPXo9XenzY4W0R1bjO68Iu8KlzvoE,11315
 ai_lls_lib/cli/commands/stripe.py,sha256=_aRsz6Z7BN-S9_07efUovXwsbL-eCE-raw1uBOkDP5g,15276
 ai_lls_lib/cli/commands/test_stack.py,sha256=FK6ITOek7j4e0QiSNTv_taLghNnR8d_kWG02cl0A3rY,7594
-ai_lls_lib/cli/commands/verify.py,sha256=a63KSXd0XfJq2LFEt3RrGmQ7SXK40pQhS-oaPo8SCdo,4349
-ai_lls_lib/cli/env_loader.py,sha256=dIgD5PC3u4MW2Qs_MHRJcUeoA0Wwe7e8nnitEe26xrY,4208
+ai_lls_lib/cli/commands/verify.py,sha256=8rTg8xbdQbJdebDy5CT7HFcJ-ODFZdAOAo2JX82ARJs,8522
+ai_lls_lib/cli/env_loader.py,sha256=ZL8GykQw8gf--aSMvIR4pdfQYKIA8bbJDWWNUpxZYsI,4260
 ai_lls_lib/core/__init__.py,sha256=ATh5sGhhB9g5Sd2H0kRqoCA0hxqe6UWonlPq2Wnl_i8,39
 ai_lls_lib/core/cache.py,sha256=4HSVaRvv_wueLV30fVbTk_KWZmXjR2mBrGl7UNT_5kQ,3817
 ai_lls_lib/core/models.py,sha256=jzvc-SlP-nLgvkom9hj-TwKHxBePbEfC9xL_Tt1Uh4Y,2458
 ai_lls_lib/core/processor.py,sha256=8PI_j1ZMOD1hru3PyV5QMmMx7Em8X0ivq8prMXwait4,10269
-ai_lls_lib/core/verifier.py,sha256=dM5DkVudc29Evsd-QSkX9cQEM8EeUJQlCYxImDIJ7Uc,2800
+ai_lls_lib/core/verifier.py,sha256=mQBgzV-vZiiKGzeeVl3TwfOWGrYTeB_zQ6wpaI07u54,3147
 ai_lls_lib/payment/__init__.py,sha256=uQwWZ2tw-cxS06hbWiKu8ubxzzYCmxeKBQQU7m_mRX4,308
 ai_lls_lib/payment/credit_manager.py,sha256=DH_t8AMx74vexegoTD3UkFNA1XuomIQWOZu9VoJMO3E,7340
 ai_lls_lib/payment/models.py,sha256=LxGop5e1hhUmBCpnzJwU-dDQSLHy6uM6gSFYYo2V_FI,3609
 ai_lls_lib/payment/stripe_manager.py,sha256=cSJvRWk1OT16SlDh5BMyoEQD8TU0IzeP0TaL8e2U4zA,18423
 ai_lls_lib/payment/webhook_processor.py,sha256=bAf8oUBzvCsb1stzKZ-cjZs02T-RJl-MeVnZmnnj5UM,8980
-ai_lls_lib/providers/__init__.py,sha256=xDh9KY3pgDef59CqQlAR215bawxdEY2OP-BRRT9ru_c,186
+ai_lls_lib/providers/__init__.py,sha256=dBjXJHn2nnA8KUuLYkgCJjZZzWeYAPPd6IJHUd7b-Kk,252
 ai_lls_lib/providers/base.py,sha256=WSnSkHtRvwpX8QtGINjO-EWsZL0augp5E8M1DPwpf00,709
-ai_lls_lib/providers/external.py,sha256=T8P_XtLNCXZBB0DzK4fradNBoiapIbpQ09Ai4DihpMM,2710
-ai_lls_lib/providers/stub.py,sha256=n8WCcuqcv62DnIO-WPhuold-AC3yrxjQAboJ4CO2n6U,1198
+ai_lls_lib/providers/external.py,sha256=MKu3BZV8gfSqV3lNcF9Vt4UmKIJixQ5Q7FI2wFeSBz0,5075
+ai_lls_lib/providers/stub.py,sha256=XXUObkIb3hs7_fYMA9mlLh1llJUGIgqQHVjgZHZl1T8,1199
 ai_lls_lib/testing/__init__.py,sha256=NytBz7T0YtNLDArRYHsczaeopIQmmBeV21-XXUprdeY,42
 ai_lls_lib/testing/fixtures.py,sha256=OC1huorIqUndePoUTfgoU-aDvsWAFJqmQ6fGDjH9E14,3414
-ai_lls_lib-1.5.0rc3.dist-info/METADATA,sha256=G3VICOTTMbTEJ5AvC6Iz0ezj0jerMMAOQS8ynl4Z91I,7302
-ai_lls_lib-1.5.0rc3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-ai_lls_lib-1.5.0rc3.dist-info/entry_points.txt,sha256=Pi0V_HBViEKGFbNQKatl5lhhnHHBXlxaom-5gH9gXZ0,55
-ai_lls_lib-1.5.0rc3.dist-info/RECORD,,
+ai_lls_lib-1.5.0rc5.dist-info/METADATA,sha256=BmJasSh-TbAwCxGegpTRVrw2Cb8BCDKe5zXhJjW34rs,8175
+ai_lls_lib-1.5.0rc5.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+ai_lls_lib-1.5.0rc5.dist-info/entry_points.txt,sha256=Pi0V_HBViEKGFbNQKatl5lhhnHHBXlxaom-5gH9gXZ0,55
+ai_lls_lib-1.5.0rc5.dist-info/RECORD,,