ai-lls-lib

ai-lls-lib

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

---

Documentation

Pipeline Artifacts

Reports are published to GitHub Pages when a push to main cuts a release.

---

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.

Branch model

• All work happens on a feature branch, merged into main through a PR.
• Five required gates run on each PR: Code quality, Security, Unit tests, Compliance, and Build validation.
• On merge to main, the pipeline runs integration tests against the persistent ai-lls-lib-test stack, then semantic-release cuts a version from the commit messages. A release publishes the package to PyPI and deploys documentation to GitHub Pages.

Branch -> environment mapping

main is the only branch with an active deploy trigger -- .github/workflows/publish.yaml runs on: push: branches: [main], and there is no dev branch in this repo today.

There is no separate staging branch or environment.

---

Quick Start

Single Phone Verification

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}")       # mobile, landline, voip, unknown
print(f"DNC: {result.dnc}")                    # True/False
print(f"Litigator: {result.known_litigator}")  # True/False (known TCPA litigator)
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,+15551234567\nJane,+15551234568"
results = processor.process_csv(csv_text)
results_csv = processor.generate_results_csv(csv_text, results)

---

CLI

ai-lls verify phone +15551234567 --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

The library reads these variables only when the corresponding constructor argument is omitted (LANDLINE_REMOVER_API_KEY has no constructor argument and is always read from the environment). ai-lls-api sets them in its template.yaml.

---

Architecture

src/ai_lls_lib/
├── __init__.py        # Public exports, version
├── common.py          # DecimalEncoder, extract_area_code
├── key_management.py  # Managed API-key hashing and generation helpers
├── core/              # PhoneVerifier, BulkProcessor, DynamoDBCache, models
├── auth/              # API Gateway authorizer-context parsers
├── apikeys/           # ManagedApiKeyService, LegacyApiKeyService
├── files/             # FileService
├── payment/           # StripeManager, CreditManager
├── admin/             # AdminService
├── providers/         # ExternalAPIProvider (landlineremover.com)
└── cli/               # ai-lls command-line interface

scripts/ at the repo root holds manual operator scripts. They are not part of the package and are never run from CI.