inbox-to-action 0.2.0__tar.gz

inbox_to_action-0.2.0/.env.example

@@ -0,0 +1,62 @@
+# ── inbox-to-action configuration ──────────────────────────────────────────
+# Copy to `.env` and fill in only the provider you use. Free-first defaults
+# require NO paid keys.
+
+# Which LLM backend the standalone CLI uses.
+#   openrouter | ollama | nim | openai | anthropic | claude | host
+# `claude` = keyless via the local `claude` CLI (Claude Code login) — fastest
+#            no-key option; great for testing. Needs `claude` on PATH.
+# `host`   = no LLM here; reasoning is supplied by Claude Code (MCP / Skill mode).
+PROVIDER=openrouter
+
+# Model id (provider-specific). Defaults shown.
+#   openrouter -> google/gemma-4-31b-it:free  (auto-falls back across free models)
+#   ollama     -> llama3.1                     (e.g. llama3.1:8b)
+#   anthropic  -> claude-opus-4-8              (cheap: claude-haiku-4-5)
+# Note: OpenRouter free models are often "rate-limited upstream" (429); the
+# client retries with backoff and rotates the fallback list automatically.
+# MODEL=
+
+# ── Triage configuration (optional) ─────────────────────────────────────────
+# Rules + freeform instructions live in config.json (see config.example.json),
+# overridable per-run with `--config PATH`. This env var overrides the file's
+# freeform instructions (handy for quick experiments):
+# TRIAGE_INSTRUCTIONS=I'm job hunting — treat relevant job alerts as action_needed.
+# INBOX_TO_ACTION_CONFIG=./config.json
+
+# ── OpenAI-compatible providers ─────────────────────────────────────────────
+# OpenRouter (free models available). https://openrouter.ai/keys
+OPENROUTER_API_KEY=
+
+# NVIDIA NIM. https://build.nvidia.com  (NVIDIA_API_KEY also accepted)
+# Default model: meta/llama-3.3-70b-instruct (override with MODEL=…).
+NIM_API_KEY=
+
+# OpenAI (paid BYOK fallback).
+OPENAI_API_KEY=
+
+# Ollama needs no key; just run `ollama serve` locally.
+# OLLAMA_BASE_URL=http://localhost:11434/v1
+
+# ── Anthropic ───────────────────────────────────────────────────────────────
+# Optional. If unset, the client uses your `ant auth login` OAuth profile
+# (fully keyless). Set only to force a specific key.
+# ANTHROPIC_API_KEY=
+
+# ── Tasks ───────────────────────────────────────────────────────────────────
+# Optional Todoist integration (--todoist flag). Free tier.
+# https://todoist.com/app/settings/integrations/developer
+TODOIST_API_TOKEN=
+
+# ── Telegram summary (--telegram flag) ──────────────────────────────────────
+# Push a concise run summary to your phone. Create a bot with @BotFather → token;
+# message the bot once, then GET https://api.telegram.org/bot<token>/getUpdates
+# to read your chat id. Off by default. Notification only — never sends email.
+# TELEGRAM_TOKEN is also accepted as an alias for TELEGRAM_BOT_TOKEN.
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=
+
+# ── Gmail ───────────────────────────────────────────────────────────────────
+# Path to OAuth client secrets downloaded from Google Cloud Console.
+# Only readonly + compose scopes are requested. Drafts only — never sends.
+GMAIL_CLIENT_SECRETS=client_secret.json

inbox_to_action-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug report
+about: Something went wrong
+title: "[bug] "
+labels: bug
+---
+
+**Command run**
+```
+inbox-to-action run ...
+```
+
+**What happened** (paste the error output — mask any secrets)
+
+**Expected**
+
+**Environment**
+- `PROVIDER`:
+- inbox-to-action version (`pip show inbox-to-action`):
+- Python + OS:

inbox_to_action-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,14 @@
+---
+name: Feature request
+about: Suggest an improvement
+title: "[feat] "
+labels: enhancement
+---
+
+**What you want**
+
+**Why it helps**
+
+**Notes** (provider/mailbox/config involved, if any)
+
+> Reminder: the tool never sends email — proposals must keep the drafts-only invariant.

inbox_to_action-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev,mcp]'
+
+      - name: Run tests
+        run: pytest --cov=. --cov-report=term-missing
+
+  # Publish to PyPI on a version tag (e.g. v0.2.0), after tests pass.
+  # Uses OIDC Trusted Publishing — no API token stored. One-time setup:
+  # configure the PyPI project's Trusted Publisher (repo tarunlnmiit/inbox-to-action,
+  # workflow ci.yml). See SETUP.md.
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install hatch
+      - run: hatch build
+      - uses: pypa/gh-action-pypi-publish@release/v1

inbox_to_action-0.2.0/.gitignore

@@ -0,0 +1,36 @@
+# Secrets & tokens
+.env
+client_secret*.json
+token.json
+*.token
+
+# Generated output
+triage-report.md
+tasks.md
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+build/
+dist/
+
+# Personal triage config (ship config.example.json instead)
+config.json
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Internal planning/spec docs — never shared to the public repo
+*-spec.md
+*-plan*.md
+plans/
+inbox-to-action-claude-code-spec.md

inbox_to_action-0.2.0/.serena/.gitignore

@@ -0,0 +1,2 @@
+/cache
+/project.local.yml

inbox_to_action-0.2.0/.serena/project.local.yml

@@ -0,0 +1,5 @@
+# This file allows you to locally override settings in project.yml for development purposes.
+#
+# Use the same keys as in project.yml here. Any setting you specify will override the corresponding
+# setting in project.yml, allowing you to customise the configuration for your local development environment
+# without affecting the project configuration in project.yml (which is intended to be versioned).

inbox_to_action-0.2.0/.serena/project.yml

@@ -0,0 +1,133 @@
+# the name by which the project can be referenced within Serena
+project_name: "inbox-to-action"
+
+
+# list of languages for which language servers are started; choose from:
+#   al                  angular             ansible             bash                clojure
+#   cpp                 cpp_ccls            crystal             csharp              csharp_omnisharp
+#   dart                elixir              elm                 erlang              fortran
+#   fsharp              go                  groovy              haskell             haxe
+#   hlsl                html                java                json                julia
+#   kotlin              lean4               lua                 luau                markdown
+#   matlab              msl                 nix                 ocaml               pascal
+#   perl                php                 php_phpactor        powershell          python
+#   python_jedi         python_ty           r                   rego                ruby
+#   ruby_solargraph     rust                scala               scss                solidity
+#   svelte              swift               systemverilog       terraform           toml
+#   typescript          typescript_vts      vue                 yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
+#   - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
+#   - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- python
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# The settings are considered only if the project is trusted (see global configuration to define trusted projects).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#language-server-specific-settings
+ls_specific_settings: {}
+
+# list of additional workspace folder paths for cross-package reference support (e.g. in monorepos).
+# Paths can be absolute or relative to the project root.
+# Each folder is registered as an LSP workspace folder, enabling language servers to discover
+# symbols and references across package boundaries.
+# Currently supported for: TypeScript.
+# Example:
+#   additional_workspace_folders:
+#     - ../sibling-package
+#     - ../shared-lib
+additional_workspace_folders: []
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+fixed_tools: []
+
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+default_modes:
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []

inbox_to_action-0.2.0/CLAUDE.md

