ai-lls-lib 3.13.1

Landline Scrubber core library - phone verification and DNC checking

ai-lls-lib

Core Python library for Landline Scrubber -- phone number verification, line-type detection, DNC registry checking, and bulk processing with caching.

---

Pipeline Artifacts

Reports are published to GitHub Pages on every push to the default branch.

Report	Link
API Documentation	pdoc reference
Test Coverage	HTML coverage report
Test Results	Unit test results
Security Scans	Bandit, Safety, pip-audit
License Compliance	Dependency license report
PyPI Package	pypi.org/project/ai-lls-lib

---

What This Does

• Phone number normalization (E.164 format)
• Line type detection (mobile/landline/VoIP) via landlineremover.com API
• DNC (Do Not Call) list checking
• DynamoDB caching with 90-day TTL
• Bulk CSV processing with streaming support
• Stripe payment integration (credits, subscriptions)
• Admin user management and API key operations

---

Getting Started

This project uses AI-assisted development. You do not need to memorize git commands or CI configuration -- your AI agent handles that.

Prerequisites

• Python 3.12+
• uv package manager
• AWS credentials (for integration tests)

First-time setup

git clone https://github.com/Augmenting-Integrations/ai-lls-lib.git
cd ai-lls-lib
uv sync --all-extras

Running locally

uv run pytest -m "not integration" -v   # Unit tests
uv run pre-commit run --all-files       # Lint + format + type check
uv run mypy src/                        # Type checking

---

How to Contribute

Contributions are made through AI agents (Claude Code, Copilot, etc.). You describe what you want changed in plain language; the agent handles branching, coding, testing, and submitting a pull request.

1. Open Claude Code (or your AI agent) in this repo.
2. Describe the change you want -- a bug fix, a new feature, a doc update.
3. The agent will:
   • Create a feature branch
   • Make the changes
   • Run pre-commit checks and tests
   • Open a pull request
4. Review the PR when the agent is done. CI runs automatically.
5. Merge once CI is green.

If you need to work manually, see the full contributor guide (if available).

---

Quick Start

Single Phone Verification

from ai_lls_lib import PhoneVerifier, DynamoDBCache

cache = DynamoDBCache(table_name="phone-cache")
verifier = PhoneVerifier(cache)

result = verifier.verify("[phone]")
print(f"Line type: {result.line_type}")  # mobile, landline, voip, unknown
print(f"DNC: {result.dnc}")              # True/False
print(f"Cached: {result.cached}")        # True/False

Bulk Processing

from ai_lls_lib import BulkProcessor, PhoneVerifier, DynamoDBCache

cache = DynamoDBCache(table_name="phone-cache")
verifier = PhoneVerifier(cache)
processor = BulkProcessor(verifier)

csv_text = "name,phone\nJohn,[phone]\nJane,[phone]"
results = processor.process_csv(csv_text)
results_csv = processor.generate_results_csv(csv_text, results)

---

CLI

ai-lls verify phone [phone] --stack landline-api
ai-lls verify bulk input.csv -o output.csv --stack landline-api
ai-lls cache stats --stack landline-api
ai-lls admin user-credits user123 --add 100
ai-lls admin api-keys --user user123

---

Configuration

Variable	Description	Required
LANDLINE_REMOVER_API_KEY	API key for landlineremover.com	Yes (production)
AWS_REGION	AWS region for DynamoDB	No (default: us-east-1)

---

Architecture

src/ai_lls_lib/
├── __init__.py      # Public exports, version
├── core/            # PhoneVerifier, BulkProcessor, DynamoDBCache
├── auth/            # JWT/API key authentication
├── payment/         # StripeManager, CreditManager
├── admin/           # AdminService
├── providers/       # External API clients
├── cli/             # Command-line interface
└── testing/         # Test fixtures