HydraLLM: Orkestrator Cerdas

HydraLLM: Orkestrator Cerdas

HydraLLM adalah gateway sadar konteks yang dirancang untuk memanfaatkan berbagai sumber daya LLM secara efisien. Ia merutekan permintaan di Gemini / Groq / Cerebras, menyediakan circuit breaker per penyedia, rotasi kunci acak (termasuk cooldown yang sadar kuota), kemampuan pengayaan web real-time, dan membangun API yang kompatibel dengan OpenAI di atas Clean Architecture yang ketat (Domain lalu Services lalu Adapters lalu API).

• Versi: 1.3.0 (pyproject.toml)
• Python: 3.10+
• Titik masuk eksekusi: python main.py
• UI terintegrasi: http://localhost:8000/ui
• Endpoint kompatibel OpenAI: POST /v1/chat/completions

Spesifikasi Teknis HydraLLM (SPEC)

1. Gambaran umum

HydraLLM adalah gateway LLM highly available yang mematuhi Clean Architecture. Ia menyediakan perutean cerdas antar banyak penyedia, isolasi kegagalan berbasis circuit breaker, kemampuan pengayaan web real-time, dan mendukung spesifikasi OpenAI API secara penuh.

2. Spesifikasi komponen inti

2.1 Gateway (src/services/gateway.py)

• Orkestrasi: Mengoordinasikan alur pemuatan sesi -> analisis konteks -> pengayaan web -> eksekusi tangguh -> persistensi.
• Alasan perutean teknis: Menyertakan dasar pengambilan keputusan dalam semua respons sebagai konstanta yang jelas.
  • USER_HINT: penentuan eksplisit oleh pengguna
  • TOKEN_OPTIMIZED: optimasi berbasis jumlah token
  • WEB_INTENT_SEARCH: hasil analisis intent pencarian web
  • MULTIMODAL_ANALYSIS: deteksi kebutuhan pemrosesan gambar
  • KEY_AVAILABILITY: status kunci dan hasil failover

2.2 Context Analyzer (src/services/analyzer.py)

• Algoritma perutean: Menganalisis panjang token, sifat multimodal, dan niat pencarian web untuk menghasilkan RoutingDecision yang optimal.
• Pemfilteran ketersediaan dinamis: Mencerminkan status real-time dari KeyManager, sehingga model dari penyedia yang tidak memiliki kunci aktif dikeluarkan dari opsi pemilihan.

2.3 Key Manager (src/services/key_manager.py)

• Rotasi kunci: Pemilihan acak dalam pool kunci aktif dan pelacakan penggunaan.
• Manajemen kegagalan: Menerapkan cooldown yang berbeda menurut jenis error.
  • 403 Forbidden: 24 jam (menangani kegagalan permanen pada level kunci)
  • 429 Rate Limit / Quota: 1 jam
  • Error komunikasi lainnya: 5 menit

2.4 Web Context Service (src/services/web_context_service.py)

• Pengayaan data: Pengumpulan informasi real-time berbasis Playwright/Scrapling dan injeksi ke prompt.
• Pelacakan performa: Mencatat tingkat keberhasilan, jumlah karakter yang dikumpulkan, dan latensi melalui tabel scraping_metrics.

3. Pola ketahanan dan pemulihan (Troubleshooting Insights)

• Concurrency Guard: Menerapkan asyncio.Lock dan threading.Lock pada operasi tulis KeyManager dan SessionManager untuk menjamin integritas data dalam kondisi beban tinggi.
• Self-Healing Scraper: Mengaktifkan mekanisme restart otomatis saat terdeteksi crash pada instance browser.
• Unpacking Guard: Mematuhi tipe pengembalian yang ketat (tuple[list, str | None]) dan guard untuk mencegah error NoneType yang dapat terjadi saat memproses data pengayaan.