🤖 GUA (General Usage Agent)

GUA is a powerful, autonomous AI assistant built on Blazor Server (.NET 10). It serves as a multi-modal orchestrator capable of managing file systems, executing terminal commands, browsing the web, and processing media (TTS/Transcription) through a unified agentic interface.

---

📑 Table of Contents

1. 🚀 Features
2. 🧠 Model Optimization
3. 📦 Installation Guide
   • Playwright Setup
   • llama.cpp Setup
   • whisper.cpp Setup
   • Kokoro TTS Setup
4. ⚠️ Limitations & Known Issues
5. 🛠️ Tools Reference
6. 📁 Project Structure

---

🚀 Features

• Autonomous Agent Mode: Multi-turn reasoning loops (up to 50 turns) using tool-calling to solve complex tasks.
• Persistent Terminal: Real-time shell execution with session persistence across messages.
• Deep Web Research: Google Search and Playwright-powered browser automation.
• Media Suite:
  • Voice cloning/Synthesis via Kokoro.
  • Video-to-audio extraction and burning subtitles with FFmpeg.
  • High-accuracy transcription via Whisper.
• Repository Ingestion: Analyze entire GitHub repositories in one go using the GitIngest tool.
• Modern UI: Dark-themed Blazor interface with markdown support and collapsible tool-execution logs.

---

🧠 Model Optimization

GUA is specifically tuned for high-parameter local models and state-of-the-art APIs:

• Primary Optimization: Qwen3.5-35B-A3B (Optimized for reasoning and tool-calling accuracy).
• Secondary Support: Fully compatible with DeepSeek-V3/R1 via API.
• Local Inference: Designed to work seamlessly with llama-server.exe providing the OpenAI-compatible endpoint.

---

📦 Installation Guide

1. Playwright (Browser Automation)

Used for the browser_use tool to navigate real websites.

# Install the Playwright CLI tool
dotnet tool install --global Microsoft.Playwright.CLI

# Build the project to generate the executable
dotnet build

# Install the required browser (Chromium)
# Note: Check your bin path (net10.0)
pwsh bin/Debug/net10.0/playwright.ps1 install chromium

2. llama.cpp (Inference Server)

GUA requires an OpenAI-compatible API endpoint.

1. Download: llama.cpp Releases.
2. Model: Download the GGUF for Qwen3.5-35B-A3B.
3. Run:

   llama-server.exe -m path/to/Qwen3.5-35B-A3B.gguf --port 8080 -c 262144

3. whisper.cpp (Transcription Server)

1. Download: whisper.cpp Releases.
2. Model: Use ggml-large-v3.bin.
3. Run:

   whisper-server.exe -m models/ggml-large-v3.bin --port 8081

4. Kokoro TTS (Python)

The text-to-speech service requires the Kokoro Python implementation.

1. Navigate to your Kokoro folder.
2. Setup: python -m venv venv and pip install flask kokoro soundfile.
3. Run the server on port 8082.

---

⚠️ Limitations & Known Issues

Current Limitations

• No Persistence: There is no database or LocalStorage implementation. Refreshing the browser will wipe the current chat history and session state.
• No Multi-user: The application is designed for local, single-user use. Session sandboxing is internal but not authenticated.
• UI Desyncs: The UI may occasionally flicker or desync during high-speed agent streaming or complex parallel tool calls.

Known Technical Issues

• Zombie Terminal Processes: If the application crashes or is force-closed during a command execution, the underlying cmd.exe or bash process may remain running in the background and must be closed manually via Task Manager.
• Playwright Cleanup: The Chromium window opened by Playwright often stays open after the main program ends. These windows must be closed manually.

---

🛠️ Tools Reference

Category	Tools
Filesystem	create_file, read_file, edit_file, delete_file, list_directory, zip_directory, unzip_file, create_pdf
Terminal	run_command, read_terminal_output
Web	web_search, scrape_url, browser_use, git_ingest
Media	extract_audio, transcribe_audio, burn_subtitles, text_to_speech, merge_audio

---

📁 Project Structure

GUA_Blazor/
├── Components/       # UI Layer (Pages, Layouts, Modals)
├── Helper/           # SessionSandbox (Path security logic)
├── Models/           # Data objects and System Instructions
├── Service/          # AIService (Orchestrator) and Media Wrappers
├── Tools/            # AI Tool Definitions
│   ├── Filesystem/   # File IO
│   ├── Terminal/     # Shell Execution
│   ├── Web/          # Playwright & Scrapers
│   └── TTS/          # Audio/Video processing
├── wwwroot/          # Styles and Client-side JS
└── run_all_servers.bat # Batch script for local dependencies

---

Built with ❤️ using .NET 10 and Blazor Server.