aimailsdk 0.1.0__py3-none-any.whl

aimail/__init__.py

@@ -0,0 +1,175 @@
+# -*- coding: utf-8 -*-
+"""aimail — AIMail runtime SDK (Python). Unified public entry point.
+
+This package is the single public surface for integrating aimail: both the
+platform hosts (Hermes / OpenClaw / DeerFlow) and third-party agents should
+``import aimail`` and use the re-exported API, rather than each doing its own
+``sys.path`` bootstrap + flat-script imports.
+
+Unified usage (recommended — hosts AND third parties):
+
+    import aimail
+    aimail.send_mail(to="x@example.com", subject="hi", body="hello")
+    client = aimail.GatewayClient(aimail.agent_email(), api_key="...")
+    aimail.manage_contacts(action="list")
+
+The runtime core is implemented as flat scripts (``aimail_base.py``,
+``aimail_tools.py``, ...) that import each other by top-level name, so they
+must sit on ``sys.path``. ``import aimail`` does that bootstrap for you and
+re-exports the curated public API below. The legacy flat path (insert
+``aimail.core_dir()`` on ``sys.path`` then ``import aimail_tools``) still
+works and is what the host adapters' bootstrap relies on — it is preserved,
+not replaced.
+
+Module layout inside the wheel mirrors the repository ``pysdk/`` directory
+(single source of truth), so the runtime's flat imports keep working:
+
+  aimail/
+    aimail_base.py        shared core (platform-agnostic)
+    aimail_tools.py       shared core (GatewayClient / send_mail)
+    aimail_board.py       shared core (A2A board)
+    gateway_api.py           standard amail API client
+    amail_mcp_server.py      platform-agnostic MCP server (stdio JSON-RPC)
+    _aimail_bootstrap.py     location-agnostic sys.path bootstrap (runtime glue)
+    install.py               self-contained install/uninstall entry
+    _resources_release.py    board/skills resource release (install-time)
+    hermes/                  Hermes adapter (6 modules, host-injected registry)
+    openclaw/                OpenClaw adapter (amail_base)
+    deer-flow/               DeerFlow adapter (inbound router / manage / base)
+    resources/
+      skills/                aimail SKILL.md + DESCRIPTION.md
+      board/role_prompt_en|zh, role_soul_en|zh   board templates
+"""
+
+import os as _os
+import sys as _sys
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # path helpers
+    "root",
+    "core_dir",
+    "skills_dir",
+    "board_role_prompt_dir",
+    "mcp_server_path",
+    # identity
+    "agent_email",
+    # outbound
+    "send_mail",
+    "GatewayClient",
+    # contacts
+    "manage_contacts",
+    "contact_profile",
+    "set_contact_profile",
+    # email
+    "email_summary",
+    "set_email_summary",
+    "store_inbound_message",
+    "render_message",
+]
+
+
+# ── Path helpers ──────────────────────────────────────────────────────────
+
+def root() -> str:
+    """Absolute path of this package directory."""
+    return _os.path.dirname(_os.path.abspath(__file__))
+
+
+def core_dir() -> str:
+    """Directory holding the flat-script core modules (aimail_base.py ...).
+
+    Insert this on ``sys.path`` to enable the legacy flat imports::
+
+        import sys, aimail
+        sys.path.insert(0, aimail.core_dir())
+        import aimail_base
+
+    In an installed wheel the flat modules are force-included into the package
+    dir, so this equals ``root()``. In a raw repo checkout pysdk/ is the
+    single source of truth and mirrors the wheel layout 1:1, so this equals
+    ``root()`` there as well. Either way, the returned dir is guaranteed to
+    contain ``aimail_base.py``.
+    """
+    return _resolve_core_dir()
+
+
+def skills_dir() -> str:
+    """aimail SKILL.md / DESCRIPTION.md directory."""
+    return _os.path.join(root(), "resources", "skills")
+
+
+def board_role_prompt_dir() -> str:
+    """Board role prompt templates (English, default) directory."""
+    return _os.path.join(root(), "resources", "board", "role_prompt_en")
+
+
+def mcp_server_path() -> str:
+    """Path of the platform-agnostic MCP server entry script."""
+    return _os.path.join(root(), "amail_mcp_server.py")
+
+
+# ── Unified core bootstrap + re-export ────────────────────────────────────
+
+def _resolve_core_dir() -> str:
+    """Locate the directory containing the flat core modules.
+
+    Resolution order (most specific first):
+      1. installed layout / repo pysdk — flat modules sit directly in the
+         package dir (pysdk/ is the single source of truth; the wheel
+         mirrors it 1:1 inside site-packages/aimail/)
+      2. AIMAIL_RUNTIME_DIR env override (explicit)
+
+    Returns the first candidate that contains ``aimail_base.py``, falling
+    back to ``root()`` (best effort) if none match.
+    """
+    here = root()
+    # 1. installed / repo pysdk layout: core modules are flat siblings here.
+    if _os.path.isfile(_os.path.join(here, "aimail_base.py")):
+        return here
+    # 2. explicit override.
+    env = _os.environ.get("AIMAIL_RUNTIME_DIR", "").strip()
+    if env:
+        d = _os.path.expanduser(env)
+        if _os.path.isfile(_os.path.join(d, "aimail_base.py")):
+            return d
+    return here
+
+
+def _import_core():
+    """Idempotently put the core dir on sys.path and import the flat core
+    modules as top-level modules (the same module objects the host adapters
+    use — no dual-module identity problem). Returns (base, tools, board, api).
+    """
+    core = _resolve_core_dir()
+    if core not in _sys.path:
+        _sys.path.insert(0, core)
+    # Reuse the single-source runtime bootstrap so any entry-point layout
+    # (adapter subdirs, env override) is handled consistently.
+    try:
+        import _aimail_bootstrap as _b
+        _b.ensure_core(core)
+    except Exception:
+        pass  # core already on path from the insert above; bootstrap is glue.
+    import aimail_base as _base
+    import aimail_tools as _tools
+    import aimail_board as _board
+    import gateway_api as _api
+    return _base, _tools, _board, _api
+
+
+_base, _tools, _board, _api = _import_core()
+
+# Re-export the curated public API (single public entry point).
+send_mail = _tools.send_mail
+GatewayClient = _tools._GatewayClient
+agent_email = _tools._resolve_agent_email
+manage_contacts = _tools.manage_contacts
+contact_profile = _tools.contact_profile
+set_contact_profile = _tools.set_contact_profile
+email_summary = _tools.email_summary
+set_email_summary = _tools.set_email_summary
+store_inbound_message = _tools.store_inbound_message
+render_message = _base.render_message

aimail/_aimail_bootstrap.py

@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+"""_aimail_bootstrap — runtime core location resolution (single source).
+
+Runtime modules are flat-script style (``import aimail_base``) and must
+run from any location: the source repository (tools/), an installed bundle
+(~/.aimail/... provisioner copies), or site-packages (pip aimail).
+This module resolves the directory containing the shared core modules
+(aimail_base.py / aimail_tools.py / aimail_board.py /
+gateway_api.py) and puts it — plus the calling entry point's own
+directory, for sibling imports — on sys.path.
+
+Resolution order (most specific first):
+  1. AIMAIL_RUNTIME_DIR env var (explicit override)
+  2. the directory above the entry point (bundle / site-packages layout:
+     adapter dirs openclaw|deer-flow sit directly under the core dir)
+  3. the entry point's own directory (flat layout: entry lives in core)
+
+The repo checkout is deliberately NOT a path fallback: installed runtimes
+must be self-contained (bundles) or installed (pip). Development from the
+repo works via case 3, which is local by definition.
+
+Entry points use it like:
+
+    def _amail_bootstrap():
+        import importlib.util as _ilu
+        _here = os.path.dirname(os.path.abspath(__file__))
+        for _d in (_here, os.path.dirname(_here)):
+            _p = os.path.join(_d, "_aimail_bootstrap.py")
+            if os.path.isfile(_p):
+                _spec = _ilu.spec_from_file_location("_aimail_bootstrap", _p)
+                _m = _ilu.module_from_spec(_spec)
+                sys.modules["_aimail_bootstrap"] = _m
+                _spec.loader.exec_module(_m)
+                _m.ensure_core(_here)
+                return
+        raise ImportError("aimail runtime core not found — set AIMAIL_RUNTIME_DIR")
+
+    _amail_bootstrap()
+
+    import aimail_base as _base          # noqa: E402
+"""
+
+import os
+import sys
+
+
+def _core_ok(d):
+    return bool(d) and os.path.isfile(os.path.join(d, "aimail_base.py"))
+
+
+def ensure_core(self_dir=None):
+    """Put the core module dir (and the entry point's own dir) on sys.path.
+
+    Returns the resolved core dir, or None if no candidate exists.
+    Idempotent: repeated calls do not duplicate entries.
+    """
+    self_dir = os.path.abspath(self_dir or os.path.dirname(os.path.abspath(__file__)))
+    here = self_dir
+
+    core = None
+    # 1. explicit override
+    env = os.environ.get("AIMAIL_RUNTIME_DIR", "").strip()
+    if env:
+        d = os.path.expanduser(env)
+        if _core_ok(d):
+            core = d
+    # 2. parent dir (adapter layout: core sits above openclaw|deer-flow)
+    if core is None and os.path.basename(here) in ("openclaw", "deer-flow", "hermes"):
+        d = os.path.dirname(here)
+        if _core_ok(d):
+            core = d
+    # 3. own dir (flat layout: entry point lives in the core dir)
+    if core is None and _core_ok(here):
+        core = here
+
+    if core is None:
+        return None
+
+    # adapter dir first (sibling imports), then core; dedupe both
+    for d in (here, core):
+        if d not in sys.path:
+            sys.path.insert(0, d)
+    return core
+
+
+if __name__ == "__main__":
+    print(ensure_core())

