Py Agent

gpt   claude   grok   gemini   openrouter   hf   gguf

Overview & Execution Modes

Lightweight Python orchestration (rich + requests + sqlite-vec + uvloop) controlling a C++ backend llama-server. Built for extreme efficiency on quantized local models (LFM2.5-8B-A1B, Qwen3.5-2B, Qwen3.6-35B-A3B, Qwen3.8-27B) and cloud providers.

🟢 Active: Official Huggingface Router endpoints: (Qwen/Qwen3.8-2.4T-A95B, DeepSeek-V4-Flash-0731).

• Direct Shell Jaccard (<plugins>): Sub-millisecond fuzzy intent routing for shell shortcuts, diagnostic tools, and custom plugins mapped in ai-context.md.
• Single-Turn Query (ai <query>): Instant response piped straight back to your active shell prompt.
• Multi-Turn Chat (ai): Persistent interactive terminal session with memory context.
• Workspace Agent (ai init <path>): Full codebase graph indexing, path-healing file editing, and sub-agent concurrency.
• Native GUI IDE (/pyc): Cross-platform React desktop & browser development workspace powered by PyCode.
• llama.cpp WebAgent (/webui): Autonomous tool-enabled web gateway on top of official llama-server UI (http://127.0.0.1:3000).

Key Systems & Integrations

Core Capabilities

CLI Launch Interface

Customize box themes with /box [1-5]. For detailed multi-agent workflows, read the Workspace Manual.

1. Interactive Multi-Turn Chat (ai)

~ ❯ ai
╭─  ∿ Py Agent  ────────────────────╮
│     model:  Qwen3.6-35B-A3B.gguf  │
│ directory:  ~                     │
│     skill:  chat                  │
│  database:  stateless             │
╰────────────────── Ctrl+C to exit ─╯
 Startup context: 103 tokens
❯ 

Plugin Extensions

React Desktop IDE (PyCode) /pyc · /pyc web	Textual PyTUI /tui	Web Assistant (PyBot) /pybot (Coming Soon)
llama.cpp WebAgent /webui

Setup & Installation

1. Install py-agent

# 1. Install system dependencies & clone
sudo pacman -S python-rich python-requests
git clone https://github.com/j5onrf/py-agent.git ~/.config/py-agent

# 2. 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)

Configure providers automatically via the interactive selector or copy the template:

# Option A: Interactive TUI Selector
model select

# Option B: Manual Configuration
cp ~/.config/py-agent/.env.example ~/.config/py-agent/.env
nano ~/.config/py-agent/.env

# ==============================================================================
# Py-Agent Environment Configuration Template
# Top-Down Priority: The first active (uncommented) provider key is used.
# ==============================================================================

# ── 1. Custom Endpoints / Hugging Face Router ─────────────────────────────────
# Get a free read token at: https://huggingface.co/settings/tokens
# CUSTOM_API_KEY="hf_YourHuggingFaceTokenHere"
CUSTOM_URL="https://router.huggingface.co/hf-inference/v1/chat/completions"
CUSTOM_MODEL="Qwen/Qwen3.8-27B"

# ── 2. Google Gemini ─────────────────────────────────────────────────────────
# Get key at: https://aistudio.google.com/app/apikey
# GEMINI_API_KEY="AIzaSyYourGeminiApiKeyHere"
GEMINI_MODEL="gemini-3.7-flash"

# ── 3. OpenRouter (Free & Paid Catalog) ───────────────────────────────────────
# Get key at: https://openrouter.ai/keys
# OPENROUTER_API_KEY="sk-or-v1-YourOpenRouterKeyHere"
OPENROUTER_MODEL="openrouter/free"

# ── 4. Anthropic Claude ──────────────────────────────────────────────────────
# CLAUDE_API_KEY="sk-ant-YourClaudeKeyHere"
CLAUDE_MODEL="claude-Fable"

# ── 5. OpenAI ────────────────────────────────────────────────────────────────
# OPENAI_API_KEY="sk-YourOpenAIKeyHere"
OPENAI_MODEL="gpt-luna"

# ── 6. x.AI Grok ─────────────────────────────────────────────────────────────
# XAI_API_KEY="xai-YourGrokKeyHere"
XAI_MODEL="grok-5.6"

# ── Voice Bridge Transcription (Optional) ────────────────────────────────────
# GEM_VOICE="AIzaSyYourGeminiApiKeyHere"
# GEM_MODEL="gemini-3.5-flash-lite"

# ── Context Window Budget ────────────────────────────────────────────────────
AI_MAX_TOKENS="8192"

3. Optional Client Surfaces

Roadmap to v1.0.0

• Core Engine Optimization: Production pass on streaming, token counting, and sub-agent concurrency.
• Thinking UI Controls: Real-time thinking TPS metrics and /t show|hide panel toggles.
• Modular Agent Personas & Tool Loop: Interactive profile selector on ai init (pi, claude, hermes) with automated path-healing file editing & YOLO execution loops.
• Textual Async PyTUI: Sub-millisecond uvloop event loop integration, Unix socket sub-agent hub, and live workspace watchers.
• Reasonix Cognitive Step: Real-time reasoning cognitive transition extraction, real-time thinking step formatting, and stream interception.
• Ralph Autonomous Task Loop: On-demand while loop engine (/task, TASK.md) with automated completion verification.
• Voice to Text: Low-latency HTTPS tablet or phone voice bridge, Gemini cloud transcription, and non-blocking stdin injection loop (/v [auto]).
• Kokoro Neural Text-to-Speech: Real-time local neural voice reader (/tts), PipeWire audio integration, and automatic thinking/code block filtering.
• NOOA IPython Kernel Harness: Single-tool Python kernel execution engine (/py) with NVIDIA NOOA bounded previews (preview()), model-callable memory/graph APIs, in-kernel delegate() sub-agents, AST safety gates, and stateful context token conservation.
• DeepSeek Session Audit & IPC: Real-time JSONL event logging (.agent/session.jsonl), JSON-RPC 2.0 sub-agent socket IPC, and YAML skill profile frontmatter headers.
• Self-Healing Tool Parser: Unsloth-inspired resilient JSON argument healer auto-balancing brackets, stripping leaked XML tokens, and repairing unescaped newlines for small local models.
• PyCode Cross-Platform GUI (T3 Fork): Local-first React desktop and WebUI workspace connected via ACP (Agent Client Protocol) stdio JSON-RPC bridge (/pyc, /pyc web)—featuring real-time token/thought streaming, custom vector branding, theme-reactive ambient aurora glow toggle, and automatic workspace AST indexing.
• llama.cpp WebAgent Gateway: Real-time tool execution (list_dir, write_file, AST index maps) and streaming proxy for the official llama.cpp WebUI (/webui).
• PyBot Integration (OpenBot Plugin): Embedded web assistant & customizable agent widget plugin to bring py-agent intelligence to browser overlays and multi-surface chat bots.
• Context Stress Testing: Continuous context-window pressure tests across quantized local engines.
• Automated File Containment Validation: Zero-trust security verification on traversal boundaries.
• v1.0.0 Production Release Tag!

License

• License: Licensed under the permissive MODIFIED MIT LICENSE.
• Community: Contributions are always welcome!