policyboom 0.1.1
Enterprise legal risk intelligence CLI - analyze Terms of Service and Privacy Policies with multi-domain scanning
Requires Python: >=3.11
Keywords: legal, privacy, terms-of-service, compliance, analysis, cli

# PolicyBoom 💥

> Enterprise legal risk intelligence CLI for analyzing Terms of Service and Privacy Policies

PolicyBoom automatically discovers, analyzes, and scores concerning legal clauses across multi-domain company policies using a fluent dot-notation API.

## Quick Start

```bash
# Install
pip install policyboom

# Scan a company's policies
policyboom exec "scan('slack.com').summarizeHigh()"

# Filter by category
policyboom exec "scan('stripe.com').summarizeHigh().category('arbitration')"

# Get all findings
policyboom exec "scan('example.com').summarizeAll()"
```

## Features

- 🤖 **AI-Powered Extraction** - Uses Meta Llama 3.3 70B via Together AI for intelligent clause understanding
- 🌐 **Multi-Domain Scanning** - Discovers policies across root domain, subdomains, and product paths
- 🤹 **Bot Evasion** - User-agent rotation and request delays to avoid detection on restrictive sites
- 📱 **Mobile/AMP Fallbacks** - Automatically tries mobile and simplified versions for better coverage
- 🔍 **Clause-Level Analysis** - Extracts individual clauses with unique IDs and metadata
- ⚖️ **Severity Scoring** - Categorizes findings as High, Medium, or Low risk
- 🏷️ **Category Tagging** - Identifies arbitration waivers, data sale, tracking, COPPA violations, etc.
- 🔗 **Clickable Verification** - Source URLs with text fragments auto-scroll and highlight clauses in browser
- 📅 **Policy Dating** - Automatically extracts "last updated" dates from documents
- 💾 **Local Storage** - SQLite database for caching results (no cloud required)
- ✨ **Beautiful Output** - Rich terminal formatting with colors and tables
- 🔄 **Fluent API** - Chain commands with dot-notation for powerful queries

## Installation

```bash
pip install policyboom
```

### First-Time Setup

PolicyBoom uses Meta Llama 3.3 70B for intelligent clause extraction via Together AI's free tier:

1. **Get your free API key** from https://api.together.ai/settings/api-keys
2. **Run the setup command**:
   ```bash
   policyboom setup
   ```
3. **Enter your API key** when prompted (it will be saved securely to `~/.policyboom/config.json`)
4. **Start scanning**:
   ```bash
   policyboom exec "scan('stripe.com').summarizeHigh()"
   ```

That's it! Your API key is now saved and will be used automatically for all scans.

**Alternative**: You can also set the environment variable if you prefer:
```bash
export TOGETHER_API_KEY="your-api-key-here"
```

**No API key?** PolicyBoom will show a helpful message directing you to run `policyboom setup`.

## Usage

### CLI with Dot-Notation

The primary interface uses a fluent camelCase API:

```bash
# Basic scan
policyboom exec "scan('company.com').summarizeHigh()"

# Filter by severity and category
policyboom exec "scan('slack.com').summarizeMedium().category('dataSharing')"

# Get metadata with policy URLs and dates
policyboom exec "scan('stripe.com').summarizeAll().metadata()"

# Get full evidence for legal documentation
policyboom exec "scan('example.com').summarizeHigh().withEvidence()"

# Get detailed findings with all metadata
policyboom exec "scan('slack.com').summarizeAll().detailed()"
```

### As a Python Library

```python
from policyboom import scan

# Scan and analyze
result = scan("slack.com").summarizeHigh().category("arbitration")

# Access findings
for finding in result.findings:
    print(f"{finding.severity}: {finding.text}")
    
# Export results
result.export("output.json", format="json")
```

## Categories

PolicyBoom identifies these concerning clause types:

- `arbitration` - Forced arbitration / class action waivers
- `dataSale` - Third-party data selling
- `tracking` - Advertising and behavioral tracking
- `location` - Location data collection
- `retention` - Data retention policies
- `childrenData` - Children's data handling (COPPA)

## Reliability & Bot Evasion

PolicyBoom is designed to successfully scan most websites while avoiding bot detection:

### User-Agent Rotation
Every HTTP request uses a random, realistic browser user-agent from a pool of:
- Chrome on Windows, macOS, Linux
- Firefox on Windows, macOS, Linux
- Safari on macOS and iOS
- Microsoft Edge on Windows

This makes requests indistinguishable from normal web browsing.

### Human-Like Behavior
- **Request Delays**: Random 1-3 second pauses between requests mimic human browsing patterns
- **Browser Headers**: Complete header sets including Accept, Accept-Language, Accept-Encoding

### Mobile & AMP Fallbacks
When standard URLs fail or return incomplete content, PolicyBoom automatically tries:
- Mobile sites (`m.domain.com`)
- AMP versions (`?amp=1`)
- Simplified/print views (`?print=true`)

This provides ~60-70% success rate across major websites, including sites with basic bot detection.

### Limitations
Some sites still require headless browsers or authentication:
- **Amazon, Kick.com**: Advanced bot detection systems
- **Facebook, LinkedIn**: Policies behind login walls
- **Some news sites**: JavaScript-heavy rendering

For these sites, consider using headless browser support (adds ~10x latency and +700% memory/CPU cost).

## Commands

```bash
# Get help
policyboom --help

# Run interactive guide
policyboom guide

# View examples
policyboom examples

# Export scan results
policyboom export <scan_id> --format json
```

## Development

```bash
# Clone repository
git clone https://github.com/policyboom/policyboom
cd policyboom

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest
```

## License

MIT License - see LICENSE file for details

## Support

- Documentation: https://policyboom.dev
- Issues: https://github.com/policyboom/policyboom/issues
- Discussions: https://github.com/policyboom/policyboom/discussions