zkzkAgent 🚀

📋 Overview

zkzkAgent is a sophisticated, privacy-first AI assistant built specifically for Ubuntu/Debian-based Linux systems. Powered by LangGraph for intelligent workflow automation and Ollama for completely local LLM inference, it transforms how you interact with your system—all while keeping your data securely on your machine, with zero cloud dependencies.

✨ Key Features

🤖 Intelligent Automation

• Background Deployment - Execute long-running scripts with AI-assisted decision making
• Process Management - Natural language control for monitoring and managing processes
• Smart File Operations - Intelligent file searching, reading, writing with safety limits
• Context-Aware Actions - AI understands scripts and code in your specific context
• Real-Time Streaming - Token-by-token responses for immediate feedback
• Low-Latency Startup - Adaptive model warm-up for quick readiness

🌐 Network Awareness

• Auto-Connectivity Check - Verifies internet access before network operations
• Self-Healing Wi-Fi - Automatic reconnection via nmcli when disconnected
• Network-First Operations - Reliable browser, deployment, and search tasks
• DuckDuckGo Integration - Web search, image search, and media downloads

🔒 Safety & Security

• Human-in-the-Loop - Explicit confirmation for all system-modifying operations
• Dangerous Tool Protection - Safeguards for file operations, trash, tmp management
• Local Execution - Fully offline-capable with no cloud dependencies
• Privacy-First - All inference and actions stay on your device

📦 Safe Local Package Management (NEW!)

• 100% Offline - No web searches required for known packages
• Smart Installation Order:
  • Special cases (Postman → snap)
  • Flatpak for GUI applications (preferred)
  • Snap as fallback
  • apt for CLI/system tools
• Safety Features:
  • Installation verification checks
  • Dry-run previews with full command output
  • Explicit confirmation before any action
  • Post-installation verification

🎤 Voice Interaction (Optional)

• Voice Input - Whisper-based speech recognition with VAD and noise reduction
• Text-to-Speech - Natural responses via Coqui TTS
• Hands-Free Operation - Complete system control with voice commands

🛠️ Comprehensive Toolset

With 23+ specialized tools categorized for your needs:

🏗️ Architecture

zkzkAgent leverages a sophisticated cyclic graph architecture:

graph TD
    A[User Input] --> B[LangGraph State]
    B --> C{AI Decision}
    C --> D[Execute Tool]
    C --> E[Need Confirmation?]
    E -->|Yes| F[Pending Confirmation]
    F --> G[User Approves]
    G --> H[Run Protected Action]
    E -->|No| H
    H --> I[Update State]
    I --> B

🚀 Getting Started

Prerequisites

• OS: Ubuntu 20.04+, Debian 11+, or other Debian-based distributions
• Python: 3.10 or higher
• RAM: 8-16 GB recommended
• Storage: 5-10 GB for models
• Ollama: Installed with a model (qwen recommended)

Quick Installation

# Clone the repository
git clone https://github.com/zkzkGamal/zkzkAgent.git
cd zkzkAgent

# Run the installation script
chmod +x install.sh
./install.sh

# Or install manually
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure your model in config.yaml
# Start the assistant
python3 main.py

Configuration

Customize your experience through prompt.yaml and model configurations:

# Example config.yaml snippet
model:
  name: "qwen2.5:7b"
  temperature: 0.7
  context_length: 4096

voice:
  enabled: false
  tts_engine: "coqui"
  vad_threshold: 0.5

safety:
  require_confirmation: true
  max_file_size: 10485760  # 10MB

💡 Usage Examples

# File Operations
> find all Python files modified in the last day
> create a new project folder called "myapp" with a basic structure

# Process Management
> show me running processes using more than 1GB RAM
> kill the process using port 3000

# Package Management (NEW!)
> install Visual Studio Code
[Preview] Would run: sudo snap install code --classic
Proceed? (yes/no): yes
Installing... Done!

> check if Firefox is installed
> upgrade all system packages

# Network Tasks
> search DuckDuckGo for "Linux AI assistants"
> download the first image result to my Pictures folder

# Voice Mode
> (after enabling voice) "what's my system uptime?"

🛡️ Safety First

zkzkAgent prioritizes system safety with multiple layers of protection:

• Explicit Confirmation: All system-modifying actions require user approval
• Dry-Run Previews: See exactly what will execute before confirmation
• Post-Action Verification: Confirms successful completion
• Rollback Planning: Smart fallbacks for failed operations
• Input Validation: Prevents command injection and unsafe operations

📊 Performance

• Startup Time: < 2 seconds (with warm model)
• Response Latency: 50-200ms for tool execution
• Memory Usage: 200-500MB base + model size
• CPU Usage: 10-30% during inference

🤝 Contributing

We welcome contributions! See our Contributing Guidelines for details.

Development Setup

git clone https://github.com/zkzkGamal/zkzkAgent.git
cd zkzkAgent
python3 -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt
pre-commit install

🙏 Acknowledgments

• LangGraph for stateful workflow management
• Ollama for local LLM inference
• Coqui TTS for text-to-speech
• OpenAI Whisper for speech recognition

📞 Support

• Documentation: Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions