Borsa Analizi Multi-Agent Sistemi

Uzun Türkçe borsa analiz ses kayıtlarını otomatik olarak transkript eden, içindeki finansal sinyalleri yapay zeka ile çıkaran ve vektör veritabanına kaydederek aranabilir hale getiren uçtan uca bir sistemdir.

1. Sistem Mimarisi
2. Nasıl Çalışır
3. Gereksinimler
4. Kurulum
5. Yapılandırma
6. Sistemi Başlatma
7. Arayüz Genel Bakış
8. Kullanım Kılavuzu
9. Proje Yapısı
10. Sık Karşılaşılan Sorunlar

flowchart TB
 USER["🖥️ KULLANICI Tarayıcı<br/>http://localhost:8501"]
 UI["Streamlit UI — ui/app.py<br/>Ses/Video yükleme · Transkript görüntüleme<br/>Analiz başlatma · Sinyal kartları<br/>Oturum yönetimi · Vektör arama"]
 API["FastAPI Backend — api/main.py<br/>/jobs/transcribe · /jobs/analyze<br/>/jobs/{id}/poll · /sessions<br/>/signals/search · /signals/all"]
 subgraph AGENTS[" "]
 direction TB
 A1["AJAN 1 — Chunker<br/>mlx-whisper transkripsiyon → segment bazlı chunk<br/>Dinamik chunk boyutu (max 30 dk)<br/>300 kelime örtüşme (bağlam kaybı önleme)<br/>Durdur / Devam Et desteği"]
 A2["AJAN 2 — Analyst<br/>Gemini 2.5 Flash (yedek: GPT-4o-mini)<br/>Finansal sinyal çıkarımı (alım/satım/destek/direnc...)<br/>Hisse kodu eşleştirme (Whisper hataları dahil)<br/>Güven skoru ataması"]
 A3["AJAN 3 — Uploader<br/>BGE-M3 embedding → Qdrant upsert<br/>Dense + sparse hibrit vektör<br/>Duplikat önleme (fiyat + hisse + tip bazlı)"]
 A1 -->|chunk listesi| A2
 A2 -->|sinyal JSON| A3
 end
 QDRANT["Qdrant Vektör DB (Docker)<br/>Koleksiyon: finansal_analiz<br/>Dense (1024 boyut) + Sparse hibrit arama"]
 USER -- HTTP --> UI
 UI -- "HTTP (localhost:8000)" --> API
 API --> AGENTS
 A3 -- "HTTP (localhost:6333)" --> QDRANT

flowchart TD
 F["Ses/Video Dosyası<br/>.m4a / .mp3 / .wav / .mp4"]
 S1["1. mlx-whisper transkripsiyon<br/>→ segment listesi (start, end, text)"]
 S2["2. Chunk birleştirme<br/>→ dinamik boyutlu metin parçaları<br/>→ her parçaya önceki 300 kelime bağlam eklenir"]
 S3["3. Gemini 2.5 Flash analizi (her chunk için sırayla)<br/>→ JSON: hisse, sinyal_tipi, fiyat, güven, kaynak_cumle"]
 S4["4. BGE-M3 embedding + Qdrant kayıt<br/>→ duplikat kontrol → arama yapılabilir vektör"]
 S5["5. Streamlit UI'da görüntüleme ve arama"]
 F --> S1 --> S2 --> S3 --> S4 --> S5

Ses dosyası mlx-whisper ile Türkçe olarak yazıya dökülür. Model olarak mlx-community/whisper-large-v3-mlx kullanılır. Whisper'ın döndürdüğü segment sınırları korunarak metin parçalara (chunk) bölünür — hiçbir cümlenin ortasından kesilme yapılmaz.

Dinamik chunk boyutu: Kayıt 30 dakikadan kısaysa tek parça; daha uzunsa eşit parçalara bölünür (her biri en fazla 30 dakika). 95 dakikalık bir kayıt 4 parçaya ayrılır.

