Metadata-Version: 2.4
Name: Methoryn
Version: 0.1.44
Summary: Methoryn — Multi-Agent CLI powered by Groq, Cloudflare, Gemini, Mistral, and NVIDIA
Author: Methoryn Team
Author-email: Anvyl.cli@gmail.com
License: MIT
Project-URL: Homepage, https://methoryn.github.io
Project-URL: Documentation, https://methoryn.github.io/docs.html
Project-URL: Repository, https://github.com/anaydesai/Methoryn
Project-URL: Download, https://pypi.org/project/Methoryn/#files
Project-URL: Bug Tracker, https://github.com/anaydesai/Methoryn/issues
Keywords: ai,cli,assistant,terminal,groq,gemini,agent,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development
Classifier: Topic :: Communications
Classifier: Topic :: Internet
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: groq==1.5.0
Requires-Dist: openai==2.48.0
Requires-Dist: google-genai==2.14.0
Requires-Dist: google-auth==2.56.0
Requires-Dist: google-auth-oauthlib==1.4.0
Requires-Dist: google-api-python-client==2.198.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: textual==1.0.0
Requires-Dist: rich==15.0.0
Requires-Dist: pyperclip==1.9.0
Requires-Dist: python-docx==1.1.2
Requires-Dist: fpdf2==2.8.3
Dynamic: license-file

# Methoryn

**A multi-agent AI assistant that runs on your desktop.**

Methoryn is a terminal app (TUI) powered by [Groq](https://console.groq.com/) and [Gemini](https://aistudio.google.com/). Groq handles your primary tasks with tool execution and streaming output. Gemini handles parallel sub-tasks in the background. The interface is built with [Textual](https://textual.textualize.io/).

![Python](https://img.shields.io/badge/python-3.13%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

---

## Features

- **Multi-agent execution** — Groq runs your task while Gemini sub-agents handle parallel work
- **Tool use** — reads/writes files, runs shell commands, searches the web
- **Google Workspace** — Gmail, Drive, Docs, Sheets, Slides, Forms, Calendar (optional OAuth sign-in)
- **Bring Your Own Key (BYOK)** — set API keys inside the app with `/keys set`, no `.env` editing required
- **Session memory** — conversation context carries over between sessions automatically
- **File export** — save output as `.txt`, `.md`, `.html`, `.csv`, `.docx`, or `.pdf`
- **Slash commands** — `/help`, `/gmail`, `/drive`, `/save`, `/copy`, `/sign-in`, and more

---

## Requirements

- Python 3.13+
- A [Groq API key](https://console.groq.com/) — **required** (free tier available)
- A [Google AI Studio API key](https://aistudio.google.com/app/apikey) — optional, enables Gemini sub-agents
- A Google Cloud OAuth2 `credentials.json` — optional, enables Gmail / Drive / Docs / Calendar

---

## Installation

**Requirements:** Python 3.13+ is required. Older versions will not work.

### Quick Install (Recommended)

For the most reliable installation experience, use `uv`:

```bash
# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Methoryn with Python 3.13 in an isolated environment
uv tool install methoryn --python 3.13

# Launch (note the capital M)
Methoryn
```

### Traditional Install

If you already have Python 3.13+:

```bash
pip install Methoryn
Methoryn
```

### Installation Troubleshooting

**Command not found: `methoryn`**
- The command is `Methoryn` (capital M), not `methoryn`
- Both `Methoryn` and `methoryn` work as of v0.1.39+

**"No matching distribution found"**
- You need Python 3.13+. Check with `python --version`
- On macOS: System Python is too old. Install via Homebrew: `brew install python@3.13`
- On older Ubuntu: Add deadsnakes PPA: `sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.13`

**"Methoryn --help" hangs**
- This is normal behavior in versions before 0.1.40
- Methoryn launches a TUI immediately, not a traditional CLI
- Use `uv tool list` or `pip list | grep -i methoryn` to verify installation

**macOS: "Developer cannot be verified"**
- Go to System Settings → Privacy & Security → Allow Anyway (one-time)

**Multiple Python versions on Windows**
- Use Python Launcher: `py -3.13 -m pip install Methoryn`
- Then run with: `py -3.13 -m Methoryn`

### Getting Started

1. **Get API keys** (at minimum, Groq is required):
   - [Groq](https://console.groq.com/) — free tier: 12K tokens/minute
   - [Google AI Studio](https://aistudio.google.com/app/apikey) — optional: enables Gemini sub-agents

2. **Launch and configure**:
   ```bash
   Methoryn
   ```
   On first run, you'll see a setup screen. Add your Groq API key and optionally sign in with Google.

3. **Try your first prompt**:
   ```bash
   Methoryn "write a Python script that lists files by size"
   ```

---

## API Keys

Methoryn supports five providers, one per agent layer. Only Groq is strictly required for basic operation, but the full multi-layer architecture needs the others.

| Key | Provider | Layer | Used for |
|-----|----------|-------|----------|
| `GROQ_API_KEY` | [Groq](https://console.groq.com/) | 1 | **Conversation & orchestration** (required) |
| `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` | [Cloudflare](https://developers.cloudflare.com/) | 2 | **Library management** (task-plan execution) |
| `GOOGLE_API_KEY` | [Google AI Studio](https://aistudio.google.com/app/apikey) | 3 | **Multimodal & research** (Gemini) |
| `MISTRAL_API_KEY` | [Mistral](https://console.mistral.ai/) | 4 | **Coding agent** |
| `NVDA_API_KEY` | [NVIDIA NIM](https://build.nvidia.com/) | 5 | **Quality control & review** |

`GOOGLE_ACCOUNT_EMAIL` is also read from `.env` to enable Google Workspace OAuth (Gmail/Drive/Docs/Sheets/Calendar).

You can set any key inside the app without touching `.env`:

```
/keys set GROQ_API_KEY your_key_here
/keys list
/keys remove GROQ_API_KEY
```

Keys set this way are stored in `~/.Methoryn/byok.json` on your local machine and override `.env` values.

---

## Slash Commands

Type `/` in the prompt bar to open the command palette.

| Command | What it does | Uses AI? |
|---------|-------------|----------|
| `/help` | Show what Methoryn can do | No |
| `/keys` | Manage API keys (set / remove / list) | No |
| `/sign-in` | Connect your Google account | No |
| `/sign-out` | Disconnect Google | No |
| `/drive` | List Google Drive files | No |
| `/gmail` | Show recent Gmail inbox | No |
| `/copy` | Copy all output to clipboard | No |
| `/save` | Save session to disk | No |
| `/docs` | Start a Google Doc prompt | Yes |
| `/sheets` | Start a Google Sheet prompt | Yes |
| `/slides` | Start a Slides presentation prompt | Yes |
| `/forms` | Start a Google Form prompt | Yes |
| `/calendar` | Add a Calendar event | Yes |
| `/image` | Generate an image | Yes |
| `/python` | Write a Python script | Yes |
| `/run` | Run a shell command | Yes |
| `/write` | Write a file | Yes |
| `/md` `/txt` `/html` `/csv` `/word` `/pdf` | Export output in that format | Yes |

---

## Keybindings

| Key | Action |
|-----|--------|
| `Enter` | Send prompt |
| `Tab` | Accept slash command suggestion |
| `Ctrl+S` | Save session |
| `Ctrl+Y` | Copy all output to clipboard |
| `Ctrl+C` | Quit |

---

## Project Structure

```
Methoryn/
├── Methoryn/
│   ├── app.py               — Textual UI (layout, input, slash commands)
│   ├── cli.py               — `Methoryn` command entry point
│   ├── groq_agent.py        — Layer 1: Conversation & Orchestration (Groq)
│   ├── cloudflare_agent.py  — Layer 2: Library Manager (Cloudflare)
│   ├── gemini_agent.py      — Layer 3: Multimodal & Research (Gemini)
│   ├── mistral_agent.py     — Layer 4: Coding Agent (Mistral)
│   ├── nvidia_agent.py      — Layer 5: Quality Control (NVIDIA)
│   ├── inter_agent_protocol.py — Agent-to-agent protocol + TaskPlan
│   ├── task_plan.py         — TaskPlan parsing / delegation helpers
│   ├── state.py             — Shared app state (single source of truth)
│   ├── config.py            — API key loading (.env + BYOK)
│   ├── byok.py              — Bring Your Own Key persistence (~/.Methoryn/byok.json)
│   ├── output.py            — Session save/load (sessions/ folder)
│   ├── file_output.py       — Local file export (.txt .md .html .csv .docx .pdf)
│   ├── google_auth.py       — Google OAuth2 flow (token cached at ~/.Methoryn/)
│   ├── intro.py             — Splash animation
│   ├── setup_screen.py      — First-run API key setup
│   ├── taskbar.py           — Taskbar progress indicator
│   └── widgets.py           — MainBox, SideBar, SlashPalette, PromptEditor
├── tests/                  — Pytest test suite
├── .env.example            — Key names with blank values (safe to commit)
├── pyproject.toml          — Package metadata and dependencies
└── requirements.txt        — Flat dependency list
```

---

## Running Tests

```
pip install pytest
pytest
```

Requires `GROQ_API_KEY` to be set.

---

## Notes

- Sessions are auto-saved on quit and auto-loaded on next launch so context carries over
- `GOOGLE_API_KEY` is optional — if absent, Gemini sub-agents are disabled and a warning appears at startup; all other features work normally
- `sessions/` and `outputs/` are local-only and excluded from git
- Google tokens are stored at `~/.Methoryn/google_token.json`, outside the project directory
- BYOK keys are stored at `~/.Methoryn/byok.json` — local to the machine, never synced

---

## License

MIT © 2026 [Methoryn](mailto:Anvyl.cli@gmail.com)
