Public repository · core project

mono-api-agent

Name: mono-api-agent
Author: Oleksandr Shevchenko

RAG agent over monobank's official OpenAPI specification: chunking per method, hybrid retrieval and a deterministic hallucination check instead of an LLM judge.

— 25 endpoints and 45 schemas, ~70 chunks
— Chunking per method, not by character count
— Hybrid retrieval: lexical signal over vectors
— Deterministic checking instead of an LLM judge

Repository on GitHub ↗

Case study · RAG & retrieval

A RAG agent over an official OpenAPI specification — in one day

The agent answers questions about monobank's public API strictly from their official OpenAPI specification: 25 endpoints and 45 schemas, split into roughly 70 chunks. Built in a single day — and rebuilt twice that day because the measurements demanded it.

My role

Architecture, retrieval strategy and every measurement are mine; the implementation is AI-assisted — I can justify each decision about why it is built this way and not another.

Key decisions

— Chunking per API method instead of by character count: in API documentation a method is the natural boundary — size-based splitting tears the description away from its fields.
— The embedding is not computed over the whole chunk: with a two-line description and forty lines of expanded schema, the vector described field names instead of the method's purpose — invoice/create never reached the top 3.
— A lexical signal sits on top of vector search: scores clustered at 0.82–0.87, and an exact word match is a strong signal that the vector underweights.
— Self-checking is deterministic rather than an LLM judge: the judge produced false positives and forced an extra round trip.

What works technically

— Response time 60 s → 2.8 s, model calls per question 5 → 2
— The deterministic check catches invented endpoint paths
— If no model responds, the agent returns the retrieved spec fragments with a warning

Next development step

An honest limit: the check catches invented paths but not yet invented field names — that is exactly the next step.

View source code ↗