correspond 0.0.2__py3-none-any.whl

correspond/__init__.py

@@ -0,0 +1,113 @@
+"""correspond: a channel facade for AI agents.
+
+Read, listen, write and identify the sender over GitHub, email, push notifications,
+Telegram and a web inbox, through one model and one set of verbs::
+
+    >>> import correspond                                                  # doctest: +SKIP
+    >>> messages = correspond.read("github:octocat/hello-world#1")         # doctest: +SKIP
+    >>> messages[0].author.handle, messages[0].authenticity.grade.value    # doctest: +SKIP
+    ('octocat', 'platform')
+    >>> correspond.send("ntfy:", "backup finished", dry_run=True).plan     # doctest: +SKIP
+
+A conversation reference is ``<channel>:<id>``. Each channel implements the operations it
+can (``read``, ``listen``, ``send``, ``edit``, ``react``, ``upload``, ``verify``); asking
+for one it lacks raises :class:`NotSupported`, and :func:`capabilities` says so in advance.
+correspond knows no people: a message's ``author`` is what the platform attests, and its
+``authenticity`` is how sure the channel is.
+
+The command line (``correspond read github:octocat/hello-world#1``) and the MCP server use
+the same verbs, through :mod:`correspond.tools`.
+"""
+
+from correspond.errors import (
+    ChannelError,
+    CorrespondError,
+    InvalidRef,
+    MissingRequirement,
+    NotSupported,
+    UnknownChannel,
+)
+from correspond.model import (
+    Account,
+    Attachment,
+    Authenticity,
+    Capabilities,
+    ChannelIdentity,
+    ConversationRef,
+    Draft,
+    Event,
+    Grade,
+    HistoryDepth,
+    Message,
+    SendResult,
+    Support,
+)
+from correspond.ops import (
+    Editor,
+    Listener,
+    Reactor,
+    Reader,
+    Uploader,
+    Verifier,
+    Writer,
+    capabilities,
+    edit,
+    get_channel,
+    listen,
+    parse_ref,
+    react,
+    read,
+    send,
+    upload,
+    verify,
+)
+from correspond.registry import check_requirements, register_channel, unregister_channel
+from correspond.registry import channels as channel_registry
+from correspond.routing import RouteDecision, check_binding, metadata_rule, route
+
+__all__ = [
+    "Account",
+    "Attachment",
+    "Authenticity",
+    "Capabilities",
+    "ChannelError",
+    "ChannelIdentity",
+    "ConversationRef",
+    "CorrespondError",
+    "Draft",
+    "Editor",
+    "Event",
+    "Grade",
+    "HistoryDepth",
+    "InvalidRef",
+    "Listener",
+    "Message",
+    "MissingRequirement",
+    "NotSupported",
+    "Reactor",
+    "Reader",
+    "RouteDecision",
+    "SendResult",
+    "Support",
+    "UnknownChannel",
+    "Uploader",
+    "Verifier",
+    "Writer",
+    "capabilities",
+    "channel_registry",
+    "check_binding",
+    "check_requirements",
+    "edit",
+    "get_channel",
+    "listen",
+    "metadata_rule",
+    "parse_ref",
+    "react",
+    "read",
+    "register_channel",
+    "route",
+    "send",
+    "unregister_channel",
+    "upload",
+    "verify",
+]

correspond/__main__.py

