service-finder/docs/V02/22_Robot_Ecosystem.md

22. Robot Ökoszisztéma & AI Intelligence (v2.0)

Ez a dokumentum az autonóm ágensek technikai specifikációját és koordinációját tartalmazza.

22.1 Robot 1: Catalog Scout (The Discovery)

• Feladat: Új járműmodellek importálása külső forrásokból (RDW, NHTSA).
• Működés: unverified státuszú alaprekordokat hoz létre. Ha a forrás blokkol (Ban-Detection), a robot automatikusan "Silent Mode"-ba vált.

22.2 Robot 2: Technical Enricher (The Detective v1.2.6)

A legfejlettebb modul, amely a nyers adatokat master-adatokká dúsítja.

AI Search RAG (Retrieval-Augmented Generation):

• Mivel a Google Search tool használatakor a Gemini letiltja a kényszerített JSON formátumot, a robot Regex-alapú JSON bányászatot alkalmaz a nyers válaszból.
• Cél: Modellkódok, évjáratok és szervizintervallumok kinyerése közvetlenül az internetről.

Safe-Merge & Not-Null védelem:

• Fallback Kódok: Ha az AI nem talál kódot, a robot N/A-{id} vagy UNKNOWN-{id} ál-kódokat generál az SQL kényszerek (Unique, Not-Null) betartása érdekében.
• Deduplikáció: Csak akkor von össze rekordokat, ha a technikai kód ÉS a hengerűrtartalom (CCM) is megegyezik.

22.3 Robot 3: OCR & Multimodal Document AI

• Feladat: Számlák, forgalmik és kilométerórák elemzése.
• Integráció: A felismerés során kinyert szervizadatokat keresztellenőrzi a data.organizations táblával. Ha ellentmondást talál, a szervizt flagged státuszba teszi.

22.4 Robot 4: Service Hunter (Tervezett)

• Cél: A dúsított technikai adatok alapján szerviz-csomagok és árak automatizált keresése.
• Működés: A specifications mezőben tárolt folyadékmennyiségek és alkatrész-típusok alapján generál ajánlat-tervezeteket.

22.5 Robot Koordináció (Orchestration)

A robotok az adatbázist használják "jelzőtáblának", elkerülve az ütközéseket:

1. R1 rögzíti az alapot.
2. R2 dúsít és validál.
3. R3 (OCR) bizonyítékokat csatol a jármű életútjához.
4. Minden művelet a ProcessLog táblában kerül rögzítésre az auditálhatóság érdekében.

2026.02.18 Frissített Robot 2.0 Dúsítés több példányban

🤖 TechEnricher Robot (v1.2.6) - Dokumentáció

1. Célkitűzés

A TechEnricher feladata a data.vehicle_model_definitions táblában található nyers, tisztítatlan járműadatok automatizált dúsítása technikai adatokkal (CCM, kW, Évjárat, Szervizintervallumok) és a duplikációk intelligens felszámolása.

2. Technikai Architektúra

• Motor: Python 3.10+ Asynchronous IO
• AI Integráció: Google Gemini 2.0 Flash
• Adatbázis Logika: SQLAlchemy 2.0 + PostgreSQL Row Level Locking
• Deduplikációs Kulcs: make + technical_code + vehicle_type

3. Kulcsfunkciók

🛡️ Manuális Védelem (Manual Override)

A robot soha nem írja felül a manuálisan rögzített adatokat. Ha a rekord is_manual mezője true, a folyamat érintetlenül hagyja azt.

🔗 Intelligens Összefűzés (Smart Merge)

Az egyediségi kényszerek (Unique Constraints) megsértése helyett a robot felismeri az ütközéseket:

• Ha a technikai kód alapján már létezik rekord, az új bejegyzést duplicate státuszba helyezi.
• Létrehozza a kapcsolatot a parent_id mezőn keresztül.
• A Master rekord synonyms mezőjét automatikusan bővíti az új elnevezéssel.

🛑 Anti-Loop és Hibakezelés

• Attempts: Minden rekord maximum 3 esélyt kap.
• Last Error: A hibás tranzakciók okát a robot elmenti a rekordhoz.
• Circuit Breaker: 10 egymást követő kritikus hiba esetén a robot 15 percre "alvó üzemmódba" vált az API-kvóta védelme érdekében.

