DEV Community: zkaria gamal

I Spent 4 Hours Fixing Broken Imports – So I Built a Complete Agentic AI Tutorial

zkaria gamal — Mon, 06 Apr 2026 08:06:23 +0000

*A true story from last month: *

I was building an intelligent agent using LangGraph + MCP, and I asked Claude for the latest code to implement a Multi-Node Agent.

It gave me a clean-looking code. I copied it, ran it… Import error.

I went to GPT-4o. Different code, but still outdated imports.

Tried Gemini. Same problem.

I lost over 4 hours tweaking imports, updating StateGraph, digging through LangChain's changelog… until I hit complete frustration.

That's when I said: Enough.

I decided to do something completely different.

I started collecting only the modern code that actually works in 2026, tested it myself, fixed what was broken, and organized everything in one place.

The result?

🔥 Agentic AI Tutorial

A complete, up-to-date reference for building Agentic AI using the latest versions of LangChain + LangGraph + MCP.

Why I built this repo

To end the daily struggle of "outdated/copied-pasted-broken code"
To help you build powerful agents without wasting hours on debugging
To give you one trusted, updated reference where everything actually runs

What's inside?

Chapter	Content
1	LLM basics + Streaming + Advanced Prompts
2	LangChain LCEL + Tools + Chains
3	Advanced Memory + Full RAG (Chroma & FAISS)
4	Advanced LangGraph (ReAct, Router, Multi-Agent, Self-Refine, Human-in-the-Loop)
5	Complete MCP + FastMCP Server + Multi-Node Agent System (Router → Execution → Summary)

Everything is available as Jupyter Notebooks + Python files, ready to run.

Works locally (Ollama) and cloud (GPT-4o, Gemini).

A question for you:

Are you already at Chapter 5, or still at the beginning?

Drop a comment below 👇

AgenticAI#LangChain#LangGraph#MCP#Python#LLM#GenerativeAI#Opensource

Building Production-Ready Agentic AI: From Tutorial to High-Performance Serving (vLLM vs SGLang Benchmark)

zkaria gamal — Sun, 29 Mar 2026 11:14:24 +0000

Building Production-Ready Agentic AI: From Tutorial to Real-World Serving Benchmark

Hey devs 👋

If you’ve been building ReAct agents with LangGraph, you’ve probably faced the same question I did:

“I can build a cool agent in a tutorial… but which serving engine should I actually use in production?”

That’s why I connected my two repositories:

Agentic-AI-Tutorial → Learn how to build a full ReAct agent from scratch
concurrent-llm-serving → Benchmark vLLM vs SGLang under heavy agent load

Now the two repos are linked: the exact same agent from the tutorial is included as simpleagent/ inside the benchmark repo.

What’s Inside the Agentic AI Tutorial

You start with a clean, production-style LangGraph ReAct Agent that has three nodes:

Conversation – Handles multi-turn dialogue
Act – Calls real tools (DuckDuckGo Search + Calculator)
Summarize – Processes long document context (10k+ tokens)

Everything is explained step-by-step:

Tool calling
Structured outputs
Memory management
Error handling

Repo → https://github.com/zkzkGamal/Agentic-AI-Tutorial

The Missing Piece: Which Engine Should You Serve It With?

Tutorials usually stop at “run it locally.”

I wanted to go further.

So I took the exact same agent and stress-tested it under 3 concurrent sessions (5 turns each, up to ~25,000 tokens total context) using:

Model: Qwen3.5-0.8B (single GPU)
Engines: vLLM vs SGLang

Full benchmark report is here:

README_agent_benchmark.md

High-Level Results

|-------------------------------|---------------|----------------|-------------|

| Total Wall Time (3 sessions) | 229.8s | 255.8s | vLLM (-11%) |

| Context Limit Errors | 0 | 2 | vLLM |

| Successful Sessions | 3/3 | 3/3 | Tie |

Node-Level Breakdown (this is where it gets interesting)

Act Node (Tool Calling) → SGLang wins by 71%

Thanks to RadixAttention prefix caching — perfect for repeated tool calls.

Summarize Node (Long Context) → vLLM wins

Much more stable when context balloons to 10k+ tokens.

Verdict:

Use SGLang if your agents do a lot of tool calling in loops.
Use vLLM if your agents handle heavy RAG or summarization workloads.

How to Use Both Repos Together (The Full Flow)

Clone the tutorial and build your agent


   git clone https://github.com/zkzkGamal/Agentic-AI-Tutorial.git

   cd Agentic-AI-Tutorial

