Metadata-Version: 2.4
Name: Methoryn
Version: 0.1.62
Summary: Methoryn — A private, local-first desktop AI assistant powered by Ollama and Gemini
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,Ollama,Gemini,agent,local
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: 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
Requires-Dist: ddgs>=9.15.0
Dynamic: license-file

# Methoryn

**A private, local-first desktop AI assistant powered by Ollama and Gemini.**

Methoryn is a terminal app (TUI) built on a **2-agent architecture**:

| Agent | Engine | Role |
|-------|--------|------|
| **Methoryn Agent** | [Ollama](https://ollama.com/) — Qwen 2.5 Coder 3B | Everything local — conversation, planning, task execution, coding |
| **Architect** | [Gemini](https://aistudio.google.com/) — Gemini Flash | Images only — image generation & understanding |

Everything runs on-device through the local Ollama engine (`localhost:11434`). No cloud API keys are needed for chat, planning, coding, or shell/file actions — only Gemini retains a key for image generation. 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

- **Local-first AI** — conversation, planning, coding, and execution run entirely on your machine via Ollama
- **Automatic setup** — Ollama is detected, started, or silently installed on first launch; required models are pulled automatically
- **Model warm-up** — Qwen is pre-loaded into VRAM during startup so first replies are fast
- **Tool use** — reads/writes files, runs shell commands (PowerShell), searches the web, takes screenshots
- **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 `/account`, 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`, `/image`, `/search`, `/drive`, `/run`, and more

---

## Requirements

- Python 3.13+
- [Ollama](https://ollama.com/download) — **required**, runs the local models
  - Auto-pulled on first launch (~4 GB total):
    - `qwen2.5-coder:3b` — all Ollama tasks (~2.2 GB)
    - `moondream` — local image understanding (~1.7 GB)
- A [Google AI Studio API key](https://aistudio.google.com/app/apikey) — **required**, powers Gemini image generation (`GOOGLE_API_KEY`)
- A Google Cloud OAuth2 `credentials.json` — optional, enables Gmail / Drive / Docs / Sheets / Slides / Forms / 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`

**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. **Install Ollama**: https://ollama.com/download
   (On Windows, Methoryn detects, starts, or silently installs it automatically.)
2. **Get a Gemini key**: [Google AI Studio](https://aistudio.google.com/app/apikey)
3. **Launch and configure**:
   ```bash
   Methoryn
   ```
   On first run, you'll see a setup screen. Enter your `GOOGLE_API_KEY` and optionally sign in with Google.
4. **Try your first prompt**:
   ```bash
   Methoryn "write a Python script that lists files by size"
   ```

---

## API Keys

Only one key is required:

| Key | Provider | Used for |
|-----|----------|----------|
| `GOOGLE_API_KEY` | [Google AI Studio](https://aistudio.google.com/app/apikey) | **Architect — image generation** (required) |
| `GOOGLE_ACCOUNT_EMAIL` | Google | Optional — enables Workspace OAuth (Gmail/Drive/Docs/Sheets/Slides/Forms/Calendar) |

No key is needed for the Methoryn Agent — it runs locally through Ollama.

You can set any key inside the app without touching `.env` — run `/account` and edit the key fields directly.

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 |
| `/account` | Check Ollama status and manage Google accounts / API keys | No |
| `/image` | Generate an image (Gemini Imagen) | Yes |
| `/search` | Search the web and print results | No |
| `/fetch` | Fetch and read a URL | No |
| `/desktop` | Create a file or folder on your Desktop | No |
| `/drive` | List your Google Drive files | No |
| `/gmail` | Read recent Gmail messages | No |
| `/docs` | Create a new Google Doc | No |
| `/sheets` | Create a new Google Sheet | No |
| `/slides` | Create a Slides presentation | No |
| `/forms` | Create a Google Form | No |
| `/calendar` | Add a Calendar event | No |
| `/run` | Run a shell command | No |
| `/write` | Write a file | No |
| `/python` | Write and run a Python script | No |
| `/md` `/txt` `/html` `/word` `/pdf` `/csv` | Write a file in that format | No |
| `/copy` | Copy all output to clipboard | No |
| `/save` | Save session to disk | No |

---

## 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 (startup checks, warm-up)
│   ├── agent.py             — Methoryn Agent: conversation, planning, execution (Ollama)
│   ├── ollama_client.py     — Local Ollama engine wrapper (health, model pull, warm-up)
│   ├── gemini_agent.py      — Architect: image generation & understanding (Gemini)
│   ├── library_catalog.py   — Library/script discovery for the agent
│   ├── config.py            — Key loading (.env + BYOK), model constants
│   ├── byok.py              — Bring Your Own Key persistence (~/.Methoryn/byok.json)
│   ├── state.py             — Shared app state (single source of truth)
│   ├── output.py            — Session save/load (sessions/ folder)
│   ├── google_auth.py       — Google OAuth2 flow (token cached at ~/.Methoryn/)
│   ├── intro.py             — Splash animation
│   ├── setup_screen.py      — First-run setup
│   ├── taskbar.py           — Taskbar progress indicator
│   └── widgets.py           — MainBox, SideBar, SlashPalette, PromptEditor
├── libraries/               — Deterministic tool libraries
│   ├── command_line         — run_shell, run_python
│   ├── web_operations       — weather, search_web, fetch_url, news, finance
│   ├── google_gmail / calendar / drive / docs / sheets / slides / forms
│   ├── gui_operations       — take_screenshot, describe_image, click_at, type_text
│   └── google_credentials   — OAuth scopes/helpers
├── 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
```

---

## Notes

- Sessions are auto-saved on quit and auto-loaded on next launch so context carries over
- Models are downloaded once on first run and cached by Ollama
- If Ollama isn't reachable, Methoryn shows the setup screen and offers to install/start it automatically (Windows)
- `sessions/` and `outputs/` are local-only and excluded from git
- Google accounts and tokens are stored at `~/.Methoryn/accounts.json` and `~/.Methoryn/tokens/`, 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)
