Referencia

API referencia

Az SDK összes publikus osztályának és interfészének tömör referenciája. A részletes leíráshoz és példákhoz az egyes fejezetek hivatkozásait kövesd. A stub jelölés azt jelenti, hogy az osztály metódus-törzseit a generátor eltávolítja – az aláírások változatlanok, de az implementáció csak futásidőn érhető el. Ez fordítási időben elegendő a plugin lefordításához; futásidőben a PluginClassLoader parent-first betöltése miatt mindig a platform valódi implementációja fut, tehát egy stub osztály metódusa futásidőben ugyanúgy, hibátlanul viselkedik, mintha a teljes forráskód rendelkezésre állna (részletek: → KnowledgeGraphService fejezet).

Tool interfészek

Interfész	Csomag	Leírás	Fejezet
`IChatbotTool<Request>`	`tool.intf`	Minden tool alapja. Kötelező: `getName()`, `getDomain()`, `getInstruction()`, `getExecutableInstruction()`, `getRequestAsJsonNode()`, `getRequestClass()`, `executeWithResult(systems, userPrompt, userLang, importantWords, progressEmitter, finalCallback)` – a `userLang` a válasz elvárt nyelve, a normalizálás állapítja meg a tool aktiválása előtt. Default metódusok: `getEligibleSystem()` – `null` esetén a tool csak akkor aktiválódik, ha a kérésben nincs system szűrő; ha minden system mellett aktívnak kell maradnia system-szűrős kérésnél is, az `IChatbotTool.ALL`-t kell visszaadnia. `getSystemPromptSupplement()`, `getIdentityDescription()` – szabad szövegű leírás arról, mire képes a tool (vagy orchestrátor); a beépített `IdentityTool` ebből építi fel a chatbot saját kilétét/képességeit ismertető válaszát, a kérés domain-jéhez és system-listájához illeszkedő példányok leírását összefűzve. Orchestrátoros pluginnál elég egyszer, az orchestrátor szintjén megírni a teljes plugin tudását; önálló, orchestrátor nélküli tool-nál magának a tool-nak kell felülírnia – lásd 5.10. fejezet. `toolProgressEmitter()`, `isEligible(Map userData)` – alapértelmezetten mindenkinek elérhető; felülírással a plugin saját jogosultsági logikája dönthet tool-onként; `executeWithResult(domain, systems, userPrompt, userLang, importantWords, progressEmitter, finalCallback)` – domain-paraméterrel bővített változat azoknak a tool-oknak, amelyek több domain-en aktiválódnak (`getDomain()` értéke `IChatbotTool.ALL`) és futásidőben kell megtudniuk, melyik domain hívta őket; felülírás nélkül a default implementáció eldobja a kapott `domain` értéket, és a 6 paraméteres, domain nélküli `executeWithResult(...)`-ra delegál. Az `ALL` konstans (`"ALL"`) mindkét célra – domain és system jelölésre is – ugyanaz. `exractToolParam(llmAssistant, objectMapper, userPrompt[, instruction])` – struktúrált paraméter-kinyerés a tool saját JSON-sémájával, instrukció nélküli overloadnál `getInstruction()`-nel (→ 8). `AGENT_COORDINATOR_MARKER` konstans és `isCoordinatorRequested(text)` – annak megállapítására, hogy egy kapott szöveg (részben vagy egészben) egy `IAgentCoordinator` által meghatározott feladatot hordoz-e, nem kizárólag a felhasználó saját üzenetét (→ 5.11).	3, 4, 5.5
`IOrchestratorTool`	`tool.intf`	Orchestrátor jelölő interfész. Az LLM tool routing kizárja; kizárólag orchestrátor pipeline-ból aktiválható. Kötelező: `@Scope("prototype")`.	5
`IOrchestratorActivatedTool`	`tool.intf`	Csak orchestrátor aktiválhatja. Kötelező: `getPriority()` – kisebb érték = korábban fut.	4
`IClarifiableTool<Request>`	`tool.intf`	Kiterjeszti `IChatbotTool` + `IOrchestratorActivatedTool`. Kötelező: `executeWithClarification(ClarificationSession, ...)`.	7
`IContextConsumerTool<Request>`	`tool.intf`	Kiterjeszti `IChatbotTool`. Kötelező: `executeWithPriorContext(systems, userPrompt, userLang, importantWords, priorToolContexts, responseEmitter, finalCallback)` – az orchestrátor a tool-t mindig ezen keresztül hajtja végre, és az addig lefutott tool-ok kontextus-pufferének pillanatképét paraméterként adja át (kulcs: `taskNo:toolName` completion-kulcs; soha nem null). A kapott kontextus példánymezőben nem tárolható. A kontextus nélküli `executeWithResult(...)` alapértelmezése `UnsupportedOperationException`-t dob.	4.8, 6.7
`IClarifiableContextConsumerTool<Request>`	`tool.intf`	Kiterjeszti `IContextConsumerTool` + `IClarifiableTool`. Kötelező még: `executeWithClarificationAndPriorContext(ClarificationSession, priorToolContexts, responseEmitter, finalCallback)` – a tisztázó kör folytatása is a korábbi kontextussal történik. A kontextus nélküli `executeWithClarification(...)` alapértelmezése `UnsupportedOperationException`-t dob.	6.7
`IAgentCoordinator`	`tool.intf`	Opcionális kiegészítő interfész `IOrchestratorActivatedTool` implementálóknak. Kötelező: `decomposeIntoSubtasks(TaskInfo)` – a kapott `TaskInfo`-t módosítja (nem újat hoz létre), ha az implementáció saját algoritmusa szerint releváns rá nézve: kiegészítheti a `taskPrompt` szövegét és/vagy feltöltheti a `subTasks` mezőjét önálló rész-lépésekkel; nem releváns feladatnál a bemenetet változatlanul adja vissza. Az orchestrátor minden körben (friss hívásnál és tisztázó kör folytatásakor is) lefuttatja a domain aktiválható, ezt implementáló tool-jait priority sorrendben, a feladat saját suitability tesztje és tool-aktiválása előtt – `appliedCoordinatorNames` alapján egy adott coordinator legfeljebb egyszer fut le ugyanazon a feladaton (vagy leszármazottján). Rész-lépések esetén ezek teljes, rekurzív lezárása (tisztázó körükkel együtt) mindig megelőzi a szülő feladat saját tool-aktiválását. Opcionális: `decideConditionalSubtask(TaskInfo parentTask, TaskInfo nextSubtask, Map<String, List<PromptAndContext>> completedSoFar)` – egy általa feltételesként megjelölt rész-lépés indítása előtt hívódik, és `SubtaskDecision`-t ad vissza (alapértelmezés: `RUN`).	5.11
`IToolDependent`	`tool.intf`	Garantált függőség-deklaráció. Kötelező: `getRequiredTools()` – konkrét tool példányok halmaza, amelyek nélkül a tool nem tud dolgozni; `executeWithRequiredContext(systems, userPrompt, userLang, importantWords, requiredToolContexts, progressEmitter, finalCallback)` – a függőségek kontextusát paraméterként kapja, nem instance-mezőn keresztül. A megjelölt függőségeket az engine az LLM aktiválási döntésétől függetlenül lefuttatja.	4.8
`IIngestionTool<Request>`	`tool.intf`	Ingestion pipeline tool. Kizárva a chat routing-ból. Kötelező: `executeIngestion(String domain, String basePath, String progressBasePath, Dataset<Embeddings> lemmatizedEmbeddings, boolean pageLevelMode, IngestionProgressReporter progressReporter)` – egyetlen metódus, nincs hozzá overload. A `pageLevelMode` mechanikus jelzés arra, hogy a jelen futás page-level módban zajlik-e (a döntést nem a tool, hanem a domain+system-hez tartozó orchestrátor hozza meg); a `progressReporter` a tool saját feldolgozási szakaszainak jelzésére szolgál. Default: `getRelationTypesForPromptType()`, `isGraphBoostEnabled()`.	10, 10.5
`IAsyncTaskTool<Request>`	`tool.intf`	Külső hívó által, a Platform API-n keresztül explicit módon indítható, hosszú futásidejű feladat. Kizárva a chat routing-ból és az ingestion pipeline-ból. Kötelező: `getTaskType()`, `getRequestClass()`, `executeTask(String taskId, String domain, Request request, AsyncTaskProgressReporter progressReporter) throws Exception` – a `domain` a feladat indításakor megadott domain-t hordozza. Default: `getDomain()` – `null`; az `ALL` állandó minden domain-hez érkező indítási kéréssel elindítható feladat-végrehajtót jelöl.	12
`AsyncTaskProgressReporter`	`common.intf`	Egy folyamatban lévő aszinkron feladat előrehaladásának jelzésére szolgáló csatorna. Metódusok: `reportPhase(phase)`, `reportProgress(succeeded, failed, total)`, `reportProgress(succeeded, failed)`, `beginLiveProgress(phase, progressBasePath, succeededCounter, failedCounter, total)`, `endLiveProgress(phase)`.	12.4
`IngestionProgressReporter`	`common.intf`	Egy ingestion tool feldolgozási szakaszainak jelzésére szolgáló csatorna. Metódusok: `reportPhase(phase)`, `beginLiveProgress(phase, progressBasePath, succeededCounter, failedCounter, total)`, `endLiveProgress(phase)`. `NO_OP` konstans – olyan ingestion tool implementációkhoz, amelyek nem kaptak valódi csatornát a hívótól.	10
`ILlmAssistant`	`tool.intf`	Plugin toolok LLM hívásaihoz. `@Autowired`-del injektálható, nem kell `BaseAIAssistant`-ból örökölni. Egyetlen metódus: `generateToolRequest(userPrompt, systemPrompt, tasks, tool)`.	8

