gpt claude grok gemini openrouter hf gguf
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 inai-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 officialllama-serverUI (http://127.0.0.1:3000).
| Feature System | Foundation & Architectural Roots | Interface Command / Link |
|---|---|---|
| PyCode Native Desktop IDE | Customized T3 Code fork connected via native Agent Client Protocol (ACP) over stdio JSON-RPC 2.0 with live token & thought streaming. | /pyc (or /pyc web) |
| Temporal Personality Memory (TPM) | Reconciles personal identity & workspace habits using Weaviate Engram concepts + Noema Markdown files. | .agent/tpm.md |
| Codebase Graph & Relational Index | Structural codebase maps (Graphify) + relational queries (codebase-memory-mcp) + sqlite-vec vector RAG with class inheritance graph mapping. | index-map <dir> |
| Ralph Autonomous Task Loop | Self-directed iteration loop (Ralph Wiggum) executing tasks against project specs (TASK.md) until verified complete. |
/task [goal] |
| NOOA IPython Kernel Harness | NVIDIA Object-Oriented Agent (NOOA + Prime Agent) stateful Python kernel with pass-by-reference bounded previews (preview()), model-callable memory/graph APIs, and in-kernel delegate() sub-agents. |
/py |
| DeepSeek Session Audit & IPC | Structured JSONL session event logs + JSON-RPC 2.0 socket IPC + YAML skill frontmatter overlays inspired by DeepSeek Harness. | .agent/session.jsonl |
| Reasonix Cognitive Engine | Real-time reasoning trace step extraction (Reasonix) + cognitive phase formatting inside thinking stream. | /t [N|show|hide] |
| System Admin & Diagnostics | Live health monitoring, AUR/security audits, system optimization, status routing, and git commit hooks. | tools/agentic/system/ |
| Model Select TUI | Real-time Cloud Connection TUI, key toggles, and endpoint selector. | model select |
| Interactive Textual PyTUI | Full-screen Textual TUI workspace with JSON-RPC 2.0 sub-agent socket IPC powered by a C-speed uvloop event loop. |
/tui |
| llama.cpp WebAgent Gateway | Full autonomous agent tool execution (list_dir, write_file, AST graph) injected directly into official llama.cpp WebUI. |
/webui |
| Core Module | Capability | Description |
|---|---|---|
| Engine | Zero-Daemon | 0% idle CPU/RAM usage. Native Python standard-library execution. |
| Providers | Active Provider | Direct .env configuration: Custom Endpoints / HF, Gemini, OpenRouter, OpenAI, Claude, Grok, or Local GGUF. |
| Multi-Agent | Subagents | Vercel Eve-style sub-agents with herdr multiplexing (-save/-load) + in-kernel delegate("goal") sub-loops. |
| Safety | Zero-Trust Gates | Mandatory approval prompts for commands and out-of-bounds file access. |
| Integrity | Type-Safe & AST Guard | Pydantic AI schemas + OpenAI Agents-style self-correcting .py/.json file writes. |
| Resilience | Self-Healing Tool Calls | Unsloth-inspired heuristic parser fixing malformed JSON/XML arguments on the fly before tool execution. |
| Optimization | Token-Slasher | Custom tools/ and skills/ integration built for minimal token consumption. |
| Voice-to-Text | Tablet/Phone Bridge | Zero-latency HTTPS voice bridge with Gemini cloud transcription and native Wayland virtual typing (wtype) directly into PyCode IDE and CLI (/v [auto]). |
| Text-to-Speech | Neural Kokoro TTS | Local PipeWire audio reader (/tts) using koko with automatic code/thinking filtering. |
Customize box themes with
/box [1-5]. For detailed multi-agent workflows, read the Workspace Manual.
~ ❯ ai
╭─ ∿ Py Agent ────────────────────╮
│ model: Qwen3.6-35B-A3B.gguf │
│ directory: ~ │
│ skill: chat │
│ database: stateless │
╰────────────────── Ctrl+C to exit ─╯
Startup context: 103 tokens
❯
React Desktop IDE (PyCode)/pyc · /pyc web
|
Textual PyTUI/tui
|
Web Assistant (PyBot)/pybot (Coming Soon) |
llama.cpp WebAgent/webui
|
# 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 ~/.bashrcConfigure 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📋 View Example ~/.config/py-agent/.env (Click to Expand)
# ==============================================================================
# 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"| Surface | Installation Command | Requirement |
|---|---|---|
| Desktop GUI (PyCode) | install-pycode(or ~/.config/py-agent/plugins/pycode/setup.sh) |
Node.js 20+, pnpm |
| Textual PyTUI | sudo pacman -S python-textual python-uvloop && yay -S python-sqlite-vec |
uvloop & sqlite-vec |
- Core Engine Optimization: Production pass on streaming, token counting, and sub-agent concurrency.
- Thinking UI Controls: Real-time thinking TPS metrics and
/t show|hidepanel 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
uvloopevent 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
whileloop 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-callablememory/graphAPIs, in-kerneldelegate()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 officialllama.cppWebUI (/webui). - PyBot Integration (OpenBot Plugin): Embedded web assistant & customizable agent widget plugin to bring
py-agentintelligence 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: Licensed under the permissive MODIFIED MIT LICENSE.
- Community: Contributions are always welcome!