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 |
| Agent role definitions | .claude/agents/ |
| 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 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.
- 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.
If you need to work manually, see the full contributor guide (if available).
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. A few job-level if:
conditions in publish.yaml also reference refs/heads/dev (inherited
from the org's shared dev->main promotion template), but they're inactive
here since the workflow's push trigger never fires on dev.
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
| 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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ai_lls_lib-3.17.0.tar.gz.
File metadata
- Download URL: ai_lls_lib-3.17.0.tar.gz
- Upload date:
- Size: 55.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5a1e7e578d8ff2e8dddf3d25ac0f3476676218aca1f7f23ef66966a1fa050b3f
|
|
| MD5 |
ea098b40465db0ad15bc9d1832841465
|
|
| BLAKE2b-256 |
c7434ab2cfcb666fbe5c01c78441075f1a11fcf4927ecfd6d8afc154d4b4f485
|
Provenance
The following attestation bundles were made for ai_lls_lib-3.17.0.tar.gz:
Publisher:
publish.yaml on Augmenting-Integrations/ai-lls-lib
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ai_lls_lib-3.17.0.tar.gz -
Subject digest:
5a1e7e578d8ff2e8dddf3d25ac0f3476676218aca1f7f23ef66966a1fa050b3f - Sigstore transparency entry: 2580889411
- Sigstore integration time:
-
Permalink:
Augmenting-Integrations/ai-lls-lib@c81bbdc7096081431c281a271b6365f992dc02fe -
Branch / Tag:
refs/heads/main - Owner: https://github.com/Augmenting-Integrations
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yaml@c81bbdc7096081431c281a271b6365f992dc02fe -
Trigger Event:
push
-
Statement type:
File details
Details for the file ai_lls_lib-3.17.0-py3-none-any.whl.
File metadata
- Download URL: ai_lls_lib-3.17.0-py3-none-any.whl
- Upload date:
- Size: 70.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
62516b44a702220523bcd6f43ef9f630aaae9d1cd9b086b294a4f6eb592b3911
|
|
| MD5 |
28f2cd155ce22736419b16197a860b15
|
|
| BLAKE2b-256 |
d90ac72d8b1c9cad3cac0c29b1ddeef8fec9a721e640d40f343918369c171c75
|
Provenance
The following attestation bundles were made for ai_lls_lib-3.17.0-py3-none-any.whl:
Publisher:
publish.yaml on Augmenting-Integrations/ai-lls-lib
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ai_lls_lib-3.17.0-py3-none-any.whl -
Subject digest:
62516b44a702220523bcd6f43ef9f630aaae9d1cd9b086b294a4f6eb592b3911 - Sigstore transparency entry: 2580889453
- Sigstore integration time:
-
Permalink:
Augmenting-Integrations/ai-lls-lib@c81bbdc7096081431c281a271b6365f992dc02fe -
Branch / Tag:
refs/heads/main - Owner: https://github.com/Augmenting-Integrations
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yaml@c81bbdc7096081431c281a271b6365f992dc02fe -
Trigger Event:
push
-
Statement type:
