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
Metadata
1 maintainer
Release files for ai-lls-lib 3.18.0
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.0.tar.gz | 56.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ai_lls_lib-3.18.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 127.2 kB
Release files / ai_lls_lib-3.18.0.tar.gz
| Download URL | ai_lls_lib-3.18.0.tar.gz |
|---|---|
| Size | 56.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
60213d08ad6278588f982f46e82a1feebd4fba8e857f7de031ede6ee16e1c8e4
|
|
BLAKE2b-256 checksum How to use checksums |
9c2c1ad65c8a7c00c7e2a0ff1008f294355b2c13a2bb12eca66375bfd0a0dbe2
|
| 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 Aug 28, 2026.
Transparency logRelease files / ai_lls_lib-3.18.0-py3-none-any.whl
| Download URL | ai_lls_lib-3.18.0-py3-none-any.whl |
|---|---|
| Size | 71.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
34ed1c4e4b1c4c7dea44d3f2a76e895a3c48e9a8e451223351329298e6ebeef2
|
|
BLAKE2b-256 checksum How to use checksums |
93f4ef719e3434fc8ec19b076d1d0a912305c0fb28e29a2c6bdaaaba450254b1
|
| 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 Aug 28, 2026.
Transparency log
