first commit

2026-05-11 15:08:50 +03:00
commit a408821410
47 changed files with 4670 additions and 0 deletions
@@ -0,0 +1,228 @@
+# LLM Gateway / Proxy Projesi - Geliştirici İş Emri (Türkçe)
+
+Bu doküman, bir geliştiriciye veya yapay zeka asistanına verilip projeyi tamamen uygulattıracak detaylı iş emridir. Hedef: Go + Fiber v3 tabanlı bir servis geliştirmek; OpenAI-compat ve Anthropic-compat proxy/gateway, Bifrost mapping, PostgreSQL (GORM) entegrasyonu, Swagger dokümanları ve Docker destekli dağıtım.
+
+---
+
+## Özet Hedefler
+- OpenAI-uyumlu istekleri alın, hedef backend: `https://api.deepseek.com`.
+- Anthropic-uyumlu istekleri alın, hedef backend: `https://api.deepseek.com/anthropic` veya (konfigürasyona bağlı olarak) Bifrost (`http://10.80.80.70:8080/v1`).
+- Lokalde Anthropic endpoint'i: `http://localhost:8000/anthropic` (Bifrost mapping).
+- Kullanılacak kütüphaneler:
+  - `github.com/gofiber/fiber/v3`
+  - `gorm.io/gorm`
+  - `gorm.io/driver/postgres`
+
+---
+
+## Çalışma Ortamı / Gereksinimler
+- Go modül yapısı (go1.20+ önerilir).
+- PostgreSQL veritabanı (docker-compose ile sağlanabilir).
+- Docker & docker-compose (opsiyonel ama önerilir).
+- İstenen `go get` komutları (README'de gösterilecek):
+  - `go mod download` (tüm bağımlılıklar go.mod'da tanımlı)
+  - `go get -u gorm.io/gorm`
+  - `go get -u gorm.io/driver/postgres`
+
+---
+
+## Konfigürasyon (Environment Variables)
+- `PORT` (default: `8000`)
+- `OPENAI_BACKEND` (default: `https://api.deepseek.com`) ##Örnek
+- `ANTHROPIC_BACKEND` (default: `https://api.deepseek.com/anthropic`)##Örnek
+- `USE_BIFROST_FOR_ANTHROPIC` (`true`/`false`) — `true` ise Anthropic çağrıları `BIFROST_URL`'e yönlendirilir
+- `BIFROST_URL` (örnek: `http://10.80.80.70:8080/v1`)##Örnek
+- `POSTGRES_DSN` (örnek: `host=localhost user=app password=pass dbname=app port=5432 sslmode=disable TimeZone=UTC`)##Örnek
+- `REQUEST_TIMEOUT_SECONDS` (ör: `30`)##Örnek
+
+Örnek `.env.example`:
+```env
+PORT=8000
+OPENAI_BACKEND=https://api.deepseek.com
+ANTHROPIC_BACKEND=https://api.deepseek.com/anthropic
+BIFROST_URL=http://10.80.80.70:8080/v1
+USE_BIFROST_FOR_ANTHROPIC=true
+POSTGRES_DSN=host=postgres user=app password=pass dbname=app port=5432 sslmode=disable TimeZone=UTC
+REQUEST_TIMEOUT_SECONDS=30
+```
+
+---
+
+## API Endpoint Gereksinimleri
+
+### OpenAI-uyumlu
+- `POST /v1/chat/completions` -> forward to `${OPENAI_BACKEND}/v1/chat/completions`
+- `POST /v1/completions` -> forward to `${OPENAI_BACKEND}/v1/completions`
+- Tüm `/v1/*` OpenAI endpoint'leri generic olarak hedef backend'e yönlendirilmeli (method korunacak).
+
+Kurallar:
+- Authorization header (Bearer ...) ve diğer önemli header'lar hedefe iletilecek.
+- Body genelde olduğu gibi POST edilecek.
+- Hedeften gelen status code ve body olduğu gibi client'a iletilecek.
+- Hedefe ulaşılamazsa 502 döndürülecek.
+
+### Anthropic-uyumlu
+- `POST /anthropic/*` (ör. `/anthropic/complete`) -> eğer `USE_BIFROST_FOR_ANTHROPIC=false` ise `${ANTHROPIC_BACKEND}`'e, `true` ise `${BIFROST_URL}`'e yönlendir.
+- Eğer Bifrost formatı ile Anthropic formatı farklıysa, minimal bir dönüşüm fonksiyonu yazılmalı (request/response mapping).
+
+Hata durumları:
+- Hedefe ulaşılamaz veya hata alınırsa uygun HTTP kodu döndürülecek (502/504/500 gibi).
+
+### Sağlık ve Dokümantasyon
+- `GET /health` -> servis, DB ve opsiyonel hedef backendlere temel sağlık bilgisi dönecek.
+- Swagger UI: `/swagger/*` (Fiber v3 native HTML + CDN Swagger UI ile sunulacak).
+
+---
+
+## İstek / Yanıt İşleme
+- Timeout yönetimi (env'den): `REQUEST_TIMEOUT_SECONDS`.
+- Retries (opsiyonel): tercih halinde `github.com/hashicorp/go-retryablehttp` veya benzeri kullanılabilir.
+- İsteklerin DB'ye loglanması (Postgres + GORM) — minimal kayıt:
+  - timestamp, endpoint, method, client IP, model (varsa), tokens estimate (opsiyonel), response status, latency
+- Büyük request body'leri truncation ile kaydedilecek (ör. 2000 karakter).
+- Sensitive veriler (Authorization vb.) maskelenmeli, düz kaydedilmemeli.
+
+---
+
+## Veri Modeli (Minimal)
+- `RequestLog`:
+  - ID (UUID / auto increment)
+  - CreatedAt
+  - Endpoint (string)
+  - Method (string)
+  - ClientIP (string)
+  - RequestBody (text, truncate)
+  - ResponseStatus (int)
+  - LatencyMs (int)
+- GORM AutoMigrate ile migration sağlanacak.
+
+---
+
+## Proje Yapısı (Öneri)
+- `main.go` (Fiber app, config yükleme, route register)
+- `handlers/openai.go`
+- `handlers/anthropic.go`
+- `internal/proxy/proxy.go` (generic forwarder)
+- `internal/transform/anthropic_bifrost.go` (dönüşüm fonksiyonları)
+- `models/request_log.go`
+- `config/config.go` (env yükleme)
+- `docker/Dockerfile`
+- `docker/docker-compose.yml`
+- `README.md`
+- `tests/*` (unit test örnekleri)
+- `go.mod`, `go.sum`
+
+---
+
+## Swagger
+- Fiber v3 native HTML handler + CDN Swagger UI ile `/swagger/*` altında UI sunulacak.
+- En az OpenAI-compatible `chat/completions` ve Anthropic endpoint'leri için örnek request/response gösterilecek.
+
+---
+
+## Docker & docker-compose
+- Multi-stage `Dockerfile` (build + runtime).
+- `docker-compose.yml`:
+  - `app` servisi (build)
+  - `postgres` servisi (resmi image, örnek env)
+- `docker-compose` ile test sağlanabilecek (izole ortam).
+
+---
+
+## Testler
+- Unit test: OpenAI proxy handler için en az iki test:
+  - başarılı forward (mock backend ile)
+  - hedef hata verdiğinde uygun hata dönüşü
+- Integration test (opsiyonel): docker-compose altında mocked backend'e karşı örnek.
+
+---
+
+## Komutlar / Kurulum (README'de belirtilecek)
+- `go mod init github.com/<you>/<repo>`
+- `go mod download` (fiber v3 ve diğer bağımlılıklar go.mod'da)
+- `go get -u gorm.io/gorm`
+- `go get -u gorm.io/driver/postgres`
+- `go build ./...`
+- `docker build -t llm-gateway:latest .`
+- `docker-compose up -d`
+
+---
+
+## Örnek curl Çağrıları
+
+OpenAI compatible:
+```bash
+curl -X POST "http://localhost:8000/v1/chat/completions" \
+  -H "Authorization: Bearer $OPENAI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+Anthropic (lokal mapped to Bifrost veya deepseek):
+```bash
+curl -X POST "http://localhost:8000/anthropic/complete" \
+  -H "Authorization: Bearer $ANTHROPIC_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"Say hello", "max_tokens": 64}'
+```
+
+---
+
+## Teslim Edilecekler (Repository içinde)
+- `main.go`
+- `handlers/openai.go`
+- `handlers/anthropic.go`
+- `internal/proxy/proxy.go`
+- `internal/transform/anthropic_bifrost.go`
+- `models/request_log.go`
+- `config/config.go`
+- `docker/Dockerfile`
+- `docker/docker-compose.yml`
+- `README.md` (kurulum, env örnekleri, docker-compose, curl örnekleri)
+- `tests/*` (unit testler)
+- `go.mod`, `go.sum`
+
+---
+
+## Kabul Kriterleri (Acceptance Criteria)
+- `/v1/*` istekleri `OPENAI_BACKEND`'e başarılı yönleniyor.
+- `/anthropic/*` istekleri `USE_BIFROST_FOR_ANTHROPIC` konfigürasyonuna göre `BIFROST_URL` veya `ANTHROPIC_BACKEND`'e gidiyor.
+- İstekler DB'ye loglanıyor (Postgres çalışırken).
+- Swagger UI erişilebilir (`/swagger/*`).
+- README yönergelerine göre proje çalıştırılabiliyor.
+- En az 1 birim testi geçiyor (`go test ./...`).
+
+---
+
+## Teknik Notlar / İpuçları
+- HTTP client: `net/http` + `context` (timeout) veya tercih edilirse fiber'ın client'ı.
+- Retries: isteğe bağlı; `go-retryablehttp` önerilir.
+- Büyük body'leri DB'ye kaydederken truncate et (ör. 2000 char).
+- Sensitive alanlar maskelenmeli.
+- Anthropic <-> Bifrost dönüşümleri karmaşıksa, minimal mapping uygula ve README'de açıkla.
+- Environment swap ile Deepseek <-> Bifrost kolayca değiştirilebilmeli.
+
+---
+
+## Geliştirme Adımları (Öneri Sırayla)
+1. Repo skeleton oluştur (go mod init, klasör yapısı).
+2. `config/config.go`: env yükleme ve default ayarlar.
+3. `main.go`: Fiber app init, DB bağlantısı (GORM), AutoMigrate, route register.
+4. `internal/proxy/proxy.go`: generic forwarder implementasyonu (timeout, header forwarding).
+5. `handlers/openai.go` & `handlers/anthropic.go`: handler'ları yaz, DB logging çağrılarını ekle.
+6. Basit Swagger dokümantasyonu ekle.
+7. Dockerfile & docker-compose ekle.
+8. Unit testleri yaz ve çalıştır.
+9. README güncelle, örnek env ve curl'leri ekle.
+
+---
+
+## İletişim / Teslim
+- Repo URL veya zip ile teslim.
+- README ile çalıştırma adımları.
+- Örnek curl komutları ve `.env.example`.
+- (Opsiyonel) Dönüşümlere dair kısa açıklama ve input/output örnekleri.
+
+---
+
+Eğer bu prompt'u doğrudan bir geliştiriciye/assistant'e vereceksen bu dosyayı kullan. İstersen ben bu prompt'u kullanarak ilk adımda repository skeleton'ını ve `main.go` + temel proxy handler'ı oluşturmaya başlayabilirim — başlamak istersen sadece "başla" de.