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

ai_lls_lib/__init__.py

@@ -0,0 +1,27 @@
+"""
+AI LLS Library - Core business logic for Landline Scrubber
+"""
+from ai_lls_lib.core.models import (
+    PhoneVerification,
+    BulkJob,
+    BulkJobStatus,
+    LineType,
+    VerificationSource,
+    JobStatus
+)
+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.0.0"
+__all__ = [
+    "PhoneVerification",
+    "BulkJob",
+    "BulkJobStatus",
+    "LineType",
+    "VerificationSource",
+    "JobStatus",
+    "PhoneVerifier",
+    "BulkProcessor",
+    "DynamoDBCache",
+]

ai_lls_lib/cli/__init__.py

@@ -0,0 +1,3 @@
+"""
+Landline Scrubber CLI - Infrastructure-aware administrative tools
+"""

ai_lls_lib/cli/__main__.py

@@ -0,0 +1,29 @@
+"""
+Landline Scrubber CLI entry point
+"""
+import click
+import sys
+from ai_lls_lib.cli.commands import verify, cache, admin, test_stack
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="ai-lls")
+def cli():
+    """Landline Scrubber CLI - Administrative and debugging tools"""
+    pass
+
+# Register command groups
+cli.add_command(verify.verify_group)
+cli.add_command(cache.cache_group)
+cli.add_command(admin.admin_group)
+cli.add_command(test_stack.test_stack_group)
+
+def main():
+    """Main entry point"""
+    try:
+        cli()
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

ai_lls_lib/cli/aws_client.py

@@ -0,0 +1,115 @@
+"""
+AWS client utilities for CLI operations
+"""
+import os
+import boto3
+from typing import Optional, Any, Dict
+from botocore.exceptions import ClientError
+import click
+
+class AWSClient:
+    """Wrapper for AWS operations with proper error handling"""
+
+    def __init__(self, region: Optional[str] = None, profile: Optional[str] = None):
+        """Initialize AWS clients"""
+        self.region = region or os.environ.get("AWS_REGION", "us-east-1")
+        self.profile = profile
+
+        # Create session
+        if profile:
+            self.session = boto3.Session(profile_name=profile, region_name=self.region)
+        else:
+            self.session = boto3.Session(region_name=self.region)
+
+        # Lazy-load clients
+        self._dynamodb = None
+        self._s3 = None
+        self._sqs = None
+        self._secretsmanager = None
+        self._cloudformation = None
+
+    @property
+    def dynamodb(self):
+        """Get DynamoDB client"""
+        if not self._dynamodb:
+            self._dynamodb = self.session.resource('dynamodb')
+        return self._dynamodb
+
+    @property
+    def s3(self):
+        """Get S3 client"""
+        if not self._s3:
+            self._s3 = self.session.client('s3')
+        return self._s3
+
+    @property
+    def sqs(self):
+        """Get SQS client"""
+        if not self._sqs:
+            self._sqs = self.session.client('sqs')
+        return self._sqs
+
+    @property
+    def secretsmanager(self):
+        """Get Secrets Manager client"""
+        if not self._secretsmanager:
+            self._secretsmanager = self.session.client('secretsmanager')
+        return self._secretsmanager
+
+    @property
+    def cloudformation(self):
+        """Get CloudFormation client"""
+        if not self._cloudformation:
+            self._cloudformation = self.session.client('cloudformation')
+        return self._cloudformation
+
+    def get_stack_outputs(self, stack_name: str) -> Dict[str, str]:
+        """Get CloudFormation stack outputs"""
+        try:
+            response = self.cloudformation.describe_stacks(StackName=stack_name)
+            stack = response['Stacks'][0]
+            outputs = {}
+            for output in stack.get('Outputs', []):
+                outputs[output['OutputKey']] = output['OutputValue']
+            return outputs
+        except ClientError as e:
+            if e.response['Error']['Code'] == 'ValidationError':
+                raise click.ClickException(f"Stack '{stack_name}' not found")
+            raise
+
+    def get_table_name(self, stack_name: str, logical_name: str) -> str:
+        """Get actual table name from stack"""
+        try:
+            response = self.cloudformation.describe_stack_resource(
+                StackName=stack_name,
+                LogicalResourceId=logical_name
+            )
+            return response['StackResourceDetail']['PhysicalResourceId']
+        except ClientError:
+            # Fallback to conventional naming
+            return f"{stack_name}-{logical_name.lower()}"
+
+    def scan_table(self, table_name: str, limit: int = 100) -> list:
+        """Scan DynamoDB table"""
+        try:
+            table = self.dynamodb.Table(table_name)
+            response = table.scan(Limit=limit)
+            return response.get('Items', [])
+        except ClientError as e:
+            raise click.ClickException(f"Error scanning table: {e}")
+
+    def put_item(self, table_name: str, item: dict) -> None:
+        """Put item to DynamoDB"""
+        try:
+            table = self.dynamodb.Table(table_name)
+            table.put_item(Item=item)
+        except ClientError as e:
+            raise click.ClickException(f"Error putting item: {e}")
+
+    def delete_item(self, table_name: str, key: dict) -> None:
+        """Delete item from DynamoDB"""
+        try:
+            table = self.dynamodb.Table(table_name)
+            table.delete_item(Key=key)
+        except ClientError as e:
+            raise click.ClickException(f"Error deleting item: {e}")

