ai-lls-lib

CI/CD Pipeline PyPI version Python 3.12+ License

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.

  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).

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.

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

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (3.17.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for svange from gravatar.com svange

Credits

Author: LandlineScrubber Team

Requires

Python >=3.12

Provides Extra

dev

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ai_lls_lib-3.15.1.tar.gz (51.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ai_lls_lib-3.15.1-py3-none-any.whl (66.3 kB view details)

Uploaded Python 3

File details

Details for the file ai_lls_lib-3.15.1.tar.gz.

File metadata

  • Download URL: ai_lls_lib-3.15.1.tar.gz
  • Upload date:
  • Size: 51.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ai_lls_lib-3.15.1.tar.gz
Algorithm Hash digest
SHA256 dae14fffeaed1a4852cf292d9df448480632a9cf90da842ff108a58364566d43
MD5 2d2cdc54e8a479609ee202daadd6f229
BLAKE2b-256 c4ee26b7bbf4b7d82e9a0214741c091bfa445a3ab596d1e8fa1cca7358cb79c0

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_lls_lib-3.15.1.tar.gz:

Publisher: publish.yaml on Augmenting-Integrations/ai-lls-lib

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_lls_lib-3.15.1-py3-none-any.whl.

File metadata

  • Download URL: ai_lls_lib-3.15.1-py3-none-any.whl
  • Upload date:
  • Size: 66.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ai_lls_lib-3.15.1-py3-none-any.whl
Algorithm Hash digest
SHA256 f2ed233499aa13bffa21c9dc76e02a20bdbbfe331d911d6e0f4899fc08e60f47
MD5 8f682d55d6432da6a2c9753bf92c9ea0
BLAKE2b-256 d35a476880b206b1c7256185214950a3df98dff4a944f6538c8f3acf2dc926c5

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_lls_lib-3.15.1-py3-none-any.whl:

Publisher: publish.yaml on Augmenting-Integrations/ai-lls-lib

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

3.17.0

2 files

3.16.0

2 files

3.15.3

2 files

3.15.2

2 files

This release

3.15.1 This release

2 files

3.15.0

2 files

3.14.1

2 files

3.14.0

2 files

3.13.1

2 files

3.12.2

2 files

3.12.1

2 files

3.12.0

2 files

3.11.9

2 files

3.11.8

2 files

3.11.7

2 files

3.11.6

2 files

3.11.5

2 files

3.11.4

2 files

3.11.3

2 files

3.11.2

2 files

3.11.1

2 files

3.11.0

2 files

3.10.0

2 files

3.9.0

2 files

3.7.1

2 files

3.7.0

2 files

3.6.7

2 files

3.6.6

2 files

3.6.5

2 files

3.6.4

2 files

3.6.3

2 files

3.6.2

2 files

3.6.1

2 files

3.6.0

2 files

3.5.0

2 files

3.4.5

2 files

3.4.4

2 files

3.4.3

2 files

3.4.2

2 files

3.4.1

2 files

3.4.0

2 files

3.3.0

2 files

3.2.0

2 files

3.1.0

2 files

3.0.0

2 files

2.4.1

2 files

2.4.0

2 files

2.3.0

2 files

2.2.0

2 files

2.1.1

2 files

2.1.0

2 files

2.0.0

2 files

Pre-release

2.0.0rc2

2 files

Pre-release

2.0.0rc1

2 files

Pre-release

1.5.0rc10

2 files

Pre-release

1.5.0rc9

2 files

Pre-release

1.5.0rc8

2 files

Pre-release

1.5.0rc7

2 files

Pre-release

1.5.0rc6

2 files

Pre-release

1.5.0rc5

2 files

Pre-release

1.5.0rc4

2 files

Pre-release

1.5.0rc3

2 files

Pre-release

1.5.0rc2

2 files

1.4.0

2 files

Pre-release

1.4.0rc6

2 files

Pre-release

1.4.0rc4

2 files

Pre-release

1.4.0rc3

2 files

Pre-release

1.4.0rc2

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.1

2 files

1.2.0

2 files

1.1.0

2 files

1.0.0

2 files

Pre-release

1.0.0rc1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page