agent-alerts 0.1.0__tar.gz

agent_alerts-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Chien LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_alerts-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: agent-alerts
+Version: 0.1.0
+Summary: Structured alert routing to humans and AI agents
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/henrychien/agent-alerts
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=0.1.0; extra == "mcp"
+Provides-Extra: agent
+Requires-Dist: httpx>=0.27.0; extra == "agent"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# agent-alerts
+
+Structured alert routing to humans and AI agents.
+
+## Install
+
+```bash
+pip install agent-alerts
+pip install "agent-alerts[mcp]"
+pip install "agent-alerts[agent]"
+```
+
+Python imports stay under `alerts`.
+
+## Quick Start
+
+Send a simple alert directly to Telegram:
+
+```python
+from alerts import send
+
+send("Screen complete: 4 names passed", channel="telegram")
+```
+
+That reads `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` from your environment unless you pass `token=` and `chat_id=` explicitly.
+
+Use `AlertRouter` for structured routing, thresholds, quiet hours, and agent follow-up:
+
+```python
+from alerts import Alert, AlertCategory, AlertLevel, AlertRouter
+
+router = AlertRouter(config_path="alerting.yaml")
+
+result = router.send(
+    Alert(
+        title="Estimate revisions turning negative",
+        body="NVDA revisions rolled over after guidance.",
+        level=AlertLevel.HIGH,
+        category=AlertCategory.SIGNAL,
+        source="portfolio-system",
+        source_type="estimate_revisions",
+        metadata={"passed_count": 1},
+    )
+)
+
+print(result.delivered_channels)
+print(result.agent_dispatched)
+```
+
+## Channels
+
+| Channel | Purpose | Required config |
+| --- | --- | --- |
+| `telegram` | Fast human notification | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` |
+| `imessage` | Local macOS delivery | `IMESSAGE_TARGET` or `channels.imessage.recipient`; optional `backend`, `service` |
+| `email` | SMTP delivery | `smtp_host`, `smtp_port`, `from`, `to` plus `EMAIL_USERNAME`, `EMAIL_PASSWORD` |
+| `agent` | Background agent analysis with human feedback | `gateway_url`, `gateway_api_key_env`; optional `model`, `feedback_channel` |
+
+## Router Config
+
+Example `alerting.yaml`:
+
+```yaml
+schema_version: 2
+on_config_error: use_last_good
+
+channels:
+  telegram:
+    enabled: true
+  imessage:
+    enabled: false
+    recipient: "+15555551212"
+    backend: applescript
+  email:
+    enabled: false
+    smtp_host: smtp.gmail.com
+    smtp_port: 587
+    from: alerts@example.com
+    to:
+      - user@example.com
+  agent:
+    enabled: true
+    gateway_url: "http://127.0.0.1:8002"
+    gateway_api_key_env: "ALERTS_GATEWAY_API_KEY"
+    model: "claude-sonnet-4-6"
+    feedback_channel: telegram
+
+routing:
+  critical: [telegram, agent]
+  high: [telegram, agent]
+  normal: [telegram]
+  low: []
+  by_category:
+    signal:
+      critical: [telegram, agent]
+    screen_result:
+      high: [telegram, agent]
+
+quiet_hours:
+  enabled: true
+  start: "22:00"
+  end: "07:00"
+  timezone: "America/New_York"
+  per_channel:
+    agent:
+      enabled: false
+
+rate_limits:
+  enabled: true
+  global_max_per_hour: 20
+  agent_max_per_hour: 5
+
+thresholds:
+  _default:
+    min_passed_count: 1
+    default_level: normal
+    max_per_hour: 3
+  estimate_revisions:
+    min_passed_count: 1
+    level_rules:
+      - when:
+          passed_count_gte: 3
+        level: critical
+```
+
+## MCP Server
+
+The package exposes an MCP server entry point:
+
+```bash
+alerts-mcp
+python -m alerts.mcp_server
+```
+
+It provides three tools:
+
+- `notify_send`
+- `notify_list_channels`
+- `notify_test_channel`
+
+## License
+
+MIT

agent_alerts-0.1.0/README.md

@@ -0,0 +1,143 @@
+# agent-alerts
+
+Structured alert routing to humans and AI agents.
+
+## Install
+
+```bash
+pip install agent-alerts
+pip install "agent-alerts[mcp]"
+pip install "agent-alerts[agent]"
+```
+
+Python imports stay under `alerts`.
+
+## Quick Start
+
+Send a simple alert directly to Telegram:
+
+```python
+from alerts import send
+
+send("Screen complete: 4 names passed", channel="telegram")
+```
+
+That reads `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` from your environment unless you pass `token=` and `chat_id=` explicitly.
+
+Use `AlertRouter` for structured routing, thresholds, quiet hours, and agent follow-up:
+
+```python
+from alerts import Alert, AlertCategory, AlertLevel, AlertRouter
+
+router = AlertRouter(config_path="alerting.yaml")
+
+result = router.send(
+    Alert(
+        title="Estimate revisions turning negative",
+        body="NVDA revisions rolled over after guidance.",
+        level=AlertLevel.HIGH,
+        category=AlertCategory.SIGNAL,
+        source="portfolio-system",
+        source_type="estimate_revisions",
+        metadata={"passed_count": 1},
+    )
+)
+
+print(result.delivered_channels)
+print(result.agent_dispatched)
+```
+
+## Channels
+
+| Channel | Purpose | Required config |
+| --- | --- | --- |
+| `telegram` | Fast human notification | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` |
+| `imessage` | Local macOS delivery | `IMESSAGE_TARGET` or `channels.imessage.recipient`; optional `backend`, `service` |
+| `email` | SMTP delivery | `smtp_host`, `smtp_port`, `from`, `to` plus `EMAIL_USERNAME`, `EMAIL_PASSWORD` |
+| `agent` | Background agent analysis with human feedback | `gateway_url`, `gateway_api_key_env`; optional `model`, `feedback_channel` |
+
+## Router Config
+
+Example `alerting.yaml`:
+
+```yaml
+schema_version: 2
+on_config_error: use_last_good
+
+channels:
+  telegram:
+    enabled: true
+  imessage:
+    enabled: false
+    recipient: "+15555551212"
+    backend: applescript
+  email:
+    enabled: false
+    smtp_host: smtp.gmail.com
+    smtp_port: 587
+    from: alerts@example.com
+    to:
+      - user@example.com
+  agent:
+    enabled: true
+    gateway_url: "http://127.0.0.1:8002"
+    gateway_api_key_env: "ALERTS_GATEWAY_API_KEY"
+    model: "claude-sonnet-4-6"
+    feedback_channel: telegram
+
+routing:
+  critical: [telegram, agent]
+  high: [telegram, agent]
+  normal: [telegram]
+  low: []
+  by_category:
+    signal:
+      critical: [telegram, agent]
+    screen_result:
+      high: [telegram, agent]
+
+quiet_hours:
+  enabled: true
+  start: "22:00"
+  end: "07:00"
+  timezone: "America/New_York"
+  per_channel:
+    agent:
+      enabled: false
+
+rate_limits:
+  enabled: true
+  global_max_per_hour: 20
+  agent_max_per_hour: 5
+
+thresholds:
+  _default:
+    min_passed_count: 1
+    default_level: normal
+    max_per_hour: 3
+  estimate_revisions:
+    min_passed_count: 1
+    level_rules:
+      - when:
+          passed_count_gte: 3
+        level: critical
+```
+
+## MCP Server
+
+The package exposes an MCP server entry point:
+
+```bash
+alerts-mcp
+python -m alerts.mcp_server
+```
+
+It provides three tools:
+
+- `notify_send`
+- `notify_list_channels`
+- `notify_test_channel`
+
+## License
+
+MIT