Move to the serving benchmark repo (now includes simpleagent/)


   git clone https://github.com/zkzkGamal/concurrent-llm-serving.git

   cd concurrent-llm-serving/simpleagent

Run the exact same agent with either engine using the provided launch scripts.

Everything is documented — you can literally go from learning the agent pattern to benchmarking production serving in minutes.

Why This Matters

Most agent tutorials leave you with a notebook.

This project gives you the complete pipeline:

Build the agent ✅
Understand the serving trade-offs ✅
Choose the right engine for your workload ✅
Deploy it at scale ✅

Try It Yourself

Tutorial repo: Agentic-AI-Tutorial
Benchmark repo (with integrated simpleagent): concurrent-llm-serving

Would love to hear from you:

What serving engine are you using for your agents today?
Have you noticed the same trade-offs between vLLM and SGLang?
Want me to add more models / workloads / frameworks (CrewAI, AutoGen, etc.)?

Drop your thoughts below 👇

Happy building!

— zkzkGamal

Concurrent LLM Serving: Benchmarking vLLM vs SGLang vs Ollama

zkaria gamal — Mon, 16 Mar 2026 08:47:59 +0000

I wanted to know exactly how the three most popular open-source LLM serving engines perform when real users hit your server at the same time. So I built this educational repo and ran identical tests on a single GPU.

Repo: https://github.com/zkzkGamal/concurrent-llm-serving

Model: Qwen/Qwen3.5-0.8B

Hardware: Single GPU

Concurrency: 16 simultaneous requests (only 4 for Ollama)

Task: Diverse AI & programming questions (max_tokens=150)

The Results (spoiler: one engine destroys the others)

|----------|----------|------------|-----------------------|----------------------------|

| SGLang | 16 | 2.47s | 0.68–2.46s | True parallel batching + RadixAttention |

| vLLM | 16 | 11.26s | ~10.25–11.26s | PagedAttention + continuous batching |

| Ollama | 4 | 134.72s| 26–134s | Sequential (time-sliced) |

SGLang was 4.6× faster than vLLM and completely smoked Ollama.

Why the huge difference? The Core Algorithms

1. KV-Cache & Memory Management

Every LLM needs to store Key/Value vectors for previous tokens. Without smart caching, you waste VRAM and kill concurrency.

vLLM → PagedAttention (treats KV cache like OS virtual memory pages → no fragmentation)
SGLang → RadixAttention (trie-based prefix tree → shares any common prefix across requests automatically)

2. Continuous Batching

Instead of waiting for a full batch, new requests join the GPU forward pass instantly. Both vLLM and SGLang do this. Ollama does not.

3. Other Tricks

SGLang: Chunked prefill + custom Triton kernels + zero warm-up
vLLM: Broad model support + CUDA graph warm-up
Ollama: GGUF quantization + llama.cpp (great for single-user, terrible for concurrency)

When Should You Use Each Engine?

SGLang → Maximum throughput, structured JSON/regex output, production serving
vLLM → Stability, 50+ model architectures, when you need reliability over raw speed
Ollama → Quick prototyping, local development, zero-config experience

How to Reproduce the Tests Yourself

The repo includes everything:

install.sh (one-click setup)
sglang_concurrent_test.py / vllm_concurrent_test.py / ollama_concurrent_test.py
Raw logs + result markdowns
Video demos (test_sglang.mkv, ollama_test.mkv)

Just clone and run:


git clone https://github.com/zkzkGamal/concurrent-llm-serving

cd concurrent-llm-serving

bash install.sh

(Full startup commands and API compatibility notes are in the README.)

Project Structure


├── sglang_concurrent_test.py     # 16 concurrent requests

├── vllm_concurrent_test.py

├── ollama_concurrent_test.py

├── install.sh

├── *_results.md                  # Formatted benchmark outputs

└── README.md                     # Full deep-dive guide

Final Thoughts

Concurrent serving is no longer optional — it's table stakes for any serious LLM application. The difference between "works on my machine" and "handles 16 users at once" is huge, and the right engine choice can save you GPUs (and money).

If you're building anything with local LLMs — agents, RAG, chat apps, etc. — I highly recommend trying SGLang first.

⭐ Star the repo if you found it useful!

Feedback, PRs, and questions are all welcome.

What engine are you using right now? Have you hit concurrency limits yet? Drop a comment below 👇

llm #vllm #sglang #ollama #aiserving #machinelearning #opensource #gpu #inference

Building a Production-Ready Agentic AI System with LangGraph and MCP

zkaria gamal — Tue, 10 Mar 2026 12:57:31 +0000