aimail/_resources_release.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""_resources_release — SDK 资源的本地配置目录展开(python 版)。
+
+架构:资源(role_prompt/role_soul × en/zh + skills)是公共种子,随 SDK
+分发;安装/启动时释放到 ~/.aimail/systems/{sid}/board/ 供运行时读取
+(pysdk 与 tssdk 运行时同路径)。只补缺失/更新的文件,绝不覆盖用户已在
+配置目录个性化过的内容。
+
+与 tssdk mail-core release-resources.ts、cli 旧 release-board-resources.sh
+同语义;本模块为 pip/repo 双形态的 python 实现。
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+
+# 双形态自举:core 目录(含本模块与 aimail_base.py)即 _CORE
+_CORE = os.path.dirname(os.path.abspath(__file__))
+
+# 源子目录(包内 resources/board) → 配置目录目标子目录
+_DIR_MAP = (
+    ("role_prompt_en", "role_prompt"),
+    ("role_prompt_zh", "role_prompt_zh"),
+    ("role_soul_en", "role_soul"),
+    ("role_soul_zh", "role_soul_zh"),
+)
+
+_AIMAIL_HOME = os.path.join(os.path.expanduser("~"), ".aimail")
+
+
+def agentmail_home() -> str:
+    return os.environ.get("AIMAIL_HOME", "") or _AIMAIL_HOME
+
+
+def resources_board_dir() -> str:
+    """包内 resources/board 目录(repo:pysdk/resources/board;pip:aimail/resources/board)。"""
+    return os.path.join(_CORE, "resources", "board")
+
+
+def release_resources(system_id: str, board_root: str | None = None) -> dict:
+    """释放 board 资源到 ~/.aimail/systems/{sid}/board/(幂等)。"""
+    src_root = board_root or resources_board_dir()
+    board_dir = os.path.join(agentmail_home(), "systems", system_id, "board")
+    copied = 0
+    skipped = 0
+    for src_name, dst_name in _DIR_MAP:
+        src_dir = os.path.join(src_root, src_name)
+        if not os.path.isdir(src_dir):
+            continue
+        dst_dir = os.path.join(board_dir, dst_name)
+        os.makedirs(dst_dir, exist_ok=True)
+        for fname in sorted(os.listdir(src_dir)):
+            if not fname.endswith(".md"):
+                continue
+            src = os.path.join(src_dir, fname)
+            dst = os.path.join(dst_dir, fname)
+            if os.path.exists(dst):
+                if os.path.getmtime(dst) >= os.path.getmtime(src):
+                    skipped += 1
+                    continue
+            shutil.copy2(src, dst)
+            copied += 1
+    return {"board_dir": board_dir, "copied": copied, "skipped": skipped}
+
+
+def release_all_systems(board_root: str | None = None) -> list:
+    """对 ~/.aimail/systems/ 下全部已有系统展开(单系统机器亦覆盖)。"""
+    systems_root = os.path.join(agentmail_home(), "systems")
+    if not os.path.isdir(systems_root):
+        return []
+    out = []
+    for ent in sorted(os.listdir(systems_root)):
+        p = os.path.join(systems_root, ent)
+        if os.path.isdir(p):
+            try:
+                out.append(release_resources(ent, board_root))
+            except Exception:  # noqa: BLE001
+                pass
+    return out
+
+
+if __name__ == "__main__":
+    # 便捷:python _resources_release.py [system_id...]
+    sids = sys.argv[1:] or sorted(
+        d for d in os.listdir(os.path.join(agentmail_home(), "systems"))
+        if os.path.isdir(os.path.join(agentmail_home(), "systems", d))
+    ) if os.path.isdir(os.path.join(agentmail_home(), "systems")) else []
+    for sid in sids:
+        r = release_resources(sid)
+        print(f"{sid}: {r['board_dir']} (copied {r['copied']}, kept {r['skipped']})")