Bağlam örtüşmesi: Analist bir cümleye bir parçanın sonunda başlayıp diğerinde bitirdiğinde hisse adı kaybolabilir. Bunu önlemek için her parçanın başına önceki parçanın son 300 kelimesi eklenir. Bu bölüm Qdrant'a kaydedilmez, yalnızca model bağlamı içindir.

Durdur / Devam Et: Transkripsiyon istediğiniz an durdurulabilir. Devam edildiğinde kaldığı chunk'tan devam eder.

Her chunk Gemini 2.5 Flash modeline gönderilir. Model şu sinyalleri çıkarır:

Güven skoru: Her sinyal için yuksek, orta veya dusuk güven atanır. Kesin ifadeler yüksek, koşullu veya belirsiz ifadeler orta/düşük güven alır.

Whisper hata düzeltme: Whisper bazı şirket adlarını yanlış yazabilir (ses benzerliği, ünsüz düşmesi vb.). Sistem, bist_hisseler.json'daki alias tablosu ve LLM'in ses benzerliği kurallarıyla bu hataları otomatik düzeltir.

Hata toleransı: Gemini başarısız olursa sistem otomatik olarak GPT-4o-mini'ye geçer. Tenacity ile her model için 3 deneme yapılır.

Her sinyal BGE-M3 modeli ile hem dense (1024 boyut) hem de sparse vektöre dönüştürülür. Bu hibrit yaklaşım hem semantik benzerliği hem de anahtar kelime eşleşmesini destekler.

Kayıt öncesi duplikat kontrolü yapılır: aynı hisse + sinyal tipi + fiyat kombinasyonu zaten varsa kayıt atlanır.

Sistem, analiz edilen her sinyali kaydettikten sonra otomatik olarak bir doğrulama ajanı (src/verification/agent.py) çalıştırır. Bu ajan:

1. Sinyaldeki hisse kodunu (THYAO, GARAN vb.) alır
2. borsapy kütüphanesi aracılığıyla BIST'ten o anki gerçek piyasa fiyatını çeker
3. Analistin söylediği fiyat ile mevcut piyasa fiyatını karşılaştırır

Örnek çıktı:

THYAO | Analist: 45.50 TL | Piyasa: 47.20 TL | Fark: +3.7% ↑
GARAN | Analist: 28.00 TL (destek) | Piyasa: 29.15 TL | Destek üstünde ✓

Bu kıyaslama UI'daki Arama sekmesinde, "📈 Tüm Hisselerin Güncel Fiyatlarını Getir" butonuna basıldığında görüntülenir. Mevcut analizdeki tüm hisseler için fiyatlar paralel olarak BIST'ten çekilir; sonuçlar tablo formatında renk kodlu listelenir: pozitif fark yeşil, negatif fark kırmızı.

Tüm ajanlar birbirleriyle yalnızca yapılandırılmış JSON ile haberleşir. Ajan 1'den Ajan 2'ye geçen chunk formatı:

{
 "chunk_id": "02",
 "start_sec": 1800.0,
 "end_sec": 3600.0,
 "text": "...transkript metni...",
 "context_prefix": "...önceki 300 kelime..."
}

Ajan 2'den Ajan 3'e geçen sinyal formatı:

{
 "chunk_id": "02",
 "bahsedilen_hisseler": ["THYAO", "GARAN"],
 "sinyaller": [
 {
 "hisse": "THYAO",
 "sinyal_tipi": "alım",
 "fiyat": 45.50,
 "para_birimi": "TL",
 "gerekce": "analistin tam ifadesi",
 "kaynak_cumle": "metinden birebir alıntı",
 "guven": "yuksek"
 }
 ],
 "teknik_terimler": ["RSI", "MACD"],
 "genel_yorum": "chunk özeti"
}

Hiçbir ajan diğerinin iç yapısını bilmez; yalnızca bu JSON sözleşmesine göre çalışır.

• İşlemci: Apple Silicon (M1/M2/M3/M4/M5) — mlx-whisper yalnızca Apple Silicon'da çalışır
• RAM: En az 16 GB önerilir (Whisper large-v3 ~6 GB, BGE-M3 ~2 GB)
• Disk: En az 10 GB boş alan (modeller ilk çalıştırmada indirilir)