As AI engineers, we often start by giving a massive LLM (like GPT-4) a giant prompt and a long list of Python functions (tools) it can call. This monolithic approach works for simple scripts, but it quickly becomes expensive, slow, and a security risk when the LLM has direct access to sensitive resources like email passwords or file systems.

To move beyond prototypes, we need to separate the "thinking" from the "doing." In this chapter of my open‑source tutorial, we rebuild an agentic assistant using two powerful technologies:

LangGraph – for routing logic across specialized nodes.
Model Context Protocol (MCP) – for secure, decoupled tool execution.

The result is a production‑ready, decoupled AI system that is safer, faster, and more reusable.

👉 GitHub Repository: Agentic-AI-Tutorial

🏗️ Architecture: Brain vs. Hands

Instead of a single monolithic agent, our application consists of two distinct parts communicating over Server‑Sent Events (SSE).

1. The Hands: FastMCP Server

All physical tools (math logic, Python SMTP/IMAP email operations) live in a standalone ASGI server running on port 8000. Using the Model Context Protocol (an open standard), we expose these functions securely.

# McpServer/tools/weather.py
from server import mcp

@mcp.tool()
def get_temperature(city: str) -> str:
    """Get the current temperature for a given city."""
    return f"The weather in {city} is 72°F."

Thanks to MCP, the server automatically reads the docstrings and type hints, generating a standardized JSON schema. Crucially, the LangGraph agent never possesses your passwords nor directly executes this code – it only sends requests via the protocol.

2. The Brain: LangGraph Orchestrator

On the other side, we built a StateGraph with distinct nodes to handle user requests efficiently.

router.py (The Fast Path)

Uses a fast, cheap LLM to classify the user's intent: math, email, or conversation.
execute.py (The Heavy Lifter)

If the router chooses a tool‑based intent, this node takes over. It uses LangChain’s create_tool_calling_agent and dynamically binds to the remote MCP server.
summarize.py (The Formatter)

Takes the raw JSON output from the MCP server and uses an LLM to synthesize a polite, conversational response for the user.
conversation.py (The Chitchat Fallback)

If the user just says “Hello,” we skip all heavy execution. This node feeds the conversation history directly to the LLM, saving tokens and time.

🚀 Why This Matters

Security & Isolation

The MCP server acts as a secure boundary. You can host the LangGraph agent in the cloud while running the MCP server on your local corporate intranet to access private databases – all without exposing credentials.

Reusability

Once you build an MCP server (like our Mail/Math server), you can plug it into any MCP‑compatible client. The same tools work in LangChain, Claude Desktop, Cursor, or your own custom UIs – no rewriting needed.

Run It 100% Offline with Ollama

Don’t want to pay for OpenAI API keys? Standardising with LangChain and MCP makes swapping LLMs trivial. You can run the entire workflow locally and for free using Ollama!

Simply update the agent nodes (e.g., router.py, execute.py) from:

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-3.5-turbo")

to:

from langchain_ollama import ChatOllama
llm = ChatOllama(model="llama3.1", temperature=0)

Because LangChain provides unified interfaces, the node routing and tool calling continue to work seamlessly with your local Llama 3 model.

💻 Try It Yourself!

All code, diagrams, and step‑by‑step instructions are available in Chapter 5 of my open‑source tutorial repository:

👉 GitHub: Agentic-AI-Tutorial

Clone it, spin up the FastMCP server, and watch the LangGraph nodes gracefully orchestrate tool execution!

📸 Demo: From User Request to Delivered Email

Here’s a real example of the agent in action, showing the entire flow from a user asking to send an email to the confirmation that it actually arrived.

1. The User Request & Agent's Execution

In the screenshot below, you can see the user submitting a request: "send email to Gamal saying hello from the agent". The LangGraph router correctly classifies this as an email intent, and the execute node invokes the remote MCP server's email tool. The agent then reports back that the email was sent successfully.

2. Proof of Execution

To verify that the MCP server actually performed the task—and that the agent wasn't just "hallucinating" success—we can check the real destination. The following screenshot shows the actual "Gamal" inbox with the email delivered exactly as requested. This confirms the secure, end-to-end functionality of the decoupled architecture.

This walkthrough visually confirms that the brain (LangGraph agent) correctly interprets the request and delegates to the hands (MCP server), which securely performs the action without exposing any credentials or internal logic to the agent itself.

🧠 What’s Next?

What tools are you planning to build for your MCP servers? Let me know in the comments below – I’d love to hear about your ideas and see what you create!

