Fetch is a local CLI agent. Currently adding Laya to decide tool vs chat, Needle 3 to run tools locally, and local models (or cloud) to write the final answer. (Planning Stage)

User Query │ ▼ ┌────────────────────────────────────┐ │ Stage 1: Router │ │ Laya (Intent & Safety Triage) │ └─────────────────┬──────────────────┘ │ ┌───────────────┴───────────────┐ ▼ ▼ [ Tool Intent ] [ Conversational ] │ │ ▼ │ ┌───────────────────┐ │ │ Cactus Needle 3 │ │ │ (JSON Extractor) │ │ └─────────┬─────────┘ │ │ │ ▼ │ Execute Local Tool │ │ │ ▼ │ ┌─────────────────────────────────────────▼─┐ │ Stage 3: Final Answer │ │ Local SLM / LLM / Cloud Model │ │ (Synthesize result or reply to user) │ └───────────────────────────────────────────┘

---

<sub>1. Router (Laya): Decides tool vs chat in ~35ms.  •  2. Tool Runner (Needle 3): Runs tools locally on-device.
3. Final Answer (Local/Cloud): Writes the response using Ling, Occamy, or Gemini.</sub>

Fetch

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.}

Sub-27B Compact (SLM) Ultra-fast tool calling, shell triage & single-turn code edits Ling-3.0-tiny*  •  LFM2.5-8B MiniCPM5-2B  •  Qwen3.5-2B+

27B+ Autonomous (LLM) Deep reasoning, multi-file refactoring & recursive sub-agents Occamy-1.0*  •  Nex-N2.5-mini KAT-Coder-V2.5  •  Qwen3.8-27B Qwen3.6-35B  •  Ornith/Tiel Qwen3.8-Flash-Next  •  DeepSeek‑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
╭─  Fetch  ────────────────╮
│     model:  Occamy-1.0   │
│ directory:  ~            │
│   profile:  chat         │
│  database:  stateless    │
╰──────────────────────────╯

❯ █

_{Customize box themes with /box [1-8]. For detailed workflows, read the Workspace Manual.}

---

Execution Surfaces

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

_{Session Hotkeys: /com compact  •  /adp adapters  •  /py iPython  •  /gnd grounding  •  /hs hindsight}

---

Runtime Architecture

• Hardened Containment: Non-bypassable [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.
• Self-Healing Adapters (/adp): Out-of-band argument normalizer repairing malformed JSON and bracket syntax on small models. Opt-in.
• Deterministic Diffing: 3-stage resilient replacement (Exact → Whitespace → 88% Fuzzy) verified by Python AST syntax guards to eliminate corruption.

---

Benchmark & Efficiency

_{Synthesizing battle-tested patterns from Pi (3-zone context compaction), SmallCoder (resilient 3-stage AST diffs),
Unsloth AI (out-of-band schema healing), and OKF (git-native persistent memory).}

Sub-27B Challenge	Without Adapters	With /adp Active
AG-03 (Surgical Edit & Test)	16 turns	6 turns
AG-07 (In-Memory Batch Loop)	14 turns	2 turns
Full Suite Pass Rate	Retries / Failures	100% (7/7)

Operational Tier	Fetch	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 (11 tools + AST)	2,500–4,000+ tokens
Idle Overhead	0% CPU / 0 MB RAM	Node.js Active

---

Client Surfaces & Environments

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

PyCode IDE /pyc · /pyc web Local-first React desktop workspace with ACP JSON-RPC 2.0.

Textual PyTUI /tui Full-screen reactive terminal workspace with uvloop, socket IPC.

llama.cpp WebAgent /webui · /web Autonomous tool reverse proxy for official llama-server.

_{/v Voice-to-Text (:9999)  •  /tts Neural Kokoro Audio  •  /pybot Web Assistant}

---

Setup & Installation

1. Install fetch

# 1. Install dependencies (Arch/CachyOS or pip)
sudo pacman -S python-rich python-requests

# 2. Clone repository
git clone https://github.com/j5onrf/fetch.git ~/.config/fetch

# 3. Register shell hook (bash / zsh)
echo '[ -f "$HOME/.config/fetch/ai-hook.sh" ] && \
source "$HOME/.config/fetch/ai-hook.sh"' >> ~/.bashrc
source ~/.bashrc

2. Configure Providers (.env)

# Option A: Interactive TUI Selector
model select

# Option B: Manual Configuration
cp ~/.config/fetch/.env.example ~/.config/fetch/.env

📋 View Example (~/.config/fetch/.env.example)

# ==============================================================================
# Fetch 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"

---

Documentation & License

• Workspace Manual
• System Architecture
• Licensed under the permissive MODIFIED MIT LICENSE