samuelpkg/samuel

Was macht samuel?

Samuel v2 – Rails für KI-Codierungsassistenten. Schlankes Framework + Plugin-Lader, agentenunabhängig über AGENTS.md, dreistufiges Plugin-Modell (Skill/WASM/OCI), TOON-kodierte Laufzeit, Methodik-Hooks.

Übersicht

Samuel ist ein leichtgewichtiges Framework, das KI-Codierungsassistenten die Möglichkeit gibt, flexibel und erweiterbar zu arbeiten. Es definiert eine klare Schnittstelle zwischen dem Agenten und den Plugins, ohne an einen bestimmten Assistenten gebunden zu sein.

AGENTS.md

Jedes Projekt, das Samuel nutzt, enthält eine AGENTS.md-Datei im Wurzelverzeichnis. Diese Datei beschreibt, wie der Assistent mit Samuel interagieren soll:

• Welche Plugins geladen werden
• Wie die Plugin-Konfiguration aussieht
• Welche Methodik-Hooks aktiv sind

Plugin-Modell

Samuel unterstützt drei Arten von Plugins:

1. Skills: In natürlicher Sprache oder Markdown verfasste Anleitungen und Funktionen, die der Assistent lesen und ausführen kann.
2. WASM: WebAssembly-Module für rechenintensive Aufgaben, die mit hoher Geschwindigkeit und Sicherheit ausgeführt werden.
3. OCI: OCI-konforme Container (Docker-Images, etc.), die isolierte Umgebungen für spezifische Werkzeuge bereitstellen.

Plugins werden über den „Samuel Stack“ geladen, der die Abhängigkeiten und Reihenfolge verwaltet.

TOON-kodierte Laufzeit

Die Kommunikation zwischen Assistent und Plugins erfolgt über das TOON-Format (Transformer-Oriented Object Notation). TOON ist eine kompakte, effiziente Kodierung, die speziell für den Einsatz mit KI-Modellen optimiert ist. Es ermöglicht:

• Schnellere Serialisierung/Deserialisierung
• Reduzierten Token-Verbrauch bei API-Aufrufen
• Strukturierte, typsichere Nachrichten

Methodik-Hooks

Hooks sind Erweiterungspunkte, die es ermöglichen, in den Arbeitsablauf des Assistenten einzugreifen. Folgende Hooks sind vordefiniert:

• before_generate: Wird vor der Codegenerierung aufgerufen
• after_generate: Wird nach der Codegenerierung aufgerufen
• on_error: Wird bei Fehlern ausgelöst
• on_startup: Wird beim Start des Assistenten ausgeführt

Jeder Hook kann durch ein Plugin implementiert werden und erhält den aktuellen Kontext (z. B. Datei, Aufgabenbeschreibung).

Installation

Um Samuel in einem Projekt zu verwenden:

# Abhängigkeiten installieren (Beispiel mit npm)
npm install samuel-core

# AGENTS.md initialisieren
npx samuel init

Danach kann der Assistent die AGENTS.md lesen und die Plugins entsprechend laden.

Beispielkonfiguration

# AGENTS.md
plugins:
  - type: skill
    source: myskill.md
  - type: wasm
    source: ./plugin.wasm
  - type: oci
    source: myregistry/myimage:latest

hooks:
  - name: before_generate
    plugin: myskill
  - name: on_error
    plugin: error-handler

Lizenz

MIT