Follow me for more tutorials on production‑ready AI systems.

I Built a Local AI Agent That Plans Before Executing Linux Commands (Now Fully Dockerized)

zkaria gamal — Tue, 03 Mar 2026 11:05:29 +0000

I Built a Local AI Agent That Plans Before Executing Linux Commands (Now Fully Dockerized)

Most “AI agents” that run shell commands follow a simple flow:

User prompt → LLM → Execute command

That’s powerful.

It’s also dangerous.

So I built ZkzkAgent, a fully local Linux AI assistant that thinks and routes before it acts.

🚨 The Problem with Most Terminal AI Wrappers

A lot of open-source agents do this:

Send user prompt to an LLM
Generate shell command
Execute immediately

There’s:

No routing logic
No conditional branching
No confirmation flow
No safety model

For real system environments, that’s risky.

🧠 What Makes ZkzkAgent Different

ZkzkAgent introduces a structured agent architecture:

User
  ↓
Router Node
  ├── Conversation Node
  ├── Retrieval Node
  └── Tool Execution Node
        ↓
  Confirmation (if needed)
        ↓
  Execution

Instead of blindly executing:

✔ It decides what type of task this is
✔ It branches based on context
✔ It enforces confirmation for dangerous actions
✔ It logs and returns results back into the conversation loop

Built with:

LangGraph (stateful agent flow)
Ollama (local LLM execution)
Explicit tool safety filters

🔐 Safety Design Principles

I designed ZkzkAgent with 5 rules:

No hidden execution
Human confirmation for destructive commands
Deterministic routing
Full local-first architecture
Transparent tool layer

This makes it suitable for:

Developers
Linux power users
Self-hosted environments
AI experimentation

🐳 New: Docker Support

One of the biggest barriers to adoption was setup complexity.

Now ZkzkAgent includes official Docker support.

You can spin it up in a clean, isolated environment without touching your base system.

git clone https://github.com/zkzkGamal/zkzkAgent
cd zkzkAgent
docker build -t zkzkagent .
docker run -it zkzkagent

Reproducible.
Isolated.
Clean.

🎯 Why I Built This

I’m deeply interested in agentic AI systems — not just chatbots.

I wanted to experiment with:

Router-based architectures
Branching decision logic
Human-in-the-loop safety
Local execution models

Instead of building another “AI assistant,” I focused on architecture control.

🔮 What’s Next

Planned improvements:

More granular permission layers
Plugin-style tool system
Sandboxed execution modes
Better observability dashboard

💬 Feedback Welcome

If you’re experimenting with:

AI agents
LangGraph workflows
Local-first LLM systems
OS-level automation

I’d love your thoughts.

Repository:
https://github.com/zkzkGamal/zkzkAgent

I Gave an Open-Source AI Full Access to My Linux Terminal (And Lived to Tell the Tale)

zkaria gamal — Thu, 26 Feb 2026 11:16:55 +0000

The Problem with Cloud AI

We all love ChatGPT and Claude, but there is a fundamental disconnect for developers: they can't actually do things on your machine.

If I want an AI to install a package, troubleshoot my system logs, run a script, or clean up my temporary files, I have to constantly copy-paste commands back and forth.

That felt incredibly outdated for 2026.

So, I decided to build zkzkAgent: a fully autonomous, local AI assistant designed specifically for Linux System Management. No expensive API keys, no data leaving my machine, and full terminal execution capabilities.

Here is how I built it—and how you can build one too.

🚀 Meet zkzkAgent v3

zkzkAgent (now in v3!) is a human-in-the-loop autonomous agent that runs entirely on your local machine using Ollama, LangChain, and LangGraph.

It doesn't just answer questions. It takes action.

Key Features:

🛠️ Autonomous System Management: It can find files, read logs, check running processes, and kill rogue nodes.
📦 Safe Package Management: It features conflict-aware package management, meaning it knows how to install dependencies without breaking your Debian/Ubuntu setup.
🗣️ Voice Interactive: Integrated with Kokoro TTS and Whisper for seamless voice interactions. I built it so we can just talk to our systems.
🛡️ Human-in-the-Loop Security: It can read files and search the web by itself, but for dangerous actions (like rm or installing packages), it strictly requires your explicit confirmation before executing.

🏗️ How It Works (The Architecture)

To make it reliable, I used a Router-Planner-Executor architecture built with LangGraph:

