AmbiAlert

AmbiAlert is a powerful web monitoring tool that helps you stay informed about topics that matter to you. Instead of constantly checking websites for updates, AmbiAlert does the work for you by monitoring relevant web pages and alerting you when meaningful changes occur.

Features

• 🔍 Smart Query Expansion: Automatically expands your search queries to cover different aspects of your topic
• 🌐 Intelligent Web Monitoring: Tracks relevant websites and detects meaningful changes
• 🤖 AI-Powered Relevance Checking: Uses advanced language models to ensure changes are actually relevant to your interests
• 📧 Flexible Alerting System: Supports email notifications with more backends coming soon
• 💾 Persistent Monitoring: Uses SQLite to track monitored URLs and their states
• 🔄 Automatic Retries: Handles temporary failures gracefully

Installation

Using pip

pip install ambi-alert

From Source

# Clone the repository
git clone https://github.com/prassanna-ravishankar/ambi-alert.git
cd ambi-alert

# Install dependencies and set up development environment
make install

# Run tests
make test

# Check code quality
make check

# Build documentation
make docs

Quick Start

Command Line

The simplest way to use AmbiAlert is through its command-line interface:

# Monitor news about the next iPhone (prints alerts to console)
ambi-alert "next iPhone release"

# Monitor with email alerts
ambi-alert "next iPhone release" \
    --smtp-server smtp.gmail.com \
    --smtp-port 587 \
    --smtp-username your.email@gmail.com \
    --smtp-password "your-app-password" \
    --from-email your.email@gmail.com \
    --to-email target.email@example.com

# Check more frequently (every 15 minutes)
ambi-alert "next iPhone release" --check-interval 900

Python API

You can also use AmbiAlert programmatically:

from ambi_alert import AmbiAlert
from ambi_alert.alerting import EmailAlertBackend

# Create an alert backend (optional)
alert_backend = EmailAlertBackend(
    smtp_server="smtp.gmail.com",
    smtp_port=587,
    username="your.email@gmail.com",
    password="your-app-password",
    from_email="your.email@gmail.com",
    to_email="target.email@example.com"
)

# Create and run AmbiAlert
async with AmbiAlert(alert_backend=alert_backend) as ambi:
    # Add queries to monitor
    await ambi.add_monitoring_query("next iPhone release")
    await ambi.add_monitoring_query("AI breakthrough")

    # Start monitoring
    await ambi.run_monitor()

Development

Setup Development Environment

# Install dependencies and pre-commit hooks
make install

# Run tests
make test

# Check code quality
make check

# Build and serve documentation
make docs

# Build package
make build

# Build and publish to PyPI
make build-and-publish

Running Tests

# Run all tests
make test

# Test documentation
make docs-test

Documentation

Full documentation is available at https://prassanna-ravishankar.github.io/ambi-alert/.

To build and view documentation locally:

make docs

Then open http://127.0.0.1:8000 in your browser.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Set up development environment (make install)
4. Make your changes
5. Run tests and checks (make test && make check)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with smolagents for intelligent web search
• Uses DuckDuckGo for web search functionality
• Inspired by the need for proactive information monitoring