agim 0.0.1__tar.gz

agim-0.0.1/.gitignore

@@ -0,0 +1,24 @@
+**/.venv/
+backend/__pycache__/
+**/__pycache__/
+*.py[cod]
+frontend/node_modules/
+docs/node_modules/
+# VitePress build scratch space.
+docs/.vitepress/cache/
+docs/.vitepress/.temp/
+zett3rd/chrome-extension/node_modules/
+zett3rd/zettelekasten-chatgpt/node_modules/
+zett3rd/zettelekasten-chatgpt/dist/
+frontend/dist/
+dist/
+backend/zett/static/
+site/
+data/*.db
+.env
+.vscode/settings.json
+backend/.zett-tool-output/
+# Profiling output written next to the package, e.g. zett/profile/result.json.
+backend/zett/profile/
+**/.pytest_cache/
+**/.ruff_cache/

agim-0.0.1/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: agim
+Version: 0.0.1
+Summary: Standalone plugin toolkit for IM platform login, receive, and send
+Requires-Python: >=3.10
+Requires-Dist: cryptography<45,>=43
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<2.13,>=2.12
+Requires-Dist: typing-extensions<5,>=4.12; python_version < '3.12'
+Description-Content-Type: text/markdown
+
+# agim
+
+One stateless interface for IM login, receive, and send. agim is a plain SDK:
+it owns no storage, no plugin registry, and no host concepts. Callers persist
+the login handshake and receive cursor themselves and hand them back on the
+next call.
+
+## Interface
+
+```python
+class IMClient(ABC):
+    async def login(self) -> LoginHandshake: ...
+    async def is_login(self, handshake: LoginHandshake) -> LoginState: ...
+    async def receive(self, cursor: str | None = None) -> ReceiveResult: ...
+    async def send(self, chat_id: str, text: str, *, context_token: str | None = None) -> None: ...
+    async def aclose(self) -> None: ...
+```
+
+Because nothing is stored inside agim:
+
+- `login()` returns the QR payload **and** the provider state needed to poll it.
+  Persist the whole `LoginHandshake`, then pass it back to `is_login()`.
+- `receive()` returns the message **and** the next cursor. Persist the cursor,
+  then pass it to the next `receive()`.
+- `send()` takes the context token the caller stored from the inbound message.
+
+One `getupdates` poll can carry several messages. `receive()` still hands over
+exactly one message per call: the rest of the batch waits in memory (oldest
+first), and the returned cursor only advances past the batch once its last
+message has been handed over, so a restart mid-batch re-delivers that batch
+instead of dropping the messages behind the first one.
+
+## Platform clients
+
+`WeChatClient` implements the Tencent personal WeChat iLink/ClawBot protocol
+used by Tencent's official `openclaw-weixin` project: QR login, `getupdates`
+long polling, and `sendmessage`. More platforms (for example Discord)
+implement the same `IMClient` surface.
+
+Inbound messages carry their attachments on `InboundMessage.media`, one
+`InboundMedia` per image, voice note, file, or video. The client downloads the
+CDN reference and removes the AES-128-ECB encryption before returning, so a
+caller receives usable bytes; whether a given consumer reads an image, plays a
+voice note, or ignores both is the caller's decision. An item that cannot be
+downloaded or decrypted is logged and skipped: the message keeps the
+`[image]`/`[voice]`/`[file]`/`[video]` placeholder in its text. An item over
+`MAX_MEDIA_BYTES` raises `MediaTooLargeError` from `fetch_media` and is reported
+on `InboundMessage.rejected_media`, so a caller can tell the sender that the
+attachment was refused instead of losing it quietly.
+
+## Storage
+
+None. Whoever calls agim owns persistence.

agim-0.0.1/README.md