The Router: When you prompt the agent, a sophisticated classification node decides if the request is "Conversational", needs "Direct Execution" (like a simple ping), or requires "Planning" (multi-step complex tasks).
The Planner: For complex tasks, the agent drafts a step-by-step execution plan natively.
The Executor: The agent loops through the plan, sequentially using specific tools (like run_command, check_internet, find_file) one at a time. It observes the output of each command before deciding to proceed.

Because it runs entirely locally, it's fast, free, and completely private. It feels like having a junior sysadmin sitting in your terminal.

🎓 Want to Build Your Own? (Free Tutorial!)

see this post

Learn Agent AI

💬 Let's Discuss

I'm currently working on improving its contextual awareness and adding a sleek web UI.

I'd love to hear your thoughts!
Would you trust an autonomous agent to run commands on your system? What safety checks would you consider absolutely mandatory?

Let me know in the comments below! 👇

If you found this interesting, I'd appreciate a 💖 or 🦄 to help others find it!

Build Autonomous AI Agents Step-by-Step – My Free LangChain + LangGraph Tutorial (2026 Edition)

zkaria gamal — Tue, 24 Feb 2026 13:20:05 +0000

Hey dev community! 👋 **
I'm Zkzk from Cairo, and I've been deep in agentic AI lately. After struggling to find a clear, hands-on path from "hello LLM" to "production-ready autonomous agent," I built my own tutorial repo: **Agentic-AI-Tutorial.

It's a 5-chapter progression (4 complete, Chapter 5 launching soon) with executed Jupyter notebooks, local Ollama support, OpenAI/Gemini options, and a real-world capstone: a Personal Finance Tracker Agent that tracks expenses, analyzes patterns with RAG, and gives smart advice via FastAPI + ChromaDB.

If you're in Cairo or anywhere grinding on AI agents in 2026, this is for you. Let's break it down!

Why Agentic AI Matters Right Now

LLMs are powerful, but they're stateless chatbots without memory or tools.

Agentic AI changes that: agents reason, use tools, remember context, self-refine, and even collaborate.

My tutorial shows you how — practically, reproducibly, and locally-first (privacy + zero cost with Ollama).

Chapter Breakdown: The Journey

Chapter 1: LLM Foundations

Call models from Ollama (local Gemma/Qwen), OpenAI (gpt-4o-mini), Gemini.

Learn streaming, system prompts, token counting.

Notebook highlights:

Simple chat
Emoji-styled responses
Multi-provider switching

Great for beginners testing local vs. cloud.

Chapter 2: LangChain Chains & Tools

Build interactive workflows with LCEL.

Add memory (RunnableWithMessageHistory), bind tools, create routers/parallel chains.

Demo: Stateful chat that remembers your name + routes queries dynamically.

Chapter 3: Memory + RAG Pipelines

Persistent memory types + local embeddings (sentence-transformers).

RAG setup with ChromaDB prep (full vector store coming in Ch5).

Focus: Cost/privacy with everything local.

Chapter 4: LangGraph Orchestration (My Favorite!)

Move from chains to graphs.

Build ReAct agents, multi-agent collab, self-refinement loops.

Notebook magic:

Graph visualization with Graphviz (nodes/edges appear live!)
State updates in real-time
Tool calls (e.g., math/search)
Conditional routing + human-in-the-loop

This chapter feels "alive" — agents actually think!

Chapter 5: Real-World Capstone – Personal Finance Tracker Agent

Tying it all together:

FastAPI backend for API endpoints (/track_expense, /query_budget)
ChromaDB for embedding/storing transactions + finance tips (local RAG)
LangChain chains for parsing/categorizing/calculating
LangGraph for orchestration: Parse → Retrieve → Analyze → Advise (ReAct + refinement)
Stateful memory per user/session

Example flow:
User: "Groceries at Carrefour, 500 EGP"
Agent: Queries patterns → "Your food spending up 20% this month – try these local deals!"

Deploy locally with uvicorn, ready for extensions (Streamlit UI, EGP exchange rates).

Tech Stack (All Reproducible)

Python 3.10+
LangChain, LangGraph
Ollama (local), OpenAI, Google Gemini
ChromaDB + sentence-transformers
FastAPI + uvicorn
.env for keys, venv for isolation

No paid walls — run everything locally!

Quick Start

Clone: git clone https://github.com/zkzkGamal/Agentic-AI-Tutorial
cd into folder → python -m venv venv → activate
pip install -r requirements.txt
Set up .env (API keys if using cloud)
Run notebooks in order (Chapter1 → Chapter5)

What's Next?

Chapter 5 notebook + deployment guide dropping soon.

Planning extensions: Streamlit frontend, more tools (e.g., currency API), multi-user persistence.

