ai-lls-lib 2.0.0rc2__py3-none-any.whl

ai_lls_lib-2.0.0rc2.dist-info/METADATA

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: ai-lls-lib
+Version: 2.0.0rc2
+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
+Classifier: Programming Language :: Python :: 3.14
+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)
+Requires-Dist: stripe (>=12.5.1,<13.0.0)
+Description-Content-Type: text/markdown
+
+# AI LLS Library
+
+Core business logic library and CLI tools for Landline Scrubber - phone verification and DNC checking.
+
+## Version 2.1.0 - Streaming & Provider Architecture
+
+New features:
+- **Streaming support** for large CSV files to reduce memory usage
+- **Provider architecture** for clean separation of verification logic
+- **Contract tests** ensuring all providers behave consistently
+
+## Version 2.0.0 - Breaking Changes
+
+This is a greenfield rewrite with no backwards compatibility:
+- All file-based CSV processing replaced with text-based methods
+- Removed `_sync` suffix from all methods (everything is sync)
+- `process_csv_sync(file_path)` → `process_csv(csv_text)`
+- `generate_results_csv(...)` now returns CSV string instead of writing to file
+
+## 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("+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)
+
+# Process CSV text content
+csv_text = "name,phone\nJohn,+15551234567\nJane,+15551234568"
+results = processor.process_csv(csv_text)
+
+# Generate results CSV
+results_csv = processor.generate_results_csv(csv_text, results)
+print(results_csv)  # CSV string with added line_type, dnc, cached columns
+```
+
+### Streaming Large Files
+
+For memory-efficient processing of large CSV files:
+
+```python
+from ai_lls_lib import BulkProcessor, PhoneVerifier, DynamoDBCache
+
+cache = DynamoDBCache(table_name="phone-cache")
+verifier = PhoneVerifier(cache)
+processor = BulkProcessor(verifier)
+
+# Process CSV as a stream, yielding batches
+csv_lines = open('large_file.csv').readlines()
+for batch in processor.process_csv_stream(csv_lines, batch_size=100):
+    print(f"Processed batch of {len(batch)} phones")
+    # Each batch is a list of PhoneVerification objects
+```
+
+### Custom Verification Providers
+
+Use different verification providers based on your needs:
+
+```python
+from ai_lls_lib import PhoneVerifier, DynamoDBCache
+from ai_lls_lib.providers import StubProvider
+
+# Use stub provider for testing
+cache = DynamoDBCache(table_name="phone-cache")
+provider = StubProvider()  # Deterministic testing provider
+verifier = PhoneVerifier(cache, provider=provider)
+
+# When external APIs are ready, switch to:
+# from ai_lls_lib.providers.external import ExternalAPIProvider
+# provider = ExternalAPIProvider(phone_api_key="...", dnc_api_key="...")
+```
+
+## 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
+```
+
+### 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/
+├── 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-2.0.0rc2.dist-info/RECORD

@@ -0,0 +1,34 @@
+ai_lls_lib/__init__.py,sha256=Y11h9ZWDlbxKiKl0U-j2jd-5ITephsmmZ-961Np_Imk,792
+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=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=uhwX0Zq56R-68P53NOtKx6ZoR1ybhWawdQTq1zgK98M,14239
+ai_lls_lib/cli/commands/test_stack.py,sha256=FK6ITOek7j4e0QiSNTv_taLghNnR8d_kWG02cl0A3rY,7594
+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=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=dBjXJHn2nnA8KUuLYkgCJjZZzWeYAPPd6IJHUd7b-Kk,252
+ai_lls_lib/providers/base.py,sha256=WSnSkHtRvwpX8QtGINjO-EWsZL0augp5E8M1DPwpf00,709
+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-2.0.0rc2.dist-info/METADATA,sha256=J6A26EIFEsD7UOqpHLY4afJFKG0bGybJCHVUP5ylO84,8175
+ai_lls_lib-2.0.0rc2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+ai_lls_lib-2.0.0rc2.dist-info/entry_points.txt,sha256=Pi0V_HBViEKGFbNQKatl5lhhnHHBXlxaom-5gH9gXZ0,55
+ai_lls_lib-2.0.0rc2.dist-info/RECORD,,

ai_lls_lib-2.0.0rc2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

ai_lls_lib-2.0.0rc2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ai-lls=ai_lls_lib.cli.__main__:main
+