caucus 0.2.0__tar.gz → 0.2.1__tar.gz

{caucus-0.2.0 → caucus-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caucus
-Version: 0.2.0
+Version: 0.2.1
 Summary: Your AI agents, deliberating on the record. MCP-grounded multi-agent consensus with recorded dissent and an auditable decision log.
 Project-URL: Repository, https://github.com/srinath-jukanti/caucus
 Author: Srinath Jukanti

{caucus-0.2.0 → caucus-0.2.1}/config.example.yaml

@@ -46,5 +46,14 @@ panel:
 #   - "Which open intent, if any, is due for action today?"
 #   - "Any risks that warrant deviating from the standing plans?"
 
-# Delivery: run after the briefing renders, with the markdown path as argument.
-# notify_command: bash send_briefing.sh
+# Delivery after the briefing renders. Email credentials come from the NAMED
+# environment variables — never put secrets in this file.
+# notify:
+#   type: email                    # Gmail-friendly SMTP defaults
+#   to: you@example.com
+#   address_env: GMAIL_ADDRESS     # env var holding the sending address
+#   password_env: GMAIL_APP_PASSWORD
+# ...or run anything executable with the briefing path as its argument:
+# notify:
+#   type: command
+#   command: bash send_briefing.sh

{caucus-0.2.0 → caucus-0.2.1}/examples/trading-robinhood/config.yaml

@@ -35,5 +35,7 @@ agenda:
   - "Given the open intents, live positions, and current prices: which intent, if any, is due for its next action today, and what exactly should be done?"
   - "Does current market regime or any position's behavior warrant a defensive action (hedge, trim, or pause of an intent) beyond the standing plans?"
 
-# Delivery hook — receives the rendered briefing path as its argument.
-# notify_command: bash /path/to/send_briefing.sh
+# Delivery — Gmail via an app password; the env vars hold the credentials.
+# notify:
+#   type: email
+#   to: you@example.com

{caucus-0.2.0 → caucus-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "caucus"
-version = "0.2.0"
+version = "0.2.1"
 description = "Your AI agents, deliberating on the record. MCP-grounded multi-agent consensus with recorded dissent and an auditable decision log."
 readme = "README.md"
 requires-python = ">=3.11"

{caucus-0.2.0 → caucus-0.2.1}/src/caucus/__init__.py

@@ -1,3 +1,3 @@
 """Caucus — AI agents deliberating on the record."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{caucus-0.2.0 → caucus-0.2.1}/src/caucus/cli.py

@@ -207,16 +207,14 @@ def briefing(
 ) -> None:
     """Deliberate every agenda subject from the config and render one briefing.
 
-    Writes OUT (markdown) and its .json sibling, then runs the configured
-    notify_command with the markdown path as its argument — email scripts,
-    webhooks, anything executable.
+    Writes OUT (markdown) and its .json sibling, then delivers it via the
+    configured notifier — 'email' (SMTP, Gmail-friendly, credentials from
+    env vars) or 'command' (any executable, briefing path as argument).
     """
-    import shlex
-    import subprocess
-
     from caucus.briefing import run_agenda
     from caucus.config import Config, ConfigError
     from caucus.engine import Deliberation
+    from caucus.notify import NotifyError
 
     config_path = (
         config if config else Path("config.yaml") if Path("config.yaml").exists() else None
@@ -247,11 +245,13 @@ def briefing(
     for record in result.records:
         typer.echo(f"- {record.subject[:70]} → {record.decision[:90]} ({record.confidence:.0%})")
 
-    if loaded.notify_command:
-        completed = subprocess.run(f"{loaded.notify_command} {shlex.quote(str(out))}", shell=True)
-        if completed.returncode != 0:
-            typer.echo(f"notify command exited {completed.returncode}", err=True)
-            raise typer.Exit(1)
+    if loaded.notify is not None:
+        subject = f"[Caucus] briefing {result.generated_at[:10]} — {len(result.records)} decisions"
+        try:
+            loaded.notify.send(subject, result.to_markdown(), attachment_path=out)
+        except NotifyError as err:
+            typer.echo(str(err), err=True)
+            raise typer.Exit(1) from err
         typer.echo("notified")
 
 

{caucus-0.2.0 → caucus-0.2.1}/src/caucus/config.py

@@ -14,6 +14,7 @@ import yaml
 from caucus.backends import Backend, ClaudeCodeBackend, OpenAICompatibleBackend
 from caucus.engine import DEFAULT_PANEL, Analyst
 from caucus.evidence import EvidenceSource
+from caucus.notify import CommandNotifier, EmailNotifier
 
 
 class ConfigError(ValueError):
@@ -28,7 +29,7 @@ class Config:
     intents: Path | None = None
     evidence_sources: list[EvidenceSource] = field(default_factory=list)
     agenda: list[str] = field(default_factory=list)
-    notify_command: str | None = None
+    notify: EmailNotifier | CommandNotifier | None = None
 
     @classmethod
     def load(cls, path: Path) -> Config:
@@ -64,10 +65,14 @@ class Config:
             ):
                 raise ConfigError("'agenda' must be a non-empty list of subject strings")
             config.agenda = agenda
+        if "notify" in raw and "notify_command" in raw:
+            raise ConfigError("use either 'notify' or 'notify_command', not both")
+        if "notify" in raw:
+            config.notify = _build_notifier(raw["notify"])
         if "notify_command" in raw:
             if not isinstance(raw["notify_command"], str) or not raw["notify_command"].strip():
                 raise ConfigError("'notify_command' must be a non-empty string")
-            config.notify_command = raw["notify_command"]
+            config.notify = CommandNotifier(command=raw["notify_command"])
         return config
 
 
@@ -100,6 +105,34 @@ def _build_backend(raw: object) -> Backend:
     raise ConfigError(f"unknown backend type {kind!r} (expected 'claude' or 'openai')")
 
 
+def _build_notifier(raw: object) -> EmailNotifier | CommandNotifier:
+    if not isinstance(raw, dict):
+        raise ConfigError("'notify' must be a mapping with a 'type'")
+    kind = raw.get("type")
+    if kind == "email":
+        to = raw.get("to")
+        if not isinstance(to, str) or not to.strip():
+            raise ConfigError("email notify requires a string 'to' address")
+        options = {}
+        for key in ("smtp_host", "address_env", "password_env"):
+            if key in raw:
+                if not isinstance(raw[key], str) or not raw[key].strip():
+                    raise ConfigError(f"'{key}' must be a non-empty string")
+                options[key] = raw[key]
+        if "smtp_port" in raw:
+            port = raw["smtp_port"]
+            if isinstance(port, bool) or not isinstance(port, int) or not 0 < port < 65536:
+                raise ConfigError("'smtp_port' must be a valid port number")
+            options["smtp_port"] = port
+        return EmailNotifier(to=to, **options)
+    if kind == "command":
+        command = raw.get("command")
+        if not isinstance(command, str) or not command.strip():
+            raise ConfigError("command notify requires a string 'command'")
+        return CommandNotifier(command=command)
+    raise ConfigError(f"unknown notify type {kind!r} (expected 'email' or 'command')")
+
+
 def _build_evidence_sources(raw: object) -> list[EvidenceSource]:
     if not isinstance(raw, list):
         raise ConfigError("'evidence_sources' must be a list")

caucus-0.2.1/src/caucus/notify.py

@@ -0,0 +1,66 @@
+"""Notification: how a finished briefing reaches a human.
+
+Config-driven, two kinds:
+- email: SMTP (Gmail-friendly defaults) using stdlib smtplib. Credentials are
+  read from environment variables named in the config — never from the config
+  itself.
+- command: run any executable with the briefing path as its argument.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import smtplib
+import subprocess
+from dataclasses import dataclass
+from email.mime.text import MIMEText
+from pathlib import Path
+
+
+class NotifyError(RuntimeError):
+    """Raised when a notification cannot be delivered."""
+
+
+@dataclass
+class EmailNotifier:
+    """SMTP delivery; defaults suit a Gmail account with an app password."""
+
+    to: str
+    smtp_host: str = "smtp.gmail.com"
+    smtp_port: int = 465
+    address_env: str = "GMAIL_ADDRESS"
+    password_env: str = "GMAIL_APP_PASSWORD"
+    smtp_factory: object | None = None  # injectable for tests
+
+    def send(self, subject: str, body: str, attachment_path: Path | None = None) -> None:
+        address = os.environ.get(self.address_env)
+        password = os.environ.get(self.password_env)
+        if not address or not password:
+            raise NotifyError(
+                f"email notifier needs ${self.address_env} and ${self.password_env} set"
+            )
+        message = MIMEText(body, "plain", "utf-8")
+        message["Subject"] = subject
+        message["From"] = address
+        message["To"] = self.to
+        factory = self.smtp_factory or smtplib.SMTP_SSL
+        try:
+            with factory(self.smtp_host, self.smtp_port) as server:
+                server.login(address, password)
+                server.sendmail(address, [self.to], message.as_string())
+        except OSError as err:
+            raise NotifyError(f"email delivery failed: {err}") from err
+
+
+@dataclass
+class CommandNotifier:
+    """Runs a user-configured command with the briefing path appended."""
+
+    command: str
+
+    def send(self, subject: str, body: str, attachment_path: Path | None = None) -> None:
+        target = shlex.quote(str(attachment_path)) if attachment_path else ""
+        completed = subprocess.run(f"{self.command} {target}".strip(), shell=True)
+        if completed.returncode != 0:
+            raise NotifyError(f"notify command exited {completed.returncode}")

{caucus-0.2.0 → caucus-0.2.1}/tests/test_briefing.py

@@ -62,7 +62,9 @@ notify_command: bash send_briefing.sh
     )
     config = Config.load(path)
     assert config.agenda == ["Question one?", "Question two?"]
-    assert config.notify_command == "bash send_briefing.sh"
+    from caucus.notify import CommandNotifier
+
+    assert config.notify == CommandNotifier(command="bash send_briefing.sh")
 
 
 @pytest.mark.parametrize(

caucus-0.2.1/tests/test_notify.py

@@ -0,0 +1,111 @@
+from types import SimpleNamespace
+
+import pytest
+
+from caucus.config import Config, ConfigError
+from caucus.notify import CommandNotifier, EmailNotifier, NotifyError
+
+
+class FakeSMTP:
+    """Records logins and sends; usable as a context manager factory."""
+
+    instances = []
+
+    def __init__(self, host, port):
+        self.host, self.port = host, port
+        self.logins, self.sent = [], []
+        FakeSMTP.instances.append(self)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return False
+
+    def login(self, address, password):
+        self.logins.append((address, password))
+
+    def sendmail(self, sender, recipients, message):
+        self.sent.append(SimpleNamespace(sender=sender, recipients=recipients, message=message))
+
+
+@pytest.fixture(autouse=True)
+def reset_fake():
+    FakeSMTP.instances = []
+
+
+def test_email_notifier_sends_via_smtp(monkeypatch):
+    monkeypatch.setenv("GMAIL_ADDRESS", "me@example.com")
+    monkeypatch.setenv("GMAIL_APP_PASSWORD", "app-pass")
+    notifier = EmailNotifier(to="you@example.com", smtp_factory=FakeSMTP)
+    notifier.send("subject line", "body text")
+    server = FakeSMTP.instances[0]
+    assert server.host == "smtp.gmail.com"
+    assert server.logins == [("me@example.com", "app-pass")]
+    sent = server.sent[0]
+    assert sent.recipients == ["you@example.com"]
+    assert "subject line" in sent.message
+
+
+def test_email_notifier_requires_env(monkeypatch):
+    monkeypatch.delenv("GMAIL_ADDRESS", raising=False)
+    monkeypatch.delenv("GMAIL_APP_PASSWORD", raising=False)
+    notifier = EmailNotifier(to="you@example.com", smtp_factory=FakeSMTP)
+    with pytest.raises(NotifyError, match="GMAIL_ADDRESS"):
+        notifier.send("s", "b")
+    assert FakeSMTP.instances == []
+
+
+def test_command_notifier_runs_and_fails_loudly(tmp_path):
+    marker = tmp_path / "ran.txt"
+    CommandNotifier(command=f"touch {marker}").send("s", "b")
+    assert marker.exists()
+    with pytest.raises(NotifyError, match="exited 3"):
+        CommandNotifier(command="exit 3").send("s", "b")
+
+
+def test_config_parses_email_notifier(tmp_path):
+    path = tmp_path / "config.yaml"
+    path.write_text(
+        """
+notify:
+  type: email
+  to: you@example.com
+  address_env: MY_FROM
+  password_env: MY_PASS
+  smtp_port: 587
+"""
+    )
+    notify = Config.load(path).notify
+    assert isinstance(notify, EmailNotifier)
+    assert notify.to == "you@example.com"
+    assert notify.address_env == "MY_FROM"
+    assert notify.smtp_port == 587
+
+
+def test_config_legacy_notify_command_still_works(tmp_path):
+    path = tmp_path / "config.yaml"
+    path.write_text("notify_command: bash send.sh\n")
+    notify = Config.load(path).notify
+    assert isinstance(notify, CommandNotifier)
+    assert notify.command == "bash send.sh"
+
+
+@pytest.mark.parametrize(
+    "text",
+    [
+        "notify: email\n",
+        "notify:\n  type: email\n",
+        "notify:\n  type: email\n  to: ''\n",
+        "notify:\n  type: email\n  to: a@b.c\n  smtp_port: -5\n",
+        "notify:\n  type: email\n  to: a@b.c\n  smtp_port: true\n",
+        "notify:\n  type: command\n",
+        "notify:\n  type: slack\n",
+        "notify:\n  type: command\n  command: x\nnotify_command: y\n",
+    ],
+)
+def test_config_rejects_invalid_notify(tmp_path, text):
+    path = tmp_path / "config.yaml"
+    path.write_text(text)
+    with pytest.raises(ConfigError):
+        Config.load(path)

{caucus-0.2.0 → caucus-0.2.1}/uv.lock

@@ -34,7 +34,7 @@ wheels = [
 
 [[package]]
 name = "caucus"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },