Öffentliches Repository · Kernprojekt

mono-api-agent

Name: mono-api-agent
Author: Oleksandr Shevchenko

RAG-Agent über die offizielle OpenAPI-Spezifikation von monobank: Chunking pro Methode, hybride Suche und eine deterministische Halluzinationsprüfung statt LLM-Judge.

— 25 Endpunkte und 45 Schemata, ~70 Chunks
— Chunking pro Methode, nicht nach Zeichenzahl
— Hybride Suche: lexikalisches Signal über Vektoren
— Deterministische Prüfung statt LLM-Judge

Repository auf GitHub ↗

Case Study · RAG & Retrieval

Ein RAG-Agent über eine offizielle OpenAPI-Spezifikation — an einem Tag

Der Agent beantwortet Fragen zur öffentlichen monobank-API ausschließlich aus deren offizieller OpenAPI-Spezifikation: 25 Endpunkte und 45 Schemata, zerlegt in rund 70 Chunks. Entstanden an einem Tag — und an diesem Tag zweimal umgebaut, weil die Messwerte es verlangten.

Meine Rolle

Architektur, Retrieval-Strategie und alle Messungen stammen von mir; die Implementierung ist KI-gestützt — die Entscheidungen, warum etwas so und nicht anders gebaut ist, kann ich einzeln begründen.

Wichtige Entscheidungen

— Chunking pro API-Methode statt nach Zeichenzahl: In einer API-Dokumentation ist eine Methode die natürliche Grenze — eine größenbasierte Aufteilung reißt Beschreibung und Felder auseinander.
— Das Embedding wird nicht über den gesamten Chunk berechnet: Bei zwei Zeilen Beschreibung und vierzig Zeilen ausgerolltem Schema beschrieb der Vektor Feldnamen statt des Zwecks der Methode — invoice/create landete nicht in den Top-3.
— Ein lexikalisches Signal liegt über der Vektorsuche: Die Scores drängten sich bei 0,82–0,87 zusammen; eine exakte Wortübereinstimmung ist ein starkes Signal, das der Vektor unterbewertet.
— Die Selbstprüfung ist deterministisch statt LLM-Judge: Der Judge lieferte Fehlalarme und erzwang eine zusätzliche Runde.

Was technisch funktioniert

— Antwortzeit 60 s → 2,8 s, Modellaufrufe pro Frage 5 → 2
— Deterministische Prüfung fängt erfundene Endpunkt-Pfade ab
— Fällt kein Modell an, gibt der Agent die gefundenen Spezifikationsfragmente mit Warnung zurück

Nächster Entwicklungsschritt

Ehrliche Grenze: Die Prüfung fängt erfundene Pfade, aber noch keine erfundenen Feldnamen — genau das ist der nächste Schritt.

Quellcode ansehen ↗