Py Agent

gguf • llama.cpp • gemini • openrouter • opencode

Python runtime (lazy rich + requests) driving a local C++ llama-server backend or cloud APIs.
_{In-memory Python execution (/py), argument repair adapters (/adp), and instant startup.}

Sub-27B (SLM)

_{Tool calling, shell triage, and single-turn code edits}

LFM3-1.7B* • Ling-3.0-tiny
MiniCPM5-2B • Qwen3.5-2B+
MiniCPM-V-4.7-1B • LFM2.5-24B-A2B

27B+ (LLM)

_{Reasoning, multi-file refactoring, and sub-agents}

Clover-35B-A3B •
Sage-A1.5-35B • Flint-40B-A2.5B*
Qwen3.8-35B-D • Ornith-1.5
KAT-Coder-V2.5 • Tiel-Coder-35B
Occamy-1.0 • Nex-N2.5-mini
Qwen3.8-27B • Qwen3.8-Flash
DeepSeek‑V4.1

* Benchmark baselines • Run model select in your terminal to switch models

_{Cloud Endpoints: Hugging Face Spaces, TokenHarbor, OpenCode, and OpenRouter

Free Endpoints: big-pickle (OpenCode) • deepseek-v4.1-flash:free (TokenHarbor) • openrouter/free (OpenRouter)}

--- ```console ~ ❯ ai ╭─ ○ ────────────────────────────────────────╮ │ InternScience-Sage-A1.5 │ │ chat │ ╰────────────────────────────────────────────╯ · · ○ · · · · · · · · · · · · · · · · · · · · · · InternScience-Sage-A1.5 · · · · · · · · · · · chat · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ○ · · · · · · · · · · · · · · · · · · · ·· · InternScience-Sage-A1.5 · · chat · · · · · · · · · · · · · · · · · · · · · · · ·· ❯ █ ```

_{Select box themes with /box [1-3]. Workspace details in the Workspace Manual.}

---

Execution Surfaces

_{/yolo gate • /py repl • /adp adapters • /t reasoning • /task loop goal • /s skills • /a all meta • /md markdown • /calm zen}
_{/m map • file load • /mem memory • /com compact • /gnd search • /hs hindsight • /tok tokens • /sync index-map • /stats speed}
_{/tr • /bot • /tui • /t3 • /dsh • /zed • /webui • /v • /tts • /box • -save / -load • /c clear • /r reset}

---

Runtime Architecture

* **Security Kernel (`agent_security.py`):** Interactive `[y/N]` confirmation gates for system commands (`sudo`, `pacman`, `pip`, `systemctl`) and out-of-bounds file access, enforced even in YOLO mode. * **Workspace Memory:** Global rules (`skills/system_instructions.md`) and project directives (`.agent/memory/*.md`) stored as plaintext Markdown. * **Tool Adapters (`/adp`):** Out-of-band argument normalizer repairing malformed JSON, markdown fences, and parameter aliases.
---

Benchmark & Efficiency

Decision-grade evaluation across 7-stage agentic challenges (eval-stack).
_{Results scale with tuning: select a model foundation and optimize for your workload via profile directives, sampling flags, and /adp.}

### Agent Evaluation (`eval-stack`) | Rank | Model | Par Eff | Agent Index | | :---: | :--- | :---: | :---: | | **1** | **Flint-40B-A2.5B** | **120.0%** | **100.0 (A+)** | | **2** | **Sage-A1.5-35B** | **111.1%** | **100.0 (A+)** | | **3** | **Qwen3.8-35B-Distill** *(MTP)* | **136.4%** | **92.2 (A)** | | **4** | **KAT-Coder-V2.5-Dev** | **90.9%** | **89.8 (A)** | | **5** | **Ornith-1.5-35B-A3B** | **88.2%** | **89.3 (A)** | | **6** | **Tiel-Coder-35B-A3B** | **90.9%** | **87.6 (B)** | | **7** | **Occamy-1.0** | **90.9%** | **87.0 (B)** | | **8** | **Nex-N2.5-mini** | **88.2%** | **85.8 (B)** | | **—** | **LFM3-1.7B** *(SLM)* | **123.8%** | **100.0 (A+)** | | **—** | **Ling-3.0-tiny** *(SLM)* | **104.0%** | **100.0 (A+)** | | **—** | **LFM2.5-24B-A2B** | **44.8%** | **83.3 (B)** |
| Benchmark Challenge | Without Adapters | With `/adp` Active | Efficiency Gain | | :--- | :---: | :---: | :--- | | **AG-03 (Surgical Edit & Test)** | 16 turns | **6 turns** | **62% fewer turns** (avoids diff-retry loops) | | **AG-07 (In-Memory Batch Loop)** | 14 turns | **2 turns** | **85% fewer turns** (executes batch script on Turn 1) | | **Full Suite Pass Rate** | Retries / Failures | **100% (7/7)** | **Zero unhandled syntax or format failures** |
| AG-03 Benchmark (`Ling-3.0-tiny`) | Py-Agent (`/adp`) | Pi (`pi-tool-repair`) | | :--- | :---: | :---: | | **Pass Rate** | **100%** (Turn 1) | **100%** (Turn 1) | | **Output Spend** | **48 tokens** | 363 tokens | | **Reasoning Spend** | **21 tokens** | 4,900 tokens | | **Latency** | **1.7s** | ~4.5s |
| Operational Tier | Py-Agent | DeepSeek (`dsh`) | | :--- | :---: | :---: | | **Pure Chat** | **211 tokens** (`ai`) | ~450+ tokens | | **Pure Bash** | **~110 tokens** (`PUREBASH_TOOLS` · 167% Par, A+) | — | | **Native Core** | **~680 tokens** (`SMOL_TOOLS`) | ~632 tokens | | **Dual Mode** | **~760 tokens** (`python + native`) | ~1,200+ tokens | | **Full Graph** | **~1,100 tokens** (12 tools + AST) | 2,500–4,000+ tokens | | **Idle Overhead** | **0% CPU / 0 MB RAM** | Node.js Active |

