Qapdex/Idun-5-MoE-sdk-GGUF

idun-gguf — Lokaler GGUF Tool-Agent

idun-gguf ist ein voll funktionsfähiger lokaler Tool-Agent, der das Pattern von idun-sdk 1:1 spiegelt — aber mit lokalen GGUF-Modellen via Ollama statt Azure Cloud.

┌──────────────────────────────────────────────────┐
│              idun-gguf CLI / Python / MCP          │
│  (OpenAI-kompatibler Client, stdlib-only)          │
├──────────────────────────────────────────────────┤
│               Ollama (localhost:11434)              │
│              qwen3:8b (GGUF, Q4_K_M)               │
├──────────────────────────────────────────────────┤
│              Tool Registry (7 Tools)                │
│  web_search  memory  file_ops  code_executor       │
├──────────────────────────────────────────────────┤
│          Full Agent Trajectory Output               │
│  .text (final answer) + .steps (Schritte)          │
└──────────────────────────────────────────────────┘

Features

Feature	Beschreibung
CLI	idun-gguf chat (finale Antwort), idun-gguf trace (voller Trajectory)
Python	IdunLocalClient().complete(prompt) → .text + .steps
MCP Server	stdio MCP Server mit idun_chat + idun_trace Tools
7 Tools	web_search, memory_search, memory_save, file_read, file_write, file_list, code_executor
100% Lokal	Kein API-Key, kein Cloud-Dienst, keine Datenverlassen dein Netz
Trajectory	Vollständiger Agent-Pfad (Reasoning, Tool-Calls, Ergebnisse)
CPU-freundlich	qwen3:8b (Q4_K_M, 5.2GB) läuft auf CPU

Voraussetzungen

• Python ≥ 3.10
• Ollama (siehe Setup)
• ~8GB freier RAM (für qwen3:8b)
• ~5.2GB Festplatte (für das Modell)

Installation

1. Ollama installieren

curl -fsSL https://ollama.com/install.sh | sh

2. Ollama Server starten

ollama serve &

3. Modell pullen

ollama pull qwen3:8b

Hinweis: qwen3:8b hat exzellentes Tool-Calling (5.2GB, Q4_K_M).
Alternativen: qwen3:14b, llama3.1:8b, mistral-nemo:12b

4. idun-gguf installieren

# Aus dem Projektverzeichnis
cd /app/idun_gguf_integration_1709
pip install -e .

# Oder direkt
pip install -e /app/idun_gguf_integration_1709/

5. Abhängigkeiten

pip install duckduckgo-search chromadb click

Quick Start

CLI

# Einfache Frage (finale Antwort)
idun-gguf chat "Was ist Python?"

# Vollständigen Agent-Trajectory anzeigen
idun-gguf trace "Was ist Python?"

# Verfügbare Tools auflisten
idun-gguf tools

# Aktuelles Modell anzeigen
idun-gguf model

Python Client

from idun_gguf import IdunLocalClient, Response

# Client erstellen
client = IdunLocalClient()

# Einfache Antwort
response = client.complete("Was ist Python?")
print(response.text)       # Finale Antwort
print(len(response.steps))  # Anzahl Schritte

# Mit Trajectory
for step in response.steps:
    print(f"[{step.type}] {step.content}")
    if step.type == "tool_call":
        print(f"  → Tool: {step.tool_name}, Input: {step.tool_input}")
    if step.type == "tool_result":
        print(f"  ← Ergebnis: {step.tool_output[:100]}...")

MCP Server

# Tools auflisten
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  python3 -m idun_gguf.mcp_server

# idun_chat aufrufen
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"idun_chat","arguments":{"prompt":"Was ist Python?"}},"id":2}' | \
  python3 -m idun_gguf.mcp_server

CLI Commands

idun-gguf chat

Führt eine Anfrage aus und zeigt die finale Antwort.

# Mit Prompt als Argument
idun-gguf chat "Was ist Python?"

# Mit System-Prompt
idun-gguf chat "Erkläre ML" --system "Du bist ein ML-Experte"

# Als JSON-Ausgabe
idun-gguf chat "Hallo" --json

# Mit anderem Modell
idun-gguf chat "Hallo" --model llama3.1:8b

idun-gguf trace

Führt eine Anfrage aus und zeigt den vollständigen Agent-Trajectory.

# Vollständigen Trace anzeigen
idun-gguf trace "Was ist Python?"

# Als JSON-Ausgabe
idun-gguf trace "Hallo" --json

idun-gguf tools

Listet alle verfügbaren Tools mit ihren Parametern.

idun-gguf tools

idun-gguf model

Zeigt das aktuell verwendete Modell und die Ollama-URL.

idun-gguf model

Tools

Tool	Beschreibung	Parameter
web_search	DuckDuckGo-Websuche	query, max_results
memory_search	Vektor-Gedächtnis durchsuchen	query, n_results
memory_save	Info im Vektor-Gedächtnis speichern	text, source
file_read	Datei lesen	path, max_lines
file_write	Datei schreiben	path, content
file_list	Verzeichnis auflisten	path, pattern
code_executor	Python-Code ausführen	code, timeout

Architektur

┌──────────────────────────────────────────────────────┐
│                   idun-gguf Package                    │
│                                                        │
│  ┌─────────────┐  ┌─────────────────┐                 │
│  │   cli.py    │  │  mcp_server.py  │                 │
│  │  (Click)    │  │  (JSON-RPC)     │                 │
│  └──────┬──────┘  └────────┬────────┘                 │
│         │                  │                           │
│  ┌──────┴──────────────────┴────────┐                  │
│  │        client.py                  │                  │
│  │  IdunLocalClient: .complete()     │                  │
│  │  → Response(.text, .steps)        │                  │
│  └───────────────┬──────────────────┘                  │
│                  │                                     │
│  ┌───────────────┴──────────────────┐                  │
│  │        Tool Registry              │                  │
│  │  web_search │ memory │ file_ops  │                  │
│  │  code_executor                    │                  │
│  └──────────────────────────────────┘                  │
└──────────────────────────┬───────────────────────────┘
                           │
                           ▼
              ┌───────────────────────┐
              │  Ollama (localhost)    │
              │  qwen3:8b (GGUF)       │
              │  OpenAI-kompatible API │
              └───────────────────────┘
                           │
                           ▼
              ┌───────────────────────┐
              │  GGUF Model (Q4_K_M)   │
              │  ~5.2GB, CPU-Inference │
              └───────────────────────┘

Datenfluss

1. User gibt Prompt ein (CLI / Python / MCP)
2. IdunLocalClient sendet Prompt + Tool-Definitionen an Ollama
3. Ollama führt das GGUF-Modell aus (qwen3:8b)
4. Modell entscheidet: Antwort geben oder Tool aufrufen
5. Tool Registry führt Tool-Calls aus (web_search, memory, etc.)
6. Ergebnisse werden zurück ans Modell gegeben
7. Loop wiederholt bis finale Antwort
8. Response mit .text (finale Antwort) + .steps (vollständiger Trajectory)

Umgebungsvariablen

Variable	Default	Beschreibung
OLLAMA_BASE_URL	http://localhost:11434	Ollama Server-URL
IDUN_GGUF_MODEL	qwen3:8b	Standard-Modell

Projekte vergleichen

Aspekt	idun-sdk (Azure)	idun-gguf (Lokal)
Backend	Azure AI Foundry	Ollama + GGUF
Modell	NatureLM-Idun-5-MoE	qwen3:8b (austauschbar)
Latenz	2-10s (Cloud)	30-120s (CPU)
Kosten	Pay-per-Token	Kostenlos (Strom)
Datenschutz	Cloud	100% Lokal
Offline	❌	✅
Tools	web_search, memory_search	7 Tools (erweiterbar)
Trajectory	✅ .text + .steps	✅ .text + .steps

Troubleshooting

Ollama läuft nicht

# Prüfen
curl http://localhost:11434/api/tags

# Neustarten
ollama serve &

Modell nicht gefunden

ollama list  # Prüfen ob qwen3:8b gelistet ist
ollama pull qwen3:8b  # Falls nicht

Package-Import-Fehler

pip install -e /app/idun_gguf_integration_1709/ --force-reinstall

ChromaDB-Fehler

# ChromaDB persistiert in ~/.idun_gguf_memory/
# Bei Problemen: rm -rf ~/.idun_gguf_memory/

Entwicklung

# Repository klonen
git clone https://huggingface.co/Qapdex/Idun-5-MoE-sdk-GGUF
cd idun-gguf

# Entwicklungsmodus
pip install -e .

# Tests
python -m pytest tests/

Lizenz

MIT

Verwandte Projekte

• idun-sdk — Thin Client für NatureLM-Idun-5-MoE auf Azure
• idun-gguf auf HuggingFace — Thin Client für NatureLM-Idun-5-MoE auf Azure
• Ollama — Lokale LLM-Inference
• idun-agent-platform — Produktions-Runtime für Agenten