PDF AI Asistan

Yüklediğiniz PDF dokümanlarını analiz eden, içerikle ilgili soruları OpenAI veya Google Gemini ile yanıtlayan FastAPI + Streamlit tabanlı bir AI asistanı.

• 🔐 API anahtarları yalnızca .env dosyasında saklanır, asla repoya girmez
• 🔁 Sağlayıcı değiştirme tek satır: PROVIDER=gemini (Service Pattern + Factory)
• 🛡️ Rate limit, bağlantı kopması ve geçersiz dosya için özel hata yönetimi
• 🧪 AI çağrısı yapmadan çalışan Mock tabanlı unit testler
• 🤖 GitHub Actions ile otomatik lint + test

---

Mimari Şema

flowchart LR
    U[Streamlit UI] -->|HTTP / JSON| API[FastAPI API]
    API --> P[DocumentParser<br/>pypdf + doğrulama]
    API --> F[Provider Factory]
    F --> O[OpenAIProvider]
    F --> G[GeminiProvider]
    API --> E[Exception Handler<br/>429 / 502 / 400 ...]
    O -. Chat Completions .-> LLM
    G -. Generate Content .-> LLM

Loading

├── app/
│   ├── main.py                 # FastAPI girişi (uvicorn app.main:app)
│   ├── config.py               # .env -> pydantic-settings
│   ├── core/
│   │   ├── exceptions.py       # AppError hiyerarşisi
│   │   └── document_parser.py  # PDF doğrulama + metin + chunking
│   ├── services/
│   │   ├── base.py             # BaseLLMProvider (retry/hatalar)
│   │   ├── openai_provider.py  # OpenAI uyarlaması
│   │   ├── gemini_provider.py  # Gemini uyarlaması
│   │   └── factory.py          # PROVIDER'a göre seçim
│   ├── api/routes.py           # /upload, /ask, /health
│   └── ui/streamlit_app.py     # Web arayüzü
├── tests/                      # Mock tabanlı unit testler
├── .github/workflows/ci.yml    # CI (ruff + pytest)
├── .env.example
└── requirements.txt

Kurulum

git clone https://github.com/Pastalikek65/pdf-ai-assistant.git
cd pdf-ai-assistant
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env        # anahtarlarınızı doldurun

.env örneği:

OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AIza...
PROVIDER=openai            # veya "gemini"

Çalıştırma

# 1) API (terminal 1)
uvicorn app.main:app --reload --port 8000

# 2) Arayüz (terminal 2)
streamlit run app/ui/streamlit_app.py

Ardından tarayıcıda:

Adres	Amaç
http://127.0.0.1:8000/docs	Swagger API dokümantasyonu
http://127.0.0.1:8501	Streamlit arayüzü

API kullanımı

# PDF yükle -> session_id al
curl -F "file=@ornek.pdf" http://127.0.0.1:8000/api/upload

# Soru sor
curl -X POST http://127.0.0.1:8000/api/ask \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<yukaridaki_id>","question":"Bu faturada ne yazıyor?"}'

Test

pytest -v              # 24 test, AI çağrısı yok (mock)
ruff check app tests   # lint

Testler gerçek ağ isteği yapmaz; sağlayıcılar mock'lanır.

Sağlayıcı Değiştirme

Ayar	Açıklama
PROVIDER=openai	OpenAI (varsayılan)
PROVIDER=gemini	Google Gemini

Yeni bir sağlayıcı eklemek için app/services/ altına BaseLLMProvider'ı miras alan bir sınıf + factory'ye bir dal eklemek yeterlidir.

Hata Senaryoları

Durum	Yanıt
PDF değil / imza bozuk	400
Taranmış PDF (metin yok)	422
API anahtarı eksik	500
Rate limit (429)	429 + üstel geri çekilme
Bağlantı kopması	502 + otomatik retry
Dosya boyutu aşımı	413

Önerilen Commit Akışı

git add . && git commit -m "feat: initial project structure and dependencies"
git add app && git commit -m "feat: implement core processing logic"
git add tests && git commit -m "test: add unit tests for parsing modules"
git add .github README.md && git commit -m "docs: update README with setup instructions"

Lisans

MIT