⚠️ Önemli: Bu sistem Apple Silicon Mac'e özeldir. Intel Mac veya Windows/Linux'ta mlx-whisper çalışmaz. Farklı bir platformda kullanmak için transkripsiyon katmanını faster-whisper gibi bir alternatifle değiştirmeniz gerekir.

• macOS: Ventura (13) veya üzeri
• Python: 3.12 (kesinlikle 3.12 — diğer sürümlerde mlx uyumsuzluğu olabilir)
• Docker Desktop: Qdrant veritabanını çalıştırmak için gereklidir
• Git: Projeyi klonlamak için

En az biri yeterlidir; ikisi birden varsa Gemini birincil, GPT-4o-mini yedek olarak çalışır:

• Google Gemini API: aistudio.google.com → "Get API Key" (ücretsiz kota mevcut)
• OpenAI API: platform.openai.com → API Keys

docker.com/products/docker-desktop adresinden macOS için Docker Desktop'ı indirin ve kurun. Kurulumdan sonra uygulamayı açın; menü çubuğunda balina simgesi belirince Docker hazır demektir.

# Mevcut Python sürümünüzü kontrol edin
python3 --version

3.12 değilse python.org/downloads adresinden Python 3.12'yi indirip kurun.

git clone https://github.com/KULLANICI_ADI/finansal-ajan.git
cd finansal-ajan

python3.12 -m venv .venv
source .venv/bin/activate

Komut isteminin başında (.venv) yazısı görünüyorsa başarılıdır.

pip install --upgrade pip
pip install -r requirements.txt

Internet hızınıza bağlı olarak 5-15 dakika sürebilir. mlx-whisper ve FlagEmbedding büyük kütüphanelerdir.

Transkripsiyon ve embedding modelleri ilk kullanımda otomatik indirilir. Önceden indirmek isterseniz:

# Whisper modelini indir (~3 GB)
python3 -c "
import mlx_whisper
mlx_whisper.transcribe('', path_or_hf_repo='mlx-community/whisper-large-v3-mlx')
" 2>/dev/null || true
# BGE-M3 embedding modelini indir (~2 GB)
python3 -c "
from FlagEmbedding import BGEM3FlagModel
BGEM3FlagModel('BAAI/bge-m3', use_fp16=True)
print('BGE-M3 hazır')
"

Modeller ~/.cache/huggingface/ klasörüne kaydedilir. İndirme yalnızca bir kez yapılır.

Proje kökündeki .env.example dosyasını kopyalayın:

cp .env.example .env

.env dosyasını bir metin editörüyle açın ve API anahtarlarınızı girin:

GOOGLE_API_KEY=AIza... # Google Gemini API anahtarınız
OPENAI_API_KEY=sk-... # OpenAI API anahtarınız (opsiyonel, yedek)
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=finansal_analiz

⚠️ .env dosyasını asla Git'e commit etmeyin ve başkasıyla paylaşmayın. .gitignore'a zaten eklenmiştir.

Proje kökündeki launch.command dosyasına çift tıklayın.

İlk açılışta "İzin verilmedi" hatası alırsanız terminalde şunu çalıştırın:

chmod +x launch.command

launch.command sırasıyla şunları yapar:

1. Docker Desktop'ı başlatır (zaten açıksa atlar)
2. Qdrant vektör veritabanını Docker'da çalıştırır
3. Streamlit arayüzünü arka planda başlatır
4. FastAPI backend'ini ön planda başlatır (loglar terminalde görünür)
5. Tarayıcıda http://localhost:8501 adresini otomatik açar

Üç ayrı terminal penceresi açın:

Terminal 1 — Qdrant:

docker compose up -d qdrant

Terminal 2 — FastAPI Backend:

cd finansal-ajan
source .venv/bin/activate
uvicorn api.main:app --host 0.0.0.0 --port 8000

Terminal 3 — Streamlit UI:

cd finansal-ajan
source .venv/bin/activate
streamlit run ui/app.py --server.port 8501

Tarayıcıdan http://localhost:8501 adresine gidin.