@@ -0,0 +1,106 @@
+# PYTHON_ARGCOMPLETE_OK
+"""``correspond`` on the command line: ``cw`` over :data:`correspond.tools.TOOLS`.
+
+``--json`` anywhere prints the tool's result as JSON instead of text. ``-`` as the text of
+``send`` or ``edit`` reads it from stdin. A result with ``ok: false`` exits with status 1.
+"""
+
+import dataclasses
+import json
+import sys
+
+import cw
+
+from correspond import tools
+from correspond.render import render
+
+_REF = {
+    "help": "a conversation reference, <channel>:<id> (e.g. github:octocat/hello-world#1)"
+}
+_DRY_RUN = {"help": "show the plan; contact nothing and change nothing"}
+#: Per-parameter help for the command line (the tools' docstrings are the command help).
+HELP = {
+    "requirements": {"channel": {"help": "a channel name, e.g. telegram"}},
+    "capabilities": {"channel": {"help": "a channel name, e.g. github"}},
+    "ref": {"ref": _REF},
+    "read": {
+        "ref": _REF,
+        "since": {"help": "only messages sent or edited at or after this ISO 8601 time"},
+        "limit": {"help": "keep the most recent N messages"},
+    },
+    "listen": {
+        "ref": _REF,
+        "limit": {"help": "at most N events"},
+        "peek": {"help": "show new events without moving the cursor"},
+        "data_dir": {"help": "where cursors are kept (default: the data root)"},
+    },
+    "send": {
+        "ref": _REF,
+        "text": {"help": "the message, or - to read it from stdin"},
+        "title": {"help": "a title; on github:owner/repo it opens an issue"},
+        "reply_to": {"help": "the id of the message this answers"},
+        "priority": {"help": "low, normal, high or urgent (channels with priorities)"},
+        "dry_run": _DRY_RUN,
+    },
+    "edit": {
+        "ref": _REF,
+        "message_id": {"help": "the message id, as read shows it"},
+        "text": {"help": "the new text, or - to read it from stdin"},
+        "dry_run": _DRY_RUN,
+    },
+    "react": {
+        "ref": _REF,
+        "message_id": {"help": "the message id, as read shows it"},
+        "reaction": {"help": "the reaction, e.g. +1 or eyes (see capabilities)"},
+        "dry_run": _DRY_RUN,
+    },
+}
+
+
+def _egress(as_json):
+    def egress(result, *, out, err):
+        if as_json:
+            print(json.dumps(result, indent=2, ensure_ascii=False, default=str), file=out)
+            return 0 if result.get("ok", True) else 1
+        stdout, stderr, code = render(result)
+        if stderr:
+            print(stderr, file=err)
+        if stdout:
+            print(stdout, file=out)
+        return code
+
+    return egress
+
+
+def main(argv=None):
+    """Run one ``correspond`` command."""
+    for stream in (
+        sys.stdout,
+        sys.stderr,
+    ):  # a cp1252 pipe must not crash on a message's characters
+        getattr(stream, "reconfigure", lambda **_: None)(errors="backslashreplace")
+    argv = list(sys.argv[1:] if argv is None else argv)
+    as_json = "--json" in argv
+    commands = {tool.__name__.replace("_", "-"): tool for tool in tools.TOOLS}
+    config = {
+        command: {param: dict(spec) for param, spec in params.items()}
+        for command, params in HELP.items()
+    }
+    for command in ("send", "edit"):
+        config[command]["text"]["codec"] = lambda text: (
+            sys.stdin.read() if text == "-" else text
+        )
+    raise SystemExit(
+        cw.dispatch(
+            commands,
+            [a for a in argv if a != "--json"],
+            prog="correspond",
+            convention=dataclasses.replace(cw.MODERN, default_in_help=False),
+            egress=_egress(as_json),
+            config=config,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

correspond/channels/__init__.py

@@ -0,0 +1,6 @@
+"""The built-in channel adapters, one module each.
+
+The registry imports a module only when its channel is first used, so an adapter's
+dependencies (none, for the v0.1 adapters) are never paid for by code that does not use
+that channel.
+"""

correspond/channels/_http.py

@@ -0,0 +1,131 @@
+"""A small HTTP client over ``urllib``, shared by the HTTP adapters, with failures classified.
+
+Adapters take it as ``http=``. The call shape is
+``http(method, url, *, headers=None, body=None, timeout=DEFAULT_TIMEOUT_S) -> Response``:
+an HTTP error status comes back as a ``Response`` like any other, and only "could not reach
+the server" raises, as a ``ChannelError`` of kind ``network`` that names the host and never
+the URL (a URL path can carry a token). Tests pass a scripted function of the same shape.
+
+>>> classify(429, "slow down", {"retry-after": "3"}).retry_after
+3.0
+>>> classify(404, "gone").kind
+'not_found'
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from email.utils import parsedate_to_datetime
+from typing import Any
+from urllib.parse import urlsplit
+
+from correspond.errors import ChannelError
+
+__all__ = [
+    "DEFAULT_TIMEOUT_S",
+    "Response",
+    "classify",
+    "retry_after_seconds",
+    "urllib_http",
+]
+
+DEFAULT_TIMEOUT_S = 30
+USER_AGENT = "correspond (+https://github.com/thorwhalen/correspond)"
+
+
+@dataclass(frozen=True)
+class Response:
+    """An HTTP response: status, lower-cased headers, raw body."""
+
+    status: int
+    headers: Mapping[str, str] = field(default_factory=dict)
+    body: bytes = b""
+
+    def json(self) -> Any:
+        """The body parsed as JSON, or ``None`` when it is not JSON."""
+        try:
+            return json.loads(self.body.decode("utf-8") or "null")
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return None
+
+
+def _lowered(headers: Any) -> dict[str, str]:
+    return {k.lower(): v for k, v in headers.items()} if headers else {}
+
+
+def urllib_http(
+    method: str,
+    url: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    body: bytes | None = None,
+    timeout: float = DEFAULT_TIMEOUT_S,
+) -> Response:
+    """One request with the standard library."""
+    request = urllib.request.Request(
+        url,
+        data=body,
+        method=method,
+        headers={"User-Agent": USER_AGENT, **(headers or {})},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as reply:
+            return Response(reply.status, _lowered(reply.headers), reply.read())
+    except urllib.error.HTTPError as error:
+        try:
+            payload = error.read()
+        except OSError:
+            payload = b""
+        return Response(error.code, _lowered(error.headers), payload or b"")
+    except (urllib.error.URLError, TimeoutError, OSError) as error:
+        reason = getattr(error, "reason", None) or type(error).__name__
+        raise ChannelError(
+            f"could not reach {urlsplit(url).hostname}: {reason}",
+            kind="network",
+            retryable=True,
+        ) from None
+
+
+def retry_after_seconds(headers: Mapping[str, str] | None) -> float | None:
+    """``Retry-After`` in seconds (it may be a number or an HTTP date), or ``None``."""
+    raw = (headers or {}).get("retry-after")
+    if not raw:
+        return None
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        try:
+            return max(0.0, parsedate_to_datetime(raw).timestamp() - time.time())
+        except (TypeError, ValueError):
+            return None
+
+
+def classify(
+    status: int, message: str, headers: Mapping[str, str] | None = None
+) -> ChannelError:
+    """The :class:`~correspond.errors.ChannelError` an HTTP error status means."""
+    retry_after = retry_after_seconds(headers)
+    if status == 429:
+        return ChannelError(
+            message, kind="rate_limited", retryable=True, retry_after=retry_after
+        )
+    if status == 401:
+        return ChannelError(message, kind="auth")
+    if status == 403:
+        return ChannelError(message, kind="permission")
+    if status in (404, 410):
+        return ChannelError(message, kind="not_found")
+    if status in (408, 504):
+        return ChannelError(
+            message, kind="network", retryable=True, retry_after=retry_after
+        )
+    if 400 <= status < 500:
+        return ChannelError(message, kind="validation")
+    return ChannelError(
+        message, kind="unavailable", retryable=True, retry_after=retry_after
+    )