Skip to content

ich777/miniassistant

BranchesTags

Repository files navigation

MiniAssistant

German only... Sorry...

Schlanker lokaler Assistent mit Multi-Provider-Support: Ollama (lokal/remote), Google Gemini API, OpenAI API (GPT-4o, DALL-E, o-Serie), DeepSeek API (V3, R1), Anthropic API (Claude), Claude Code CLI. Agent-Dateien (optional AGENTS.md, SOUL, IDENTITY, TOOLS, USER), Modellwechsel per /model MODELLNAME oder Alias, Token-Auth, kleines Memory, minimalistisches Web-UI und CLI.

Installation (so schmerzlos wie möglich)

Voraussetzungen: Python 3.10 oder neuer, Modul venv (z.B. Debian: apt install python3 python3-venv python3-pip). Das Install-Skript prüft das vor dem Start.

cd /pfad/zum/projekt
./install.sh
source venv/bin/activate

System-Pakete: Das Install-Skript versucht zu Beginn automatisch, System-Pakete zu installieren (python3, python3-venv, python3-pip, libolm-dev für Matrix-E2EE). Dafür sind ggf. Rechte nötig (z. B. sudo ./install.sh). Schlägt die Installation fehl, die genannten Pakete manuell installieren und ./install.sh erneut ausführen.

Systemweit verfügbar machen (optional): Damit miniassistant ohne venv-Aktivierung aus jeder Shell aufrufbar ist:

sudo ln -s /pfad/zum/projekt/venv/bin/miniassistant /usr/local/bin/miniassistant

Optional: Init-Skript (sysvinit) oder systemd installieren:

# sysvinit (z. B. Debian ohne systemd)
./install.sh --init
sudo service miniassistant start

# systemd
./install.sh --systemd
sudo systemctl daemon-reload
sudo systemctl enable --now miniassistant

Ersteinrichtung

Ähnlich wie bei OpenClaw – geführt über CLI oder später Web:

miniassistant config

Durchlauf: Ollama-URL, num_ctx, Bind (localhost oder 0.0.0.0), Port, Agent-Verzeichnis, Standard-Modell, optional SearXNG-URL. Config landet in ~/.config/miniassistant/config.yaml oder im Projekt als miniassistant.yaml.

Ollama-Optionen (temperature, top_p, …)

Unter providers.ollama.options können alle von Ollama unterstützten ModelOptions gesetzt werden (werden bei jedem Chat-Request mitgeschickt):

  • temperature (float): Zufälligkeit (niedriger = deterministischer, z. B. 0.2 für Fakten; höher = kreativer, z. B. 0.8–1.2). Default oft 0.8.
  • top_p (float): Nucleus Sampling (z. B. 0.9). Nur entweder temperature oder top_p stark verändern.
  • top_k (int): Nur die K wahrscheinlichsten nächsten Tokens (z. B. 40).
  • num_ctx (int): Kontextlänge in Tokens (kann auch oben unter providers.ollama.num_ctx stehen).
  • num_predict (int): Maximale Anzahl zu generierender Tokens.
  • seed (int): Fester Zufallssamen für reproduzierbare Ausgaben.
  • min_p (float): Mindest-Wahrscheinlichkeit für Token-Auswahl.
  • stop (string oder Liste): Stop-Sequenzen, die die Generierung beenden.

Beispiel in config.yaml / miniassistant.yaml:

providers:
  ollama:
    base_url: http://127.0.0.1:11434
    num_ctx: 8192
    think: true
    options:
      temperature: 0.7
      top_p: 0.9
      top_k: 40

Nutzung

  • CLI-Chat: miniassistant chat (Modellwechsel: /model MODELLNAME oder /model ALIAS)
  • Web-UI: miniassistant serve – dann http://127.0.0.1:8765 (Host/Port in Config änderbar, z. B. server.port: 8080 oder --port 8080)
  • Token: Beim ersten serve wird ein Token generiert (CLI-Ausgabe oder miniassistant token). Im Browser: Startseite öffnen, Token eingeben und „Zum Chat“ klicken – oder direkt z. B. http://host:8765/chat?token=DEIN_TOKEN aufrufen. API: ?token=... in der URL oder Header Authorization: Bearer <token>.
  • Anhänge (Web-UI / Discord / Matrix): Bilder (PNG, JPG, GIF, WebP) gehen ans Vision-Modell. Dokumente (PDF, DOCX, .txt, .md, .csv, .json, .xml, .log, .rst) werden extrahiert und in die Nachricht eingebettet. Gescannte PDFs werden als Seitenbilder durchs Vision-Modell geschickt. Optional via pip install -e '.[docs]'. Details/Limits: siehe CONFIGURATION.md Abschnitt 21.

OpenAI-kompatible API

MiniAssistant stellt zwei OpenAI-kompatible Schnittstellen bereit:

/v1/ - MiniAssistant API (mit Agent-Context)

Vollstaendig OpenAI-kompatibel mit dem konfigurierten Agent-Kontext (SOUL, IDENTITY, TOOLS, USER, Memory). Ideal fuer Open WebUI, Continue.dev, Cursor und Tools die den vollen MiniAssistant-Funktionsumfang nutzen sollen.

Endpunkte:

  • GET /v1/models - Alle Modelle auflisten (inkl. Aliases)
  • POST /v1/chat/completions - Chat mit Agent-Context
  • POST /v1/completions - Text Completion (optional)
# Modelle auflisten (inkl. Aliases wie "fast", "code", "sonnet")
curl -s http://localhost:8765/v1/models -H "Authorization: Bearer TOKEN"

# Chat Completion mit Kurzname
curl -s http://localhost:8765/v1/chat/completions \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "fast", "messages": [{"role": "user", "content": "Hallo!"}]}'

# Streaming (SSE)
curl -s -N http://localhost:8765/v1/chat/completions \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "fast", "stream": true, "messages": [{"role": "user", "content": "Hallo!"}]}'

Details, Integrationsbeispiele und Einschraenkungen: OPENAI_API.md

Raw OpenAI Proxy (Optional)

Aktiviere in der Config raw_proxy.enabled: true fuer einen direkten Proxy (/raw/v1/) ohne Agent-Context. Ideal fuer externe Tools die keinen System-Prompt wollen.

# config.yaml
raw_proxy:
  enabled: true
  token: "dein-token"   # Optional: wenn leer, keine Auth erforderlich
  rate_limit: 100       # Requests pro Minute (default 100; 0 = deaktiviert)

Wichtig:

  • raw_proxy.token: Wird automatisch generiert wenn enabled: true aber kein Token vorhanden (wie server.token).
  • Token anzeigen: miniassistant token --raw-proxy
  • Token neu generieren: miniassistant token --raw-proxy --regenerate
  • Separate Rate Limits: server.rate_limit fuer /v1/, raw_proxy.rate_limit fuer /raw/v1/.
# Modelle von allen OpenAI-kompatiblen Providern
curl -s http://localhost:8765/raw/v1/models -H "Authorization: Bearer TOKEN"

# Chat-Completion (Modellname ohne provider-prefix)
curl -s http://localhost:8765/raw/v1/chat/completions \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3.5-122b-a10b", "messages": [{"role": "user", "content": "Hallo!"}]}'

Reverse-Proxy Beispiel (Nginx) - Nur Raw-Proxy freigeben:

server {
    listen 443 ssl;
    server_name ai.deinedomain.de;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Nur Raw-Proxy Endpunkte freigeben (kein Agent-Context)
    location /raw/v1 {
        proxy_pass http://127.0.0.1:8765/raw/v1;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Authorization $http_authorization;
        
        # Streaming unterstuetzen
        proxy_buffering off;
        chunked_transfer_encoding off;
    }

    # Alles andere verweigern
    location / {
        return 404;
    }
}

Client-Usage (OpenAI SDK):

from openai import OpenAI

client = OpenAI(
    base_url="https://ai.deinedomain.de/raw/v1",
    api_key="dein-raw-proxy-token"
)

response = client.chat.completions.create(
    model="qwen3.5-122b-a10b",
    messages=[{"role": "user", "content": "Hallo!"}]
)

Alle Endpunkte im Ueberblick

Pfad Beschreibung Auth Agent-Context
/chat Web-UI server.token Ja
/v1/* MiniAssistant API server.token Ja
/raw/v1/* Raw Proxy raw_proxy.token Nein
/api/* Interne APIs server.token Ja
/nutzung Usage Tracking server.token Ja
/config Config-Editor server.token Ja

Nur Raw-Proxy freigeben? Siehe Reverse-Proxy Beispiel oben - dann sind /v1/, /chat, /api/* usw. nicht von aussen erreichbar.

Unterschiede: /v1/ = mit Agent-Context (MiniAssistant), /raw/v1/ = direkter Proxy (OpenAI-kompatibel). Details: CONFIGURATION.md (#10b)

Binden auf alle Interfaces

In der Config server.host: "0.0.0.0" setzen (miniassistant config oder YAML). Wichtig: Token setzen, damit nur Berechtigte zugreifen.

Hinter einem Reverse-Proxy

Wird MiniAssistant nur via Reverse-Proxy ins Internet gestellt (empfohlen), bind weiter auf 127.0.0.1 und beachte:

  • server.trust_forwarded: true setzen. Sonst sieht der Server jede Anfrage als vom Proxy kommend (127.0.0.1) — dann teilen sich alle Clients einen Rate-Limit- und Brute-Force-Zähler, und ein einzelner Angreifer kann mit fehlgeschlagenen Logins alle Nutzer für 1 h aussperren. Nur aktivieren, wenn wirklich ein vertrauenswürdiger Proxy davorsitzt (sonst kann jeder Client seine IP per Header spoofen).
  • Der Proxy muss die echte Client-IP weiterreichen. Im Nginx-Beispiel oben zusätzlich: 
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
  • server.rate_limit (Requests/Minute pro IP für / und /v1, Default 100, 0 = aus) und raw_proxy.rate_limit greifen erst sinnvoll, wenn trust_forwarded aktiv ist — sonst zählt alles gegen die Proxy-IP.

System-Erkennung

Die LLM erfährt automatisch, auf welchem System sie läuft (OS, Distribution, Paketmanager, Init-System), damit sie die passenden Befehle nutzt (z. B. apt vs dnf, systemctl vs service). Erkannt werden u. a. Debian/Ubuntu, Fedora/RHEL, Arch, Alpine, openSUSE, macOS.

Sprache, Merken, Scheduler

  • Sprache: Priorität: respond_in_input_language: true in der Config (antwortet automatisch in der Sprache des Nutzerprompts) → Response language: in IDENTITY.md → Default Deutsch. Beim Onboarding wird die Sprache abgefragt und in IDENTITY.md eingetragen. respond_in_input_language ist nützlich für Multi-User-Bots (Matrix/Discord) mit gemischten Sprachen.
  • Merken: Das Modell weiß, dass es mit exec Dateien lesen/schreiben kann. Wenn workspace oder agent_dir gesetzt sind, werden diese Pfade im System-Prompt genannt – der Assistent kann dort Notizen anlegen, wenn du ihn darum bittest.
  • Memory abschalten: Per Default protokolliert MiniAssistant Exchanges in tägliche memory/YYYY-MM-DD.md-Dateien (und optional in mempalace). Wer das nicht will, setzt memory.enabled: false in der Config — dieser Master-Switch killt Tagesdateien, last_summary.json, den Memory-Block im System-Prompt und mempalace inkl. search_memory-Tool gemeinsam. Details: CONFIGURATION.md.
  • Geplante Jobs (ohne System-Cron): Optional scheduler.enabled: true in der Config und pip install miniassistant[scheduler]. Dann steht das Tool schedule zur Verfügung (Cron z. B. 0 9 * * * oder „in 30 minutes“). Jobs werden beim serve ausgeführt.
  • Nutzungs-Tracking: Optional server.track_usage: true – zeichnet jeden LLM-Aufruf (Modell, Typ, Dauer in Sekunden) als CSV in $config_dir/usage/usage.csv auf. In der Web-UI unter /nutzung mit Zeitfiltern (Stunde, Tag, Woche, Monat, Jahr) und Charts einsehbar.
  • Proxy für read_url: Optionale Proxy-Konfiguration für serverseitige URL-Abrufe (read_url.proxies mit Namen). Unterstützt HTTP/HTTPS/SOCKS5 sowie Strategien first, random, roundrobin, none. Details: CONFIGURATION.md.
  • JS-Rendering (optional): read_url unterstützt js: true für JavaScript-lastige Seiten (SPAs, React/Vue/Angular). Erfordert Playwright: pip install miniassistant[js] && playwright install chromium (~300 MB). Ohne Installation: Warnung + Fallback auf normalen Fetch.

Konfiguration (Doku)

Alle Einträge sind optional. Fehlt etwas in der Config, werden Defaults bzw. Ollama-Standards genutzt – es bricht nichts.

Ausführlich und strukturiert: CONFIGURATION.md (wo die Config liegt, alle Bereiche, Optionen, Beispiele). Die Doku wird mit dem Code mitgepflegt.

  • Smart Compacting: Wenn der Chatverlauf den Kontext füllt, werden ältere Messages automatisch zusammengefasst. Steuerbar via chat.context_quota (Default: 0.85 = 85% von num_ctx). Skaliert automatisch mit der Modellgröße.
  • Slot Cache (llama.cpp): Optional persistiert KV-Cache pro Conversation am LLM-Server für schnelle Resumes (10-30s gespart bei langen Conversations). Default OFF, opt-in via slot_cache.enabled: true in der Config. Funktioniert nicht mit --mmproj-Modellen. Details: CONFIGURATION.md §22.

Plan

Siehe MINIASSISTANT_PLAN.md für Features: mehrere Modelle + Aliase, Memory bei Modellwechsel, Bootup-Assistent, SOUL selbst schreiben, Matrix optional.

Lizenz

LGPL 2.1 (GNU Lesser General Public License, Version 2.1)

KI Hinweis

Was als kleines KI-Projekt von Menschen begann, schreibt sich mittlerweile selbst. Die laufende Umsetzung macht inzwischen direkt die KI; Code, Doku und Fixes entstehen mit einem KI-Agenten.

About

No description, website, or topics provided.

Resources

Readme

License

LGPL-2.1 license
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages