agent-alerts 0.1.0__py3-none-any.whl

agent_alerts-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,23 @@
+agent_alerts-0.1.0.dist-info/licenses/LICENSE,sha256=W9LQ0As1ojxIvLCcOJUn_aYKO5J17Y5w5J-StiwVPeY,1072
+alerts/__init__.py,sha256=8IHvcy2Eai9TxPMpM4wWeLfit8ZIooR3cB3U0jLvvqU,3585
+alerts/config.py,sha256=-_PIcs10naW3re8uLQRT5OdDQrQ6VTRqz-fx6s_sL1E,7743
+alerts/evaluator.py,sha256=0vYJFJ-psbyXEsmKMff2Tpq_oy9-UZG0rMGou-Wm_SY,8165
+alerts/feedback.py,sha256=OA1NqWvCzRtxBzcfkUB7zGkA0PYUQ4IQnSY7vrD_GZA,1102
+alerts/gateway_client.py,sha256=mkRpjsz_Q28A9vKoNhjIZNtXI_TQ6XhtkfEUVyEhYak,6685
+alerts/mcp_server.py,sha256=8uGTU2ylqX7d2wBsXzyhQURnbHvWWJfOWqxyuNQDptw,1850
+alerts/models.py,sha256=xgsiHvS5Py4IpFGpciwH5D_f8VT5dhljJNzzPreXL7A,1911
+alerts/prompt_builder.py,sha256=SA758FyPmXOzRGApY9msbt5-hzcbu1QFN-sU5IMksuU,2429
+alerts/quiet_hours.py,sha256=fpPv1LFU9cJUoiDKwkbKN7K6GoZyPtlYOH50jOuM-CU,2150
+alerts/rate_limiter.py,sha256=gYhKrdJvf-y8UCDvV4HRcugtfTmL2c7kzqjtOCRPBZE,1404
+alerts/router.py,sha256=2CU_nngevmZ5AABYk_cJ1VNhfPdSvHNLd6QzafADfm0,4663
+alerts/channels/__init__.py,sha256=Rq1lkwF57ScdLHc5IA5jHvNU_72-ndt5KSfZt09gNLY,346
+alerts/channels/agent.py,sha256=MV9WFGjVX91SbquCzIxOn9LTx3uiULduxOx6puG7tf8,6209
+alerts/channels/base.py,sha256=8blSY4Bv-b2F1wICynT0iblMda-5JO2bH4rkEUdsjhk,359
+alerts/channels/email.py,sha256=LULks6MTbyUwFBKu2_NRakr4LbKOQeYBnN3q65ysp0M,2706
+alerts/channels/imessage.py,sha256=hgiTB2KY8ynRX71I4PBl3tO4IQHC3nGnQIZOpTViivg,3726
+alerts/channels/telegram.py,sha256=IYcn6WliDU7TeIRJanS835zpCWuixVdq52QT_VAPhzk,2012
+agent_alerts-0.1.0.dist-info/METADATA,sha256=h0FGsfaEXvb0f3XtjHK4nEXnyey9CbvNd0BIuz7SFMY,3620
+agent_alerts-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agent_alerts-0.1.0.dist-info/entry_points.txt,sha256=o5oWTu9HKy8jGbrxcW0whaJkMxZ0qq0y6I8bF7Sd7ug,54
+agent_alerts-0.1.0.dist-info/top_level.txt,sha256=Mt78CGdVX-gAJ1lmcACyKsRN1hsKY--PPj8WNhjWlL4,7
+agent_alerts-0.1.0.dist-info/RECORD,,

agent_alerts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_alerts-0.1.0.dist-info/entry_points.txt

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

agent_alerts-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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

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",
+]

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",
+]

alerts/channels/agent.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import threading
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from ..feedback import FeedbackHandler, SUPPORTED_FEEDBACK_CHANNELS
+from ..gateway_client import GatewayClient
+from ..models import Alert, AlertLevel
+from ..prompt_builder import DefaultPromptBuilder
+
+log = logging.getLogger(__name__)
+
+
+class AgentChannel:
+    def __init__(
+        self,
+        *,
+        prompt_builder: DefaultPromptBuilder | None = None,
+        feedback_handler: FeedbackHandler | None = None,
+        gateway_client_cls: type[GatewayClient] = GatewayClient,
+        thread_factory: Callable[..., threading.Thread] = threading.Thread,
+    ) -> None:
+        self._prompt_builder = prompt_builder or DefaultPromptBuilder()
+        self._feedback_handler = feedback_handler or FeedbackHandler()
+        self._gateway_client_cls = gateway_client_cls
+        self._thread_factory = thread_factory
+
+    def send(
+        self,
+        alert: Alert,
+        *,
+        level: AlertLevel,
+        channel_config: dict[str, Any] | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> bool:
+        import httpx
+
+        _ = httpx
+        config = channel_config or {}
+        feedback_channel = str(config.get("feedback_channel", "telegram")).strip().lower() or "telegram"
+        if feedback_channel not in SUPPORTED_FEEDBACK_CHANNELS:
+            raise ValueError(f"Unsupported feedback channel: {feedback_channel}")
+
+        gateway_url = str(config.get("gateway_url", "")).strip()
+        if not gateway_url:
+            raise ValueError("Missing required agent channel config: gateway_url")
+
+        api_key_env_name = str(config.get("gateway_api_key_env", "ALERTS_GATEWAY_API_KEY")).strip()
+        if not api_key_env_name:
+            raise ValueError("Missing required agent channel config: gateway_api_key_env")
+
+        credentials = dict(os.environ if env is None else env)
+        gateway_api_key = str(credentials.get(api_key_env_name, "")).strip()
+        if not gateway_api_key:
+            raise ValueError(f"Missing required environment variable: {api_key_env_name}")
+
+        model = str(config.get("model", "")).strip() or None
+        prompt = self._prompt_builder.build(alert, level)
+        thread = self._thread_factory(
+            target=self._run_thread,
+            kwargs={
+                "alert": alert,
+                "prompt": prompt,
+                "gateway_url": gateway_url,
+                "gateway_api_key": gateway_api_key,
+                "model": model,
+                "feedback_channel": feedback_channel,
+                "env": dict(env) if env is not None else None,
+            },
+            daemon=False,
+            name=f"alerts-agent-{alert.alert_id}",
+        )
+        thread.start()
+        return True
+
+    def _run_thread(
+        self,
+        *,
+        alert: Alert,
+        prompt: str,
+        gateway_url: str,
+        gateway_api_key: str,
+        model: str | None,
+        feedback_channel: str,
+        env: Mapping[str, str] | None,
+    ) -> None:
+        loop = asyncio.new_event_loop()
+        try:
+            asyncio.set_event_loop(loop)
+            loop.run_until_complete(
+                self._stream_and_feedback(
+                    alert=alert,
+                    prompt=prompt,
+                    gateway_url=gateway_url,
+                    gateway_api_key=gateway_api_key,
+                    model=model,
+                    feedback_channel=feedback_channel,
+                    env=env,
+                )
+            )
+        except Exception:
+            log.warning("Agent channel failed for alert %s", alert.alert_id, exc_info=True)
+        finally:
+            asyncio.set_event_loop(None)
+            loop.close()
+
+    async def _stream_and_feedback(
+        self,
+        *,
+        alert: Alert,
+        prompt: str,
+        gateway_url: str,
+        gateway_api_key: str,
+        model: str | None,
+        feedback_channel: str,
+        env: Mapping[str, str] | None,
+    ) -> None:
+        import httpx
+
+        client = httpx.AsyncClient(timeout=120)
+        try:
+            gateway = self._gateway_client_cls(
+                gateway_url,
+                gateway_api_key,
+                http_client=client,
+            )
+            response_parts: list[str] = []
+            success = False
+            stream = gateway.stream_chat(
+                [{"role": "user", "content": prompt}],
+                model=model,
+            )
+            try:
+                async for event in stream:
+                    event_type = str(event.get("type", "") or "")
+                    if event_type == "text_delta":
+                        delta = str(event.get("text", "") or "")
+                        if delta:
+                            response_parts.append(delta)
+                        continue
+                    if event_type == "tool_approval_request":
+                        await gateway.submit_approval(
+                            str(event.get("tool_call_id", "") or ""),
+                            str(event.get("nonce", "") or ""),
+                            approved=False,
+                        )
+                        continue
+                    if event_type == "stream_complete":
+                        success = True
+                        break
+                    if event_type in {"stream_error", "error"}:
+                        log.warning(
+                            "Agent channel stream error for alert %s: %s",
+                            alert.alert_id,
+                            event.get("error", "unknown"),
+                        )
+                        break
+            finally:
+                close_stream = getattr(stream, "aclose", None)
+                if close_stream is not None:
+                    await close_stream()
+
+            if success and response_parts:
+                self._feedback_handler.send(
+                    "".join(response_parts),
+                    alert,
+                    channel=feedback_channel,
+                    env=env,
+                )
+        finally:
+            await client.aclose()
+
+
+__all__ = ["AgentChannel"]

alerts/channels/base.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Protocol
+
+from ..models import Alert, AlertLevel
+
+
+class ChannelAdapter(Protocol):
+    def send(
+        self,
+        alert: Alert,
+        *,
+        level: AlertLevel,
+        channel_config: dict[str, Any] | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> bool: ...

alerts/channels/email.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import os
+import smtplib
+from email.message import EmailMessage
+from typing import Any, Mapping
+
+from ..models import Alert, AlertLevel
+
+
+def send_email(
+    message: str,
+    *,
+    channel_config: dict[str, Any] | None = None,
+    env: Mapping[str, str] | None = None,
+) -> bool:
+    config = channel_config or {}
+    smtp_host = str(config.get("smtp_host", "")).strip()
+    sender = str(config.get("from", "")).strip()
+    recipients_raw = config.get("to", [])
+    if isinstance(recipients_raw, str):
+        recipients = [recipients_raw.strip()] if recipients_raw.strip() else []
+    elif isinstance(recipients_raw, list):
+        recipients = [str(recipient).strip() for recipient in recipients_raw if str(recipient).strip()]
+    else:
+        recipients = []
+
+    try:
+        smtp_port = int(config.get("smtp_port", 0))
+    except (TypeError, ValueError):
+        smtp_port = 0
+
+    if not smtp_host or not smtp_port or not sender or not recipients:
+        return False
+
+    credentials = dict(os.environ if env is None else env)
+    username = str(credentials.get("EMAIL_USERNAME", "")).strip()
+    password = str(credentials.get("EMAIL_PASSWORD", "")).strip()
+    if not username or not password:
+        return False
+
+    msg = EmailMessage()
+    msg["Subject"] = str(config.get("subject", "Investment Tools Alert"))
+    msg["From"] = sender
+    msg["To"] = ", ".join(recipients)
+    msg.set_content(message)
+
+    timeout = float(config.get("timeout_seconds", 10))
+    use_ssl = bool(config.get("use_ssl", smtp_port == 465))
+    use_starttls = bool(config.get("starttls", not use_ssl and smtp_port == 587))
+
+    if use_ssl:
+        with smtplib.SMTP_SSL(smtp_host, smtp_port, timeout=timeout) as server:
+            server.login(username, password)
+            server.send_message(msg)
+        return True
+
+    with smtplib.SMTP(smtp_host, smtp_port, timeout=timeout) as server:
+        server.ehlo()
+        if use_starttls:
+            server.starttls()
+            server.ehlo()
+        server.login(username, password)
+        server.send_message(msg)
+    return True
+
+
+class EmailChannel:
+    def send(
+        self,
+        alert: Alert,
+        *,
+        level: AlertLevel,
+        channel_config: dict[str, Any] | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> bool:
+        return send_email(_render_message(alert, level), channel_config=channel_config, env=env)
+
+
+def _render_message(alert: Alert, level: AlertLevel) -> str:
+    parts = [part for part in (alert.title.strip(), alert.body) if part]
+    message = "\n\n".join(parts)
+    if level is AlertLevel.CRITICAL:
+        return f"** ALERT ** {message}"
+    return message