---

Client Surfaces

Py-Agent is surface-agnostic. Switch seamlessly between terminal, web gateway, and desktop IDE:

T3 Code IDE

/t3 · /t3 web

_{Desktop control plane using ACP JSON-RPC 2.0.}

Textual PyTUI

/tui

_{Terminal workspace built with Textual and uvloop.}

llama.cpp WebAgent

/webui · /web

_{Tool reverse proxy for llama-server.}

_{/tr ThinkRail • /bot OpenBot • /v Voice-to-Text (:9999) • /tts Neural Kokoro Audio • /dsh DeepSeek Harness • /zed Editor}

---

Setup & Installation

### 1. Install py-agent ```bash # 1. Install dependencies (Arch/CachyOS or pip) sudo pacman -S python-rich python-requests # 2. Clone repository git clone https://github.com/j5onrf/py-agent.git ~/.config/py-agent # 3. Register shell hook (bash / zsh) echo '[ -f "$HOME/.config/py-agent/ai-hook.sh" ] && \ source "$HOME/.config/py-agent/ai-hook.sh"' >> ~/.bashrc source ~/.bashrc ``` ### 2. Configure Providers (`.env`) ```bash # Option A: Interactive TUI Selector model select # Option B: Manual Configuration cp ~/.config/py-agent/.env.example ~/.config/py-agent/.env ```

View Example (~/.config/py-agent/.env.example)

```env # ============================================================================== # Py-Agent Environment Configuration (.env.example) # # RULES: # 1. Top-Down: First uncommented key is active. # 2. Toggle: Add '#' to disable; remove '#' to enable. # 3. Add More: Define CUSTOM3_*, CUSTOM4_*, etc. anywhere. # 4. Fallback: If all keys have '#', routes to local server (:8080). # 5. TUI Config: Run 'model select' to configure everything interactively. # ============================================================================== # ── 1. Custom 1 / Hugging Face Router ───────────────────────────────────────── # CUSTOM_API_KEY="hugging-face-api-key" CUSTOM_URL="https://router.huggingface.co/v1/chat/completions" CUSTOM_MODEL="space" # ── 2. Custom 2 / Generic Endpoint (DeepSeek, OpenAI, TokenHarbor, etc.) ────── # CUSTOM2_API_KEY="sk-your-key-here" CUSTOM2_URL="https://tokenharbor.ai/v1/chat/completions" CUSTOM2_MODEL="deepseek-v4.1-flash:free" # ── 3. Custom 3 / PyRouter OpenCode (Port 20128) ────────────────────────────── #CUSTOM3_API_KEY="not-needed" CUSTOM3_URL="http://127.0.0.1:20128/v1/chat/completions" CUSTOM3_MODEL="big-pickle" # ── 4. Google Gemini (Free daily tier via Google AI Studio) ─────────────────── # GEMINI_API_KEY="AIzaSyYourGeminiApiKeyHere" GEMINI_MODEL="gemini-3.5-flash-lite" # ── 5. OpenRouter (Free community models & Universal paid gateway) ──────────── # OPENROUTER_API_KEY="sk-or-v1-YourOpenRouterKeyHere" OPENROUTER_MODEL="openrouter/free" # ── Auxiliary Services (Independent Toggles) (Optional) ─────────────────────── # Google Search Grounding (/gnd) # GND_KEY="AIzaSyYourGeminiApiKeyHere" # GND_MODEL="gemini-2.5-flash" # Voice Bridge Transcription (Speech-to-Text on :9999) # GEM_VOICE="AIzaSyYourGeminiApiKeyHere" # GEM_MODEL="gemini-3.5-flash-lite" # Multimodal Vision OCR (Pre-processor for text-only local models) # IMG_VOICE="AIzaSyYourGeminiApiKeyHere" # IMG_MODEL="gemini-3.5-flash-lite" # ── Model Context Protocol (MCP) (Optional) ─────────────────────────────────── # Firecrawl Scrape & Search # FIRECRAWL_API_KEY="fc-your-actual-api-key" # ── Context Window Budget ───────────────────────────────────────────────────── AI_MAX_TOKENS="8192" AI_MAX_AGENT_ROUNDS="15" ```

---

Documentation & License

* **Workspace Manual** * **System Architecture** * Licensed under the **[MODIFIED MIT LICENSE](LICENSE)**