Call to Action

If this resonates:

⭐ Star the repo – it really helps!
🍴 Fork & build your own agent (maybe a Cairo event planner next?)
Comment below: What real-world agent would YOU build with these tools?

Repo: https://github.com/zkzkGamal/Agentic-AI-Tutorial

Let's build agentic AI together

AIAgents #LangGraph #LangChain #OpenSource #Python #Tutorial

zkzkAgent v3 – now with safe, conflict-aware package management

zkaria gamal — Sun, 22 Feb 2026 15:54:02 +0000

Managing Linux is powerful but exhausting. Remembering exact commands, hunting down files, killing rogue processes, checking network, deploying scripts — it adds up fast.

What if you had a local AI that doesn’t just tell you what to do — it actually executes safely, with your approval every time anything dangerous happens?

That’s why I built zkzkAgent — fully offline, no cloud, no telemetry, privacy-first Linux system manager.

Repo → https://github.com/zkzkGamal/zkzkAgent

🚀 What’s Working Really Well

🛠 1. Real System Control
zkzkAgent can:

Search files & folders intelligently
Find & kill processes
Run safe shell commands (ls, date, whoami, etc.)
Deploy scripts with AI help choosing options
Handle all destructive actions (rm, install, remove) with explicit human confirmation

It reads your intent, plans the safest path, and streams results live.

🌐 2. Network Smarts

Auto-checks internet before any web/search/browser task
Reconnects Wi-Fi via nmcli if dropped
Searches DuckDuckGo or grabs images straight to your media folder

Makes remote work, quick lookups, and downloads seamless.

🎤 3. Optional Voice Mode

Whisper for speech-to-text
Coqui TTS (working on XTTS-v2 cloning for better anime-ish voices)
Hands-free control — talk to your system like a real assistant

Type or speak — it responds either way.

🔥 New: Smart Package Management (the part I’m most excited about)
Just added a package tool that actually feels safe & useful for developers:

Human-in-the-loop on every install/remove/upgrade/clean
Detects OS once → uses safe priority to avoid dependency hell:
1. Special cases (no search needed):
  - postman → sudo snap install postman
  - code/vscode → sudo snap install --classic code
  - discord/slack → snap or flatpak
  - zoom → wget .deb + dpkg
2. Flatpak first for GUI/dev tools (sandbox + shared runtimes = fewer fights)
3. Snap next
4. apt only for CLI/system utils
Checks if already installed (command -v / snap list / flatpak list) before suggesting
Shows full command preview + explanation (dry-run style)
Logs every command + your approval
No blind runs — always "yes/no" for anything that touches the system

Example flow — "install postman":

→ planner sees snap path
→ executor: check_internet() once → propose "sudo snap install postman"
→ shows preview → waits for "yes"
→ runs → verifies with postman --version

Why this matters for devs:

Avoids the classic "apt install nodejs → wrong/old version" nightmare
Reduces snap vs flatpak vs apt version conflicts (huge pain on Ubuntu)
Everything is auditable — you see exactly what ran

🧠 How I Built It

LangGraph → stateful agent graph (planner → executor → tools → human interrupt)
Ollama → local inference (Llama 3.1 8B or whatever model you run)
Tools → simple Python wrappers (subprocess for shell, etc.)
Safety → interrupt + input() for confirmation on dangerous actions

Everything 100% local — no data leaves your machine.

🧪 Honest Limitations Right Now

Only tested on Ubuntu/Debian (apt/snap/flatpak paths)
No automatic rollback if install fails (yet)
Voice TTS prosody still needs work (switching to XTTS-v2 cloning soon)
Package tool is smart but not perfect — edge cases exist

Quick Start (try it in ~2 minutes)

git clone https://github.com/zkzkGamal/zkzkAgent.git
cd zkzkAgent
chmod +x install.sh
./install.sh
source venv/bin/activate
python main.py

Then just type:

"install postman"
"install discord"
"check node version"
"find all python files in my project"
"kill firefox"

🎯 Looking for Dev Feedback

Better conflict detection? (e.g. dpkg -s / snap list before proposing apt?)
Should it auto-suggest nvm/pyenv/volta for node/python/go runtimes?
Flatpak vs snap — which should be default for GUI apps in 2026?
Any scary package edge cases I missed? (PPA hell, broken deps, etc.)

PRs, issues, forks, brutal roasts — all welcome.
Built in Cairo with ❤️ by zkaria (@zkzkgamal11)

This version keeps your voice: honest, technical enough for devs, shows real value, admits limitations, and invites collaboration — just like your original example.