# Qdrant
curl http://localhost:6333
# {"title":"qdrant - vector search engine",...} beklenir
# FastAPI
curl http://localhost:8000/sessions
# {"sessions":[...]} beklenir

Streamlit için tarayıcıdan http://localhost:8501 adresini açın.

Streamlit arayüzü üç ana sekmeden oluşur:

flowchart TB
 TITLE["📈 Türkçe Borsa Analizi"]
 TABS["[ 🎙️ Analiz ]  [ 🔍 Arama ]  [ i️ Hakkında ]"]
 subgraph LAYOUT[" "]
 direction LR
 SIDEBAR["📂 Kayıtlı Oturumlar<br/>─────────────<br/>• analiz-01<br/>• analiz-02"]
 MAIN["1️⃣ Ses Dosyası<br/>2️⃣ Transkripsiyon<br/>3️⃣ Finansal Sinyal Analizi<br/>─────────────<br/>Sinyal kartları buraya akar"]
 end
 TITLE --> TABS --> LAYOUT

Sol kenar çubuğu (Sidebar): Daha önce tamamlanan oturumlar listelenir. Her oturumun kaç chunk ve sinyal içerdiği, tarihi gösterilir. Bir oturuma tıklandığında transkript ve sinyaller anında yüklenir, yeniden analiz yapmaya gerek kalmaz. 🗑 simgesiyle oturum silinebilir.

Analiz sekmesi: Ses yükleme, transkripsiyon ve sinyal analizi adımlarını sırasıyla yönetir.

Arama sekmesi: Qdrant vektör araması ve fiyat doğrulama özelliklerini sunar.

Video dosyanız mı var? Sistem .mp4 video dosyalarını da doğrudan kabul eder — arka planda ffmpeg ile ses otomatik ayrıştırılır. .m4a, .mp3, .wav ve .mp4 formatları desteklenir. ffmpeg sisteminizde kurulu değilse brew install ffmpeg ile kurabilirsiniz.

1. Sayfanın sol kenar çubuğunda "Oturum başlığı" alanına bir isim girin (ör. analiz-01). Bu isimle oturum diske kaydedilecektir.
2. "Ses dosyası yükle" alanından .m4a, .mp3 veya .wav formatında dosyanızı seçin.
3. "▶ Başlat" butonuna tıklayın.
4. Transkripsiyon ilerledikçe metin ekranda parça parça belirmeye başlar.

Beklenen süreler (Apple M-serisi, yaklaşık):

Durdurma ve Devam Etme: Transkripsiyon sırasında "⏹ Durdur" butonuna tıklayabilirsiniz. Devam ettirmek için "▶ Devam Et" butonuna tıklayın — sistem kaldığı chunk'tan devam eder, baştan başlamaz.

"🔄 Sıfırla" butonu transkripsiyon durumunu temizler ve baştan başlamanıza olanak tanır.

Transkripsiyon tamamlandıktan sonra:

1. Sayfanın "3️⃣ Finansal Sinyal Analizi" bölümüne gidin.
2. "▶ Başlat" butonuna tıklayın.
3. Her chunk analiz edildikçe sinyal kartları ekranda akmaya başlar.

Analiz tamamlanınca üstte özet metrikler görünür:

┌────────┬───────────┬──────────┬────────┐
│ Chunk │ Başarılı │ Sinyal │ Hisse │
│ 4 │ 4 │ 39 │ 12 │
└────────┴───────────┴──────────┴────────┘
Tespit edilen hisseler: THYAO · GARAN · AKBNK · EREGL · ...

Sinyal listesinin üstünde iki filtre çubuğu vardır:

• Hisse filtresi: Sadece belirli hisseleri göster (çoklu seçim)
• Sinyal tipi filtresi: alım / satım / stop_loss / destek / direnc / genel_yorum

Not: genel_yorum sinyalleri varsayılan olarak bu listede gösterilmez. Tümünü görmek için Arama sekmesinde sorgu girmeden "Sinyal tipi → Tümü" seçip arayın.

