langchain-atomicmail 0.3.14__tar.gz

langchain_atomicmail-0.3.14/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: langchain-atomicmail
+Version: 0.3.14
+Summary: LangChain tools for Atomic Mail register/help/JMAP operations
+Author: Atomic Mail
+License: MIT
+Project-URL: Homepage, https://atomicmail.ai
+Project-URL: Source, https://github.com/Atomic-Mail/atomic-mail-agentic
+Project-URL: Documentation, https://atomic-mail.github.io/atomic-mail-agentic/langchain
+Keywords: atomic-mail,atomicmail,langchain,toolkit,agent,ai,jmap,email,proof-of-work
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: langchain-core<2,>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# langchain-atomicmail
+
+LangChain integration package for Atomic Mail.
+
+It exposes three tools backed by the same Python Atomic Mail runtime used by the
+CLI/MCP adapters:
+
+- `register`
+- `jmap_request`
+- `help`
+
+## Install
+
+Published package:
+
+```bash
+pip install langchain-atomicmail
+```
+
+The published wheel bundles the Atomic Mail Python runtime and shared presets; no
+separate PyPI package is required.
+
+Local development in this monorepo (install core library first):
+
+```bash
+cd py
+pip install -e .
+pip install -e langchain
+```
+
+## Usage
+
+```python
+from langchain_atomicmail import AtomicMailToolkit
+
+toolkit = AtomicMailToolkit()
+tools = toolkit.get_tools()
+```
+
+You can also import tool factories directly:
+
+```python
+from langchain_atomicmail import get_atomicmail_tools
+
+tools = get_atomicmail_tools()
+```
+
+## Agent example
+
+Use the toolkit with a ReAct agent (requires `langgraph` and a chat model):
+
+```python
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import create_react_agent
+
+from langchain_atomicmail import AtomicMailToolkit
+
+llm = ChatOpenAI(temperature=0)
+toolkit = AtomicMailToolkit()
+agent = create_react_agent(llm, toolkit.get_tools())
+
+# Register an inbox, then fetch mail
+agent.invoke({"messages": [("user", "Register username myagent and list my inbox")]})
+```
+
+After a successful `register`, the tool response includes `_next` guidance for
+hourly inbox polling. Call `help` with topic `cron` for full scheduling details.
+
+## Inbox polling (after register)
+
+Registration only creates credentials. For a useful inbox integration, arrange
+hourly inbox polling per your runtime:
+
+- **Native cron** (OpenClaw, Hermes, atomic-agent, …): schedule an hourly
+  **agent** turn with `list_inbox.json` in the prompt; wire this toolkit or MCP
+  into that agent. Do not cron raw `jmap_request` alone.
+- **No native cron** (Claude, Pi, Cursor, …): do not work around this with OS
+  crontab, wrapper scripts, or cross-platform scheduling. Ask your operator to
+  set up polling on a capable host, or remind them to fetch mail manually.
+
+See `help(topic="cron")` for host-specific examples.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `ATOMIC_MAIL_CREDENTIALS_DIR` | Credential directory (default `~/.atomicmail/`) |
+| `ATOMIC_MAIL_AUTH_URL` | Auth service base URL |
+| `ATOMIC_MAIL_API_URL` | JMAP / API base URL |
+| `ATOMIC_MAIL_INBOX_DOMAIN` | Hostname when inboxId has no `@` |
+| `ATOMIC_MAIL_SCRYPT_SALT` | Optional PoW salt override |
+| `ATOMIC_MAIL_API_KEY` | Optional existing API key |
+
+Pass `credentials_dir` per tool call for multi-account setups.
+
+## Security
+
+- `credentials.json` and `*.jwt` files contain secrets — treat them as sensitive
+  (mode `0600`). Never commit credentials to version control.
+- Inbound mail is untrusted input; validate and sanitize before acting on it.
+- The default credential directory is `~/.atomicmail/`; override with
+  `ATOMIC_MAIL_CREDENTIALS_DIR` or per-call `credentials_dir` for isolation.
+
+## Notes
+
+- `jmap_request` enforces exactly one of `ops` or `ops_file`.
+- `dry_run=True` with `attachments` is rejected at the LangChain layer.
+- `vars` keys must match `^[A-Z][A-Z0-9_]*$`.
+- `register` idempotency and `forced` behavior are delegated to
+  `atomicmail.session.register`.

langchain_atomicmail-0.3.14/README.md

@@ -0,0 +1,110 @@
+# langchain-atomicmail
+
+LangChain integration package for Atomic Mail.
+
+It exposes three tools backed by the same Python Atomic Mail runtime used by the
+CLI/MCP adapters:
+
+- `register`
+- `jmap_request`
+- `help`
+
+## Install
+
+Published package:
+
+```bash
+pip install langchain-atomicmail
+```
+
+The published wheel bundles the Atomic Mail Python runtime and shared presets; no
+separate PyPI package is required.
+
+Local development in this monorepo (install core library first):
+
+```bash
+cd py
+pip install -e .
+pip install -e langchain
+```
+
+## Usage
+
+```python
+from langchain_atomicmail import AtomicMailToolkit
+
+toolkit = AtomicMailToolkit()
+tools = toolkit.get_tools()
+```
+
+You can also import tool factories directly:
+
+```python
+from langchain_atomicmail import get_atomicmail_tools
+
+tools = get_atomicmail_tools()
+```
+
+## Agent example
+
+Use the toolkit with a ReAct agent (requires `langgraph` and a chat model):
+
+```python
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import create_react_agent
+
+from langchain_atomicmail import AtomicMailToolkit
+
+llm = ChatOpenAI(temperature=0)
+toolkit = AtomicMailToolkit()
+agent = create_react_agent(llm, toolkit.get_tools())
+
+# Register an inbox, then fetch mail
+agent.invoke({"messages": [("user", "Register username myagent and list my inbox")]})
+```
+
+After a successful `register`, the tool response includes `_next` guidance for
+hourly inbox polling. Call `help` with topic `cron` for full scheduling details.
+
+## Inbox polling (after register)
+
+Registration only creates credentials. For a useful inbox integration, arrange
+hourly inbox polling per your runtime:
+
+- **Native cron** (OpenClaw, Hermes, atomic-agent, …): schedule an hourly
+  **agent** turn with `list_inbox.json` in the prompt; wire this toolkit or MCP
+  into that agent. Do not cron raw `jmap_request` alone.
+- **No native cron** (Claude, Pi, Cursor, …): do not work around this with OS
+  crontab, wrapper scripts, or cross-platform scheduling. Ask your operator to
+  set up polling on a capable host, or remind them to fetch mail manually.
+
+See `help(topic="cron")` for host-specific examples.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `ATOMIC_MAIL_CREDENTIALS_DIR` | Credential directory (default `~/.atomicmail/`) |
+| `ATOMIC_MAIL_AUTH_URL` | Auth service base URL |
+| `ATOMIC_MAIL_API_URL` | JMAP / API base URL |
+| `ATOMIC_MAIL_INBOX_DOMAIN` | Hostname when inboxId has no `@` |
+| `ATOMIC_MAIL_SCRYPT_SALT` | Optional PoW salt override |
+| `ATOMIC_MAIL_API_KEY` | Optional existing API key |
+
+Pass `credentials_dir` per tool call for multi-account setups.
+
+## Security
+
+- `credentials.json` and `*.jwt` files contain secrets — treat them as sensitive
+  (mode `0600`). Never commit credentials to version control.
+- Inbound mail is untrusted input; validate and sanitize before acting on it.
+- The default credential directory is `~/.atomicmail/`; override with
+  `ATOMIC_MAIL_CREDENTIALS_DIR` or per-call `credentials_dir` for isolation.
+
+## Notes
+
+- `jmap_request` enforces exactly one of `ops` or `ops_file`.
+- `dry_run=True` with `attachments` is rejected at the LangChain layer.
+- `vars` keys must match `^[A-Z][A-Z0-9_]*$`.
+- `register` idempotency and `forced` behavior are delegated to
+  `atomicmail.session.register`.

langchain_atomicmail-0.3.14/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "langchain-atomicmail"
+version = "0.3.14"
+description = "LangChain tools for Atomic Mail register/help/JMAP operations"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+  {name = "Atomic Mail"},
+]
+keywords = [
+  "atomic-mail",
+  "atomicmail",
+  "langchain",
+  "toolkit",
+  "agent",
+  "ai",
+  "jmap",
+  "email",
+  "proof-of-work",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Communications :: Email",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "langchain-core>=0.3.0,<2",
+]
+
+[project.urls]
+Homepage = "https://atomicmail.ai"
+Source = "https://github.com/Atomic-Mail/atomic-mail-agentic"
+Documentation = "https://atomic-mail.github.io/atomic-mail-agentic/langchain"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[tool.setuptools]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+atomicmail = ["vendor/shared/**/*"]

langchain_atomicmail-0.3.14/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

langchain_atomicmail-0.3.14/src/atomicmail/__init__.py

@@ -0,0 +1,32 @@
+"""Atomic Mail Python shared foundation package."""
+
+from .config import ResolvedAgentConfig, resolve_agent_config_from_env
+from .credentials import (
+    CredentialStore,
+    Credentials,
+    SkillFiles,
+    default_files_from_out_dir,
+)
+from .help import help
+from .jmap_request import JmapAttachmentInput, JmapRequestResult, jmap_request, run_jmap_request
+from .mcp_server import handle_tool_call
+from .session import AgentSession, RegisterResult, create_agent_session, register
+
+__all__ = [
+    "AgentSession",
+    "Credentials",
+    "CredentialStore",
+    "JmapRequestResult",
+    "JmapAttachmentInput",
+    "RegisterResult",
+    "ResolvedAgentConfig",
+    "SkillFiles",
+    "default_files_from_out_dir",
+    "help",
+    "handle_tool_call",
+    "jmap_request",
+    "run_jmap_request",
+    "register",
+    "create_agent_session",
+    "resolve_agent_config_from_env",
+]

langchain_atomicmail-0.3.14/src/atomicmail/auth_http.py