Let me know if you want it shorter, more code-heavy, or tweaked for a specific platform (X thread, Reddit, DEV.to, etc.). Ready to ship! 🚀

Building zkzkAgent v2: A Local AI Assistant for Linux System Management

zkaria gamal — Mon, 16 Feb 2026 11:02:11 +0000

# Using AI to Build a Local AI Assistant That Actually Manages Your Linux System 🖥️🤖

ai #python #langchain #ollama #opensource #linux #automation #localllm

Managing Linux can be tedious. Remembering commands, hunting files, checking processes, and deploying scripts gets overwhelming fast.

What if you had an AI on your machine that actually executes commands, manages processes, searches files, and checks your network—all while keeping your data private?

That’s how I built zkzkAgent v2 — a local, privacy-first AI system manager for Linux.

Repo: https://github.com/zkzkGamal/zkzkAgent

🚀 What’s Working Really Well

🧠 1. Real System Management

zkzkAgent can:

Search files & directories intelligently
Manage processes (find, kill, monitor)
Run shell commands safely (ls, whoami, date, etc.)
Deploy scripts with AI-assisted option selection
Handle destructive actions with human confirmation

It reads your intent, decides the safest way to execute tasks, and streams results in real time.

🌐 2. Network Awareness

Auto-check internet connectivity before network-dependent tasks
Reconnect Wi-Fi automatically via nmcli
Search the web or fetch images via DuckDuckGo directly to your media folder

This makes remote deployment, browsing, and downloads seamless.

🎤 3. Optional Voice Control

Whisper-based speech recognition
Coqui TTS for natural voice responses
Noise reduction & voice activity detection
Hands-free system control

Type commands or talk to your system—zkzkAgent responds intelligently either way.

🛠 How I Built It

AI wasn’t just autocomplete — it accelerated development massively. It helped me:

Scaffold the LangGraph agent architecture
Implement stateful tool execution & human-in-the-loop safeguards
Build the quick install script
Iterate on streaming responses, network tasks, and file management tools

Everything runs locally—no cloud, no telemetry, no data leaks.

🧪 What’s Still Basic (Honest Section)

Voice TTS can be optimized for prosody & naturalness
Some deployments assume Ubuntu/Debian paths
Image downloads & web search are basic but functional

The foundation is strong:
AI agent ✔
Voice ✔
Network-aware ✔
Streaming responses ✔

💡 Why I Built This

I wanted an AI sysadmin on my machine:

Privacy-first (local execution only)
Real actions, not advice
Extensible for dev workflows & automation

Linux is powerful, but managing it shouldn’t be a chore. zkzkAgent makes it intuitive.

🛠 Quick Start

git clone https://github.com/zkzkGamal/zkzkAgent.git
cd zkzkAgent
chmod +x install.sh
./install.sh
source venv/bin/activate
python main.py

Start typing or speaking commands, and watch your system respond intelligently.

🎯 Example Interaction

User: Find all Python files in my project
AI: [Searches project folders → Returns paths]

User: Check if internet is up
AI: Connected ✅

User: Deploy my backend script
AI: Running deploy_v2.sh in background… PID 12345