@@ -0,0 +1,53 @@
+# agim
+
+One stateless interface for IM login, receive, and send. agim is a plain SDK:
+it owns no storage, no plugin registry, and no host concepts. Callers persist
+the login handshake and receive cursor themselves and hand them back on the
+next call.
+
+## Interface
+
+```python
+class IMClient(ABC):
+    async def login(self) -> LoginHandshake: ...
+    async def is_login(self, handshake: LoginHandshake) -> LoginState: ...
+    async def receive(self, cursor: str | None = None) -> ReceiveResult: ...
+    async def send(self, chat_id: str, text: str, *, context_token: str | None = None) -> None: ...
+    async def aclose(self) -> None: ...
+```
+
+Because nothing is stored inside agim:
+
+- `login()` returns the QR payload **and** the provider state needed to poll it.
+  Persist the whole `LoginHandshake`, then pass it back to `is_login()`.
+- `receive()` returns the message **and** the next cursor. Persist the cursor,
+  then pass it to the next `receive()`.
+- `send()` takes the context token the caller stored from the inbound message.
+
+One `getupdates` poll can carry several messages. `receive()` still hands over
+exactly one message per call: the rest of the batch waits in memory (oldest
+first), and the returned cursor only advances past the batch once its last
+message has been handed over, so a restart mid-batch re-delivers that batch
+instead of dropping the messages behind the first one.
+
+## Platform clients
+
+`WeChatClient` implements the Tencent personal WeChat iLink/ClawBot protocol
+used by Tencent's official `openclaw-weixin` project: QR login, `getupdates`
+long polling, and `sendmessage`. More platforms (for example Discord)
+implement the same `IMClient` surface.
+
+Inbound messages carry their attachments on `InboundMessage.media`, one
+`InboundMedia` per image, voice note, file, or video. The client downloads the
+CDN reference and removes the AES-128-ECB encryption before returning, so a
+caller receives usable bytes; whether a given consumer reads an image, plays a
+voice note, or ignores both is the caller's decision. An item that cannot be
+downloaded or decrypted is logged and skipped: the message keeps the
+`[image]`/`[voice]`/`[file]`/`[video]` placeholder in its text. An item over
+`MAX_MEDIA_BYTES` raises `MediaTooLargeError` from `fetch_media` and is reported
+on `InboundMessage.rejected_media`, so a caller can tell the sender that the
+attachment was refused instead of losing it quietly.
+
+## Storage
+
+None. Whoever calls agim owns persistence.

agim-0.0.1/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "agim"
+version = "0.0.1"
+description = "Standalone plugin toolkit for IM platform login, receive, and send"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "cryptography>=43,<45",
+  "httpx>=0.27,<1",
+  "pydantic>=2.12,<2.13",
+  "typing_extensions>=4.12,<5; python_version < '3.12'",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agim"]
+
+[dependency-groups]
+dev = [
+  "pytest>=8,<9",
+  "pytest-asyncio>=0.26,<2",
+  "ruff>=0.11,<1",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

agim-0.0.1/src/agim/__init__.py

@@ -0,0 +1,45 @@
+"""agim: one stateless interface for IM login, receive, and send.
+
+The package is a plain SDK. It owns no storage, no plugin registry, and no
+host concepts: callers persist the login handshake and receive cursor
+themselves and hand them back on the next call.
+"""
+
+from .client import IMClient
+from .errors import MediaTooLargeError
+from .models import (
+    MAX_MEDIA_BYTES,
+    MAX_MEDIA_ITEMS,
+    InboundMedia,
+    InboundMessage,
+    JsonValue,
+    LoginCredentials,
+    LoginHandshake,
+    LoginState,
+    LoginStatus,
+    MediaKind,
+    MediaRejectionReason,
+    ReceiveResult,
+    RejectedMedia,
+)
+from .wechat import WeChatAuthClient, WeChatClient
+
+__all__ = [
+    "IMClient",
+    "InboundMessage",
+    "InboundMedia",
+    "JsonValue",
+    "LoginCredentials",
+    "LoginHandshake",
+    "LoginState",
+    "LoginStatus",
+    "MAX_MEDIA_BYTES",
+    "MAX_MEDIA_ITEMS",
+    "MediaKind",
+    "MediaRejectionReason",
+    "MediaTooLargeError",
+    "RejectedMedia",
+    "ReceiveResult",
+    "WeChatAuthClient",
+    "WeChatClient",
+]

agim-0.0.1/src/agim/_compat.py

@@ -0,0 +1,32 @@
+"""Shims for standard-library features that are newer than Python 3.10.
+
+``agim`` supports Python 3.10 and newer, but a couple of pieces build on
+features that only exist from 3.11 onward. Collecting them here keeps the
+version checks in one place.
+"""
+
+from __future__ import annotations
+
+import sys
+
+if sys.version_info >= (3, 11):  # pragma: no cover - selected by the interpreter
+    from enum import StrEnum
+else:  # pragma: no cover - selected by the interpreter
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        """``enum.StrEnum`` for Python 3.10: members are their own string value."""
+
+        def __str__(self) -> str:
+            return str(self.value)
+
+        def __format__(self, format_spec: str) -> str:
+            return str.__format__(str(self), format_spec)
+
+
+if sys.version_info >= (3, 12):  # pragma: no cover - selected by the interpreter
+    from typing import TypeAliasType
+else:  # pragma: no cover - selected by the interpreter
+    from typing_extensions import TypeAliasType
+
+__all__ = ["StrEnum", "TypeAliasType"]

agim-0.0.1/src/agim/client.py

@@ -0,0 +1,36 @@
+"""The one interface every agim platform client implements."""
+
+from abc import ABC, abstractmethod
+
+from .models import LoginHandshake, LoginState, ReceiveResult
+
+
+class IMClient(ABC):
+    """Unified login, receive, and send surface for one IM platform.
+
+    agim is stateless by design: callers own and persist the login handshake
+    and the receive cursor, then hand them back on the next call.
+    """
+
+    @abstractmethod
+    async def login(self) -> LoginHandshake:
+        """Begin a login flow and return the handshake the caller must store."""
+
+    @abstractmethod
+    async def is_login(self, handshake: LoginHandshake) -> LoginState:
+        """Poll one stored handshake and return the current login state."""
+
+    @abstractmethod
+    async def receive(self, cursor: str | None = None) -> ReceiveResult:
+        """Await the next inbound message and return its next cursor."""
+
+    @abstractmethod
+    async def send(self, chat_id: str, text: str, *, context_token: str | None = None) -> None:
+        """Send one outbound message, reusing the caller's stored token."""
+
+    async def aclose(self) -> None:
+        """Release transport resources; platforms without one keep the default."""
+        return None
+
+
+__all__ = ["IMClient"]

agim-0.0.1/src/agim/errors.py

@@ -0,0 +1,13 @@
+"""Errors agim raises for platform payloads it refuses to hand back."""
+
+
+class MediaTooLargeError(ValueError):
+    """One attachment exceeded the payload size agim is willing to hold.
+
+    Callers decide what an oversized attachment means for their own surface: an
+    SDK caller may log it, and a chat host may answer the sender instead of
+    running a turn over bytes it never received.
+    """
+
+
+__all__ = ["MediaTooLargeError"]

agim-0.0.1/src/agim/log.py

@@ -0,0 +1,19 @@
+"""Logging helpers for the standalone IM gateway."""
+
+import logging
+
+
+def configure_logging() -> None:
+    """Configure process-wide gateway logging once."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return one gateway logger."""
+    return logging.getLogger(name)
+
+
+__all__ = ["configure_logging", "get_logger"]

agim-0.0.1/src/agim/models.py

@@ -0,0 +1,146 @@
+"""Typed models shared by every agim client."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ._compat import StrEnum, TypeAliasType
+
+JsonValue = TypeAliasType("JsonValue", "str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]")
+
+#: Largest single attachment a platform client keeps in memory.
+MAX_MEDIA_BYTES = 256 * 1024 * 1024
+
+#: Most attachments one inbound message may carry.
+MAX_MEDIA_ITEMS = 16
+
+
+class LoginStatus(StrEnum):
+    """Lifecycle of one QR-assisted login flow."""
+
+    PENDING = "pending"
+    SCANNED = "scanned"
+    VERIFY_REQUIRED = "verify_required"
+    CONNECTED = "connected"
+    FAILED = "failed"
+    EXPIRED = "expired"
+
+
+class LoginHandshake(BaseModel):
+    """Opaque login state the caller must persist between login and is_login.
+
+    agim never stores anything itself, so the QR payload and whatever provider
+    state keeps the poll alive travel back to the caller in this object.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    qr_content: str = Field(min_length=1, max_length=10_000)
+    qr_url: str | None = Field(default=None, max_length=10_000)
+    state: dict[str, JsonValue] = Field(default_factory=dict)
+
+
+class LoginCredentials(BaseModel):
+    """Provider config and secrets returned once a login succeeds."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    config: dict[str, JsonValue] = Field(default_factory=dict)
+    secrets: dict[str, str] = Field(default_factory=dict)
+
+
+class LoginState(BaseModel):
+    """Current login status; ``is_login`` returns this to its caller."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: LoginStatus
+    message: str = Field(min_length=1, max_length=2_000)
+    credentials: LoginCredentials | None = None
+
+
+class MediaKind(StrEnum):
+    """Attachment kinds an IM platform can deliver."""
+
+    IMAGE = "image"
+    VOICE = "voice"
+    FILE = "file"
+    VIDEO = "video"
+
+
+class MediaRejectionReason(StrEnum):
+    """Why an attachment did not arrive with its message."""
+
+    TOO_LARGE = "too_large"
+
+
+class RejectedMedia(BaseModel):
+    """One attachment the platform announced but this client refused to carry."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: MediaKind
+    reason: MediaRejectionReason
+
+
+class InboundMedia(BaseModel):
+    """One attachment of an inbound message, already downloaded and decrypted.
+
+    Callers receive the bytes so a host can store, forward, or hand them to a
+    model; whether a given model can read them is the caller's decision, not
+    agim's.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: MediaKind
+    media_type: str = Field(min_length=1, max_length=100)
+    name: str | None = Field(default=None, max_length=255)
+    data: bytes = Field(min_length=1, max_length=MAX_MEDIA_BYTES)
+
+
+class InboundMessage(BaseModel):
+    """One normalized inbound message: its text plus any attached media."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    event_id: str = Field(min_length=1, max_length=200)
+    chat_id: str = Field(min_length=1, max_length=500)
+    user_id: str = Field(min_length=1, max_length=500)
+    text: str = Field(default="", max_length=100_000)
+    media: list[InboundMedia] = Field(default_factory=list, max_length=MAX_MEDIA_ITEMS)
+    rejected_media: list[RejectedMedia] = Field(default_factory=list, max_length=MAX_MEDIA_ITEMS)
+    reply_token: str | None = Field(default=None, max_length=10_000)
+
+    @model_validator(mode="after")
+    def _require_text_or_media(self) -> InboundMessage:
+        """A message carries something: text, a delivered attachment, or a refusal."""
+        if not self.text.strip() and not self.media and not self.rejected_media:
+            raise ValueError("Inbound message requires text, media, or a media rejection")
+        return self
+
+
+class ReceiveResult(BaseModel):
+    """One inbound message plus the cursor the caller must persist next."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    message: InboundMessage
+    cursor: str = Field(default="", max_length=100_000)
+
+
+__all__ = [
+    "InboundMessage",
+    "InboundMedia",
+    "JsonValue",
+    "LoginCredentials",
+    "LoginHandshake",
+    "LoginState",
+    "LoginStatus",
+    "MAX_MEDIA_BYTES",
+    "MAX_MEDIA_ITEMS",
+    "MediaKind",
+    "MediaRejectionReason",
+    "RejectedMedia",
+    "ReceiveResult",
+]

agim-0.0.1/src/agim/wechat/__init__.py

@@ -0,0 +1,17 @@
+"""Personal WeChat iLink/ClawBot implementation."""
+
+from .auth import ILINK_BASE_URL, WeChatAuthClient
+from .client import WeChatClient, attach_media, normalize_message
+from .media import CDN_BASE_URL, MediaRef, fetch_media, media_refs
+
+__all__ = [
+    "CDN_BASE_URL",
+    "ILINK_BASE_URL",
+    "MediaRef",
+    "WeChatAuthClient",
+    "WeChatClient",
+    "attach_media",
+    "fetch_media",
+    "media_refs",
+    "normalize_message",
+]

agim-0.0.1/src/agim/wechat/auth.py

@@ -0,0 +1,141 @@
+"""Tencent iLink QR login for personal WeChat bots."""
+
+from typing import Any
+
+import httpx
+
+from ..models import LoginCredentials, LoginHandshake, LoginState, LoginStatus
+
+ILINK_BASE_URL = "https://ilinkai.weixin.qq.com"
+ILINK_APP_ID = "bot"
+ILINK_APP_CLIENT_VERSION = str((2 << 16) | (4 << 8) | 9)
+ILINK_BOT_TYPE = "3"
+
+
+def _build_headers(*, token: str | None = None, json_content: bool = False) -> dict[str, str]:
+    headers = {
+        "iLink-App-Id": ILINK_APP_ID,
+        "iLink-App-ClientVersion": ILINK_APP_CLIENT_VERSION,
+    }
+    if json_content:
+        headers["Content-Type"] = "application/json"
+    if token:
+        headers["AuthorizationType"] = "ilink_bot_token"
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+class WeChatAuthClient:
+    """Implement the official iLink QR-code login protocol."""
+
+    def __init__(
+        self,
+        *,
+        timeout_seconds: float = 40.0,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._timeout_seconds = timeout_seconds
+        self._client = client
+        self._owns_client = client is None
+
+    async def aclose(self) -> None:
+        """Close the HTTP client when this adapter created it."""
+        if self._owns_client and self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def create_login(self) -> LoginHandshake:
+        """Request one QR code and return the handshake the caller must store."""
+        response = await self._get_client().post(
+            f"{ILINK_BASE_URL}/ilink/bot/get_bot_qrcode",
+            params={"bot_type": ILINK_BOT_TYPE},
+            json={"local_token_list": []},
+            headers=_build_headers(json_content=True),
+        )
+        response.raise_for_status()
+        payload = response.json()
+        if not isinstance(payload, dict):
+            raise ValueError("WeChat QR login returned an invalid response")
+        qrcode = payload.get("qrcode")
+        qr_content = payload.get("qrcode_img_content")
+        if not isinstance(qrcode, str) or not qrcode:
+            raise ValueError("WeChat QR login response is missing qrcode")
+        if not isinstance(qr_content, str) or not qr_content:
+            raise ValueError("WeChat QR login response is missing qrcode_img_content")
+        return LoginHandshake(
+            qr_content=qr_content,
+            qr_url=qr_content if qr_content.startswith(("http://", "https://")) else None,
+            state={"qrcode": qrcode, "base_url": ILINK_BASE_URL},
+        )
+
+    async def poll_login(
+        self,
+        handshake: LoginHandshake,
+        *,
+        verify_code: str | None = None,
+    ) -> LoginState:
+        """Poll one stored handshake and normalize the platform status."""
+        qrcode = handshake.state.get("qrcode")
+        base_url = handshake.state.get("base_url") or ILINK_BASE_URL
+        if not isinstance(qrcode, str) or not qrcode or not isinstance(base_url, str):
+            return LoginState(status=LoginStatus.EXPIRED, message="Login session expired; request a new QR code.")
+        params: dict[str, str] = {"qrcode": qrcode}
+        if verify_code:
+            params["verify_code"] = verify_code
+        try:
+            response = await self._get_client().get(
+                f"{base_url.rstrip('/')}/ilink/bot/get_qrcode_status",
+                params=params,
+                headers=_build_headers(),
+            )
+            response.raise_for_status()
+            payload: Any = response.json()
+        except (httpx.TimeoutException, httpx.NetworkError):
+            return LoginState(status=LoginStatus.PENDING, message="Waiting for the WeChat QR code to be scanned.")
+        except httpx.HTTPError as error:
+            return LoginState(
+                status=LoginStatus.PENDING,
+                message=f"WeChat login service is temporarily unavailable: {error}",
+            )
+        if not isinstance(payload, dict):
+            raise ValueError("WeChat QR status returned an invalid response")
+        status = payload.get("status")
+        if status == "confirmed":
+            token = payload.get("bot_token")
+            if not isinstance(token, str) or not token:
+                raise ValueError("WeChat login confirmed without bot_token")
+            config: dict[str, Any] = {"base_url": base_url}
+            if isinstance(payload.get("ilink_bot_id"), str):
+                config["ilink_bot_id"] = payload["ilink_bot_id"]
+            if isinstance(payload.get("ilink_user_id"), str):
+                config["ilink_user_id"] = payload["ilink_user_id"]
+            return LoginState(
+                status=LoginStatus.CONNECTED,
+                message="WeChat bot connected.",
+                credentials=LoginCredentials(config=config, secrets={"bot_token": token}),
+            )
+        if status in {"scaned", "scaned_but_redirect"}:
+            return LoginState(status=LoginStatus.SCANNED, message="QR code scanned; confirm in WeChat.")
+        if status == "need_verifycode":
+            return LoginState(status=LoginStatus.VERIFY_REQUIRED, message="Enter the pairing code shown in WeChat.")
+        if status in {"expired", "verify_code_blocked"}:
+            return LoginState(status=LoginStatus.EXPIRED, message="QR code expired; request a new one.")
+        if status == "binded_redirect":
+            return LoginState(status=LoginStatus.CONNECTED, message="This WeChat bot is already linked.")
+        return LoginState(status=LoginStatus.PENDING, message="Scan the QR code with WeChat to finish signing in.")
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                timeout=self._timeout_seconds,
+                follow_redirects=True,
+            )
+        return self._client
+
+
+__all__ = [
+    "ILINK_APP_CLIENT_VERSION",
+    "ILINK_APP_ID",
+    "ILINK_BASE_URL",
+    "WeChatAuthClient",
+]