README.md
Rama main · réplica de lectura del repositorio original.
<br>
<div align="center">
<img alt="py-agent" src="logo.svg" height="130" />
<h1>Py Agent</h1>
<p>
<a href="https://github.com/j5onrf/py-agent"><img src="https://shieldcn.dev/badge/version-v0.9.9.67.svg?variant=secondary" alt="Version"></a>
<a href="https://github.com/j5onrf/py-agent"><img src="https://shieldcn.dev/badge/Python.svg?variant=branded&brand=python" alt="Language"></a>
<a href="https://github.com/j5onrf/py-agent"><img src="https://shieldcn.dev/badge/C%2B%2B.svg?variant=branded&brand=cplusplus" alt="C++"></a>
<a href="https://github.com/j5onrf/py-agent/blob/main/LICENSE"><img src="https://shieldcn.dev/badge/license-MIT-green.svg" alt="License"></a>
<a href="https://shieldcn.dev/badge/status-beta-blue.svg"><img src="https://shieldcn.dev/badge/status-beta-blue.svg" alt="Status"></a>
</p>
<p>
<code>gguf</code> • <code>llama.cpp</code> • <code>gemini</code> • <code>openrouter</code> • <code>opencode</code>
</p>
<p>
<b>Python runtime (lazy <code>rich</code> + <code>requests</code>) driving a local C++ <code>llama-server</code> backend or cloud APIs.</b><br>
<sub>In-memory Python execution (<code>/py</code>), argument repair adapters (<code>/adp</code>), and instant startup.</sub>
</p>
<br>
<table>
<tr>
<td align="center" width="50%" valign="top">
<h3>Sub-27B (SLM)</h3>
<p><sub>Tool calling, shell triage, and single-turn code edits</sub></p>
<code>LFM3-1.7B*</code> • <code>Ling-3.0-tiny</code><br>
<code>MiniCPM5-2B</code> • <code>Qwen3.5-2B+</code><br>
<code>MiniCPM-V-4.7-1B</code> • <code>LFM2.5-24B-A2B</code>
</td>
<td align="center" width="50%" valign="top">
<h3>27B+ (LLM)</h3>
<p><sub>Reasoning, multi-file refactoring, and sub-agents</sub></p>
<code>Clover-35B-A3B</code> • <code></code><br>
<code>Sage-A1.5-35B</code> • <code>Flint-40B-A2.5B*</code><br>
<code>Qwen3.8-35B-D</code> • <code>Ornith-1.5</code><br>
<code>KAT-Coder-V2.5</code> • <code>Tiel-Coder-35B</code><br>
<code>Occamy-1.0</code> • <code>Nex-N2.5-mini</code><br>
<code>Qwen3.8-27B</code> • <code>Qwen3.8-Flash</code><br>
<code>DeepSeek‑V4.1</code>
</td>
</tr>
</table>
<p>
* Benchmark baselines • Run <code>model select</code> in your terminal to switch models
</p>
<p>
<sub><b>Cloud Endpoints:</b> <a href="https://huggingface.co/spaces?category=text-generation&sort=trending">Hugging Face Spaces</a>, <a href="https://tokenharbor.ai">TokenHarbor</a>, <a href="https://models.dev">OpenCode</a>, and <a href="https://openrouter.ai">OpenRouter</a><br>
<b>Free Endpoints:</b> <a href="https://opencode.ai"><code>big-pickle</code></a> (OpenCode) • <a href="https://tokenharbor.ai"><code>deepseek-v4.1-flash:free</code></a> (TokenHarbor) • <a href="https://openrouter.ai/models?variant=free"><code>openrouter/free</code></a> (OpenRouter)</sub>
</p>
</div>
<br>
---
```console
~ ❯ ai
╭─ ○ ────────────────────────────────────────╮
│ InternScience-Sage-A1.5 │
│ chat │
╰────────────────────────────────────────────╯
· · ○ · · · · · · · · · · · · · · · · · · · · ·
· InternScience-Sage-A1.5 · · · · · · · · · ·
· chat · · · · · · · · · ·
· · · · · · · · · · · · · · · · · · · · · · · ·
· · ○ · · · · · · · · · · · · · · · · · · · ··
· InternScience-Sage-A1.5 ·
· chat ·
· · · · · · · · · · · · · · · · · · · · · · ··
❯ █
```
<div align="center">
<p><sub>Select box themes with <code>/box [1-3]</code>. Workspace details in the <a href="projects/Readme.md"><b>Workspace Manual</b></a>.</sub></p>
</div>
<br>
---
<h2 align="center">Execution Surfaces</h2>
<div align="center">
| Command | Mode | Scope |
| :--- | :---: | :---: |
| `[query]` | **Shell Intercept** | Intent matching via [`ai-context.md`](ai-context.md) |
| `ai "<query>"` | **Single Query** | Direct prompt response |
| `ai` | **Interactive Chat** | Multi-turn chat session |
| `ai init [path]` | **Workspace Agent** | Project workspace session |
</div>
<p align="center">
<sub><code>/yolo</code> gate • <code>/py</code> repl • <code>/adp</code> adapters • <code>/t</code> reasoning • <code>/task</code> loop goal • <code>/s</code> skills • <code>/a</code> all meta • <code>/md</code> markdown • <code>/calm</code> zen</sub><br>
<sub><code>/m</code> map • <code>file</code> load • <code>/mem</code> memory • <code>/com</code> compact • <code>/gnd</code> search • <code>/hs</code> hindsight • <code>/tok</code> tokens • <code>/sync</code> index-map • <code>/stats</code> speed</sub><br>
<sub><code>/tr</code> • <code>/bot</code> • <code>/tui</code> • <code>/t3</code> • <code>/dsh</code> • <code>/zed</code> • <code>/webui</code> • <code>/v</code> • <code>/tts</code> • <code>/box</code> • <code>-save</code> / <code>-load</code> • <code>/c</code> clear • <code>/r</code> reset</sub>
</p>
<br>
---
<h2 align="center">Runtime Architecture</h2>
* **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.
<br>
---
<h2 align="center">Benchmark & Efficiency</h2>
<p align="center">
Decision-grade evaluation across 7-stage agentic challenges (<code>eval-stack</code>).<br>
<sub>Results scale with tuning: select a model foundation and optimize for your workload via profile directives, sampling flags, and <code>/adp</code>.</sub>
</p>
<div align="center">
### 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)** |
<br>
| 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** |
<br>
| 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 |
<br>
| 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 |
</div>
<br>
---
<h2 align="center">Client Surfaces</h2>
<p align="center">
Py-Agent is surface-agnostic. Switch seamlessly between terminal, web gateway, and desktop IDE:
</p>
<div align="center">
<table>
<tr>
<td align="center" width="210" valign="top">
<br>
<h3><a href="https://t3.codes">T3 Code IDE</a></h3>
<p><code>/t3</code> · <code>/t3 web</code></p>
<sub>Desktop control plane using ACP JSON-RPC 2.0.</sub>
<br><br>
</td>
<td align="center" width="210" valign="top">
<br>
<h3>Textual PyTUI</h3>
<p><code>/tui</code></p>
<sub>Terminal workspace built with Textual and <code>uvloop</code>.</sub>
<br><br>
</td>
<td align="center" width="210" valign="top">
<br>
<h3>llama.cpp WebAgent</h3>
<p><code>/webui</code> · <code>/web</code></p>
<sub>Tool reverse proxy for <code>llama-server</code>.</sub>
<br><br>
</td>
</tr>
</table>
<p>
<sub><code>/tr</code> ThinkRail • <code>/bot</code> OpenBot • <code>/v</code> Voice-to-Text (<code>:9999</code>) • <code>/tts</code> Neural Kokoro Audio • <code>/dsh</code> DeepSeek Harness • <code>/zed</code> Editor</sub>
</p>
</div>
<br>
---
<h2 align="center">Setup & Installation</h2>
### 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
```
<details>
<summary><b>View Example (<code>~/.config/py-agent/.env.example</code>)</b></summary>
```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"
```
</details>
<br>
---
<h2 align="center">Documentation & License</h2>
* **<a href="projects/Readme.md">Workspace Manual</a>**
* **<a href="modules/Readme.md">System Architecture</a>**
* Licensed under the **[MODIFIED MIT LICENSE](LICENSE)**