4. Működési Sorrend (Logic Flow)

1. Fetch: 20 rekord lekérése SKIP LOCKED módban.
2. Pre-Map: Adatok kimentése memóriába (Greenlet védelem).
3. Group: Csoportosítás márkák/modellek szerint.
4. Enrich: AI vagy Belső Cache hívás.
5. Validate: Sanity check a technikai adatokra.
6. Commit: Tranzakció mentése (Master/Duplicate logika szerint).

5. Skálázás

A robot felkészített a horizontális skálázásra:

docker compose up -d --scale enricher_robot=3

🤖 22.0 Robot 0: The Strategist (Market Prioritizer)Cél: A feldolgozási sorrend optimalizálása a piaci relevancia alapján.Logika: Lekéri a külső források (pl. RDW) statisztikáit, és darabszám szerint rangsorolja a márkákat.Működés: 1.  Kategóriákra bont (Személyautó > Motor > Teherautó > Egyéb).2.  Feltölti/Frissíti a data.catalog_discovery táblát.3.  Biztosítja, hogy a Robot 1 a legnépszerűbb modellekkel kezdjen.

🤖 22.1 Robot 1: The Hunter (Paginator v2.4)Cél: Strukturált jármű-variánsok tömeges importálása.Működés: - Recon: Megszámolja az adott márkához tartozó összes rekordot ($select=count(*)).Paging: 1000-es csomagokban, módszeresen végiglapozza a teljes adatbázist.Deduplikáció: Csak az egyedi technikai variánsokat (Márka + Modell + ccm + kW) menti el a data.vehicle_model_definitions táblába.

🤖 22.2 Robot 2.1: The Researcher (Industrial-v2.1)Cél: Technikai kontextus és szervizspecifikációk "porszívózása" az internetről.Működés:DuckDuckGo/Google Search segítségével adatokat gyűjt: olajmennyiség, viszkozitás, gumiabroncs nyomás, vezérlés csereperiódus, gyújtógyertya típus.A nyers szöveget a raw_search_context mezőben tárolja el a későbbi feldolgozáshoz.

🤖 22.3 Robot 2.2: The Alchemist (AI-Gold v2.2)Cél: A kutatott szövegek strukturált JSON-ná (Arannyá) alakítása.Működés:LLM (Ollama/Gemini) segítségével kinyeri a technikai adatokat a kutatási kontextusból.Factory Data Mapping: Betölti a data.vehicle_catalog táblába a végleges adatokat.Validation: Ha az adat ellentmondásos, manual_review státuszba helyezi a rekordot.

🤖 22.4 Robot 2.3: The Guardian (Predictive Notifier)Cél: Napi monitorozás és prediktív értesítések generálása (07:00-08:00 UTC).Logika: - Okmányfigyelő: Figyeli a data.assets és data.persons táblák lejárati dátumait (Műszaki, Biztosítás, Adó, Orvosi).Karbantartási Naptár: Összeveti az utolsó szerviz óta eltelt időt/kilométert a factory_data intervallumaival.Értesítési Mátrix: - 30 nappal / 1000 km-rel előbb: Emlékeztető (Lite).7 nappal / 200 km-rel előbb: Sürgető (Action Required).Lejárat napján: Kritikus riasztás.Kimenet: Bejegyzés a data.notification_queue táblába (Email/Push).

🛠 22.5 Adatminőség & Validációs RangsorA rendszer megkülönbözteti az adatok forrását, ami befolyásolja a jármű "Trust Score"-ját:ForrásHitelességi szintHatása az Asset-rePartner SzervizHigh (Verified)Digitális szervizkönyv pecsétet kap.User (Számlával)MediumFeltöltött dokumentumhoz kötött, admin jóváhagyásra várhat.User (Csak adat)LowTájékoztató jellegű, a jármű értékét nem növeli hivatalosan.

💰 22.6 Költségcsoportosítás & Elszámolás (TCO)A költségek a data.asset_costs táblában rögzülnek az alábbi csoportosításban:Üzemanyag: Tankolások, fogyasztásmérés.Karbantartás: Alkatrész, munkadíj.Adók & Díjak: Biztosítás, adó, matrica.Munkába járás: Automatikus kalkuláció a munkanapok és a rögzített távolság alapján (NAV/Helyi norma szerinti térítés).