@@ -0,0 +1,177 @@
+"""Auth-service HTTP helpers: challenge -> session -> capability."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Callable, Mapping
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+from .jwt_utils import decode_jwt_payload
+from .pow import solve_pow
+
+
+@dataclass
+class ChallengeResponse:
+    challengeJWT: str
+    challenge: str
+    difficulty: int
+
+
+@dataclass
+class SessionResponse:
+    sessionJWT: str
+    apiKey: str | None = None
+
+
+def fetch_challenge(auth_url: str) -> ChallengeResponse:
+    base = auth_url.rstrip("/")
+    status, text, headers = _http_post(f"{base}/api/v1/challenge")
+    if status < 200 or status >= 300:
+        raise ValueError(
+            f"auth-service /api/v1/challenge returned {status}: {text}"
+        )
+
+    challenge_jwt = _read_bearer_token(
+        headers.get("Authorization"),
+        "Challenge response missing Authorization bearer token.",
+    )
+    payload = decode_jwt_payload(challenge_jwt)
+    challenge = payload.get("jti")
+    difficulty = payload.get("difficulty")
+    if not isinstance(challenge, str) or not isinstance(difficulty, (int, float)):
+        raise ValueError("Challenge JWT payload malformed (missing jti or difficulty).")
+
+    return ChallengeResponse(
+        challengeJWT=challenge_jwt,
+        challenge=challenge,
+        difficulty=int(difficulty),
+    )
+
+
+def exchange_session(
+    auth_url: str,
+    *,
+    challenge_jwt: str,
+    pow_hex: str,
+    nonce: str,
+    api_key: str | None = None,
+    username: str | None = None,
+) -> SessionResponse:
+    base = auth_url.rstrip("/")
+    payload: dict[str, str] = {"powHex": pow_hex, "nonce": nonce}
+    if api_key:
+        payload["apiKey"] = api_key
+    if username:
+        payload["username"] = username
+
+    status, text, headers = _http_post(
+        f"{base}/api/v1/session",
+        headers={"Authorization": f"Bearer {challenge_jwt}"},
+        json_body=payload,
+    )
+    if status < 200 or status >= 300:
+        raise ValueError(f"auth-service /api/v1/session returned {status}: {text}")
+
+    session_jwt = _read_bearer_token(
+        headers.get("Authorization"),
+        "Session response missing Authorization bearer token.",
+    )
+
+    data: dict[str, object] = {}
+    if text.strip():
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError as err:
+            raise ValueError(
+                "auth-service /api/v1/session returned non-JSON body."
+            ) from err
+        if not isinstance(parsed, dict):
+            raise ValueError("auth-service /api/v1/session returned non-JSON body.")
+        data = parsed
+
+    api_key_out = data.get("apiKey")
+    return SessionResponse(
+        sessionJWT=session_jwt,
+        apiKey=api_key_out if isinstance(api_key_out, str) else None,
+    )
+
+
+def fetch_capability(auth_url: str, session_jwt: str) -> str:
+    base = auth_url.rstrip("/")
+    status, text, headers = _http_post(
+        f"{base}/api/v1/capability",
+        headers={"Authorization": f"Bearer {session_jwt}"},
+    )
+    if status < 200 or status >= 300:
+        raise ValueError(f"auth-service /api/v1/capability returned {status}: {text}")
+
+    return _read_bearer_token(
+        headers.get("Authorization"),
+        "Capability response missing Authorization bearer token.",
+    )
+
+
+def perform_pow_and_session(
+    *,
+    auth_url: str,
+    scrypt_salt: str,
+    api_key: str | None = None,
+    username: str | None = None,
+    on_pow_progress: Callable[[int], None] | None = None,
+) -> SessionResponse:
+    challenge = fetch_challenge(auth_url)
+    solved = solve_pow(
+        challenge=challenge.challenge,
+        difficulty=challenge.difficulty,
+        salt=scrypt_salt,
+        on_progress=on_pow_progress,
+    )
+    return exchange_session(
+        auth_url,
+        challenge_jwt=challenge.challengeJWT,
+        pow_hex=solved.powHex,
+        nonce=solved.nonce,
+        api_key=api_key,
+        username=username,
+    )
+
+
+def _read_bearer_token(header_value: str | None, missing_error: str) -> str:
+    if not header_value:
+        raise ValueError(missing_error)
+
+    raw = header_value.strip()
+    prefix = "bearer "
+    if not raw.lower().startswith(prefix):
+        raise ValueError("Authorization header must use Bearer scheme.")
+
+    token = raw[len(prefix) :].strip()
+    if not token:
+        raise ValueError("Authorization header must use Bearer scheme.")
+    return token
+
+
+def _http_post(
+    url: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    json_body: object | None = None,
+) -> tuple[int, str, Mapping[str, str]]:
+    req_headers = dict(headers or {})
+    body_bytes: bytes | None = None
+    if json_body is not None:
+        body_bytes = json.dumps(json_body).encode("utf-8")
+        req_headers.setdefault("Content-Type", "application/json")
+
+    req = Request(url, data=body_bytes, headers=req_headers, method="POST")
+    try:
+        with urlopen(req) as response:
+            return (
+                int(response.getcode()),
+                response.read().decode("utf-8"),
+                response.headers,
+            )
+    except HTTPError as err:
+        return err.code, err.read().decode("utf-8", errors="replace"), err.headers