User: Remove old logs
AI: This will delete /home/user/logs/*. Confirm? yes
AI: Done.

🔮 Next Steps

Optimize TTS voice for clarity & expressiveness
Add smarter AI-based deployment suggestions
Expand network operations (FTP, SSH tasks)
Better error handling & logs visualization

🧠 Who This Is For

If you’re into:

Local AI agents
Linux automation
LangGraph & Ollama projects
Building self-hosted AI tools

Clone it. Break it. Improve it.

PRs, issues, and feedback are welcome.

Built with ❤️ in Cairo by Zkzk (zkzkGamal on GitHub).

Meet StudyWithMiku 🎤📚 – Your AI Anime Study Buddy That Actually Speaks & Animates!

zkaria gamal — Mon, 16 Feb 2026 08:31:33 +0000

# Using AI to Build a Study Buddy That Feels Like Hatsune Miku 🎤✨

ai #python #langchain #tts #opensource #vocaloid #rag #localllm

Studying alone? Boring.

Studying with an AI that reads your PDFs, explains concepts, remembers context, and talks like Miku with an anime-style voice?

Way better.

I used AI tools (Copilot, Claude, Gemini, local Ollama) to ship StudyWithMiku — an autonomous AI study companion that:

📚 Reads and embeds your PDFs
🧠 Answers using RAG + memory
🎀 Responds with Miku’s personality
🎙 Speaks with a character-style voice (not a robotic TTS)

Repo: https://github.com/zkzkGamal/StudyWithFriend
Demo (voice + behavior): https://github.com/zkzkGamal/StudyWithFriend/blob/main/demo.mp4

🚀 What’s Working Really Well

🎀 1. Personality That Actually Feels Alive

Miku’s personality is fully implemented using:

Prompt engineering (prompt.yaml)
LangGraph state + memory
Structured tool calling

She responds with cute, energetic vibes:

♪ Bayes time~! ★ P(A|B) = P(B|A) * P(A) / P(B) … Miku thinks this is sooo cool for studying! ^_^

She remembers context across questions. It feels less like “query → response” and more like chatting with a nerdy Vocaloid friend.

🎙 2. Custom Voice (Not Generic TTS)

Voice pipeline:

Coqui TTS (acoustic model)
DiffSinger vocoder
sounddevice playback

This gives anime-style character speech instead of flat robotic output.

It’s not fully expressive idol-concert mode yet — but it’s already very distinct.

📚 3. Real RAG, Not Just Chat

Drop a PDF into content/ → auto-embedded into ChromaDB in the background.

You get:

Smart retrieval
Context-aware answers
Tool usage (web search, open browser, system commands)
Error handling

It’s a proper agent — not just a wrapper over an LLM.

🧪 What’s Still Basic (Honest Section)

TTS is clear but not ultra-expressive yet (emotion/prosody tuning next).
Animations work (sparkles, terminal flair), but they could evolve into:
- Sprite sequences
- Mini GUI
- Browser-based visuals
Voice emotion control needs better parameter tuning in DiffSinger.

The foundation is strong:
Agent ✔
Memory ✔
Voice ✔
RAG ✔

Now it’s polish time.

💡 Why I Built This

I love Vocaloid. Studying is hard. Motivation matters.

So I asked myself:

Why not turn studying into hanging out with Miku?

Cheerful voice + personality + visual feedback = more engagement.

And honestly? It works.

⚡ How AI Helped Me Ship Fast

AI wasn’t just autocomplete — it was a multiplier.

It helped me:

Scaffold the LangGraph agent structure
Fix PyTorch + protobuf dependency chaos
Generate 90% of the Bash installer (venv, CUDA, model downloads)
Iterate on Miku’s personality in minutes
Debug Chroma, audio pipelines, tool execution

But here’s the key:

AI gave speed.
Understanding the TTS pipeline, agent state transitions, and RAG design gave growth.

That’s where the real learning happened.

🛠 Quick Start

git clone https://github.com/zkzkGamal/StudyWithFriend.git
cd StudyWithMiku
chmod +x install.sh
./install.sh

Edit .env (choose Ollama/local or cloud LLM), then:

source venv/bin/activate
python main.py

Drop PDFs into content/ and start chatting.

🎯 Example Interaction

You:
Explain Bayes theorem from my stats notes.

Miku:
♪ Bayes time~! ★ P(A|B) = P(B|A) * P(A) / P(B) … Miku thinks this is sooo powerful for updating beliefs! ^_^

(Voice playback + animation trigger happens here)

🔮 Next Steps

Emotion-aware TTS (tag-based prosody control?)
Better DiffSinger tuning
Real animated sprites
Character toggle (Teto mode?)
Flashcards & quiz generation
Study session gamification

🧠 Who This Is For

If you’re into:

Local AI agents
RAG systems
TTS pipelines
Anime/Vocaloid
Building weird but fun AI tools

Clone it. Break it. Improve it.

I’d love feedback on:

How the personality feels
Voice quality on your machine
Ideas to make her more “idol-tier”

PRs and issues are very welcome.

Built with ❤️ in Cairo by Zkzk (zkzkGamal on GitHub).

zkzkAgent – A Self-Hosted AI Assistant for Linux

zkaria gamal — Thu, 12 Feb 2026 20:47:58 +0000

I wanted to manage my Linux system using natural language instead of memorizing commands. Existing AI tools either sent data to the cloud or couldn’t safely execute commands, so I built zkzkAgent, a local AI assistant that runs entirely on your Linux machine.

It keeps your data private and helps with:

File & directory search

Process & service management

Wi-Fi auto-reconnect

Optional voice interface (Whisper + TTS)

Safe execution with human confirmation

It’s open-source, fully documented, and easy to install for Linux users. Feedback and contributions are welcome!

Tags: #linux #opensource #selfhosted #AI

Link: GitHub repo: https://github.com/zkzkGamal/zkzkAgent