⚠️

A domain-paraméteres executeWithResult(String domain, ...) overload default implementációja nem old fel semmit a getDomain() felől – egyszerűen figyelmen kívül hagyja a kapott domain értéket, és a 6 paraméteres, domain nélküli executeWithResult(...)-ra delegál. Ha egy tool ténylegesen IChatbotTool.ALL-lal regisztrálja magát és a futásidőben kapott domain-re támaszkodik (mint pl. a platform beépített IdentityTool-ja), kötelező ezt az overloadot közvetlenül felülírni – felülírás nélkül a tool sosem jut hozzá a hívó által átadott domain-hez.

⚠️

A getEligibleSystem() null visszatérése nem jelent univerzális elérhetőséget a ToolRegistry system-szűrős lekérdezéseinél (getChatTools, getOrchestratorActivatedTools, getIngestionTools(domain, systems), findToolByName): ha a kérésben van explicit system szűrő, egy null deklarációjú tool nem aktiválódik. Csak akkor illik bele minden system-szűrős kérésbe is, ha IChatbotTool.ALL-t ad vissza. Ez a szabály a domain-re nem érvényes ugyanígy: getDomain() esetén a null és az ALL jelenleg funkcionálisan azonos – mindkettő minden domain-en aktiválódó tool-t jelent.

Abstract tool alaposztályok (stub)

Osztály	Csomag	Leírás	Fejezet
`AbstractOrchestratorTool`	`tool`	Orchestrátor alap. `final` metódusok: `executeWithResult()`, `executeOrchestratorActivatedTools()`. Implementálandó: `getDomain()`, `orchestrate()`. Hook-ok: `usePerSubQueryAnswering()`, `getDeepFallbackTool(PromptType)`, `getClassificationPromptSupplement()`, `getDefaultAnswer()`, `usePageLevelIngestion(String system)`, `getContextExpansionMode(PromptType)`. Statikus segédek a koordinátoros végrehajtási szöveghez: `extractCoordinatorTask(String)`, `extractCoordinatorOriginal(String)`. A `resolveRetrievalOptions(PromptType, List<String>, Integer)` egy kérdéstípus retrieval-profilját adja LLM-hívás nélkül (a platform retrieval-mérése használja). Kötelező: `@Scope("prototype")`.	5
`AbstractNERIngestionTool`	`chatbot.tool`	NER-alapú tudásgráf-építő. Implementálandó: `defineEntityTypes()`, `defineRelationTypes()`. Opcionális: `getAdditionalRules()`, `getAliasMinPageCount()`, `getLowFrequencyEntityThreshold()`, `postProcessDomainSpecificData(String domain, String pageEmbeddingCollectionName)` – alapból üres hook, a mention-írás után egyszer meghívva (batch-enként `_SUCCESS`-fájllal védve), determinisztikus, nem LLM-alapú utófeldolgozáshoz. Segédmetódus hozzá: `findPagesByNameSuffix(String pageEmbeddingCollectionName, String system, String nameSuffix)` – `List<PageTextEntry>`-t ad vissza, a tárolt dokumentum-szerkezet elrejtésével. Derived (nem kell felülírni): `getEntityTypes()`, `getRelationTypes()`, `getEntityTypeDescriptions()`, `getInstruction()`.	5.8, 10
`AbstractPageAnalysisTool`	`chatbot.tool`	Oldalelemző toolok alapja. Konstruktorban kapja a NER ingestion tool-t, amelyből `getDomain()`, `getEligibleSystem()` és az entitástípusok automatikusan öröklődnek. A `getCharsPerChunk(IResponseEmitter)` és a `getAvailableInputChars(ISummaryDetailLevel, IResponseEmitter)` a kérés kontextuskeretéből számol; a paraméter nélküli változatok a modell kontextusablakából.	4
`AbstractEntityAnalysisTool`	`chatbot.tool`	`AbstractPageAnalysisTool` leszármazottja. Entitás-elemzés és vizualizáció. Az LLM instrukció dinamikusan a NER tool `defineEntityTypes()`-ából épül fel.	4
`AbstractContextSearchTool`	`chatbot.tool`	Kontextuselőállítás deep fallback esetén: gráf-alapú entitáskeresés, majd (ha a gráf-ág nem talált entitást, egyezést vagy választ) LLM-mel kiválasztott kifejezésre BM25 kulcsszavas keresés, végül (ha `getMaxBruteForcePageCount()` nincs beállítva) szűretlen domain-átvizsgálás a még ki nem értékelt oldalakon. Az instrukció a NER tool entitástípusaiból épül fel. A mélykereső koordinátor kereső tool-jaként is használható. Opcionális: `getMaxBruteForcePageCount()`.	5.6, 6.10
`AbstractNeighborPageSearchTool`	`chatbot.tool`	Környezet-kereső a mélykereső koordinátorhoz: a kontextus releváns oldalainak környezetében keres. Opcionális: `getNeighborSearchWindow(String system)` – az első, szűk környezet félszélessége oldalban (alapértelmezés: 5).	6.10
`AbstractDeepSearchCoordinatorTool`	`tool`	Mélykereső koordinátor, az orchestrátor `getDeepFallbackTool()` visszatérési értékeként. Implementálandó: `getSearchTool()`. Opcionális: `getNeighborSearchTool()`. Kizárt tool-ként nem kell megadni.	6.10
`AbstractSummaryTool`	`chatbot.tool`	Gráf-alapú összefoglaló generálás. Domain és system a NER tool-ból öröklődik.	4
`AbstractWebSearchTool`	`browserless.tool`	Valós idejű web keresés alaposztálya – `IChatbotTool<WebSearchRequest>`. LLM routing aktiválja. Implementálandó: `getDomain()`, a keresési logika. Visszatérési mód: `CONTEXT` vagy `ANSWERED`.	4
`AbstractRAGRetrievalTool`	`tool`	Domain-specifikus RAG retrieval. Az orchestrátor fallback-ként mindig aktiválja, ha más tool nem adott elegendő kontextust. `getPriority()` = `Integer.MAX_VALUE`.	4
`AbstractGraphEnrichmentTask<Request>`	`chatbot.tool`	Már betöltött tudásgráfot utólag, célzottan bővítő aszinkron feladat alapja, két üzemmóddal. Kinyerési módban (alapértelmezett) a domain már tárolt szövegén keres új entitásokat/relációkat – implementálandó: `defineEntityTypes()`, `defineRelationTypes()`. Újraosztályozási módban (`defineReclassificationSourceTypes()` felülírva, nem üres halmazzal) a tudásgráfban már meglévő, megadott típusú fogalmakat vizsgálja felül LLM-mel és frissíti a típusukat a helyükön – implementálandó: `defineReclassificationSourceTypes()`, `defineReclassificationTargetTypes()`; opcionális: `defineRelationTypeMigrations()`, `defineNotAnEntityMarkerType()`, a két bizalmi küszöb hook. `setAbstractNERIngestionTool(nerIngestionTool)` mindkét módban beállítja, melyik NER ingestion tool tárolt szövegén és gráfján dolgozzon a feladat. `getDomain()` és `executeTask()` már implementálva – az utóbbi a `defineReclassificationSourceTypes()` eredménye alapján dönti el, melyik módban fut.	12.5 / 12.5b
`AbstractPluginJpaConfigurer`	`chatbot.plugin`	Saját relációs adatbázis-elérés (EclipseLink JPA, MariaDB/MySQL) egy plugin számára, a platform saját `DataSource`-át (HikariCP) használva – nem nyit új connection pool-t. Implementálandó: `getPersistenceUnitName()`, `getEntityClasses()`. Opcionális hook: `getExtraJpaProperties()`, `afterConfigure(ConfigurableApplicationContext, EntityManagerFactory)`. Statikus segédek: `executeInTransaction(persistenceUnitName, work)`, `executeQuery(persistenceUnitName, work)`. Az `IPluginConfigurer` implementációja – a plugin JAR-ban a `META-INF/services/hu.medical.rag.common.plugin.IPluginConfigurer` fájlba kell felvenni.	→ Plugin adatbázis fejezet
`AbstractAIAssistant`	`tool`	Plugin által leszármazható alaposztály saját, egy adott tool-hoz kötött, strukturált LLM-kéréshez – nem azonos az `ILlmAssistant` injektált interfésszel, és nem tagja a platform-belső `BaseAIAssistant` családnak sem. Implementálandó: `getSystemPrompt()`. Kész metódus: `generateToolRequest(userPrompt, tasks, tool)` – a kapott `IChatbotTool` saját `getInstruction()` és `getRequestAsJsonNode()` eredményéből épít system promptot, JSON schema-alapú strukturált LLM-választ kér, és a válasz JSON-t `HashMap`-ként adja vissza (hiba vagy nem JSON válasz esetén üres map-et). `@Autowired` protected mezők: `cloudOpenAIClient`, `openAIClient`, `objectMapper` – a plugin no-arg konstruktorát a `PluginLoader` `autowireBean()` hívása tölti fel.
`AbstractMcpTool<Request>`	`chatbot.tool`	MCP szerverről adatot beszerző tool (`IClarifiableTool` + `IMcpClientTool`). Implementálandó: `getMcpServers()`, `executeMcp(mcp, request, context)`. Hook-ok: `onClarificationAnswer(...)`, `onCallDeclined(serverId, toolName, context)`, `extractRequest(userPrompt, context)`, `getLeakCheckInstruction(context)`, `getAdditionalSystemPromptSupplement()`, `getMaxContextChars()` (alapértelmezés: 20000), `formatForContext(result)`, `formatProgress(progress)`. Segédek: `toContext(results)`, `useRemoteInputSchema(serverId, toolName)` (dinamikus paraméter-mód). `getSystemPromptSupplement()` `final`; az `isEligible()` ismerten elérhetetlen szerver mellett `false`.	14

LLM asszisztensek (stub)

Minden asszisztens a BaseAIAssistant-ból örököl. Plugin toolok ezeket nem leszármaztatják – az ILlmAssistant interfészt @Autowired-del injektálják. Az alábbi osztályok platform-belsők, de konstruktoros tesztelési célra elérhetők az SDK-ból.

Osztály	Leírás
`OrchestratorAssistant`	Az orchestrátor LLM hívásaihoz – prompt osztályozás, sub-query bontás, suitability teszt.
`MedicalAIAssistant`	Általános célú asszisztens strukturált paraméter-kinyeréshez.
`EntityAnalysisAssistant`	Entitáskivonási asszisztens – struktúrált JSON-t ad vissza (`EntityRequest`).
`DocumentGenerationAssistant`	PDF dokumentum generálási asszisztens.
`WebSearchAssistant`	Webes keresési asszisztens – lekérdezés-átírás és eredmény-feldolgozás.
`BaseSummaryAssistant`	Összefoglaló generálás alaposztálya.

ToolExecutionResult és módok

Factory metódus	Mód	Leírás
`asContext(name, docs)`	`CONTEXT`	Dokumentumok az LLM kontextusához – minőségi kapu fut.
`asContext(name, promptContexts)`	`CONTEXT`	Multi-hop változat: explicit prompt–kontextus párok.
`asGuaranteedContext(name, docs)`	`CONTEXT`	Minőségi kapu kihagyva – a tool kezeskedik a kontextus minőségéért.
`asGuaranteedContext(name, promptContexts)`	`CONTEXT`	Multi-hop guaranteed változat.
`asAnswer(name, docs)`	`ANSWER`	Kész szöveges válasz – LLM hívás kihagyva.
`asAnswer(name, docs, contentType)`	`ANSWER`	Tipizált kimenet, pl. `"BASE64_PDF"`.
`asAnswered(name)`	`ANSWERED`	A tool maga gondoskodott a kézbesítésről.
`needsClarification(question, partialJson, name)`	`NEEDS_CLARIFICATION`	Hiányos paraméter – interaktív kérdéskör indul.

Részletes leírás: 9. fejezet.

Beans és DTO-k

Osztály	Csomag	Leírás
`UniqueTextDocument`	`beans`	Kontextus egység. `equals/hashCode`: `documentId + page + sentenceNumber`. `sentenceNumber = -1`: oldal összefoglaló. → 9.3
`TextAnswer`	`beans`	`UniqueTextDocument` leszármazott szöveges tool válaszokhoz. Konstruktor: `TextAnswer(String text)` – a `documentId` automatikusan generálódik. Factory metódusok: `asSet(String)` – egyelemet tartalmazó `HashSet`; `asSet(List<String>)` – lista elemeiből `HashSet`, automatikus `sentenceNumber` sorszámozással; `newInstance(String, Integer)` – explicit sorrendi számmal rendelkező példány. → 9.3
`InternalContextDocument`	`beans`	`UniqueTextDocument` leszármazott tool-ok közötti belső adatátadáshoz – az orchestrátor a feldolgozás összegzésekor kiszűri, mielőtt a kontextus a RAG pipeline-hoz vagy a végső LLM híváshoz kerülne. A `text` tartalma tetszőleges (strukturált adat vagy akár LLM-mel szintetizált leírás is lehet) – a szűrés a címzettségen múlik, nem a tartalom jellegén. Konstruktor: `InternalContextDocument(String text)`. Factory metódus: `asSet(String)` – egyelemet tartalmazó `HashSet`. Fogadó oldalon `instanceof`-teszttel azonosítható. → 4.8
`ClarifyingQuestion`	`tool.beans`	Visszakérdezés payload. Mezők: `questionId`, `text`, `options`, `allowFreeText`. → 7.4
`ClarificationSession`	`tool.beans`	Redis-ben tárolt clarification állapot – csak az adott hívás kiszolgálásához szükséges, a folyamatban lévő tisztázó kört hordozó taszk saját állapotából minden körben frissen átmásolt mezőket tartja: `partialRequestJson`, `pendingQuestion` (`PendingQuestion` típusú – nem sima String), `pendingAnswer`, `taskPrompt`. A tényleges, tartós feldolgozási állapot (lefutott tool-ok kontextusa, rész-lépések fája) a klasszifikáció `TaskInfo` fáján él, nem a session-ön. → 7.3
`PendingClarificationEntry`	`tool.beans`	Sorban várakozó clarification bejegyzés ha több tool egyszerre kérdez vissza. Platform kezeli, plugin nem módosítja.
`PromptAndContext`	`tool.beans`	Prompt–kontextus pár multi-hop feldolgozáshoz.
`TaskInfo`	`tool.beans`	Egy al-kérdés (vagy egy azon belüli, koordinátor tool által meghatározott rész-lépés) adatai és felgyülemlő feldolgozási állapota – rész-lépésekkel fát alkotva. Klasszifikációs mezők: `taskNo`, `taskPrompt`, `importantWords`, `synonymWords`, `promptType`. Koordinátor-mezők: `subTasks`, `appliedCoordinatorNames`, `requiredToolNames` (nem üres halmaz esetén kizárólagos aktiválás, a RAG retrieval sem fut mellette), `promptContext`, `conditional` (a rész-lépés futásáról a létrehozó coordinator dönt), `ownerCoordinatorName` (az orchestrátor tölti ki) – → 6. Saját, a fában elfoglalt helyéhez kötött feldolgozási állapot (független a testvérekétől és az ősökétől): `completedToolContexts`, `pendingClarificationToolName`/`PartialJson`/ `Question`, `remainingClarifications`, `contextGuaranteed`, `originalTaskPrompt`, `clarificationHistoryText`. A legfelső szintű lista a `ClassificationRequest.tasks` mezőn keresztül érhető el.
`SubtaskDecision`	`tool.beans`	Enum – egy coordinator döntése egy feltételes rész-lépésről: `RUN` (lefut), `SKIP` (elmarad, a többi folytatódik), `STOP` (ez és a hátralévő testvérek is elmaradnak). → 6.4
`RetrievalOptions`	`tool.beans`	Retrieval profil – ranking mód, top-K, MMR lambda, KG enrichment opciók, a `synonymWords` mező (az LLM által a kulcsszavakhoz javasolt szinonimák; a KG alias-bővítés tartaléka, ha az nem ad találatot vagy ki van kapcsolva – az alias-bővítés paramétereinek 0 értéke kikapcsolja), és a `pageLevelMode` mező (page-level ingestion/ retrieval mód – → 5.6). Az orchestrátor prompt-osztályozásból vezeti le.
`ClassificationRequest`	`tool.beans`	Eltárolt prompt-osztályozás eredménye, clarification re-entry esetén újrafelhasználva.
`TextGenerationResponse`	`beans`	SSE esemény a kliens felé a `progressEmitter` csatornán. Konstruktor: `TextGenerationResponse(String progressStatus)`; tartalom: `setContent(Object)`. Tetszőleges, tájékoztató jellegű esemény a `toolProgressEmitter()` szűrőn keresztül küldhető. Néhány `progressStatus` érték foglalt, ezeket egy `ANSWERED` módú tool a `toolProgressEmitter()` megkerülésével, közvetlenül küldi: `LLM_GENERATION` (szövegdarab, ugyanaz a kliensoldali megjelenítés, mint a platform saját LLM streamingjénél) és `SEGMENT_BREAK` (önálló szegmens vége, a stream nem zárul le). → 9.4
`EntityTypeDescriptor`	`chatbot.tool.beans`	NER entitástípus leíró – `type` (NAGY_BETŰS) + `description`. → 5.8
`RelationTypeDescriptor`	`common.beans`	NER relációtípus leíró – `type` + `description`, valamint opcionális `validFromTypes`/`validToTypes` entitástípus-halmaz a reláció két végpontjára (üres halmaz = nincs megkötés). → 10.7
`EntityRequest`	`chatbot.tool.beans`	Entitás-elemzési kérés – `entities` lista.
`Entity`	`chatbot.tool.beans`	Egyetlen entitás – `entityName`, `entityType`.
`SummaryDetailRequest`	`chatbot.tool.beans`	Összefoglaló kérés – entitások + részletesség szint.
`DetailLevelDescriptor`	`chatbot.tool.beans`	Részletesség szint leíró az összefoglaló toolhoz.
`ISummaryDetailLevel`	`chatbot.intf`	Egy összefoglaló-részletességi szint szerződése: `maxTokens()` (a végső összefoglaló LLM-hívásának max token száma), `pageLimit()` (legfeljebb ennyi oldal kerül feldolgozásra az adott szinten), `lengthHint()` (a kívánt terjedelem szöveges leírása az LLM-nek), `detailLevelInstruction()` (opcionális, alapértelmezetten üres kiegészítő instrukció) és `parseDetailLevel(String)` (egy felhasználói/kérésbeli szöveg hozzárendelése a szinthez). `AbstractSummaryTool<T extends ISummaryDetailLevel>` ezt a típusparamétert várja, és az `AbstractPageAnalysisTool.loadPagesByKeywordSearch(...)` is ezt fogadja `detailLevel` paraméterként (`null` is átadható, ha a hívó tool nem különböztet meg részletességi szinteket).
`BaseDetailLevel`	`chatbot.enumeration`	Az `ISummaryDetailLevel` kész, azonnal használható enum implementációja három szinttel (`BRIEF`/`MEDIUM`/`FULL`). Plugin fejlesztő ezt adhatja meg `AbstractSummaryTool` típusparaméterként, vagy közvetlenül átadhatja bármelyik `ISummaryDetailLevel` paraméterű hívásnak, saját implementáció írása nélkül. A `BaseDetailLevel.from(String)` statikus metódus egy szabad szöveget von be a legközelebbi szintre (ismeretlen vagy null bemenetre `FULL`-ra esik vissza).
`DocumentMetaData`	`beans`	Az `AbstractIngestionTransformer` bemeneti sortípusa – egy dokumentum (nem egy oldal/mondat). Mezők: `id`, `name`, `text` (ha kitöltve, a transformer nem tölt le semmit), `url` (letöltési forrás, ha `text` üres), `format`, `system`, `summary` (hagyd üresen, ha nincs kész, végleges összefoglaló – kitöltve az ingestion pipeline ezt tekinti véglegesnek, és nem generáltat LLM-mel újat), `date`, `sections`/`writers`/`labels` (`List<String>`, fix cikk-séma: kategóriák/szerzők/címkék – ne tetszőleges scraper-adat tárolására használd). `Encoders.bean(DocumentMetaData.class)`-szel Spark `Dataset`-té alakítható. → Spark fejezet
`Embeddings`	`beans`	Egy lemmatizált, embeddelt mondat- vagy oldal-szintű passzus sora – ezen dolgozik mind a RAG retrieval, mind a NER ingestion. Mezők: `documentId`, `name` (dokumentum neve), `page`, `sentenceNumber`, `text` (a passzus szövege), `summary`, `date`, `relevant` (relevancia-jelölő), `vector` (`List<Float>`, az embedding vektor), `lemmaText` (lemmatizált szöveg), `importantWord` (lemmatizált kulcsszavak), `metaData` (`Map<String, String[]>` – a Spark szerializáció miatt kifejezetten `String[]` értékekkel, nem tetszőleges objektummal), `url`, `system`. Az `AbstractNERIngestionTool.executeIngestion()` `Dataset<Embeddings>` paraméterként kapja meg, soronként egy embeddelt passzust képviselve. → 10.5
`InputDocument`	`beans`	A platform belső, a `RagDBService`/`DocumentLoader` olvasó oldalán használt reprezentációja. Nincs `@SdkApi` annotációja – nem része az SDK-nak, plugin ne hivatkozzon rá közvetlenül; ingestion input-hoz a `DocumentMetaData` a helyes választás. → Spark fejezet
`BatchStatus`	`beans`	Egy batch (ingestion futás) vagy aszinkron feladat állapotleírója. Mezők: `createdAt`, `status` (`String`), `accepted` (`Long`), `errors` (`List<DocumentError>`), `finishedAt`, `phases` (`Map<String, PhaseProgress>` – névvel azonosított fázisok egyidejű előrehaladása). Az `IngestService.startIngest()` hozza létre és menti Redis-be, `getIngestStatus()`-szal kérdezhető le; aszinkron feladatoknál a Platform API `GET /api/platform/async_task/{taskId}` végpontja adja vissza. → Spark fejezet, → 13.4
`PhaseProgress`	`beans`	Egyetlen, névvel azonosított fázis előrehaladási állapota egy batch vagy feladat élettartamán belül – a `BatchStatus.phases` map értéktípusa. Mezők: `startedAt`, `finishedAt` (`null`, amíg a fázis folyamatban van), `total` (`null`, ha nem ismert előre), `succeeded`, `failed`. → 12.4
`DocumentError`	`beans`	Egy dokumentum feldolgozási hibájának leírása – a `BatchStatus.errors` lista elemtípusa. Mezők: `system`, `id`, `errorMessage`. → Spark fejezet
`RestartEvent`	`beans`	Egy batch feldolgozásának egy konkrét újraindítási eseménye – ki és mikor indította újra. Mezők: `restartedByUserId`, `restartedByDisplayName`, `restartedAt`.
`EmptyAsyncTaskRequest`	`tool.beans`	Üres, mezők nélküli kérés-típus olyan `IAsyncTaskTool` implementációkhoz, amelyek indításához nem szükséges semmilyen bemeneti paraméter. → 12.2
`PageTextEntry`	`chatbot.tool.beans`	Egy oldal-szintű embedding-rekord neve és szövege, a tárolt dokumentum-szerkezet elrejtésével. Mezők: `name`, `text`. Az `AbstractNERIngestionTool.findPagesByNameSuffix()` adja vissza. → 10.8
`RelationTypeMigration`	`beans`	Record: egy fogalom típusváltásához tartozó relációtípus-csere szabálya. Mezők: `oldRelationType` (a fogalomhoz kapcsolódó él jelenlegi relációtípusa, amelyre a csere vonatkozik), `newConceptType` (a fogalom új típusa, amely mellett a csere érvényes), `newRelationType` (az él relációtípusának új értéke). A szabályban nem szereplő kombinációjú élek változatlanul maradnak. → 12.5b
`ContextExpansionMode`	`enumeration`	Mit kap az LLM a keresési találatokból: `SENTENCE_ONLY` (csak a releváns mondatokat), `PAGE_SUMMARY` (a mondatokat és az oldalak összefoglalóját), `FULL_PAGE` (a találati oldalak teljes szövegét), `AUTO` (a kontextus méretétől függően). Az orchestrátor `getContextExpansionMode(PromptType)` hookja adja meg kérdéstípusonként. → 5.6
`RankingMode`	`enumeration`	A hibrid keresés pontjainak fúzióját és a találatok újrarendezését szabályozó módszer: `HEURISTICS`, `WEIGHTED_RRF`, `SOFT_FUSION` és `ROBUST_LINEAR`, az utóbbi hármat `_WITH_MMR` (redundancia-csökkentés) vagy `_WITH_BGE` (újrarangsoroló modell) változatban is. A `RetrievalOptions` része, az orchestrátor kérdéstípusonként állítja be.
`PromptType`	`enumeration`	A felhasználói prompt osztályozása retrieval-parameterezési célra – minden értékhez jellemző retrieval-profil (chunk-szám, BM25/vector arány, MMR, gráf-bővítés, kontextusméret) tartozik. Értékek: `FACTOID` (egyetlen tényre rákérdezés, alacsony k, BM25-domináns, gráf opcionális), `ENTITY_LOOKUP` (névvel azonosítható entitás keresése, alacsony k, gráf elsődleges eszköz), `DEFINITION` (fogalom-magyarázat, kiegyensúlyozott BM25/vector), `PROCEDURAL` (lépéssorozat/ protokoll – az MMR kifejezetten kerülendő, mert a dokumentumon belüli sorrend/kontinuitás elsődleges), `COMPARATIVE` (két/több entitás szembeállítása – az MMR aktívan szükséges, hogy mindkét oldal lefedést kapjon), `REASONING` (ok-okozat/következtetés, vector-domináns, gráf ajánlott), `CONTEXTUAL` (átfogó, több aspektust érintő összefoglalás, magas k, minden dimenzió aktív – ez az alapértelmezett érték osztályozási hiba és clarification re-entry esetén is). A tényleges profilokat az `AbstractOrchestratorTool.buildRetrievalOptions()` rendeli hozzájuk. → 5.4
`OrchestratorContext`	`tool.beans`	Record: az orchestrátor per-request inicializálásához szükséges kontextus – a pipeline az `AbstractOrchestratorTool.prepareChatContext(OrchestratorContext)` hívással adja át, mielőtt az orchestrátor `executeWithResult()`-ja lefutna. Mezők: `chatId` (a Redis clarification session kulcsa), `downloadPdf` (ha `true`, a pipeline letölthető PDF-et vár a végső válasz helyett – az orchestrátor ez alapján kikapcsolja a per-sub-query LLM köröket), `platformMode` (ha `true`, a Platform API hívta az orchestrátort, nem a chat pipeline – `NEEDS_CLARIFICATION` ilyenkor tiltott), `userLang` (a kérés felhasználói nyelve, `null` ha nincs ismert preferencia), `contextSizeToken` (a kérés kontextuskerete tokenben, a modell kontextusablakával korlátozva; ebből skálázódik a retrieval-profil és ekkora kerettel keres a RAG retrieval tool; `null` esetén a modell kontextusablaka). Visszafelé kompatibilis, rövidebb konstruktorok is elérhetők: `(chatId, downloadPdf)`, `(chatId, downloadPdf, platformMode)` és `(chatId, downloadPdf, platformMode, userLang)`.
`PendingQuestion`	`tool.beans`	Egy folyamatban lévő tisztázó kör aktuális, még megválaszolatlan kérdése. Mezők: `pendingQuestionId`, `pendingQuestion` (a kérdés szövege). Ez a típusa a `ClarificationSession.pendingQuestion` és a `TaskInfo.pendingClarificationQuestion` mezőnek is – tool oldalon jellemzően a `session.getPendingQuestion().getPendingQuestionId()` mintával érhető el, az `applyAnswer()` hívás célzott kérdés-azonosítójaként. → 7.3
`ConceptCleanupRequest`	`tool.beans`	Egy tudásgráf-tisztító (fogalom-összevonó) feladat indításához szükséges bemeneti paraméterek. Mezők: `targetDomain` (null vagy a forrás-domain-nel megegyező érték esetén helyben, a forrás domain collection-jeiben történik a tisztítás; eltérő érték esetén a feladat először a teljes forrás-állományt átmásolja ebbe a domain-be, és csak ezen dolgozik tovább), `confidenceThresholdPercent` (null esetén a feladat saját alapértelmezett küszöbbel fut), `system` (ha meg van adva, csak a kizárólag ehhez az egy system-hez tartozó fogalmak/relációk vesznek részt a klaszterezésben), `mergeableTypes` (null/üres lista esetén minden entitástípus szóba jön jelöltgenerálásra és összevonásra; az itt fel nem sorolt típusú fogalmak a system-szűréstől függetlenül kimaradnak).
`ConceptPairVerdict`	`tool.beans`	Egy fogalompárra vonatkozó LLM-döntés a páronkénti összevonás-jelölt értékelésben. Mezők: `pairId` (megegyezik a kérésben az adott párhoz megadott azonosítóval), `confidencePercent` (0–100: mekkora eséllyel jelenti a pár mindkét tagja ugyanazt a valós fogalmat), `canonicalLabel` (a pár két megnevezése közül a pontosabb/standardabb), `reasoning` (rövid indoklás).
`ConceptRetypeVerdict`	`tool.beans`	Egy meglévő fogalom lehetséges új típusára vonatkozó LLM-döntés – az `AbstractGraphEnrichmentTask` újraosztályozási módjának kimenete. Mezők: `conceptKey` (a fogalom ArangoDB kulcsa), `newType` (a felkínált típuslista egyike), `confidencePercent` (0–100), `reasoning`. → 12.5b
`WebSearchRequest`	`tool`	Az LLM által kinyert keresési paraméterek az `AbstractWebSearchTool` számára – ez a tool `IChatbotTool<WebSearchRequest>` generikus paramétere. Mezők: `searchQueries` (`List<String>`, LLM által generált keresési kifejezések – több query jobb lefedettséget ad), `language` (a keresési eredmények preferált nyelve, pl. `"hu"`), `maxResultsPerQuery` (lekérdezésenkénti maximum URL szám, 1–5).

LLM kliens

Osztály	Leírás
`BaseOpenAIClient` (stub)	OpenAI-kompatibilis HTTP kliens alapja. Publikus metódusok: `chat(OpenAIRequestVO)`, `chat(OpenAIRequestVO, CallbackWithErrorHandler)`, `setFirstTokenTimeot(long)`, `setResponseTimeout(long)`, `setRetryPolicy(RetryPolicy)`.
`OpenAIClient` (stub, `@Service`)	Lokális vLLM kliens. Spring context-ben `@Autowired`-del injektálható; `BaseLLMTransformer`-ben `protected static openaiClient`-ként elérhető.
`CloudOpenAIClient` (stub, `@Service`)	Cloud OpenAI kliens. API kulcsot a platform kezeli. `BaseLLMTransformer`-ben `protected static cloudOpenAIClient`-ként elérhető.
`RetryPolicy`	Újrapróbálkozási stratégia. Konstruktor: `RetryPolicy(maxRetries, baseDelayMs, maxDelayMs)`.

OpenAI beans

Osztály	Leírás
`OpenAIRequestVO`	LLM kérés DTO. Lombok `@Builder(toBuilder=true)`. Mezők: `model`, `stream`, `messages`, `response_format`, `max_tokens`, `temperature`, `top_p`.
`OpenAIResponseVO`	LLM válasz DTO. `getMessage().getContent()` adja a szöveges választ. `isDone()` jelzi a stream végét.
`TextChatMessageVO`	Szöveges chat üzenet. `role` + `content`. Lombok `@Builder`.
`JsonChatMessageVO`	Strukturált (TOON) tartalmú chat üzenet. `role` + `content: List<ToonInstructionContentVO>`.
`ToonInstructionContentVO`	TOON formátumú tartalom elem. `dataMap` + opcionális `headColumns` (kiemelt mezők leírással); `getText()` generálja a pipe-elválasztós TOON stringet. → 8.6
`OpenAIChoiceVO`	LLM válasz egy choice eleme – `getMessage()`.
`OpenAIErrorVO`	LLM hibaválasz – `getMessage()`, `getType()`, `getCode()`.
`OpenAIUsageVO`	Token-felhasználás statisztika.

Segédosztályok

Osztály	Leírás
`ToonUtil`	Statikus segédosztály: `toToon(ObjectMapper, Object)` bármely szerializálható Java objektumot ```toon``` blokkba ágyazott stringgé alakít – tool CONTEXT vagy ANSWER szövegébe illeszthető. Konverziós hiba esetén üres stringet ad vissza. → 8.6
`GeneralUtil`	Általános célú statikus segédmetódusok. Null-safe típuskonverziók: `getValueAsLong`, `getValueAsInt`, `getValueAsFloat`, `getValueAsDouble`, `getDouble` (String→double ág nélkül) – ArangoDB és Spark `Number` altípus-problémák elkerülésére. Map műveletek: `getValue(Map, String...)` és `setValue` mélységi eléréshez. Egyéb: `coalesce`, `partition(List, int)`, `putIfNotNull`, `putIfNotBlank`, `sha256Hex`, `getValueAsLocalDateInfo` (dátum → "yyyy-MM-dd (nap neve)" magyar nap nevekkel).
`HttpContentTypeUtil`	Egy URL tartalomtípusának megállapítása. `detectByExtension(url)` – hálózati hívás nélkül, tisztán az URL végződéséből (`.pdf`, `.doc`, `.docx`, `.html`/`.htm`), ismeretlen kiterjesztésnél `null`. `detectByHead(url)` – HEAD kéréssel kérdezi le a `Content-Type` fejlécet, szigorú (5 mp) connect/request timeout-tal; hiba vagy timeout esetén `"unknown"`-t ad vissza, sosem dob kivételt és sosem blokkol a timeout-nál tovább. Ajánlott sorrend: előbb `detectByExtension`, csak `null` esetén `detectByHead` – így elkerülhető a felesleges (és egyes szervereken akár örökre blokkoló) HEAD hívás. → Spark fejezet
`StoragePathUtil`	Statikus segédosztály protokoll-független fájlrendszer-eléréshez – ugyanazok a hívások helyi (`file://`), HDFS (`hdfs://`) és S3-kompatibilis (`s3a://`) útvonalakon egyaránt működnek, a Hadoop `FileSystem` absztrakción keresztül (az útvonal sémája dönti el a tényleges klienst). A `rag.storage.root` és az ebből képzett batch-útvonalak ezért S3-kompatibilis háttértárra is mutathatnak – plugin kódban a sima `java.nio.file.Files`/`Paths` helyett ezt az osztályt érdemes használni, mert a `java.nio.file.Path` nem képes `s3a://`/`hdfs://` séma-minősített útvonalat kezelni (Windows-on kivételt dob, Unixon hibásan, szó szerinti karakterként értelmezné). Útvonal-összefűzés: `resolvePath(root, segments...)` – séma-tudatosan fűzi össze a szegmenseket; séma nélküli (helyi) eredménynél a munkakönyvtárhoz képest abszolúttá alakítja, séma-minősített eredménynél változatlanul hagyja (egy `s3a://` URI már önmagában teljes). Létezés/metaadat: `exists`, `isDirectory`, `getFileSize`, `getModificationTime`, `fileName` (útvonal utolsó szegmense, tisztán string-feldolgozás, fájlrendszer-hívás nélkül). Olvasás: `readString`, `readAllBytes`, `newBufferedReader`. Írás: `writeString`, `write` (bájttömb), `appendString`, `newBufferedWriter`, `createEmptyFile`, `createDirectories`. Listázás: `listDirectChildren` (nem rekurzív), `listFilesRecursively`, `qualify` (séma-minősített teljes forma – két, eltérő módon képzett útvonal-string csak így hasonlítható össze megbízhatóan). Törlés: `delete(path, recursive)`. `useConfiguration(Configuration)` – a platform hívja egyszer, induláskor, a Spark session Hadoop konfigurációjával, hogy az S3A hitelesítő adatok elérhetők legyenek; plugin kódnak jellemzően nincs vele dolga. Fontos: `appendString` `s3a://` útvonalon `UnsupportedOperationException`-t dob, mert az S3 objektumok írás után módosíthatatlanok – valódi append csak helyi és HDFS fájlrendszeren működik.
`PartitionProgressCounter`	Fájlrendszer-alapú, partíciónkénti progress-számláló írása – egy adott partíció a saját, egyedi nevű számlálófájljába írja az aktuális állását. `increment(basePath, phase, partitionId, counterName)` eggyel növeli; `incrementBy(basePath, phase, partitionId, counterName, delta)` tetszőleges deltával, batch-szerűen feldolgozott munkánál. A `basePath`/`phase` párnak meg kell egyeznie azzal, amit az `AsyncTaskProgressReporter.beginLiveProgress()` hívás megadott. → 12.6
`KnowledgeGraphUtil`	Állapotmentes segédfüggvények a tudásgráf collection-jeihez – minden metódus statikus és mellékhatásmentes, nincs szükség ArangoDB-kapcsolatra vagy Spring bean-re, ezért Spark executor JVM-en (particiókban futó transzformáció belsejében) is közvetlenül hívható. Collection-név konvenció: `conceptCollection(domain)`, `relationCollection(domain)`, `mentionCollection(domain)`, `graphName(domain)` – mind a `prefix(domain)`-ra épülnek (a domain neve, vagy üres string, ha a domain `null`/üres). Normalizálás: `normalizeLabel(label)` – kanonikus forma a deduplicáláshoz: kisbetű + NFD dekompozíció + diakritikusok eltávolítása (pl. "Hipertónia" → "hipertonia"). Determinisztikus kulcsok: `buildMentionKey(rawConceptKey, documentSentenceKey)`, `buildConceptKey(type, normalizedLabel)` – típus-előtag + a type/normalizedLabel SHA-256 hash-ének első 16 hex karaktere, `buildRelationKey(fromConceptKey, toConceptKey, relationType)`. → KnowledgeGraphService fejezet
`CancellationRegistry`	Statikus, a teljes JVM-folyamatra kiterjedő megszakítás-nyilvántartás – a mutálható állapot egyetlen, kérésazonosító (`String requestId`) szerint kulcsolt tárban él, nem egy elkapott objektumban, mert egy `String` érték szerint túléli a Spark closure szerializációját is. `cancel(requestId)` jelöli meg egy adott kérést megszakítottként, `isCancelled(requestId)` kérdezi le az állapotot, `clear(requestId)` törli a bejegyzést. `registerChatId(chatId, requestId)` / `unregisterChatId(chatId, requestId)` egy `chatId → requestId` leképezést tart fenn; `cancelByChatId(chatId)` ezen a leképezésen keresztül szakítja meg a hozzá tartozó válaszfolyamot, ha a hívó csak a `chatId`-t ismeri.

Spark transformer réteg

