gguf • llama.cpp • gemini • huggingface • openrouter
Lightweight Python orchestration (rich + requests) driving a high-throughput C++ llama-server backend.
Stateful in-memory Python batching (/py), self-healing tool adapters (/adp), and sub-millisecond local execution.
|
Ultra-fast tool calling, shell triage & single-turn code edits Ling-3.0-tiny* • LFM2.5-8BMiniCPM5-2B • Qwen3.5-2B+
|
Deep reasoning, multi-file refactoring & recursive sub-agents KAT-Coder-V2.5* • Ornith-1.5Qwen3.8-35B-D • Tiel-Coder-35BOccamy-1.0 • Nex-N2.5-miniQwen3.8-27B • Qwen3.8-Flash-NextDeepSeek‑V4.1
|
* Recommended benchmark baselines • Run model select in your terminal to switch models
Cloud & Community Spaces: Official Hugging Face Router endpoints
(DeepSeek-V4.1-Flash, GLM-5.3-Flash, Ling-3.0-flash-VL, and Kimi-K3).
~ ❯ ai
╭─ ∿ Py Agent ──────────────────────╮
│ model: Qwen3.8-35B-Distill │
│ directory: ~ │
│ profile: chat │
│ database: stateless │
╰───────────────────────────────────╯
❯ █Customize box themes with /box [1-8]. For detailed workflows, read the Workspace Manual.
| Command | Mode | Operational Scope |
|---|---|---|
[query] |
Shell Intercept | Intent matching via ai-context.md |
ai "<query>" |
Single Query | Instant prompt execution response |
ai |
Interactive Chat | Multi-turn chat session |
ai init [path] |
Workspace Agent | Autonomous project session |
/yolo • /py repl • /adp adapters • /t reasoning • /task loop • /s skills • /a allmeta
/m map • file load • /mem memory • /com compact • /gnd search • /hs audit • /tok tokens • /sync
/tui • /pyc • /webui • /calm • /v voice • /tts • /box • /stats • -save / -load • /c • /r
- Hardened Containment (
agent_security.py): Non-bypassable interactive[y/N]confirmation gates for system commands (sudo,pacman,pip,systemctl) and out-of-bounds file access even in YOLO mode. - Git-Native & Global Memory: Global system instructions (
skills/system_instructions.md) and workspace directives (.agent/memory/*.md). Human-editable. - Universal Self-Healing Adapters (
/adp): Out-of-band argument normalizer repairing malformed JSON, markdown fences, and parameter aliases across all model tiers. Zero overhead when native tool calls are compliant.
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.
| Rank | Model | Par Eff | Agent Index |
|---|---|---|---|
| 1 | KAT-Coder-V2.5-Dev | 96.8% | 90.3 (A) |
| 2 | Ornith-1.5-35B-A3B | 88.2% | 89.3 (A) |
| 3 | Tiel-Coder-35B-A3B | 90.9% | 87.6 (B) |
| 4 | Qwen3.8-35B-Distill (MTP) | 93.8% | 87.5 (B) |
| 5 | Occamy-1.0 | 90.9% | 87.0 (B) |
| 6 | Qwen3.8-35B-Distill (Pure) | 90.9% | 86.4 (B) |
| 7 | Nex-N2.5-mini | 88.2% | 85.8 (B) |
| — | Ling-3.0-tiny (SLM) | 108.3% | 100.0 (A+) |
| Benchmark Challenge | Without Adapters | With /adp Active |
Efficiency Gain |
|---|---|---|---|
| AG-03 (Surgical Edit & Test) | 16 turns | 6 turns | 62% fewer turns (eliminates 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 |
| Operational Tier | Py-Agent | DeepSeek (dsh) |
|---|---|---|
| Pure Chat | 211 tokens (ai) |
~450+ tokens |
| 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 |
Py-Agent is surface-agnostic. Switch seamlessly between terminal, web gateway, and desktop IDE:
|
|
uvloop, socket IPC.
|
llama-server.
|
/v Voice-to-Text (:9999) • /tts Neural Kokoro Audio • /pybot Web Assistant
# 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# 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)
# ==============================================================================
# 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="Qwen/Qwen3.8-27B"
# ── 2. Custom 2 / Generic Endpoint (DeepSeek, OpenAI, etc.) ───────────────────
# CUSTOM2_API_KEY="sk-your-key-here"
CUSTOM2_URL="https://api.deepseek.com/chat/completions"
CUSTOM2_MODEL="deepseek-chat"
# ── 3. Google Gemini (Free daily tier via Google AI Studio) ───────────────────
# GEMINI_API_KEY="AIzaSyYourGeminiApiKeyHere"
GEMINI_MODEL="gemini-3.5-flash-lite"
# ── 4. 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"- Workspace Manual
- System Architecture
- Licensed under the permissive MODIFIED MIT LICENSE