ai-lls-lib 1.0.0__tar.gz

ai_lls_lib-1.0.0/PKG-INFO

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

ai_lls_lib-1.0.0/README.md

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

ai_lls_lib-1.0.0/pyproject.toml

@@ -0,0 +1,106 @@
+[tool.poetry]
+name = "ai-lls-lib"
+version = "1.0.0"
+description = "Landline Scrubber core library - phone verification and DNC checking"
+authors = ["LandlineScrubber Team"]
+readme = "README.md"
+packages = [{include = "ai_lls_lib", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+boto3 = "^1.34.0"
+pydantic = "^2.5.0"
+phonenumbers = "^8.13.0"
+httpx = "^0.25.0"
+aws-lambda-powertools = "^2.30.0"
+click = "^8.1.0"
+rich = "^14.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.0"
+pytest-cov = "^4.1.0"
+pytest-asyncio = "^0.21.0"
+black = "^23.12.0"
+isort = "^5.13.0"
+mypy = "^1.8.0"
+boto3-stubs = {extras = ["dynamodb", "s3", "sqs"], version = "^1.34.0"}
+moto = {extras = ["dynamodb", "s3", "sqs"], version = "^4.2.0"}
+python-semantic-release = "^10.3.1"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 100
+target-version = ['py312']
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-ra -q --strict-markers"
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*", "*/test_*.py"]
+
+[tool.poetry.scripts]
+ai-lls = "ai_lls_lib.cli.__main__:main"
+
+[tool.semantic_release]
+assets = []
+commit_message = "chore(release): ai-lls-lib {version}\n\nAutomatically generated by python-semantic-release [skip ci]"
+commit_parser = "angular"
+logging_use_named_masks = false
+major_on_zero = false
+allow_zero_version = false
+no_git_verify = false
+tag_format = "ai-lls-lib-v{version}"
+version_toml = ["pyproject.toml:tool.poetry.version"]
+version_variables = ["src/ai_lls_lib/__init__.py:__version__"]
+build_command = "poetry build"
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+[tool.semantic_release.branches.dev]
+match = "dev"
+prerelease = true
+prerelease_token = "rc"
+version_format = "v{major}.{minor}.{patch}-{prerelease}.{prerelease_revision}"
+
+[tool.semantic_release.changelog]
+mode = "update"
+changelog_file = "CHANGELOG.md"
+exclude_commit_patterns = [
+    '''chore(?:\([^)]*?\))?: .+''',
+    '''ci(?:\([^)]*?\))?: .+''',
+    '''refactor(?:\([^)]*?\))?: .+''',
+    '''style(?:\([^)]*?\))?: .+''',
+    '''test(?:\([^)]*?\))?: .+''',
+    '''build\((?!deps\): .+)''',
+]
+
+[tool.semantic_release.remote]
+name = "origin"
+type = "github"
+ignore_token_for_push = false
+insecure = false
+
+[tool.semantic_release.remote.token]
+env = "GH_TOKEN"
+
+[tool.semantic_release.publish]
+dist_glob_patterns = ["libs/python/ai-lls-lib/dist/*"]
+upload_to_vcs_release = false

ai_lls_lib-1.0.0/src/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-1.0.0/src/ai_lls_lib/cli/__init__.py

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

ai_lls_lib-1.0.0/src/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-1.0.0/src/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-1.0.0/src/ai_lls_lib/cli/commands/__init__.py

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