docs: add CONTRIBUTING.md

00_STATE.md

@@ -0,0 +1,103 @@
+# 00_STATE.md — AgentMail Toolkit Analysis
+
+## Repository Overview
+
+- **Fork**: `okwn/agentmail-toolkit` (forked from `agentmail-to/agentmail-toolkit`)
+- **Upstream**: `agentmail-to/agentmail-toolkit` — 71 stars, 22 forks, TypeScript, NOT archived
+- **License**: No license set (null) — **⚠️ CONCERN**
+- **Default branch**: main
+
+## Repository Structure
+
+```
+agentmail-toolkit/
+├── README.md                    # Root README (minimal, links to python/ node/)
+├── python/                      # Python package (v0.2.7)
+│   ├── pyproject.toml          # Hatch build, Python >=3.11
+│   ├── README.md
+│   ├── examples/
+│   │   ├── openai_.py
+│   │   ├── langchain_.py
+│   │   └── pyproject.toml
+│   └── src/agentmail_toolkit/
+│       ├── __init__.py         # Generic AgentMailToolkit base
+│       ├── toolkit.py          # Abstract Toolkit[T] base class
+│       ├── tools.py            # 11 Tool definitions (list_inboxes, get_inbox, etc.)
+│       ├── schemas.py          # Pydantic param schemas
+│       ├── functions.py        # Tool implementation functions
+│       ├── openai.py           # OpenAI Agents SDK adapter
+│       ├── langchain.py         # LangChain adapter
+│       ├── livekit.py          # LiveKit Agents adapter
+│       ├── util.py             # safe_func helper
+│       └── py.typed
+└── node/                        # Node.js package (v0.3.1)
+    ├── package.json            # pnpm, MIT license
+    ├── tsconfig.json
+    ├── pnpm-workspace.yaml
+    ├── pnpm-lock.yaml
+    ├── examples/
+    │   └── package.json
+    └── src/
+        ├── index.ts            # Default export (generic)
+        ├── tools.ts            # 18 Tool definitions (11 basic + 7 draft tools)
+        ├── toolkit.ts          # BaseToolkit, ListToolkit, MapToolkit
+        ├── schemas.ts          # Zod schemas
+        ├── functions.ts        # Tool implementations
+        ├── ai-sdk.ts          # Vercel AI SDK adapter
+        ├── mcp.ts             # Model Context Protocol adapter
+        ├── langchain.ts       # LangChain adapter
+        ├── clawdbot.ts        # Clawdbot adapter
+        └── util.ts            # safeFunc, file extraction helpers
+```
+
+## Key Findings
+
+### 1. Node package is more complete than Python
+- **Node**: 18 tools (11 basic + 7 draft tools: create/list/get/update/send/delete_draft)
+- **Python**: 11 tools (missing all draft tools)
+- **Version mismatch**: Node is 0.3.1, Python is 0.2.7
+
+### 2. No CI/CD workflows found
+- No `.github/workflows/` directory
+- No GitHub Actions configured
+- No test suite found
+
+### 3. License issue
+- Repository has `license: null` — **no open source license set**
+- This is a legal concern for contributing
+
+### 4. Open Issues (6)
+| # | Title |
+|---|-------|
+| 24 | chore: add repo description, homepage URL, and topics for GitHub discoverability |
+| 23 | docs: enhance README with framework matrix, comparison table, and quick start examples |
+| 18 | Improve root README — add framework table, quick start, badges |
+| 16 | Console landing page too heavy — particle effects cause lag |
+| 12 | x402 ecosystem partner: Fía Signals crypto intelligence API |
+| 11 | x402 ecosystem partner: Fía Signals crypto intelligence |
+
+### 5. Open Pull Requests (2)
+| # | Title | State |
+|---|-------|-------|
+| 23 | docs: enhance README with framework matrix... | open |
+| 18 | Improve root README — add framework table, quick start, badges | open |
+
+### 6. Upstream branches (9)
+- `main` (6dbb78b — v0.3.1)
+- `addDraftTools` — draft tools feature branch
+- `deletionFix` — MCP undefined result fix
+- `harry/fix-langchain-dts` — merged (fix-langchain-dts)
+- `improve-readme*` (4 variants) — all stale/closed
+- `mcp` — MCP protocol branch
+- `jarvis/improve-readme` — stale
+
+### 7. Quality Issues
+- Python: `get_attachment` in `functions.py` uses incorrect client method: `client.threads.get_attachment()` but should be `client.inboxes.threads.get_attachment()`
+- Both packages have error handling via `safe_func` patterns
+- No test coverage
+- README is very sparse
+
+### 8. Dependencies
+**Python**: agentmail>=0.4.10, openai-agents>=0.6.1, langchain>=1.1.0, livekit-agents>=1.3.5, pydantic>=2.12.5, pymupdf, python-docx, filetype
+
+**Node**: agentmail@^0.4.10, jszip@^3.10.1, unpdf@^1.4.0, zod@^4.1.13 (peerDeps: @modelcontextprotocol/sdk, ai, langchain, clawdbot)

01_REPO_MAP.md

@@ -0,0 +1,145 @@
+# 01_REPO_MAP.md — AgentMail Toolkit Repository Map
+
+## File Structure
+
+### Root
+| File | Purpose |
+|------|---------|
+| `README.md` | Minimal root README linking to `python/` and `node/` |
+| `.gitignore` | Ignores `node_modules`, `dist`, `build`, `*.egg-info`, `__pycache__` |
+
+### Python (`python/`)
+| File | Purpose |
+|------|---------|
+| `pyproject.toml` | Package config: v0.2.7, Python >=3.11, hatch build |
+| `README.md` | Python-specific README with pip install + usage example |
+| `uv.lock` | Lock file for uv |
+| `.gitignore` | Standard Python gitignore |
+| `examples/pyproject.toml` | Examples workspace |
+| `examples/openai_.py` | OpenAI agent example |
+| `examples/langchain_.py` | LangChain agent example |
+| `src/agentmail_toolkit/__init__.py` | Exports `AgentMailToolkit`, `Tool` |
+| `src/agentmail_toolkit/toolkit.py` | Abstract `Toolkit[T]` base class |
+| `src/agentmail_toolkit/tools.py` | 11 `Tool` definitions + `tools` list |
+| `src/agentmail_toolkit/schemas.py` | Pydantic parameter schemas |
+| `src/agentmail_toolkit/functions.py` | Tool implementation functions |
+| `src/agentmail_toolkit/openai.py` | OpenAI Agents SDK adapter |
+| `src/agentmail_toolkit/langchain.py` | LangChain adapter |
+| `src/agentmail_toolkit/livekit.py` | LiveKit Agents adapter |
+| `src/agentmail_toolkit/util.py` | `safe_func`, `ToolError` |
+| `src/agentmail_toolkit/py.typed` | PEP 561 typed marker |
+
+### Node (`node/`)
+| File | Purpose |
+|------|---------|
+| `package.json` | Package: v0.3.1, MIT license, pnpm |
+| `tsconfig.json` | TypeScript config |
+| `pnpm-workspace.yaml` | Workspace config |
+| `pnpm-lock.yaml` | Lock file |
+| `examples/package.json` | Examples workspace |
+| `src/index.ts` | Default `AgentMailToolkit` (generic) |
+| `src/tools.ts` | 18 `Tool` definitions (includes 7 drafts) |
+| `src/toolkit.ts` | `BaseToolkit`, `ListToolkit`, `MapToolkit` |
+| `src/schemas.ts` | Zod schemas for all params |
+| `src/functions.ts` | Tool implementations + draft functions |
+| `src/ai-sdk.ts` | Vercel AI SDK adapter (`MapToolkit`) |
+| `src/mcp.ts` | MCP (Model Context Protocol) adapter |
+| `src/langchain.ts` | LangChain adapter |
+| `src/clawdbot.ts` | Clawdbot adapter |
+| `src/util.ts` | `safeFunc`, `detectFileType`, PDF/DOCX extraction |
+
+## Tool Map
+
+### Python Tools (11)
+```
+list_inboxes       → list_inboxes()
+get_inbox          → get_inbox()
+create_inbox       → create_inbox()
+delete_inbox       → delete_inbox()
+list_threads       → list_threads()
+get_thread         → get_thread()
+get_attachment     → get_attachment()  ⚠️ BUG: wrong client path
+send_message       → send_message()
+reply_to_message   → reply_to_message()
+forward_message    → forward_message()
+update_message     → update_message()
+```
+
+### Node Tools (18) — superset of Python
+All Python tools PLUS:
+```
+create_draft       → createDraft()
+list_drafts        → listDrafts()
+get_draft          → getDraft()
+update_draft       → updateDraft()
+send_draft         → sendDraft()
+delete_draft       → deleteDraft()
+```
+
+## Framework Adapters
+
+### Python
+| Framework | File |
+|-----------|------|
+| Generic | `__init__.py` |
+| OpenAI Agents SDK | `openai.py` |
+| LangChain | `langchain.py` |
+| LiveKit | `livekit.py` |
+
+### Node
+| Framework | File | Toolkit Type |
+|-----------|------|--------------|
+| Generic | `index.ts` | `ListToolkit` |
+| Vercel AI SDK | `ai-sdk.ts` | `MapToolkit` |
+| MCP (Model Context Protocol) | `mcp.ts` | `ListToolkit` |
+| LangChain | `langchain.ts` | ? |
+| Clawdbot | `clawdbot.ts` | ? |
+
+## Schema Comparison
+
+| Operation | Python (Pydantic) | Node (Zod) |
+|-----------|-------------------|------------|
+| `inboxId` | `Annotated[str, Field]` | `z.string().describe()` |
+| `limit` | `int, default=10` | `z.number().optional().default(10)` |
+| `before/after` | `datetime` objects | `z.string().pipe(z.coerce.date())` |
+| `attachments` | `List[Attachment]` | `z.array(AttachmentSchema)` |
+| `replyAll` | `bool` | `replyAll: z.boolean()` |
+
+## Key Code Patterns
+
+### Python: Tool definition
+```python
+Tool(name="list_inboxes", description="List inboxes", params_schema=ListItemsParams, func=list_inboxes)
+```
+
+### Python: Toolkit base
+```python
+class Toolkit(Generic[T], ABC):
+    _tools: Dict[str, T] = None
+    def __init__(self, client: Optional[AgentMail] = None):
+        self.client = client or AgentMail()
+        self._tools = {tool.name: self._build_tool(tool) for tool in tools}
+    @abstractmethod
+    def _build_tool(self, tool: Tool) -> T: pass
+```
+
+### Node: Tool definition
+```typescript
+{name: 'list_inboxes', description: 'List inboxes', paramsSchema: ListItemsParams, func: listInboxes, annotations: {readOnlyHint: true, openWorldHint: false}}
+```
+
+### Node: Toolkit types
+```typescript
+// ListToolkit<T> — getTools() returns T[]
+// MapToolkit<T> — getTools() returns Record<string, T>
+```
+
+## Defects Identified
+
+1. **Python `get_attachment()` bug**: Uses `client.threads.get_attachment()` but should be `client.inboxes.threads.get_attachment()`
+2. **Python missing draft tools**: Node has 7 draft tools; Python has none
+3. **Version skew**: Node v0.3.1 vs Python v0.2.7
+4. **No license**: `license: null` in repo metadata
+5. **Sparse README**: Root README is very minimal
+6. **No tests**: No test files found
+7. **No CI**: No GitHub Actions workflows