@@ -0,0 +1,60 @@
+# CLAUDE.md — project context for Claude Code
+
+One-pass agentic inbox triage: fetch unread mail → classify → summarize → extract
+tasks → draft replies (**never sends**) → flag calendar → write `triage-report.md`.
+
+## Commands
+
+```bash
+inbox-to-action run --since 24h [--no-drafts] [--max N] [--telegram] [--todoist] [--config PATH] [--mock]
+inbox-to-action auth [--account <id>] [--config PATH] [--client-secrets PATH]
+inbox-to-action mcp                      # stdio MCP server (also: python -m inbox_to_action.mcp_server)
+pytest --cov=.                           # tests (LLM + Gmail mocked)
+ruff check inbox_to_action/
+```
+
+## Security invariant (do not break)
+
+Gmail scopes = `gmail.readonly` + `gmail.compose` ONLY. Outlook = `Mail.Read` +
+`Mail.ReadWrite` ONLY. No send scope, no send call anywhere. Drafts only. Enforced by
+`tests/test_gmail.py`. `--mock` never writes to real Gmail.
+
+## Package layout
+
+```
+inbox_to_action/
+  main.py          Typer CLI (run/auth/mcp)
+  agent.py         per-email trajectory (classify→summarize→tasks→draft→calendar)
+  llm_client.py    providers: claude, ollama, openrouter, nim, openai, anthropic, host
+  reasoner.py      ProviderReasoner vs HostReasoner injection seam
+  config.py        Settings: triage_instructions, rules[], accounts[]
+  models.py        Email, Task, TriageResult, CATEGORIES
+  report.py        triage-report.md renderer
+  mcp_server.py    FastMCP: fetch_emails, save_gmail_draft, append_tasks, write_report
+  mailboxes/       MailAccount protocol; gmail.py (works), outlook.py (stub)
+  tools/           classifier, summarizer, tasks (+ Todoist), gmail (+ is_noreply),
+                   calendar_flag, notify (Telegram)
+  fixtures/        sample_inbox.json (--mock)
+```
+
+## Config & env
+
+- `config.json` (gitignored; example: `config.example.json`): `triage_instructions`,
+  `rules[]` (field: sender|subject|body|any → category), `accounts[]`
+  (id, kind: gmail|outlook, label, client_secret?, client_id?, tenant?).
+- `.env` (gitignored; example: `.env.example`): `PROVIDER`, `MODEL`, provider keys
+  (`OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `NIM_API_KEY`/`NVIDIA_API_KEY`,
+  `ANTHROPIC_API_KEY`, `OLLAMA_BASE_URL`), `TRIAGE_INSTRUCTIONS`,
+  `INBOX_TO_ACTION_CONFIG`, `TODOIST_API_TOKEN`, `TELEGRAM_BOT_TOKEN`/`TELEGRAM_TOKEN`
+  + `TELEGRAM_CHAT_ID`, `GMAIL_CLIENT_SECRETS`, `INBOX_TO_ACTION_TOKEN`,
+  `INBOX_TO_ACTION_HTTP_TIMEOUT`.
+
+## Categories
+
+`action_needed` (→ tasks + draft + calendar) · `fyi` · `newsletter` · `noise`.
+
+## Conventions
+
+Every change via the git loop: branch → PR to `main` → squash-merge → delete branch.
+Conventional commits. Small modules, type hints, tests for new behavior (mock the LLM
+with `FakeReasoner`, network with `respx`).

inbox_to_action-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thanks for helping improve `inbox-to-action`.
+
+## The one hard rule
+
+**The tool must never send email.** It requests only `gmail.readonly` +
+`gmail.compose` (drafts) and, for Outlook, `Mail.Read` + `Mail.ReadWrite`. No PR may
+add a send scope or a send call (`messages().send`, `sendMail`, etc.). This is
+enforced by tests — keep them passing.
+
+## Dev setup
+
+```bash
+git clone https://github.com/tarunlnmiit/inbox-to-action && cd inbox-to-action
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev,mcp]'
+```
+
+## Before opening a PR
+
+```bash
+ruff check inbox_to_action/          # lint
+pytest --cov=. --cov-report=term-missing   # all tests pass, coverage stays high
+```
+
+- One focused change per PR.
+- Add tests for new behavior (see `tests/`). Provider/network code is mocked with
+  `respx`; the LLM is mocked with `FakeReasoner` (see `conftest.py`).
+- Don't commit secrets — `.env` and `config.json` are gitignored. Ship
+  `.env.example` / `config.example.json` changes instead.
+- Match the existing style: small focused modules, type hints, no mutation of shared
+  state.
+
+## High-value contributions
+
+- New mailbox providers (finish Outlook / Microsoft Graph — read + draft only).
+- New LLM providers in `llm_client.py` (OpenAI-compatible ones are easy).
+- Better classification/extraction prompts.
+- New outbound notifiers (mirror `tools/notify.py`).
+
+## Reporting bugs
+
+Open an issue with: the exact command, the error output, your `PROVIDER`, and
+Python + OS versions.

inbox_to_action-0.2.0/Dockerfile

@@ -0,0 +1,27 @@
+# Dockerfile for Glama MCP listing + general container use.
+# Builds the inbox-to-action MCP server (stdio transport).
+FROM python:3.11-slim
+
+LABEL org.opencontainers.image.source="https://github.com/tarunlnmiit/inbox-to-action" \
+      org.opencontainers.image.description="One-pass agentic inbox triage — MCP server" \
+      org.opencontainers.image.licenses="MIT"
+
+WORKDIR /app
+
+# Install build deps first for layer caching.
+COPY pyproject.toml README.md ./
+COPY inbox_to_action ./inbox_to_action
+
+# Example config read from the working dir at runtime (real config.json is mounted).
+COPY config.example.json ./
+
+# Install the package with the MCP extra.
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir ".[mcp]"
+
+# The MCP server exposes IO-only tools; Claude Code (the host) is the LLM, so
+# no provider key is required. Gmail credentials, if used, are mounted/supplied
+# at runtime. The server starts and answers introspection without any secrets.
+
+# FastMCP serves over stdio.
+CMD ["python", "-m", "inbox_to_action.mcp_server"]

inbox_to_action-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tarun Gupta
+
+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.