Skip to content
Back to search

kap-agent

BIST KAP disclosure agent with rule-based XBRL extraction, read-only SQLite+FTS5 self-healing SQL, citation gating, and MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kadirchelik--kap-agent/badge.svg)](/listings/kadirchelik--kap-agent)

HTML

<a href="/listings/kadirchelik--kap-agent"><img src="/api/listings/kadirchelik--kap-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 111 lines
  1. # KAP Agent — BIST KAP Bildirim Analizi ve Self-Healing SQL Ajanı
  2. > **Uyarı & Kapsam Sınırı:** Bu proje yalnızca Kamuyu Aydınlatma Platformu (KAP) bildirimlerini yapılandırılmış veriye dönüştürür ve kaynak bildirim ID'leriyle (`[kap:ID]`) doğrulanabilir analiz sunar. **Yatırım danışmanlığı, hedef fiyat tahmini veya al-sat önerisi vermez.**
  3. ---
  4. ## Mimari Genel Bakış
  5. KAP Agent, halüsinasyon riskini ve API maliyetini düşürmek için **Çevrimdışı Yapılandırılmış Çıkarım** ile **Çevrimiçi Salt-Okunur Ajan Çalışma Zamanı**nı birbirinden ayırır:
  6. 1. **Çevrimdışı Veri & Çıkarım Hattı (`backend/app/pipeline/`)**:
  7. - **Kibar CLI Çekici (`fetcher.py`):** 85 günlük dönem parçalaması, `byCriteria` ve bildirim istekleri arası gecikme + jitter, yerel disk önbelleği (`data/raw/`), özel `User-Agent` ve V1 banka hariç tutma filtresi uygular.
  8. - **Pydantic v2 Çıkarıcı (`extractor.py`) ve Çoklu Sağlayıcı Zinciri (`backend/app/llm/`):** 3 bildirim türü (`dividend`, `financial_report`, `material_event`) için **bildirim başına 1 kez** SHA-256 içerik özetiyle önbellekli JSON çıkarımı yapar. `prepare_extraction_text` ile büyük XBRL HTML raporlarını (`150+ KB`) gürültüden arındırarak `25.000` karakter sınırı içinde gelir tablosu/bilanço özetini korur. `FallbackChainProvider` giden hız sınırlaması (`llm_min_interval_sec`) ve `429 Retry-After` beklemesiyle `Gemini -> Groq -> OpenRouter` arasında otomatik geçiş yapar.
  9. - **SQLite + FTS5 (`schema.sql`, `connection.py`):** Tam metin arama (`unicode61 remove_diacritics 2`) ve ilişkisel tablolar (`disclosures`, `dividend_events`, `financial_reports`, `material_events`) tutar.
  10. 2. **Çevrimiçi Ajan Runtime & Güvenlik Katmanı (`backend/app/agent/`)**:
  11. - **Çift Bağlantı İzolasyonu:** Ajan araçları **yalnızca** `mode=ro` + `PRAGMA query_only = ON` + `1500ms` timeout ile açılan `get_readonly_agent_conn` üzerinden çalışır.
  12. - **Tek-`SELECT` `sql_guard.py`:** Çoklu ifade (`;`), yorum satırı (`--`, `/* */`), `WITH` CTE, yazma/DDL/PRAGMA ifadeleri ile `review_flags` / `sqlite_master` erişimini engeller; `LIMIT <= 50` zorunlu kılar.
  13. - **SQL Self-Healing Döngüsü (`orchestrator.py`):** `run_sql` hatası döndüğünde hata mesajı ve şema özeti ajana geri beslenir; ajan sorguyu en fazla **3 kez** (`max_sql_retries=3`) kendi kendine düzeltir.
  14. - **Al-Sat Guardrail & `citation_gate.py`:** Yatırım tavsiyesi sorularını 0 LLM maliyetiyle reddeder; yanıtlardaki `[kap:ID]` atıflarını araç çıktıları ve veritabanıyla doğrulamadan kullanıcıya dönmez.
  15. 3. **Kullanıcı Düzeltme Kuyruğu & Kota Koruması (`backend/app/api/`)**:
  16. - **`review_flags` + Admin Onayı (`routes_reviews.py`):** Arayüzden gelen düzeltme önerileri HTML/script temizliği ve IP rate-limit sonrası `status = 'pending'` olarak kuyruğa alınır; ana tablolar yalnızca `X-Admin-Token` doğrulamalı admin kararıyla güncellenir.
  17. - **Kota ve Hız Koruması (`quota_guard.py`, `main.py`):** Sorgu önbelleği, `/api/*` için IP başına global `60/dk` sliding-window rate-limit middleware'i (`429 Retry-After`), günlük limitler ve örnek sorular için sıfır maliyetli **Demo Modu** içerir.
  18. 4. **İnce MCP Server Katmanı (`backend/app/mcp/server.py`)**:
  19. - Aynı salt-okunur `search_disclosures`, `get_disclosure` ve `run_sql` araçlarını stdio JSON-RPC 2.0 MCP sunucusu olarak Claude Code, Antigravity veya Claude Desktop'a açar.
  20. ---
  21. ## Veri Kaynağı Şeffaflığı ve Canlı Eval Sonuçları
  22. - Repodaki `data/sample_seed/` (24 bildirim: 8 temettü, 8 finansal rapor, 8 özel durum) kurulumsuz unit test ve CI doğrulaması için deterministik test verisi olarak korunur (`SYNTHETIC_SAMPLE_SEED`).
  23. - Yerel üretim veritabanı (`data/kap_agent.db`, `.gitignore` altında) BIST 30'daki 18 banka dışı şirketten çekilmiş **185 gerçek KAP bildirimi** içerir (`2025-04-28` – `2026-11-19`); `2026/09` finansal sonuçları yayımlanan **17/18** şirketin tamamı kapsanmıştır *(KONTR SPK ek süre kapsamında, `kap:1695620`)*. Arka plan senkronizasyonu (`KAP_AUTO_SYNC_ENABLED=true`, her `15 dk` ve soğuk başlangıçta `45` günlük otomatik tarama) ile yeni bildirimler otomatik eklenir.
  24. - `evals/extraction_gold.jsonl` (50 gerçek bildirim) ve `evals/agent_gold.jsonl` (30 gerçek soru) kayıtları canlı `https://www.kap.org.tr/tr/Bildirim/<ID>` sayfalarıyla (`51/51 HTTP 200 OK`) karşılaştırılıp doğrulanarak **`"verified": true`** işaretlenmiştir.
  25. - Değerlendirme betikleri **yalnızca `"verified": true` kayıtlar üzerinden** metrik hesaplar; API anahtarı olmayan/offline koşullarda çalıştırıldığında **`OFFLINE/SAHTE`** uyarısı basar.
  26. | Eval Paketi | Doğrulanmış (`verified: true`) | Ölçüm Modu (`--live`) | Ölçülen Gerçek Sonuçlar |
  27. | --- | --- | --- | --- |
  28. | Çıkarım Eval (`evals/run_extraction_eval.py`) | 50 / 50 | `LIVE_LLM (gemini-3-flash-preview)` | Şema Geçerliliği `%100.0` · Alan Eşleşmesi `%93.84` (`financial_report` `%99.12`, `dividend` `%92.86`, `material_event` `%89.17`) · Sayısal Doğruluk `%92.31` *(XBRL ön-işleme öncesi `%82.05`)* |
  29. | Agent Eval (`evals/run_agent_eval.py`) | 30 / 30 | `LIVE_LLM (gemini-3-flash-preview)` | İlk Denemede SQL `%95.83` (ort. tekrar `0.03`) · Citation Precision `%100.0` / Recall `%100.0` · Tavsiye Reddi `%100.0` · Cevap Eşleşmesi `%90.0` (`p50: 24,095.89 ms`) |
  30. ---
  31. ## Kapsam ve Bilinen Sınırlar
  32. - **Şirket Evreni:** BIST 30 içinden seçili 18 reel sektör şirketi (`THYAO`, `TUPRS`, `FROTO`, `ASELS`, `BIMAS`, `EREGL`, `SISE`, `TCELL`, `TTKOM`, `KCHOL`, `SAHOL`, `TOASO`, `ARCLK`, `MGROS`, `PGSUS`, `ENKAI`, `ASTOR`, `KONTR`).
  33. - **Bankalar Hariç:** `GARAN`, `AKBNK`, `ISCTR`, `YKBNK`, `VAKBN`, `HALKB`, `TSKB`, `ALBRK`, `SKBNK` banka hisseleri BDDK bilanço formatı farkı nedeniyle V1 `financial_report` şemasından hariçtir.
  34. - **Kapsam Dışı:** Al-sat önerisi, kullanıcı girişi, vektör veritabanı, fine-tuning ve çoklu ajan (multi-agent swarm) mimarisi.
  35. ---
  36. ## Hızlı Başlangıç
  37. ### 1. Ortam Değişkenleri ve Backend (FastAPI)
  38. ```powershell
  39. Copy-Item .env.example .env
  40. # .env içine GEMINI_API_KEY (ve isteğe bağlı yedek GROQ_API_KEY / OPENROUTER_API_KEY) ekleyin
  41. cd backend
  42. python -m pip install -e . pytest
  43. uvicorn app.main:app --reload --port 8000
  44. ```
  45. ### 2. Frontend (React + TypeScript + Vite)
  46. ```powershell
  47. cd frontend
  48. npm install
  49. npm run dev
  50. ```
  51. ### 3. Yerelde Gerçek KAP Verisi Çekme ve Canlı Eval (`--live`)
  52. ```powershell
  53. cd backend
  54. python -m app.pipeline.fetcher --limit 25 --delay-sec 2.5 --start-date 2025-01-01
  55. python -m app.pipeline.extractor
  56. python -m app.pipeline.fetcher --skip-fetch --promote-to-sample 24 --build-gold-draft ..\evals\extraction_gold.jsonl
  57. python -m app.db.seed_loader --dataset full
  58. # evals/*.jsonl içinde kontrol ettiğiniz kayıtlara "verified": true yazdıktan sonra:
  59. cd ..
  60. python evals/run_extraction_eval.py --live
  61. python evals/run_agent_eval.py --live
  62. ```
  63. ### 4. Testler, CI ve Docker
  64. ```powershell
  65. # Backend (pytest)
  66. cd backend && python -m pytest
  67. # Frontend (vitest + build)
  68. cd frontend && npm test && npm run build
  69. # Docker Compose ile tek komut çalıştırma
  70. docker compose up --build
  71. ```
  72. Otomatik CI (`.github/workflows/ci.yml`), `master`/`main` push ve PR'larda backend `pytest` ve frontend `vitest` + `vite build` adımlarını çalıştırır.
  73. ### 5. MCP Server Entegrasyonu (`mcp_config.json`)
  74. ```json
  75. {
  76. "mcpServers": {
  77. "kap-agent": {
  78. "command": "python",
  79. "args": ["-m", "app.mcp.server"],
  80. "cwd": "C:/Users/Windows/Desktop/kap-agent/backend"
  81. }
  82. }
  83. }
  84. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.