Osztály	Leírás
`BaseTransformer` (stub)	SparkML `Transformer` kiterjesztése. Protected utility metódusok: `copyRowWithUpdatedField(Row, Map)`, `hasField(StructType, String)`.
`BaseLLMTransformer` (stub)	Párhuzamos LLM-alapú Spark transformer. Implementálandó abstract metódusok: `isNeedTransform(Row)`, `prepareDataSet(Dataset)`, `parseResponseJson(Row, String)`. Konfigurálható setterek: `setSystemPrompt(prompt, responseFormat)`, `setBatchSize(n)`, `setRetryPolicy(RetryPolicy)`, `setTemperature(f)`, `setMaxCompletitionToken(n)`, `setUsedLlm(type)`, `setModel(name)`, `setFirstTokenTimeout(minutes)`, `setResponseTimeout(minutes)`, `setInputCol(col)`, `setBasePath(basePath)`, `setPhase(phase)` – ez utóbbi kettő hívása nélkül a transform() nem ír élő progress-számlálót, a végrehajtás egyébként változatlan marad. Elérhető protected static mezők: `openaiClient`, `cloudOpenAIClient`, `objectMapper`. → Spark fejezet
`BaseBatchedTransformer` (stub)	`BaseLLMTransformer` nem-LLM testvére – ugyanaz a párhuzamos, batch-elt sor-feldolgozó keret, tetszőleges soronkénti mellékhatáshoz. Implementálandó abstract metódusok: `isNeedTransform(Row)`, `prepareDataSet(Dataset)`, `processRow(Row)`. Konfigurálható setterek: `setInputCol(col)`, `setBatchSize(n)`. → Spark fejezet
`AbstractIngestionTransformer` (stub)	`BaseBatchedTransformer` leszármazottja – kész, dokumentum-alapú ingestion transformer. Bemenet: `DocumentMetaData` sorokból álló `Dataset`. Soronként: ha `text` kitöltve, változatlanul tárolja; ha csak `url`, letölti és tartalomtípus szerint konvertálja (doc/docx → PDF, már PDF → változatlan, html → kinyert szöveg) – nem követ újabb linkeket. A platform meglévő ingestion staging formátumába (`source.json` + tartalom fájlok) ír. Nincs paraméterezett konstruktor (SDK-hatály alá tartozó osztályok csak no-arg konstruktort kaphatnak) – a domain/system a `setDomain(String)`/ `setSystem(String)` settereken keresztül állítódik be, a tárolási hely pedig a `setBatchId(String batchId)` hívásból (a `rag.storage.root` system property + batchId alapján, fix konvenció szerint - nincs domain alkönyvtár; a domaint egy "domain" nevű jelölőfájl viszi tovább a batch könyvtár gyökerében). A Redis feldolgozó-sorba való beütemezés nem a transformer feladata – azt az `IngestService` végzi (l. Platform service-ek). Resume-safe URL deduplikáció: letöltés előtt megnézi, nincs-e már a kért URL-hez tartozó fájl egy másik (még fel nem dolgozott, ezért még nem törölt) batch könyvtárában – ha igen, onnan másolja át, letöltés/konverzió nélkül. → Spark fejezet
`GraphWriteTransformer` (stub)	`BaseTransformer` leszármazottja, `mapPartitions`-alapú. Bemenet: a NER ingestion soronkénti nyers kimenete. Kimenet: soronként a `KnowledgeGraphService.upsertConcept(...)` hívásokkal kompatibilis struktúrájú concept/mention/relation oszlopok (egy sor = egy oldal). Minden reláció-jelöltet a deklarált relációtípus végpont-korlátjainak megfelelően ellenőriz, és ha az eredeti irányban nem illeszkedik, megfordított iránnyal is megpróbálja.
`RelationDiagnosticsTransformer` (stub)	`GraphWriteTransformer` diagnosztikai testvére – ugyanazt a végpont-típus szerinti illesztést végzi, de egyetlen collection-be sem ír. Minden reláció-jelöltet a kimenetben `VALID`, `SWAPPED` vagy `DROPPED` minősítéssel lát el, az illesztés eredménye szerint.

MCP kliens

Osztály	Csomag	Leírás
`IMcpClientTool`	`tool.intf`	MCP szervereket használó tool: `getMcpServers()` – a szerver-leírók, a tool regisztrálásakor egyszer hívva; üres lista esetén a tool nem használ MCP-t. → 14.3
`McpServerDescriptor`	`mcp`	Egy szerver elérési leírója, megváltoztathatatlan. `fromEnvironment(id, environment)` az `mcp.{id}.*` kulcsokból; `builder(id, url)`; `expectTools(names...)`, `expectTool(name, argumentsBean)`. Getterek: `getId()`, `getUrl()`, `isExternal()`, `getHeaders()`, `getConnectTimeoutMs()`, `getCallTimeoutMs()`, `isInsecureTls()`, `getOAuth()`, `isElicitation()`, `getExpectedTools()`. → 14.3
`McpOAuthClientCredentials`	`mcp`	Rekord: `tokenUrl`, `clientId`, `clientSecret`, `scope`, `audience`; a szöveges alakja a titkot nem tartalmazza. → 14.12
`IMcpSession`	`mcp`	Egy tool-futás MCP hozzáférése: `callTool(serverId, toolName, arguments[, options])`, `getTool(serverId, toolName)`, `listTools(serverId)`, `choose(key, question, choices)`, `ask(key, question)`, `missingRequired(serverId, toolName, arguments)`, `completeArguments(serverId, toolName, arguments, question)`. Nem szálbiztos. → 14.4–14.5
`McpCallOptions`	`mcp`	Hívás-beállítások, megváltoztathatatlan: `defaults()`, `retryable()`, `requireConfirmation(question)`, `withTimeoutMs(ms)`, `withRetryable()`, `withConfirmation(question)`.
`McpChoice`	`mcp`	Rekord: `value`, `label` (`null` felirat esetén az érték); `McpChoice.of(value, label)`.
`McpToolResult`	`mcp`	Egy hívás eredménye: `isError()`, `structured()`, `as(Class)`, `text()`, `contents()`, `isSuspicious()`, `getSuspiciousMatch()`, `getServerId()`, `getToolName()`. Publikus konstruktorral saját tartalmú eredmény is előállítható.
`McpContent`	`mcp`	Rekord, egy tartalmi elem: `type`, `text`, `mimeType`, `uri`, `name`, `data`, `raw`; `hasText()`.
`McpToolDefinition`	`mcp`	Egy meghirdetett tool leírása: `getName()`, `getTitle()`, `getDescription()`, `getInputSchema()`, `getOutputSchema()`, `getAnnotations()`, `getHeaderParameters()`. Megbízhatatlan, harmadik féltől származó adat.
`McpExecutionContext`	`mcp`	Rekord: `domain`, `systems`, `userPrompt`, `userLang`, `importantWords`, `requestId`, `chatId`, `userId` (az utóbbi kettő lehet `null`).
`McpLeakCheckContext`	`mcp`	Rekord: `userPrompt`, `server`, `toolName`, `outgoingArguments`. → 14.7
`McpProgress`	`mcp`	Rekord: `serverId`, `toolName`, `progress`, `total`, `message`; `percent()`. → 14.11
`McpException`	`mcp`	Futásidejű kivétel: `getKind()` (`NOT_SENT`, `OUTCOME_UNKNOWN`, `TIMEOUT`, `CANCELLED`, `PROTOCOL_ERROR`, `SERVER_UNAVAILABLE`, `UNSUPPORTED_RESULT`, `AUDIT_UNAVAILABLE`, `LEAK_CHECK_FAILED`, `INTERRUPTED`), `getJsonRpcCode()`, `getData()`, `isSafeToRetry()`.
`McpSchemaNormalizer`	`mcp`	`normalize(inputSchema)` – egy MCP tool bemeneti sémája a strukturált LLM-kimenethez használható részhalmazra alakítva. → 14.9
`McpContextFormatter`	`mcp`	`toReadableText(JsonNode)` – JSON olvasható, behúzásos kulcs–érték szöveggé, JSON-szintaxis nélkül. → 14.10

Platform service-ek