agent_alerts-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "agent-alerts"
+version = "0.1.0"
+description = "Structured alert routing to humans and AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["PyYAML>=6.0"]
+
+[project.optional-dependencies]
+mcp = ["fastmcp>=0.1.0"]
+agent = ["httpx>=0.27.0"]
+dev = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/henrychien/agent-alerts"
+
+[project.scripts]
+alerts-mcp = "alerts.mcp_server:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["alerts*"]
+exclude = ["alerts.tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["src/alerts/tests"]
+python_files = ["test_*.py"]
+addopts = ["-ra", "--tb=short"]

agent_alerts-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_alerts-0.1.0/src/agent_alerts.egg-info/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: agent-alerts
+Version: 0.1.0
+Summary: Structured alert routing to humans and AI agents
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/henrychien/agent-alerts
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=0.1.0; extra == "mcp"
+Provides-Extra: agent
+Requires-Dist: httpx>=0.27.0; extra == "agent"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# agent-alerts
+
+Structured alert routing to humans and AI agents.
+
+## Install
+
+```bash
+pip install agent-alerts
+pip install "agent-alerts[mcp]"
+pip install "agent-alerts[agent]"
+```
+
+Python imports stay under `alerts`.
+
+## Quick Start
+
+Send a simple alert directly to Telegram:
+
+```python
+from alerts import send
+
+send("Screen complete: 4 names passed", channel="telegram")
+```
+
+That reads `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` from your environment unless you pass `token=` and `chat_id=` explicitly.
+
+Use `AlertRouter` for structured routing, thresholds, quiet hours, and agent follow-up:
+
+```python
+from alerts import Alert, AlertCategory, AlertLevel, AlertRouter
+
+router = AlertRouter(config_path="alerting.yaml")
+
+result = router.send(
+    Alert(
+        title="Estimate revisions turning negative",
+        body="NVDA revisions rolled over after guidance.",
+        level=AlertLevel.HIGH,
+        category=AlertCategory.SIGNAL,
+        source="portfolio-system",
+        source_type="estimate_revisions",
+        metadata={"passed_count": 1},
+    )
+)
+
+print(result.delivered_channels)
+print(result.agent_dispatched)
+```
+
+## Channels
+
+| Channel | Purpose | Required config |
+| --- | --- | --- |
+| `telegram` | Fast human notification | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` |
+| `imessage` | Local macOS delivery | `IMESSAGE_TARGET` or `channels.imessage.recipient`; optional `backend`, `service` |
+| `email` | SMTP delivery | `smtp_host`, `smtp_port`, `from`, `to` plus `EMAIL_USERNAME`, `EMAIL_PASSWORD` |
+| `agent` | Background agent analysis with human feedback | `gateway_url`, `gateway_api_key_env`; optional `model`, `feedback_channel` |
+
+## Router Config
+
+Example `alerting.yaml`:
+
+```yaml
+schema_version: 2
+on_config_error: use_last_good
+
+channels:
+  telegram:
+    enabled: true
+  imessage:
+    enabled: false
+    recipient: "+15555551212"
+    backend: applescript
+  email:
+    enabled: false
+    smtp_host: smtp.gmail.com
+    smtp_port: 587
+    from: alerts@example.com
+    to:
+      - user@example.com
+  agent:
+    enabled: true
+    gateway_url: "http://127.0.0.1:8002"
+    gateway_api_key_env: "ALERTS_GATEWAY_API_KEY"
+    model: "claude-sonnet-4-6"
+    feedback_channel: telegram
+
+routing:
+  critical: [telegram, agent]
+  high: [telegram, agent]
+  normal: [telegram]
+  low: []
+  by_category:
+    signal:
+      critical: [telegram, agent]
+    screen_result:
+      high: [telegram, agent]
+
+quiet_hours:
+  enabled: true
+  start: "22:00"
+  end: "07:00"
+  timezone: "America/New_York"
+  per_channel:
+    agent:
+      enabled: false
+
+rate_limits:
+  enabled: true
+  global_max_per_hour: 20
+  agent_max_per_hour: 5
+
+thresholds:
+  _default:
+    min_passed_count: 1
+    default_level: normal
+    max_per_hour: 3
+  estimate_revisions:
+    min_passed_count: 1
+    level_rules:
+      - when:
+          passed_count_gte: 3
+        level: critical
+```
+
+## MCP Server
+
+The package exposes an MCP server entry point:
+
+```bash
+alerts-mcp
+python -m alerts.mcp_server
+```
+
+It provides three tools:
+
+- `notify_send`
+- `notify_list_channels`
+- `notify_test_channel`
+
+## License
+
+MIT

agent_alerts-0.1.0/src/agent_alerts.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+LICENSE
+README.md
+pyproject.toml
+src/agent_alerts.egg-info/PKG-INFO
+src/agent_alerts.egg-info/SOURCES.txt
+src/agent_alerts.egg-info/dependency_links.txt
+src/agent_alerts.egg-info/entry_points.txt
+src/agent_alerts.egg-info/requires.txt
+src/agent_alerts.egg-info/top_level.txt
+src/alerts/__init__.py
+src/alerts/config.py
+src/alerts/evaluator.py
+src/alerts/feedback.py
+src/alerts/gateway_client.py
+src/alerts/mcp_server.py
+src/alerts/models.py
+src/alerts/prompt_builder.py
+src/alerts/quiet_hours.py
+src/alerts/rate_limiter.py
+src/alerts/router.py
+src/alerts/channels/__init__.py
+src/alerts/channels/agent.py
+src/alerts/channels/base.py
+src/alerts/channels/email.py
+src/alerts/channels/imessage.py
+src/alerts/channels/telegram.py

agent_alerts-0.1.0/src/agent_alerts.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_alerts-0.1.0/src/agent_alerts.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+alerts-mcp = alerts.mcp_server:main

agent_alerts-0.1.0/src/agent_alerts.egg-info/requires.txt

@@ -0,0 +1,10 @@
+PyYAML>=6.0
+
+[agent]
+httpx>=0.27.0
+
+[dev]
+pytest
+
+[mcp]
+fastmcp>=0.1.0

agent_alerts-0.1.0/src/agent_alerts.egg-info/top_level.txt

@@ -0,0 +1 @@
+alerts

agent_alerts-0.1.0/src/alerts/__init__.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from .channels.email import send_email
+from .channels.imessage import send_imessage
+from .channels.telegram import send_telegram
+from .config import _load_dotenv, get_imessage_target, get_telegram_config
+from .evaluator import AlertDecision, AlertEvaluator
+from .models import Alert, AlertCategory, AlertLevel, AlertResult, coerce_alert_category, coerce_alert_level
+from .router import AlertRouter, DEFAULT_CONFIG_PATH
+
+
+def send(message: str, channel: str = "telegram", **kwargs) -> dict | bool:
+    env = _resolve_env(kwargs.pop("env", None), kwargs.pop("env_file", None))
+
+    if channel == "telegram":
+        token = kwargs.pop("token", None)
+        chat_id = kwargs.pop("chat_id", None)
+        if not token or not chat_id:
+            env_token, env_chat_id = get_telegram_config(env)
+            token = token or env_token
+            chat_id = chat_id or env_chat_id
+        return send_telegram(message, token, chat_id, **kwargs)
+
+    if channel == "imessage":
+        target = kwargs.pop("target", None) or get_imessage_target(env)
+        service = kwargs.pop("service", "imessage")
+        backend = kwargs.pop("backend", None)
+        return send_imessage(message, target, service=service, backend=backend)
+
+    if channel == "email":
+        channel_config = kwargs.pop("channel_config", None)
+        return send_email(message, channel_config=channel_config, env=env)
+
+    raise ValueError(f"Unknown channel: {channel}")
+
+
+def send_alert(
+    alert: Alert,
+    *,
+    router: AlertRouter | None = None,
+    config_path: str | Path | None = None,
+    env_file: str | Path | None = None,
+    env: Mapping[str, str] | None = None,
+) -> AlertResult:
+    active_router = router or AlertRouter(config_path=_require_config_path(config_path), env_file=env_file, env=env)
+    return active_router.send(alert)
+
+
+def send_alert_message(
+    message: str,
+    *,
+    title: str = "",
+    level: AlertLevel | str = AlertLevel.NORMAL,
+    category: AlertCategory | str = AlertCategory.CUSTOM,
+    source: str = "",
+    source_type: str = "",
+    metadata: dict[str, Any] | None = None,
+    channel: str | None = None,
+    router: AlertRouter | None = None,
+    config_path: str | Path | None = None,
+    env_file: str | Path | None = None,
+    env: Mapping[str, str] | None = None,
+) -> AlertResult:
+    alert = Alert(
+        title=title,
+        body=message,
+        level=coerce_alert_level(level),
+        category=coerce_alert_category(category),
+        source=source,
+        source_type=source_type,
+        metadata=dict(metadata or {}),
+    )
+    active_router = router or AlertRouter(config_path=_require_config_path(config_path), env_file=env_file, env=env)
+    if channel:
+        return active_router.send_channel(alert, channel=channel, level=alert.level)
+    return active_router.send(alert)
+
+
+def _resolve_env(env: Mapping[str, str] | None, env_file: str | Path | None) -> Mapping[str, str] | None:
+    if env is not None:
+        return dict(env)
+    if env_file is not None:
+        return _load_dotenv(env_file)
+    return None
+
+
+def _require_config_path(config_path: str | Path | None) -> str | Path:
+    return config_path or DEFAULT_CONFIG_PATH
+
+
+__all__ = [
+    "Alert",
+    "AlertCategory",
+    "AlertDecision",
+    "AlertEvaluator",
+    "AlertLevel",
+    "AlertResult",
+    "AlertRouter",
+    "get_imessage_target",
+    "get_telegram_config",
+    "send",
+    "send_alert",
+    "send_alert_message",
+    "send_email",
+    "send_imessage",
+    "send_telegram",
+]

agent_alerts-0.1.0/src/alerts/channels/__init__.py

@@ -0,0 +1,14 @@
+from .base import ChannelAdapter
+from .email import EmailChannel, send_email
+from .imessage import IMessageChannel, send_imessage
+from .telegram import TelegramChannel, send_telegram
+
+__all__ = [
+    "ChannelAdapter",
+    "EmailChannel",
+    "IMessageChannel",
+    "TelegramChannel",
+    "send_email",
+    "send_imessage",
+    "send_telegram",
+]