Metadata-Version: 2.3
Name: ai-lls-lib
Version: 3.13.1
Summary: Landline Scrubber core library - phone verification and DNC checking
Author: LandlineScrubber Team
Requires-Dist: boto3>=1.34.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: phonenumbers>=8.13.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: aws-lambda-powertools>=2.30.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=14.0
Requires-Dist: stripe>=12.5.1
Requires-Dist: pytest>=7.4.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0 ; extra == 'dev'
Requires-Dist: ruff>=0.8.0 ; extra == 'dev'
Requires-Dist: mypy>=1.8.0 ; extra == 'dev'
Requires-Dist: boto3-stubs[dynamodb,s3,sqs]>=1.34.0 ; extra == 'dev'
Requires-Dist: moto[cognitoidp,dynamodb,s3,sqs]>=4.2.0 ; extra == 'dev'
Requires-Dist: python-semantic-release>=10.3.1 ; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0 ; extra == 'dev'
Requires-Dist: bandit>=1.7.0 ; extra == 'dev'
Requires-Dist: pip-audit>=2.7.0 ; extra == 'dev'
Requires-Dist: pip-licenses>=5.0.0 ; extra == 'dev'
Requires-Dist: pdoc>=15.0.0 ; extra == 'dev'
Requires-Dist: pytest-html>=4.0.0 ; extra == 'dev'
Requires-Dist: joserfc>=0.9.0 ; extra == 'dev'
Requires-Dist: hypothesis>=6.0.0 ; extra == 'dev'
Requires-Python: >=3.12
Provides-Extra: dev
Description-Content-Type: text/markdown

# ai-lls-lib

[![CI/CD Pipeline](https://github.com/Augmenting-Integrations/ai-lls-lib/actions/workflows/pipeline.yaml/badge.svg)](https://github.com/Augmenting-Integrations/ai-lls-lib/actions/workflows/pipeline.yaml)
[![PyPI version](https://badge.fury.io/py/ai-lls-lib.svg)](https://badge.fury.io/py/ai-lls-lib)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-proprietary-red.svg)](LICENSE)

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

---

## Pipeline Artifacts

> Reports are published to GitHub Pages on every push to the default branch.

| Report | Link |
|--------|------|
| API Documentation | [pdoc reference](https://augmenting-integrations.github.io/ai-lls-lib/ai_lls_lib.html) |
| Test Coverage | [HTML coverage report](https://augmenting-integrations.github.io/ai-lls-lib/coverage/htmlcov/) |
| Test Results | [Unit test results](https://augmenting-integrations.github.io/ai-lls-lib/tests/test-report.html) |
| Security Scans | [Bandit, Safety, pip-audit](https://augmenting-integrations.github.io/ai-lls-lib/security/security-reports.html) |
| License Compliance | [Dependency license report](https://augmenting-integrations.github.io/ai-lls-lib/compliance/license-report.html) |
| PyPI Package | [pypi.org/project/ai-lls-lib](https://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](https://docs.astral.sh/uv/) package manager
- AWS credentials (for integration tests)

### First-time setup

```bash
git clone https://github.com/Augmenting-Integrations/ai-lls-lib.git
cd ai-lls-lib
uv sync --all-extras
```

### Running locally

```bash
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](CONTRIBUTING.md) (if available).

---

## Quick Start

### Single Phone Verification

```python
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"Cached: {result.cached}")        # True/False
```

### Bulk Processing

```python
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

```bash
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
```