Osztály	Leírás
`SparkSessionStorage` (stub, `@Service`)	Spark session és modellek tárolása. Kulcs metódus: `getSession()` – az aktív `SparkSession`-t adja vissza. `@Autowired`-del injektálható tool-okba és transformer-ekbe. → Spark fejezet
`KnowledgeGraphService` (stub, `@Service`)	Tudásgráf UPSERT és lekérdező műveletek. Kulcs metódusok: `upsertConcept()`, `upsertRelation()`, `saveMention()`, `normalizeLabel(String)`, `findAliasesByLabels()`, `findConceptInfoByLabels()`, `findPageKeysByLabels()`, `findConceptPagesByLabels()` (fogalmanként az oldalak), `countMentionedPages()`, `findConnectedConcepts(domain, normalizedLabels, relationType, reverse, targetType)` – általános 1-hop, típusszűrhető gráfbejárás egy adott relációtípus mentén, irányparaméterrel. `@Autowired`-del injektálható bármely tool-ba, nem csak NER ingestion tool-okba. → 10. fejezet, → KnowledgeGraphService fejezet
`IngestService` (stub, `@Service`)	Az `AbstractIngestionTransformer` lefutása után kapott `Dataset<Row>` beütemezését és állapotkövetését végzi. Kulcs metódusok: `startIngest(String batchId, Dataset<Row> rows)` – kikényszeríti a Spark lusta kiértékelést, `BatchStatus`-t ment Redis-be, majd a batchId-t a feldolgozó sorba löki; és `getIngestStatus(String batchId)` – a mentett `BatchStatus` lekérdezése. `@Autowired`-del injektálható a plugin saját, ingestiont indító service-ébe – nincs szükség `RedisTemplate` vagy tárolási property-k közvetlen injektálására a plugin oldalán. → Spark fejezet

Infrastruktúra

Osztály	Leírás
`ToolRegistry`	Tool regisztrálás és keresés. `register(IChatbotTool)` – a platform automatikusan hívja; plugin fejlesztő általában nem hívja közvetlenül.
`OrchestratorRegistry`	Orchestrátor példányosítás. `registerPluginSupplier(Supplier)` – a `PluginLoader` hívja plugin orchestrátorokhoz.
`AsyncTaskRegistry`	Aszinkron feladat-végrehajtó komponensek nyilvántartása, domain és feladattípus szerint kereshetően. `register(IAsyncTaskTool)`/ `unregister(IAsyncTaskTool)` – a platform automatikusan hívja betöltéskor/eltávolításkor; plugin fejlesztő általában nem hívja közvetlenül. `findByTaskType(domain, taskType)` – a Platform API async task végpontjai használják a feladat indításához.
`JsonSchemaGenerator` (stub)	Request osztályból JSON schema generálás. `generateSchema(Class<?>)` – a `getRequestAsJsonNode()` implementálásához. Sima `Field` reflection alapján dolgozik – a mező Java típusából következtet a schema típusára (`List`→array, enum→string+enum értékek, szám/primitív szám→number, `Boolean`/ `boolean`→boolean, `String`→string, egyéb→beágyazott object). Semmilyen Jackson annotációt nem olvas ki (`@JsonPropertyDescription`, `@JsonProperty` stb. hatástalan) – a mezőkhöz tartozó, LLM-nek szánt leírás kizárólag a tool `getInstruction()` szövegéből származhat, nem a request bean annotációiból. Egy mezőt a saját, nem Jackson-alapú `@ExcludeFromSchema` annotációval lehet kihagyni a sémából – a mező a tényleges JSON (de)szerializációban ettől függetlenül, változatlanul részt vesz, csak az LLM-nek felkínált sémából marad ki. Ha egy típus – közvetlenül vagy beágyazott mezőkön keresztül – önmagára hivatkozik, az önhivatkozás pontján a beágyazott séma üres object-ként zárul le, végtelen rekurzió nélkül. A `generateSchema()` a mezők leírását adja (egy objektumséma `properties` tartalmát); `asObjectSchema(JsonNode)` – `{"type":"object","properties":…}` keretbe teszi, ha a csomópontnak nincs szöveges `type` mezője, a teljes sémát változatlanul hagyja. A platform paraméter-kinyerése ezzel ágyazza be a `getRequestAsJsonNode()` eredményét, így az mezőleírás és teljes séma is lehet.
`CallbackWithErrorHandler<T, E>`	Streaming callback interfész. `onSuccess(String, T)`, `onFailure(Call, String, E)`.
`IResponseEmitter`	A tool és a pipeline közötti válaszfolyam csatorna – a `IChatbotTool.executeWithResult()` és a többi tool-metódus `responseEmitter`/`progressEmitter` paraméterének tényleges típusa. Kiterjeszti a `FluxSink<TextGenerationResponse>`-t. Saját tagjai: `getRequestId()` – a válaszfolyamhoz tartozó, sima String egyedi azonosító, amely végrehajtási környezethatárokon is sértetlenül átvihető, és amely alapján egy külön tárolóban lekérdezhető, hogy a válaszfolyam időközben megszakításra került-e; és a default `progress(String status)` kényelmi metódus, amely egy csak `progressStatus`-t (tartalom nélkül) hordozó `TextGenerationResponse`-t küld. A default `getContextSizeToken()` a kérés kontextuskeretét adja tokenben (a modell kontextusablakával korlátozva, `null`, ha a kérés nem ad keretet); a pipeline a `setContextSizeToken(Integer)`-rel állítja be. Az `AbstractPageAnalysisTool` ebből számolja a chunkok és az LLM-bemenet méretét. → 9.4
`TextGenerationResponseEmitter`	Az `IResponseEmitter` egy konkrét, becsomagoló implementációja: ha a becsomagolt `FluxSink<TextGenerationResponse>` `null`, no-op emitterként viselkedik – minden hívás biztonságosan elnyelődik –, egyébként az eseményeket változatlanul továbbítja neki. Ha a becsomagolt válaszfolyam maga is `IResponseEmitter`, a konstruktor átveszi annak `requestId`-jét (nem generál újat), különben új azonosítót generál és bekapcsolja a megszakítás-figyelést. A kontextuskeretet, ha magának nincs beállítva, a becsomagolt válaszfolyamtól kérdezi le. → 9.4
`IPluginConfigurer`	Plugin inicializáló hook. A `PluginLoader` betöltéskor meghívja a `configure(ApplicationContext)` metódust – itt lehet Spring bean-eket regisztrálni, adatforrásokat inicializálni. Az általa regisztrált singleton bean-ek az unload-kor automatikusan törlődnek (`destroySingleton`). → 11. fejezet

Authentikáció

A platform a saját autentikációs rendszerében (Keycloak) azonosítja a hívó felhasználót. Ez kizárólag azonosítást ad – a jogosultsági logika (ki, mely tool-t futtathatja) a plugin fejlesztőjének hatásköre, tetszőleges saját autorizációs réteggel felépíthető a platform user azonosítójára támaszkodva. → 5.5

Osztály	Csomag	Leírás
`CurrentUserUtil` (stub)	`security.util`	Statikus segédosztály a hívó felhasználó lekérdezéséhez. `getCurrentUser()` – a platform autentikációs kontextusából (Spring `SecurityContextHolder`) visszaadja a bejelentkezett felhasználót `IUser`-ként, vagy `null`-t anonim esetben. `getCurrentUserId()` – kényelmi shortcut, csak az azonosítót adja vissza.
`IUser`	`security.intf`	A platform autentikált principaljának minimális azonosító-szerződése. `getId()` / `setId(Long)`.
`UserMap`	`security.beans`	`HashMap<String, Object>` alapú `IUser` implementáció – a platform ezt adja vissza `getCurrentUser()`-ből. Tetszőleges további kulcs-érték párt hordozhat a bejelentkezett felhasználóról.

💡

Az executeOrchestratorActivatedTools(Map userData, ...) és az ebből minden tool isEligible(Map userData) hívásába továbbadott userData paraméter nem kell, hogy a platform UserMap-ja legyen. Jellemző minta: a plugin CurrentUserUtil.getCurrentUserId()-vel lekéri a platform-beli azonosítót, ezzel kihív a saját autorizációs rendszerébe, és az onnan kapott jogosultsági attribútumokból épít egy saját Map-et – ez jelenik meg utána minden tool isEligible() hívásában.

11. fejezet: Plugin deploy 12. fejezet: Aszinkron feladatok