ai_lls_lib/cli/commands/__init__.py

@@ -0,0 +1,3 @@
+"""
+CLI command modules
+"""

ai_lls_lib/cli/commands/admin.py

@@ -0,0 +1,174 @@
+"""
+Administrative commands for user and credit management
+"""
+import click
+import json
+from datetime import datetime
+from ai_lls_lib.cli.aws_client import AWSClient
+
+@click.group(name="admin")
+def admin_group():
+    """Administrative commands"""
+    pass
+
+@admin_group.command(name="user-credits")
+@click.argument("user_id")
+@click.option("--add", type=int, help="Add credits")
+@click.option("--set", "set_credits", type=int, help="Set credits to specific value")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def user_credits(user_id, add, set_credits, stack, profile, region):
+    """Manage user credits"""
+    aws = AWSClient(region=region, profile=profile)
+    credits_table = aws.get_table_name(stack, "CreditsTable")
+
+    try:
+        table = aws.dynamodb.Table(credits_table)
+
+        # Get current credits
+        response = table.get_item(Key={"user_id": user_id})
+        current = response.get('Item', {}).get('credits', 0)
+
+        click.echo(f"User {user_id} - Current credits: {current}")
+
+        if add:
+            new_credits = current + add
+            table.update_item(
+                Key={"user_id": user_id},
+                UpdateExpression="SET credits = :val, updated_at = :now",
+                ExpressionAttributeValues={
+                    ":val": new_credits,
+                    ":now": datetime.utcnow().isoformat()
+                }
+            )
+            click.echo(f"Added {add} credits. New balance: {new_credits}")
+
+        elif set_credits is not None:
+            table.update_item(
+                Key={"user_id": user_id},
+                UpdateExpression="SET credits = :val, updated_at = :now",
+                ExpressionAttributeValues={
+                    ":val": set_credits,
+                    ":now": datetime.utcnow().isoformat()
+                }
+            )
+            click.echo(f"Set credits to {set_credits}")
+
+    except Exception as e:
+        click.echo(f"Error managing credits: {e}", err=True)
+
+@admin_group.command(name="api-keys")
+@click.option("--user", help="Filter by user ID")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def list_api_keys(user, stack, profile, region):
+    """List API keys"""
+    aws = AWSClient(region=region, profile=profile)
+    keys_table = aws.get_table_name(stack, "ApiKeysTable")
+
+    try:
+        if user:
+            # Query by user using GSI
+            table = aws.dynamodb.Table(keys_table)
+            response = table.query(
+                IndexName='gsi_user',
+                KeyConditionExpression='user_id = :uid',
+                ExpressionAttributeValues={':uid': user}
+            )
+            items = response.get('Items', [])
+        else:
+            # Scan all
+            items = aws.scan_table(keys_table)
+
+        if not items:
+            click.echo("No API keys found")
+            return
+
+        click.echo(f"\nAPI Keys ({len(items)} total):")
+        click.echo("=" * 60)
+
+        for item in items:
+            click.echo(f"Key ID: {item.get('api_key_id', 'N/A')}")
+            click.echo(f"User: {item.get('user_id', 'N/A')}")
+            click.echo(f"Created: {item.get('created_at', 'N/A')}")
+            click.echo(f"Last Used: {item.get('last_used', 'Never')}")
+            click.echo("-" * 60)
+
+    except Exception as e:
+        click.echo(f"Error listing API keys: {e}", err=True)
+
+@admin_group.command(name="queue-stats")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def queue_stats(stack, profile, region):
+    """Show SQS queue statistics"""
+    aws = AWSClient(region=region, profile=profile)
+
+    try:
+        # Get queue URLs from stack
+        outputs = aws.get_stack_outputs(stack)
+
+        # Find queue URLs or construct them
+        queue_name = f"{stack}-bulk-processing"
+        dlq_name = f"{stack}-bulk-processing-dlq"
+
+        # Get queue attributes
+        queues = [
+            ("Processing Queue", queue_name),
+            ("Dead Letter Queue", dlq_name)
+        ]
+
+        for display_name, queue in queues:
+            try:
+                response = aws.sqs.get_queue_url(QueueName=queue)
+                queue_url = response['QueueUrl']
+
+                attrs = aws.sqs.get_queue_attributes(
+                    QueueUrl=queue_url,
+                    AttributeNames=['All']
+                )['Attributes']
+
+                click.echo(f"\n{display_name}:")
+                click.echo(f"  Messages Available: {attrs.get('ApproximateNumberOfMessages', 0)}")
+                click.echo(f"  Messages In Flight: {attrs.get('ApproximateNumberOfMessagesNotVisible', 0)}")
+                click.echo(f"  Messages Delayed: {attrs.get('ApproximateNumberOfMessagesDelayed', 0)}")
+
+            except aws.sqs.exceptions.QueueDoesNotExist:
+                click.echo(f"\n{display_name}: Not found")
+
+    except Exception as e:
+        click.echo(f"Error getting queue stats: {e}", err=True)
+
+@admin_group.command(name="secrets")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--show", is_flag=True, help="Show secret values (CAREFUL!)")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def manage_secrets(stack, show, profile, region):
+    """Manage secrets"""
+    aws = AWSClient(region=region, profile=profile)
+    secret_name = f"{stack}-secrets"
+
+    try:
+        response = aws.secretsmanager.describe_secret(SecretId=secret_name)
+        click.echo(f"\nSecret: {secret_name}")
+        click.echo(f"ARN: {response['ARN']}")
+        click.echo(f"Last Updated: {response.get('LastChangedDate', 'N/A')}")
+
+        if show and click.confirm("Show secret values? This will display sensitive data!"):
+            secret_value = aws.secretsmanager.get_secret_value(SecretId=secret_name)
+            secrets = json.loads(secret_value['SecretString'])
+
+            click.echo("\nSecret Values:")
+            for key, value in secrets.items():
+                # Mask most of the value
+                masked = value[:4] + "*" * (len(value) - 8) + value[-4:] if len(value) > 8 else "*" * len(value)
+                click.echo(f"  {key}: {masked}")
+
+    except aws.secretsmanager.exceptions.ResourceNotFoundException:
+        click.echo(f"Secret '{secret_name}' not found")
+    except Exception as e:
+        click.echo(f"Error managing secrets: {e}", err=True)

