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

bash

# 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

bash

# 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

python

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

bash

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

bash

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

bash

# 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

User gibt Prompt ein (CLI / Python / MCP)
IdunLocalClient sendet Prompt + Tool-Definitionen an Ollama
Ollama führt das GGUF-Modell aus (qwen3:8b)
Modell entscheidet: Antwort geben oder Tool aufrufen
Tool Registry führt Tool-Calls aus (web_search, memory, etc.)
Ergebnisse werden zurück ans Modell gegeben
Loop wiederholt bis finale Antwort
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

bash

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

# Neustarten
ollama serve &

Modell nicht gefunden

bash

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

bash

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

Entwicklung

bash

# 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

Qapdex/Idun-5-MoE-sdk-GGUF

idun-gguf — Lokaler GGUF Tool-Agent

Features

Voraussetzungen

Installation

1. Ollama installieren

2. Ollama Server starten

3. Modell pullen

4. idun-gguf installieren

5. Abhängigkeiten

Quick Start

CLI

Python Client

MCP Server

CLI Commands

idun-gguf chat

idun-gguf trace

idun-gguf tools

idun-gguf model

Tools

Architektur

Datenfluss

Umgebungsvariablen

Projekte vergleichen

Troubleshooting

Ollama läuft nicht

Modell nicht gefunden

Package-Import-Fehler

ChromaDB-Fehler

Entwicklung

Lizenz

Verwandte Projekte

Qapdex/
Idun-5-MoE-sdk-GGUF

`idun-gguf chat`

`idun-gguf trace`

`idun-gguf tools`

`idun-gguf model`