05_PR_CANDIDATES.md

@@ -0,0 +1,67 @@
+# 05_PR_CANDIDATES.md — AgentMail Toolkit PR Candidates
+
+## Open Issues (6) — Potential PR Topics
+
+| # | Title | Labels | Priority | Effort |
+|---|-------|--------|----------|--------|
+| 24 | chore: add repo description, homepage URL, and topics for GitHub discoverability | chore | medium | low |
+| 23 | docs: enhance README with framework matrix, comparison table, and quick start examples | docs | high | medium |
+| 18 | Improve root README — add framework table, quick start, badges | docs | medium | low |
+| 16 | Console landing page too heavy — particle effects cause lag and hurt trust | bug? | low | unknown |
+| 12 | x402 ecosystem partner: Fía Signals crypto intelligence API (42 endpoints, pay-per-call) | partner | low | unknown |
+| 11 | x402 ecosystem partner: Fía Signals crypto intelligence (42 pay-per-call endpoints, USDC on Solana) | partner | low | unknown |
+
+## Open Pull Requests (2)
+
+| # | Title | Status | Reviewable |
+|---|-------|--------|------------|
+| 23 | docs: enhance README with framework matrix, comparison table, and quick start examples | open | yes |
+| 18 | Improve root README — add framework table, quick start, badges | open | yes |
+
+## Code Defects Found (From Code Review)
+
+### Bug: Python `get_attachment()` uses wrong client path
+**File**: `python/src/agentmail_toolkit/functions.py`, line 39
+**Issue**: Uses `client.threads.get_attachment()` but AgentMail SDK requires `client.inboxes.threads.get_attachment()`
+```python
+# CURRENT (buggy):
+attachment = client.threads.get_attachment(
+    thread_id=kwargs["thread_id"], attachment_id=kwargs["attachment_id"]
+)
+# SHOULD BE:
+attachment = client.inboxes.threads.get_attachment(
+    thread_id=kwargs["thread_id"], attachment_id=kwargs["attachment_id"]
+)
+```
+**Severity**: High — tool will crash when called
+
+### Missing Feature: Python lacks draft tools
+**Status**: Node has 7 draft tools (create/list/get/update/send/delete_draft + schedule support), Python has 0
+**Impact**: Feature parity gap between Node and Python SDKs
+**Effort**: Medium — requires adding 7 new tools and updating schemas
+
+## Improvement Opportunities
+
+### 1. Version parity
+- Node: v0.3.1, Python: v0.2.7
+- Recommend aligning Python to 0.3.x with matching toolset
+
+### 2. Test coverage
+- No test files found in repository
+- Could add `pytest` tests and GitHub Actions CI
+
+### 3. CI/CD missing
+- No `.github/workflows/` directory
+- Could add: lint, typecheck, test, build, publish workflows
+
+### 4. License clarification
+- `license: null` — no open source license
+- Should add MIT or Apache 2.0
+
+## Prioritized Candidates for PRs
+
+1. **Fix Python `get_attachment()` bug** — high impact, low effort, clear fix
+2. **Add draft tools to Python** — feature parity with Node, medium effort
+3. **Improve root README** — addresses issues #18, #23, #24
+4. **Add GitHub Actions CI** — quality of life, enables safe contributions
+5. **Align package versions** — v0.3.x for both python and node