Analiz de durdurulup devam ettirilebilir. "🔄 Sıfırla" ile sonuçlar temizlenip baştan çalıştırılabilir.

Her sinyal kartı şunları gösterir:

┌──────────────────────────────────────────────┐
│ THYAO ●くろまる yuksek #02 │
│ alım 45.50 TL │ 
│ "Kesinlikle 45.50 üzerinde alabilirsiniz" │
└──────────────────────────────────────────────┘

• Hisse kodu (sol üst) — hangi BIST hissesi
• Güven rengi — 🟢 Yeşil: yuksek, 🟡 Sarı: orta, ⚫ Gri: dusuk
• #02 — Kaynaklandığı chunk numarası (hangi zaman dilimine denk gelir)
• Sinyal tipi ve fiyat — alım / satım / stop_loss / destek / direnc / genel_yorum
• Kaynak cümle — analistin tam ifadesi

Arama sekmesi iki ayrı işlev sunar:

Sol paneldeki filtreler:

• Hisse: Açılır menüden hisse kodu seçin veya "Tümü" bırakın
• Sinyal tipi: alım / satım / stop_loss / destek / direnc / genel_yorum
• Güven: yuksek / orta / dusuk
• Sonuç sayısı: 5-50 arası kaydırıcı

Sağ panele doğal dil sorgusu yazıp "🔍 Ara" butonuna basın. Qdrant, hem semantik benzerlik hem de anahtar kelime eşleşmesini birlikte kullanır:

Filtreler + metin araması birlikte kullanılabilir: ör. hisse=THYAO + sinyal_tipi=alım + sorgu "kesinlikle" → "Sadece THYAO'nun güçlü alım noktalarını getir" anlamına gelir.

Her sinyal Qdrant'ta şu metadata alanlarıyla etiketlidir: hisse, sinyal_tipi, fiyat, para_birimi, guven, chunk_id, zaman_sn, video_title, created_at.

"📈 Tüm Hisselerin Güncel Fiyatlarını Getir" butonuna tıklayın. Sistem mevcut analizde tespit edilen tüm hisselerin fiyatlarını BIST'ten paralel olarak çeker ve fiyat içeren tüm sinyallerle karşılaştırır:

Hisse │ Sinyal │ Analist Fiyatı │ Anlık Fiyat │ Fark │ Yorum
──────┼────────┼────────────────┼─────────────┼─────────┼───────────────────────
THYAO │ alım │ 45.50 TL │ 47.20 TL │ +3.7% ↑ │ Analist 45.50 dedi...
GARAN │ destek │ 28.00 TL │ 29.15 TL │ +4.1% ↑ │ Analist 28.00 dedi...

Pozitif fark yeşil, negatif fark kırmızı renkte gösterilir.

"🗑 Temizle" butonu Qdrant'taki tüm kayıtları siler. Dikkatli kullanın.

Tamamlanan analizler otomatik olarak data/sessions/ klasörüne kaydedilir. Sol kenar çubuğundaki oturum listesinden herhangi birine tıklayarak eski transkript ve sinyalleri yükleyebilirsiniz.

finansal-ajan/
│
├── src/ # Kaynak kodlar
│ ├── transcription/
│ │ ├── transcriber.py # mlx-whisper transkripsiyon
│ │ └── prompts.py # Whisper ve LLM sistem promptları
│ ├── agents/
│ │ ├── chunker.py # Metin parçalama — Ajan 1
│ │ └── analyst.py # Sinyal çıkarımı — Ajan 2
│ ├── qdrant/
│ │ ├── client.py # Qdrant bağlantı yönetimi
│ │ ├── uploader.py # BGE-M3 embedding + kayıt — Ajan 3
│ │ └── searcher.py # Hibrit vektör arama
│ ├── verification/
│ │ └── agent.py # Gerçek zamanlı fiyat doğrulama — Bonus Ajan
│ └── utils/
│ ├── api_helpers.py # Gemini / GPT-4o-mini sarmalayıcı
│ └── logger.py # Merkezi loglama
│
├── api/
│ └── main.py # FastAPI endpoint'leri, job sistemi
│
├── ui/
│ └── app.py # Streamlit arayüzü
│
├── data/
│ └── sessions/ # Kaydedilen oturumlar
│ └── {oturum-adi}/
│ ├── chunks.json # Transkript parçaları
│ ├── signals.json # LLM çıktısı sinyaller
│ └── meta.json # Oturum meta verisi
│
├── orchestrator.py # Pipeline orkestratörü (CLI)
├── bist_hisseler.json # BIST hisse listesi + konuşma dili alias'ları
├── docker-compose.yml # Qdrant Docker yapılandırması
├── launch.command # Tek tıkla başlatıcı (macOS)
├── requirements.txt # Python bağımlılıkları
├── .env.example # Örnek ortam değişkenleri
└── README.md # Bu dosya

