puffin-local 0.3.0__tar.gz

puffin_local-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Puffin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

puffin_local-0.3.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: puffin-local
+Version: 0.3.0
+Summary: Puffin SDK, CLI and MCP server for AI agent identity and communications
+Home-page: https://www.justpuffin.tech
+Author: Puffin
+License: MIT
+Keywords: puffin,ai agents,email,sms,mcp,cli
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: cryptography<51,>=50
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.12; extra == "mcp"
+Provides-Extra: tunnel
+Requires-Dist: websockets<17,>=15; extra == "tunnel"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# puffin-local
+
+Python SDK, `puffin` command line and local MCP server for [Puffin](https://www.justpuffin.tech), the identity and communications layer for AI agents.
+
+## Install
+
+```bash
+pip install puffin-local
+# With the local MCP server and tunnel worker:
+pip install "puffin-local[mcp,tunnel]"
+```
+
+## Configure
+
+Create an agent and a scoped agent key in the Puffin dashboard, then set:
+
+```bash
+export PUFFIN_API_URL=https://puffin-api.onrender.com
+export PUFFIN_API_KEY=pf_...          # keep this secret
+export PUFFIN_IDENTITY_ID=<agent id>
+```
+
+## Python
+
+```python
+from puffin import Puffin
+
+client = Puffin(api_key, "https://puffin-api.onrender.com")
+agent = client.agent(identity_id)
+print(agent.identity())
+agent.send("someone@example.com", "Hello", "Subject", transport="resend")  # waits for approval
+print(agent.search("invoice"))
+```
+
+## Command line
+
+```bash
+puffin identity
+puffin email search invoice
+puffin email draft --to someone@example.com --subject Hi --body "Draft text"
+puffin contacts list
+puffin events watch
+```
+
+Every outgoing message waits for a workspace administrator's approval.
+
+## MCP
+
+`puffin-mcp` runs a local stdio MCP server with the same tools as the hosted endpoint (`<API URL>/mcp`).

puffin_local-0.3.0/README.md

@@ -0,0 +1,49 @@
+# puffin-local
+
+Python SDK, `puffin` command line and local MCP server for [Puffin](https://www.justpuffin.tech), the identity and communications layer for AI agents.
+
+## Install
+
+```bash
+pip install puffin-local
+# With the local MCP server and tunnel worker:
+pip install "puffin-local[mcp,tunnel]"
+```
+
+## Configure
+
+Create an agent and a scoped agent key in the Puffin dashboard, then set:
+
+```bash
+export PUFFIN_API_URL=https://puffin-api.onrender.com
+export PUFFIN_API_KEY=pf_...          # keep this secret
+export PUFFIN_IDENTITY_ID=<agent id>
+```
+
+## Python
+
+```python
+from puffin import Puffin
+
+client = Puffin(api_key, "https://puffin-api.onrender.com")
+agent = client.agent(identity_id)
+print(agent.identity())
+agent.send("someone@example.com", "Hello", "Subject", transport="resend")  # waits for approval
+print(agent.search("invoice"))
+```
+
+## Command line
+
+```bash
+puffin identity
+puffin email search invoice
+puffin email draft --to someone@example.com --subject Hi --body "Draft text"
+puffin contacts list
+puffin events watch
+```
+
+Every outgoing message waits for a workspace administrator's approval.
+
+## MCP
+
+`puffin-mcp` runs a local stdio MCP server with the same tools as the hosted endpoint (`<API URL>/mcp`).

puffin_local-0.3.0/puffin/__init__.py

@@ -0,0 +1,4 @@
+from .client import Puffin, Agent, PuffinError
+from .crypto import encrypt, decrypt, totp
+
+__all__ = ["Puffin", "Agent", "PuffinError", "encrypt", "decrypt", "totp"]

puffin_local-0.3.0/puffin/cli.py

@@ -0,0 +1,125 @@
+"""`puffin` command line. Tokens come only from the environment; sends ask for confirmation.
+
+Exit codes: 0 success, 1 API error, 2 usage or configuration, 3 cancelled at a prompt, 4 local error.
+"""
+import json
+import os
+import sys
+from .client import Puffin, PuffinError
+from .commands import build_parser, LocalError
+
+
+class Cancelled(Exception):
+    pass
+
+
+def scalar(value):
+    text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False)
+    text = " ".join(text.split())
+    return text if len(text) <= 80 else text[:77] + "..."
+
+
+def render(data):
+    """Human-readable output; pass --json for the exact API response."""
+    if data is None:
+        return "ok"
+    if isinstance(data, dict):
+        return "\n".join(f"{key}: {scalar(value)}" for key, value in data.items()) or "{}"
+    if isinstance(data, list):
+        if not data:
+            return "(none)"
+        return "\n".join("- " + ("  ".join(f"{key}={scalar(value)}" for key, value in item.items() if not isinstance(value, (dict, list))) or scalar(item))
+                         if isinstance(item, dict) else "- " + scalar(item) for item in data)
+    return str(data)
+
+
+class Context:
+    """What handlers may use: a lazily built client, confirmation, output and the tunnel."""
+
+    def __init__(self, args, token):
+        self.args = args
+        self.url = args.url
+        self.token = token
+        self._client = None
+
+    @property
+    def puffin(self):
+        # Looked up at call time so tests can monkeypatch puffin.cli.Puffin.
+        return Puffin
+
+    @property
+    def client(self):
+        if self._client is None:
+            if not self.token:
+                raise LocalError("Set PUFFIN_API_KEY; tokens are never accepted on the command line")
+            self._client = Puffin(self.token, self.url)
+        return self._client
+
+    def agent(self):
+        return self.client.agent(self.args.identity)
+
+    def confirm(self, summary):
+        if self.args.yes:
+            return
+        try:
+            answer = input(f"{summary}? [y/N] ")
+        except EOFError:
+            answer = ""
+        if answer.strip().lower() not in {"y", "yes"}:
+            raise Cancelled()
+
+    def emit(self, data, stream=False):
+        if self.args.json:
+            print(json.dumps(data, ensure_ascii=False, indent=None if stream else 2), flush=True)
+        else:
+            print(render(data), flush=True)
+
+    def tunnel(self, argv):
+        from . import tunnel  # optional websockets dependency; imported only when used
+        return tunnel.main(argv)
+
+    def close(self):
+        if self._client is not None:
+            self._client.close()
+
+
+def main(argv=None):
+    parser = build_parser()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    args, extra = parser.parse_known_args(argv)
+    if args.command == "tunnel":
+        # Everything after the subcommand belongs to puffin-tunnel, including its options.
+        args.args = argv[argv.index("tunnel") + 1:]
+    elif extra:
+        parser.error("unrecognized arguments: " + " ".join(extra))
+    token = os.getenv("PUFFIN_API_KEY")
+    if args.needs_key and not token:
+        parser.error("Set PUFFIN_API_KEY; tokens are never accepted on the command line")
+    if args.needs_identity and not args.identity:
+        parser.error("Set PUFFIN_IDENTITY_ID or --identity")
+    ctx = Context(args, token)
+    try:
+        result = args.handler(ctx, args)
+        if result is not None:
+            ctx.emit(result)
+        return 0
+    except PuffinError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    except Cancelled:
+        print("Cancelled; nothing was sent.", file=sys.stderr)
+        return 3
+    except LocalError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 4
+    except ValueError as exc:  # invalid UUID or base URL
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+    finally:
+        ctx.close()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

puffin_local-0.3.0/puffin/client.py

@@ -0,0 +1,282 @@
+import time
+import uuid
+import re
+from urllib.parse import urlparse
+import requests
+
+class PuffinError(RuntimeError):
+    def __init__(self, status, detail):
+        self.status = status
+        super().__init__(f"Puffin {status}: {detail}")
+
+def check_base_url(base_url):
+    parsed = urlparse(base_url)
+    if parsed.scheme != "https" and not (parsed.scheme == "http" and parsed.hostname in {"localhost", "127.0.0.1", "::1"}):
+        raise ValueError("Use HTTPS except for local loopback servers")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ValueError("Base URL must not contain credentials, query or fragment")
+    return base_url.rstrip("/")
+
+def parse(response):
+    if not 200 <= response.status_code < 300:
+        try:
+            detail = response.json().get("detail", "Request failed")
+        except (ValueError, AttributeError):
+            detail = "Invalid response"
+        raise PuffinError(response.status_code, detail)
+    return response.json() if response.content else None
+
+def anonymous(method, base_url, path, data=None, headers=None):
+    """Unauthenticated call for self-signup. It never attaches an API key."""
+    response = requests.request(method, check_base_url(base_url) + path, json=data, headers=headers, timeout=30, allow_redirects=False)
+    return parse(response)
+
+def uid(value):
+    return str(uuid.UUID(str(value)))
+
+def call_sid(value):
+    """Call IDs are provider call SIDs such as CA followed by 32 hex characters, not UUIDs."""
+    if not re.fullmatch(r"CA[0-9a-fA-F]{32}", str(value)):
+        raise ValueError("Invalid call ID")
+    return str(value)
+
+def handle_path(handle):
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,99}", handle or ""):
+        raise ValueError("Invalid agent handle")
+    return handle
+
+class Puffin:
+    def __init__(self, api_key, base_url="http://127.0.0.1:8000", organization_id=None):
+        self.base_url = check_base_url(base_url)
+        self.session = requests.Session()
+        self.session.headers["Authorization"] = "Bearer " + api_key
+        if organization_id:
+            self.session.headers["X-Puffin-Organization"] = organization_id
+
+    def request(self, method, path, data=None, params=None, headers=None):
+        response = self.session.request(method, self.base_url + path, json=data, params=params, headers=headers, timeout=30, allow_redirects=False)
+        return parse(response)
+
+    def capabilities(self):
+        return self.request("GET", "/v1/capabilities")
+
+    def identities(self):
+        return self.request("GET", "/v1/identities")
+
+    def create_identity(self, handle, name, description=None):
+        return self.request("POST", "/v1/identities", {"handle": handle, "name": name, "description": description})
+
+    def agent(self, identity_id):
+        return Agent(identity_id, client=self)
+
+    def billing(self):
+        return self.request("GET", "/v1/billing")
+
+    def checkout(self, plan):
+        return self.request("POST", "/v1/billing/checkout", {"plan": plan})
+
+    def phone_numbers(self):
+        return self.request("GET", "/v1/phone/numbers")
+
+    def phone_availability(self, country, area_code=None, contains=None):
+        params = {"country": country, **({"area_code": area_code} if area_code else {}), **({"contains": contains} if contains else {})}
+        return self.request("GET", "/v1/phone/availability", params=params)
+
+    @staticmethod
+    def signup(base_url, code, handle, name, contact_email, description=None):
+        """Request an agent identity with an invitation code. Keep the returned status token; it is not an API key."""
+        return anonymous("POST", base_url, "/v1/signup", {"code": code, "handle": handle, "name": name, "description": description, "contact_email": contact_email})
+
+    @staticmethod
+    def signup_verify(base_url, signup_id, status_token, code):
+        return anonymous("POST", base_url, f"/v1/signup/{uid(signup_id)}/verify", {"code": code}, headers={"X-Puffin-Signup-Token": status_token})
+
+    @staticmethod
+    def signup_resend(base_url, signup_id, status_token):
+        return anonymous("POST", base_url, f"/v1/signup/{uid(signup_id)}/resend", {}, headers={"X-Puffin-Signup-Token": status_token})
+
+    @staticmethod
+    def signup_status(base_url, signup_id, status_token):
+        return anonymous("GET", base_url, f"/v1/signup/{uid(signup_id)}/status", headers={"X-Puffin-Signup-Token": status_token})
+
+    @staticmethod
+    def a2a_card(base_url, handle, token=None):
+        """Fetch a peer agent's card. Discoverable cards need no credential; others need the receiver-issued peer token."""
+        return anonymous("GET", base_url, "/a2a/" + handle_path(handle) + "/card", headers={"Authorization": "Bearer " + token} if token else None)
+
+    @staticmethod
+    def a2a_send(base_url, handle, text, token, message_id=None, context_id=None):
+        """Send a text task to a peer (A2A 1.0 over JSON-RPC) using its receiver-issued peer token, never an agent key."""
+        message = {"role": "ROLE_USER", "parts": [{"text": text}], "messageId": message_id or str(uuid.uuid4()), **({"contextId": uid(context_id)} if context_id else {})}
+        envelope = anonymous("POST", base_url, "/a2a/" + handle_path(handle), {"jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": {"message": message, "configuration": {"returnImmediately": True}}},
+                             headers={"Authorization": "Bearer " + token, "A2A-Version": "1.0"})
+        if "error" in envelope:
+            raise PuffinError(422, f"A2A {envelope['error'].get('code')}: {envelope['error'].get('message')}")
+        return envelope.get("result")
+
+    def close(self):
+        self.session.close()
+
+class Agent:
+    def __init__(self, identity_id, api_key=None, base_url="http://127.0.0.1:8000", client=None):
+        self.id = uid(identity_id)
+        self.client = client or Puffin(api_key, base_url)
+        self.path = f"/v1/identities/{self.id}"
+        self.mailbox = Mailbox(self)
+
+    def identity(self):
+        return self.client.request("GET", self.path)
+
+    def send(self, recipient, body, subject="", channel="email", idempotency_key=None, in_reply_to=None, transport="simulated", attachments=None):
+        """Request a send; real email always needs administrator approval."""
+        return self.client.request("POST", self.path + "/messages", {"recipient": recipient, "subject": subject, "body": body, "channel": channel, "in_reply_to": in_reply_to, "transport": transport, "attachments": attachments or []},
+            headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())})
+
+    def messages(self, after=None, limit=100):
+        return self.client.request("GET", self.path + "/messages", params={"limit": limit, **({"after": after} if after else {})})
+
+    def search(self, q, **filters):
+        """Full-text search; filters are channel, direction and limit."""
+        return self.client.request("GET", self.path + "/messages/search", params={"q": q, **{k: v for k, v in filters.items() if v is not None}})
+
+    def threads(self):
+        return self.client.request("GET", self.path + "/threads")
+
+    def thread(self, thread_id):
+        return self.client.request("GET", self.path + "/threads/" + uid(thread_id))
+
+    def import_mail(self, filename, content_base64):
+        """Import an .eml or .mbox export (base64) into this identity's mailbox."""
+        return self.client.request("POST", self.path + "/mail/import", {"filename": filename, "content_base64": content_base64})
+
+    def events(self, consumer="default", after=None):
+        return self.client.request("GET", self.path + "/events", params={"consumer": consumer, **({"after": after} if after is not None else {})})
+
+    def ack(self, cursor, consumer="default"):
+        return self.client.request("POST", self.path + "/events/ack", {"cursor": cursor, "consumer": consumer})
+
+    def watch(self, consumer="default", poll_interval=2, ack=True):
+        """At-least-once delivery: a batch is acknowledged only after every event in it was yielded and handled by the caller."""
+        while True:
+            batch = self.events(consumer)
+            for event in batch["events"]:
+                yield event
+            if ack and batch["events"]:
+                self.ack(batch["next_cursor"], consumer)
+            time.sleep(max(0.1, poll_interval))
+
+    def resources(self, kind=None):
+        return self.client.request("GET", "/v1/resources", params={"kind": kind} if kind else None)
+
+    def create_resource(self, kind, name, data):
+        return self.client.request("POST", "/v1/resources", {"kind": kind, "name": name, "data": data, "identity_ids": [self.id]})
+
+    def endpoint(self):
+        return self.client.request("POST", self.path + "/endpoint")
+
+    def submit_task(self, target_id, text):
+        return self.client.request("POST", self.path + "/tasks", {"target_id": target_id, "input": text})
+
+    def tasks(self):
+        return self.client.request("GET", self.path + "/tasks")
+
+    def update_task(self, task_id, status, result=None):
+        return self.client.request("PATCH", f"/v1/tasks/{uid(task_id)}", {"status": status, "result": result})
+
+    def drafts(self):
+        return self.client.request("GET", self.path + "/drafts")
+
+    def create_draft(self, **fields):
+        return self.client.request("POST", self.path + "/drafts", fields)
+
+    def update_draft(self, draft_id, version, **fields):
+        """Optimistic concurrency: pass the version you last read."""
+        return self.client.request("PATCH", self.path + "/drafts/" + uid(draft_id), {"version": version, **fields})
+
+    def attach_draft(self, draft_id, files):
+        return self.client.request("POST", self.path + "/drafts/" + uid(draft_id) + "/attachments", {"attachments": files})
+
+    def send_draft(self, draft_id, idempotency_key=None):
+        return self.client.request("POST", self.path + "/drafts/" + uid(draft_id) + "/send", {}, headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())})
+
+    def duplicate_draft(self, draft_id):
+        return self.client.request("POST", self.path + "/drafts/" + uid(draft_id) + "/duplicate")
+
+    def revise_draft(self, draft_id, instructions):
+        return self.client.request("POST", self.path + "/drafts/" + uid(draft_id) + "/revise", {"instructions": instructions})
+
+    def contacts(self, q=None):
+        return self.client.request("GET", "/v1/contacts", params={"q": q} if q else None)
+
+    def contact(self, contact_id):
+        return self.client.request("GET", "/v1/contacts/" + uid(contact_id))
+
+    def create_contact(self, **fields):
+        return self.client.request("POST", "/v1/contacts", fields)
+
+    def memories(self, contact_id):
+        return self.client.request("GET", "/v1/contacts/" + uid(contact_id) + "/memories")
+
+    def remember(self, contact_id, kind, content, citations):
+        """Citations are [{"message_id": ..., "quote": ...}] taken from messages this identity can read."""
+        return self.client.request("POST", "/v1/contacts/" + uid(contact_id) + "/memories", {"kind": kind, "content": content, "citations": citations})
+
+    def texts(self, q=None):
+        return self.client.request("GET", self.path + "/texts", params={"q": q} if q else None)
+
+    def calls(self):
+        return self.client.request("GET", self.path + "/calls")
+
+    def transcript(self, call_id):
+        return self.client.request("GET", self.path + "/calls/" + call_sid(call_id) + "/transcript")
+
+    def imessage_evaluate(self, number):
+        return self.client.request("GET", self.path + "/imessage/evaluate", params={"number": number})
+
+    def imessage_send(self, body, recipient=None, group_id=None, recipients=None, attachments=None, send_style=None, idempotency_key=None):
+        """Send to one recipient, an existing group_id, or a new group of recipients."""
+        data = {"body": body, "recipient": recipient, "group_id": group_id, "recipients": recipients, "attachments": attachments, "send_style": send_style}
+        return self.client.request("POST", self.path + "/imessage/messages", {k: v for k, v in data.items() if v is not None},
+            headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())})
+
+    def imessage_groups(self):
+        return self.client.request("GET", self.path + "/imessage/groups")
+
+    def imessage_react(self, message_id, reaction, remove=False):
+        return self.client.request("POST", self.path + "/imessage/messages/" + uid(message_id) + "/reaction", {"reaction": reaction, "remove": remove})
+
+    def imessage_typing(self, recipient):
+        return self.client.request("POST", self.path + "/imessage/typing", {"recipient": recipient})
+
+    def companion(self):
+        return self.client.request("GET", self.path + "/companion")
+
+    def update_companion(self, **fields):
+        return self.client.request("PUT", self.path + "/companion", fields)
+
+class Mailbox:
+    def __init__(self, agent):
+        self.agent = agent
+
+    @property
+    def address(self):
+        mailbox = self.agent.identity().get("mailbox")
+        return mailbox["email_address"] if mailbox else None
+
+    def send(self, recipient, body, subject="", idempotency_key=None, in_reply_to=None, transport="simulated", attachments=None):
+        return self.agent.send(recipient, body, subject, idempotency_key=idempotency_key, in_reply_to=in_reply_to, transport=transport, attachments=attachments)
+
+    def wait_for_otp(self, timeout=60, after=None, sender=None):
+        from datetime import datetime, timezone
+        start = time.monotonic()
+        # By default ignore old OTPs already sitting in the mailbox.
+        after = after or datetime.now(timezone.utc).isoformat()
+        while time.monotonic() - start < timeout:
+            for message in self.agent.messages(after=after):
+                if message["direction"] != "inbound" or (sender and message["sender"].lower() != sender.lower()):
+                    continue
+                match = re.search(r"(?<!\d)(\d{6})(?!\d)", message["subject"] + " " + message["body"])
+                if match:
+                    return match.group(1)
+            time.sleep(1)
+        raise TimeoutError("No matching OTP received")