ai-lls-lib
Core Python library for Landline Scrubber -- phone number verification, line-type detection, DNC registry checking, and bulk processing with caching.
Documentation
| Role | Document |
|---|---|
| Agent context and architecture constraints | CLAUDE.md |
| CI pipeline and shipping workflow | CLAUDE.md ("CI pipeline" / "Shipping a change") |
| Compliance overrides | .github/.ai-compliance.yaml |
Pipeline Artifacts
Reports are published to GitHub Pages when a push to
maincuts a release.
| Report | Link |
|---|---|
| API Documentation | pdoc reference |
| Test Coverage | HTML coverage report |
| Test Results | Unit test results |
| Security Scans | Bandit, 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.
- Open Claude Code (or your AI agent) in this repo.
- Describe the change you want -- a bug fix, a new feature, a doc update.
- The agent will:
- Create a feature branch
- Make the changes
- Run pre-commit checks and tests
- Open a pull request
- Review the PR when the agent is done. CI runs automatically.
- Merge once CI is green.
Branch model
- All work happens on a feature branch, merged into
mainthrough 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 persistentai-lls-lib-teststack, 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.
| Push to | Always deploys | Deploys on release only |
|---|---|---|
main |
Redeploys the persistent ai-lls-lib-test SAM stack (test infrastructure) and re-runs integration tests. |
Publishes the package to PyPI and deploys API docs / coverage / security / compliance reports to GitHub Pages, but only when semantic-release determines the commits warrant a version bump. |
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.
| Variable | Read by | Description |
|---|---|---|
LANDLINE_REMOVER_API_KEY |
ExternalAPIProvider |
landlineremover.com API key |
AWS_REGION |
CLI AWSClient, boto3 |
AWS region (default: us-east-1) |
CREDITS_TABLE |
CreditManager, AdminService |
DynamoDB credits table |
API_KEYS_TABLE |
LegacyApiKeyService |
DynamoDB legacy API-key table |
MANAGED_API_KEYS_TABLE |
ManagedApiKeyService |
DynamoDB managed API-key table |
FILES_TABLE |
FileService |
DynamoDB file-metadata table |
USER_POOL_ID |
AdminService |
Cognito user pool |
STRIPE_SECRET_KEY |
StripeManager |
Stripe secret key |
ENVIRONMENT |
StripeManager |
Deployment name, staging or prod (default: staging) |
LLS_BULK_MAX_WORKERS |
BulkProcessor |
Worker threads for bulk verification (default: 10) |
LLS_PROVIDER_MAX_RETRIES |
ExternalAPIProvider |
Retries per vendor call (default: 3) |
LLS_PROVIDER_RETRY_AFTER_CAP_SECONDS |
ExternalAPIProvider |
Longest wait a vendor Retry-After header can impose (default: 60) |
LLS_PROVIDER_RATE_LIMIT_PER_SECOND |
ExternalAPIProvider |
Outbound rate limit; 0 disables (default: 0) |
LLS_PROVIDER_BREAKER_THRESHOLD |
ExternalAPIProvider |
Consecutive failures that open the circuit (default: 5) |
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.
1 maintainer
Metadata
1 maintainer
Release files for ai-lls-lib 3.18.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ai_lls_lib-3.18.5.tar.gz | 56.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ai_lls_lib-3.18.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 128.4 kB
Release files / ai_lls_lib-3.18.5.tar.gz
| Download URL | ai_lls_lib-3.18.5.tar.gz |
|---|---|
| Size | 56.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b151c2c1bd3a8c146efa4031f2464008b1046cbdb0141192d121ea28322c805a
|
|
BLAKE2b-256 checksum How to use checksums |
19418bdb1dc61b3075001f374ebda56523a4f3377cfdfe6c9277276841dfb570
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / ai_lls_lib-3.18.5-py3-none-any.whl
| Download URL | ai_lls_lib-3.18.5-py3-none-any.whl |
|---|---|
| Size | 71.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fe21da06b7a1fa9b3b87f10b1aaa55e443078c085fd047a95f671f5c3f710853
|
|
BLAKE2b-256 checksum How to use checksums |
3591dfb5fd4270e545506bf6eb005f34a667607fccdabe8bce02571eb119505b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency log