mlx yalnızca Apple Silicon Mac'lerde çalışır. Intel Mac kullanıyorsanız mlx-whisper yüklenemez. Bu durumda requirements.txt'ten mlx-whisper satırını kaldırın ve src/transcription/transcriber.py dosyasını faster-whisper gibi bir alternatifle güncelleyin.

Whisper modeli ilk çalıştırmada Hugging Face'den indirilir (~3 GB). İndirme tamamlanana kadar beklemeniz normaldir. Terminalde indirme ilerlemesini görebilirsiniz. İndirme tamamlandıktan sonra işlem hızlanır.

.env dosyasındaki API anahtarını kontrol edin:

• Anahtarın başında veya sonunda boşluk olmamalı
• Anahtarın tırnak işareti içinde yazılmamış olması gerekir (ör. GOOGLE_API_KEY=AIza... doğru, GOOGLE_API_KEY="AIza..." yanlış)
• aistudio.google.com adresinden anahtarın aktif olduğunu doğrulayın

Docker Desktop'ın çalıştığından emin olun:

# Docker durumunu kontrol et
docker ps
# "qdrant" adında container yoksa:
docker compose up -d qdrant
# Qdrant'ın çalışıp çalışmadığını test et
curl http://localhost:6333

Olası nedenler ve çözümler:

1. Transkript boş veya çok kısa → "Transkripsiyon" sekmesinde metnin gelip gelmediğini kontrol edin
2. API kotası doldu → Terminaldeki log mesajlarına bakın; her iki API da başarısız oluyorsa kota veya bağlantı sorunu var demektir
3. Ses dosyası formatı desteklenmiyor → .m4a, .mp3, .wav formatlarından birini kullanın

FastAPI backend'inin çalıştığından emin olun:

curl http://localhost:8000/sessions

Hata alıyorsanız backend başlatılmamış demektir:

source .venv/bin/activate
uvicorn api.main:app --host 0.0.0.0 --port 8000

8000 veya 8501 portunda başka bir işlem çalışıyor olabilir:

# 8000 portunu kullanan işlemi bul ve sonlandır
lsof -ti:8000 | xargs kill -9
# 8501 portunu kullanan işlemi bul ve sonlandır
lsof -ti:8501 | xargs kill -9

Oturumun data/sessions/{isim}/chunks.json dosyasının mevcut olup olmadığını kontrol edin. Eğer bu dosya yoksa (eski sürümde kaydedilmemişse) transkript alanı boş görünür; ancak analiz yeniden çalıştırılabilir.

Sistem, analistlerin şirket adlarını konuşma dilinde söyleme biçimlerini bist_hisseler.json dosyasındaki alias tablosundan öğrenir. Yeni bir hisse veya takma ad eklemek için:

{
 "ticker": "THYAO",
 "name": "Turk Hava Yollari A.O.",
 "aliases": ["thy", "türk hava yolları", "türk havayolları", "thy hissesi"]
}

Whisper'ın yanlış transkribe ettiği formlar da alias olarak eklenebilir (ör. Whisper "Vakfa" → "Akpa" yazıyorsa "akpa" alias'ı VAKFA'ya eklenir).

Bu proje kişisel kullanım amaçlıdır. Ticari kullanım için Google Gemini, OpenAI ve BAAI/bge-m3 model lisanslarını ayrıca değerlendirin.