| Name | muonry JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | None |
| Summary | Muonry - Sequential AI coding assistant with planning, websearch, and resilient fallbacks |
| upload_time | 2025-08-09 19:32:15 |
| maintainer | None |
| docs_url | None |
| author | Muonry Contributors |
| requires_python | >=3.10 |
| license | None |
| keywords |
ai
assistant
coding
cli
llm
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Muonry – Simple Sequential AI Coding Assistant
Muonry is a **reliable, sequential AI coding assistant** built on Bhumi with optional planning capabilities. The complex multi-agent orchestrator has been **removed** in favor of a clean, straightforward approach that actually works.
## ✨ Key Features
- **🎯 Sequential Execution** – Reliable step-by-step task completion
- **🧠 Optional Planning** – Cerebras-powered task breakdown for complex projects
- **🔧 Rich Tool Set** – File operations, shell commands, code patching
- **📋 Smart Planning** – AI-powered task decomposition with sequential execution
- **⚡ No Concurrency Issues** – Simple, reliable execution without coordination failures
- **📊 Compact Codebase** – 1,238 lines of focused, maintainable code
- **🛡️ Rate‑Limit Fallback** – Automatically retries with a fallback model on rate limits
- **🪓 Context Trimming** – Sliding‑window message trimming to avoid context overflow (~131k)
- **✅ Satya Validation** – Robust schema validation for planner outputs (dict/model safe)
- **🔎 Websearch Improvements** – Structured results and fallback parsing for Title/URL blocks
## 🚀 Quick Start
1. **Set API Keys:**
```bash
export GROQ_API_KEY=your_groq_key
export CEREBRAS_API_KEY=your_cerebras_key # Optional for multi-model
export EXA_API_KEY=your_exa_key # Optional for websearch tool
export MUONRY_MAX_CONTEXT_CHARS=120000 # Optional: context cap (chars)
```
2. **Run the Assistant:**
```bash
python assistant.py
```
## 💬 Usage
### Interactive Chat
Simply run `python assistant.py` and start chatting! The assistant automatically handles:
**Simple Tasks** → Direct execution:
```
💬 You: Read config.json
🤖 Assistant: [reads file directly]
```
**Complex Tasks** → Planning + Sequential execution:
```
💬 You: Create 6 Fire Nation stories in a folder
🧠 Planning task with 6 steps...
📋 Plan created: 1. Create folder, 2-6. Generate stories
💻 [Executes each step sequentially]
```
### Available Tools
- **File Operations**: `read_file`, `write_file`, `apply_patch`
- **System Commands**: `run_shell`, `get_system_info`, `grep`, `search_replace`
- **Planning**: `planner` (automatic for complex tasks)
- **Development**: `update_plan`
- **Web Search**: `websearch` (requires `EXA_API_KEY` or api_key param)
- **Interactive Shell**: `interactive_shell` (PTY; scripted answers, env)
- **Quick Checks**: `quick_check` (syntax/health checks)
## 🎯 How the Sequential Approach Works
1. **Simple Detection**: AI recognizes simple vs complex tasks automatically
2. **Optional Planning**: For complex tasks, uses Cerebras to break them into steps
3. **Sequential Execution**: Executes each step in order using appropriate tools
4. **Reliable Results**: No coordination issues, race conditions, or worker failures
**Example Output:**
```
💬 You: Create 6 Fire Nation stories in a folder
🧠 Planning task with 6 steps...
📋 Plan created successfully
💻 Shell: mkdir -p "fire nation" (exit 0)
📝 Writing story 1: The First Flame...
📝 Writing story 2: The Phoenix Crown...
✅ All 6 stories created successfully!
```
## 📊 Architecture
### Core Components (sequential, no orchestrator)
- **`assistant.py`** – Main sequential assistant. Handles chat loop, model fallback, and context trimming.
- **`tools/toolset.py`** – Consolidated tool implementations (planner, shell, patching, file ops, quick checks, interactive shell, etc.).
- **`tools/websearch.py`** – Exa-powered web search with structured JSON output and fallback Title/URL parsing.
- **`tools/apply_patch.py`**, **`tools/shell.py`**, **`tools/update_plan.py`**, etc. – Supporting modules used by `toolset.py`.
### Models & Fallback
- **Primary execution model**: `groq/moonshotai/kimi-k2-instruct` (requires `GROQ_API_KEY`).
- **Fallback model on rate-limit**: `cerebras/qwen-3-coder-480b` (auto retry once).
- **Planner model**: `cerebras/qwen-3-235b-a22b-thinking-2507` (requires `CEREBRAS_API_KEY`).
### Error Handling & Limits
- **Rate-limit handling**: Auto-detects rate limit errors; switches to fallback model and retries once.
- **Context length**: Sliding-window trimming keeps the latest messages within `MUONRY_MAX_CONTEXT_CHARS` (default 120k, below ~131k cap).
- **Planner validation**: Satya schema validation with safe conversion of model/dict step objects.
### Web Search
- `websearch` returns compact JSON: title, url, published_date, author, snippet, and limited text.
- If the provider returns a text block, the tool extracts Title/URL pairs to preserve clickable sources.
---
Muonry is a compact, reliable, sequential assistant. No multi-agent orchestration, no worker state—just focused tools and robust guardrails.
Raw data
{
"_id": null,
"home_page": null,
"name": "muonry",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, assistant, coding, cli, llm",
"author": "Muonry Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/38/82/64d410c691a6b8fafd25ad8a0226f0ae4427114417ac12278077863e09c2/muonry-0.1.2.tar.gz",
"platform": null,
"description": "# Muonry \u2013 Simple Sequential AI Coding Assistant\n\nMuonry is a **reliable, sequential AI coding assistant** built on Bhumi with optional planning capabilities. The complex multi-agent orchestrator has been **removed** in favor of a clean, straightforward approach that actually works.\n\n## \u2728 Key Features\n\n- **\ud83c\udfaf Sequential Execution** \u2013 Reliable step-by-step task completion\n- **\ud83e\udde0 Optional Planning** \u2013 Cerebras-powered task breakdown for complex projects\n- **\ud83d\udd27 Rich Tool Set** \u2013 File operations, shell commands, code patching\n- **\ud83d\udccb Smart Planning** \u2013 AI-powered task decomposition with sequential execution\n- **\u26a1 No Concurrency Issues** \u2013 Simple, reliable execution without coordination failures\n- **\ud83d\udcca Compact Codebase** \u2013 1,238 lines of focused, maintainable code\n- **\ud83d\udee1\ufe0f Rate\u2011Limit Fallback** \u2013 Automatically retries with a fallback model on rate limits\n- **\ud83e\ude93 Context Trimming** \u2013 Sliding\u2011window message trimming to avoid context overflow (~131k)\n- **\u2705 Satya Validation** \u2013 Robust schema validation for planner outputs (dict/model safe)\n- **\ud83d\udd0e Websearch Improvements** \u2013 Structured results and fallback parsing for Title/URL blocks\n\n## \ud83d\ude80 Quick Start\n\n1. **Set API Keys:**\n ```bash\n export GROQ_API_KEY=your_groq_key\n export CEREBRAS_API_KEY=your_cerebras_key # Optional for multi-model\n export EXA_API_KEY=your_exa_key # Optional for websearch tool\n export MUONRY_MAX_CONTEXT_CHARS=120000 # Optional: context cap (chars)\n ```\n\n2. **Run the Assistant:**\n ```bash\n python assistant.py\n ```\n\n## \ud83d\udcac Usage\n\n### Interactive Chat\nSimply run `python assistant.py` and start chatting! The assistant automatically handles:\n\n**Simple Tasks** \u2192 Direct execution:\n```\n\ud83d\udcac You: Read config.json\n\ud83e\udd16 Assistant: [reads file directly]\n```\n\n**Complex Tasks** \u2192 Planning + Sequential execution:\n```\n\ud83d\udcac You: Create 6 Fire Nation stories in a folder\n\ud83e\udde0 Planning task with 6 steps...\n\ud83d\udccb Plan created: 1. Create folder, 2-6. Generate stories\n\ud83d\udcbb [Executes each step sequentially]\n```\n\n### Available Tools\n- **File Operations**: `read_file`, `write_file`, `apply_patch`\n- **System Commands**: `run_shell`, `get_system_info`, `grep`, `search_replace`\n- **Planning**: `planner` (automatic for complex tasks)\n- **Development**: `update_plan`\n- **Web Search**: `websearch` (requires `EXA_API_KEY` or api_key param)\n- **Interactive Shell**: `interactive_shell` (PTY; scripted answers, env)\n- **Quick Checks**: `quick_check` (syntax/health checks)\n\n## \ud83c\udfaf How the Sequential Approach Works\n\n1. **Simple Detection**: AI recognizes simple vs complex tasks automatically\n2. **Optional Planning**: For complex tasks, uses Cerebras to break them into steps\n3. **Sequential Execution**: Executes each step in order using appropriate tools\n4. **Reliable Results**: No coordination issues, race conditions, or worker failures\n\n**Example Output:**\n```\n\ud83d\udcac You: Create 6 Fire Nation stories in a folder\n\ud83e\udde0 Planning task with 6 steps...\n\ud83d\udccb Plan created successfully\n\ud83d\udcbb Shell: mkdir -p \"fire nation\" (exit 0)\n\ud83d\udcdd Writing story 1: The First Flame...\n\ud83d\udcdd Writing story 2: The Phoenix Crown...\n\u2705 All 6 stories created successfully!\n```\n\n## \ud83d\udcca Architecture\n\n### Core Components (sequential, no orchestrator)\n- **`assistant.py`** \u2013 Main sequential assistant. Handles chat loop, model fallback, and context trimming.\n- **`tools/toolset.py`** \u2013 Consolidated tool implementations (planner, shell, patching, file ops, quick checks, interactive shell, etc.).\n- **`tools/websearch.py`** \u2013 Exa-powered web search with structured JSON output and fallback Title/URL parsing.\n- **`tools/apply_patch.py`**, **`tools/shell.py`**, **`tools/update_plan.py`**, etc. \u2013 Supporting modules used by `toolset.py`.\n\n### Models & Fallback\n- **Primary execution model**: `groq/moonshotai/kimi-k2-instruct` (requires `GROQ_API_KEY`).\n- **Fallback model on rate-limit**: `cerebras/qwen-3-coder-480b` (auto retry once).\n- **Planner model**: `cerebras/qwen-3-235b-a22b-thinking-2507` (requires `CEREBRAS_API_KEY`).\n\n### Error Handling & Limits\n- **Rate-limit handling**: Auto-detects rate limit errors; switches to fallback model and retries once.\n- **Context length**: Sliding-window trimming keeps the latest messages within `MUONRY_MAX_CONTEXT_CHARS` (default 120k, below ~131k cap).\n- **Planner validation**: Satya schema validation with safe conversion of model/dict step objects.\n\n### Web Search\n- `websearch` returns compact JSON: title, url, published_date, author, snippet, and limited text.\n- If the provider returns a text block, the tool extracts Title/URL pairs to preserve clickable sources.\n\n---\n\nMuonry is a compact, reliable, sequential assistant. No multi-agent orchestration, no worker state\u2014just focused tools and robust guardrails.\n",
"bugtrack_url": null,
"license": null,
"summary": "Muonry - Sequential AI coding assistant with planning, websearch, and resilient fallbacks",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/justrach/muonry",
"Website": "https://muonry.com"
},
"split_keywords": [
"ai",
" assistant",
" coding",
" cli",
" llm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a4eaabdb0515c41efd6f132e98023b8c21f8fb32d2b8577abed17d2bed511f3a",
"md5": "3e692c0d731773bf9dacc8669e5d2c6a",
"sha256": "7fe7a7b60358110e6ba8820b61c15f4b1bb49476eeac2d565b5749d606bc337d"
},
"downloads": -1,
"filename": "muonry-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3e692c0d731773bf9dacc8669e5d2c6a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 55050,
"upload_time": "2025-08-09T19:32:13",
"upload_time_iso_8601": "2025-08-09T19:32:13.701348Z",
"url": "https://files.pythonhosted.org/packages/a4/ea/abdb0515c41efd6f132e98023b8c21f8fb32d2b8577abed17d2bed511f3a/muonry-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "388264d410c691a6b8fafd25ad8a0226f0ae4427114417ac12278077863e09c2",
"md5": "c6b8b117200772ed237345667a490d25",
"sha256": "cfd18b4d3f5b9c90261179dc661a15f5c74e7864b9c43a1910e1c8a12d10559b"
},
"downloads": -1,
"filename": "muonry-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "c6b8b117200772ed237345667a490d25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 57592,
"upload_time": "2025-08-09T19:32:15",
"upload_time_iso_8601": "2025-08-09T19:32:15.207699Z",
"url": "https://files.pythonhosted.org/packages/38/82/64d410c691a6b8fafd25ad8a0226f0ae4427114417ac12278077863e09c2/muonry-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 19:32:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "justrach",
"github_project": "muonry",
"github_not_found": true,
"lcname": "muonry"
}