ai_lls_lib/cli/commands/cache.py

@@ -0,0 +1,142 @@
+"""
+Cache management commands
+"""
+import click
+import json
+from datetime import datetime, timedelta
+from ai_lls_lib.cli.aws_client import AWSClient
+
+@click.group(name="cache")
+def cache_group():
+    """Cache management commands"""
+    pass
+
+@cache_group.command(name="stats")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def cache_stats(stack, profile, region):
+    """Show cache statistics"""
+    aws = AWSClient(region=region, profile=profile)
+    cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+
+    try:
+        # Get table description for item count
+        table = aws.dynamodb.Table(cache_table)
+        desc = table.meta.client.describe_table(TableName=cache_table)
+
+        click.echo(f"\nCache Table: {cache_table}")
+        click.echo("=" * 50)
+        click.echo(f"Item Count: {desc['Table']['ItemCount']:,}")
+        click.echo(f"Table Size: {desc['Table']['TableSizeBytes']:,} bytes")
+        click.echo(f"Status: {desc['Table']['TableStatus']}")
+
+        # Sample some items to show age distribution
+        items = aws.scan_table(cache_table, limit=100)
+        if items:
+            now = datetime.utcnow()
+            ages = []
+            for item in items:
+                if 'verified_at' in item:
+                    verified = datetime.fromisoformat(item['verified_at'].replace('Z', '+00:00'))
+                    age = (now - verified.replace(tzinfo=None)).days
+                    ages.append(age)
+
+            if ages:
+                click.echo(f"\nCache Age (sample of {len(ages)} items):")
+                click.echo(f"  Newest: {min(ages)} days")
+                click.echo(f"  Oldest: {max(ages)} days")
+                click.echo(f"  Average: {sum(ages)/len(ages):.1f} days")
+
+    except Exception as e:
+        click.echo(f"Error getting cache stats: {e}", err=True)
+
+@cache_group.command(name="get")
+@click.argument("phone_number")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+def cache_get(phone_number, stack, profile, region):
+    """Get cached entry for a phone number"""
+    from ai_lls_lib.core.verifier import PhoneVerifier
+    from ai_lls_lib.core.cache import DynamoDBCache
+
+    aws = AWSClient(region=region, profile=profile)
+    cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+
+    # Normalize phone first
+    verifier = PhoneVerifier(cache=DynamoDBCache(table_name=cache_table))
+    try:
+        normalized = verifier.normalize_phone(phone_number)
+    except ValueError as e:
+        click.echo(f"Invalid phone: {e}", err=True)
+        return
+
+    # Get from cache
+    cache = DynamoDBCache(table_name=cache_table)
+    result = cache.get(normalized)
+
+    if result:
+        click.echo(f"\nCached entry for {normalized}:")
+        click.echo(json.dumps(result.dict() if hasattr(result, 'dict') else result, indent=2, default=str))
+    else:
+        click.echo(f"No cache entry found for {normalized}")
+
+@cache_group.command(name="invalidate")
+@click.argument("phone_number")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+@click.confirmation_option(prompt="Are you sure you want to invalidate this cache entry?")
+def cache_invalidate(phone_number, stack, profile, region):
+    """Invalidate cached entry for a phone number"""
+    from ai_lls_lib.core.verifier import PhoneVerifier
+    from ai_lls_lib.core.cache import DynamoDBCache
+
+    aws = AWSClient(region=region, profile=profile)
+    cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+
+    # Normalize phone
+    verifier = PhoneVerifier(cache=DynamoDBCache(table_name=cache_table))
+    try:
+        normalized = verifier.normalize_phone(phone_number)
+    except ValueError as e:
+        click.echo(f"Invalid phone: {e}", err=True)
+        return
+
+    # Delete from cache
+    try:
+        aws.delete_item(cache_table, {"phone_number": normalized})
+        click.echo(f"Cache entry invalidated for {normalized}")
+    except Exception as e:
+        click.echo(f"Error invalidating cache: {e}", err=True)
+
+@cache_group.command(name="clear")
+@click.option("--stack", default="landline-api", help="CloudFormation stack name")
+@click.option("--older-than", type=int, help="Clear entries older than N days")
+@click.option("--profile", help="AWS profile")
+@click.option("--region", help="AWS region")
+@click.confirmation_option(prompt="This will clear cache entries. Continue?")
+def cache_clear(stack, older_than, profile, region):
+    """Clear cache entries"""
+    aws = AWSClient(region=region, profile=profile)
+    cache_table = aws.get_table_name(stack, "PhoneCacheTable")
+
+    if older_than:
+        click.echo(f"Clearing entries older than {older_than} days...")
+        cutoff = datetime.utcnow() - timedelta(days=older_than)
+
+        # Scan and delete old entries
+        items = aws.scan_table(cache_table, limit=1000)
+        deleted = 0
+
+        for item in items:
+            if 'verified_at' in item:
+                verified = datetime.fromisoformat(item['verified_at'].replace('Z', '+00:00'))
+                if verified.replace(tzinfo=None) < cutoff:
+                    aws.delete_item(cache_table, {"phone_number": item['phone_number']})
+                    deleted += 1
+
+        click.echo(f"Deleted {deleted} entries older than {older_than} days")
+    else:
+        click.echo("Full cache clear not implemented for safety. Use --older-than option.")