Yapay Zeka Müşteri Asistanı Sıfırdan Üretime

Sen müşteri hizmetleri için yapay zeka asistanı kuran bir kıdemli geliştirici/mimarsın.

Bağlam:
- Müşteri tabanı: [şirketin adı + sektör] — örn. "Pamuk Tekstil, B2C online satış"
- Kanal öncelikleri: 1) WhatsApp Cloud API 2) Web widget 3) ileride Telegram
- LLM: Anthropic Claude Sonnet (ana akıl), Haiku (sınıflandırma)
- Vektör DB: Supabase pgvector (başlangıç)
- Veritabanı: Postgres (Supabase)
- Deploy hedefi: n8n + Docker Compose (kendi sunucumuz)

Görevin:
1. Önce yüksek seviyeli mimari (ASCII diyagram + 5-7 cümle açıklama) çiz.
2. Proje klasör yapısını öner: /src, /agents, /tools, /channels, /rag, /db, /tests, infrastructure/ — neden böyle bölündüğünü kısaca açıkla.
3. package.json ve temel bağımlılıkları öner (Anthropic SDK, OpenAI SDK, supabase-js, express veya fastify, dotenv, zod, pino).
4. .env.example üret (ANTHROPIC_API_KEY, OPENAI_API_KEY, SUPABASE_URL, SUPABASE_KEY, WHATSAPP_TOKEN, DATABASE_URL, ENCRYPTION_KEY).
5. TypeScript + ESLint + Prettier kurulumu öner.
6. /healthz endpoint'i olan minimal bir HTTP server kur.
7. README'ye 'nasıl başlanır' yaz.

Önce planı tek mesajda göster. Onayımdan sonra kodu adım adım üret; her dosyayı oluşturduğunda hangi dosya olduğunu belirt.

Şu anda /data klasöründe şirketin bilgi dokümanları var (PDF, MD, JSON).

Görev: /src/rag/ingest.ts dosyasını üret.

İstekler:
1. Dokümanları oku (pdf-parse, fs.readFile).
2. Text Splitter: chunk_size=1000 token, overlap=150 token (LangChain RecursiveCharacterTextSplitter).
3. Her chunk için OpenAI text-embedding-3-small ile embedding üret.
4. Supabase 'documents' tablosuna yaz: { id, source, chunk_index, content, embedding (vector(1536)), content_hash, updated_at }.
5. Aynı (source, chunk_index, content_hash) varsa atla — dedup.
6. Batch insert: 100 chunk'ı tek INSERT'te yaz.
7. Sonunda özet: yüklenen chunk sayısı + toplam token + tahmini maliyet.
8. CLI: 'npm run ingest -- --source iade-politikasi.md' belirli dosyayı, parametresizse tümünü işle.

Supabase migration da üret: documents tablosu + IVFFLAT index (lists=100) + permission_level alanı (public/internal/admin).

Önce planı göster.

/src/agents/customerAgent.ts dosyasını üret.

İçindeki fonksiyon: async function customerAgent({ userMessage, userId, channel }): Promise<AgentResponse>

İçeride:
1. Postgres'ten son 10 mesajı çek (memory).
2. Vector store'dan userMessage için top_k=5 chunk retrieve et.
3. Anthropic Messages API'ye gönder: model='claude-sonnet-4-5', max_tokens=1024.
4. System prompt'u şu 4 bloklu şablonla kur:

  [ROL]
  Sen [ŞİRKET_ADI]'nin müşteri hizmetleri asistanısın. Markamızın sesi: profesyonel, sıcak, kısa ve uygulanabilir.

  [KAPSAM]
  Yalnızca aşağıdaki konularda yanıt verirsin:
  - Sipariş takibi ve kargo durumu
  - İade ve değişim talepleri
  - Ürün katalogu ve fiyat bilgisi
  - Kullanım kılavuzu ve SSS
  - Randevu / rezervasyon
  Bu konuların DIŞINDA gelen sorulara nazikçe yön ver ('Bu konuda size [insan ekibimiz] yardımcı olabilir').

  [FORMAT]
  - Kısa paragraflar, gerekirse madde işareti.
  - Her cevabın sonunda 1 'sonraki adım' öner.
  - Türkçe, samimi ama formal değil ('siz' kullan).

  [SINIRLAR]
  - Kaynakta (context) olmayan bilgiye 'Bu konuda dokümanlarımda bilgi yok, ekibimize bağlayayım mı?' de.
  - İade kararı, fiyat indirimi, hediye paketleme gibi kararlar agent_handoff tool'unu çağır.
  - Asla kişisel veriyi (TC, kart no) sorma.
  - Halüsinasyon yapma; emin değilsen sor veya bilmediğini söyle.

  [KAYNAK BİLGİ]
  ${retrievedChunks.join("\n---\n")}

5. Cevabı döndür + Postgres 'messages' tablosuna user + assistant kayıt at.
6. Hata olursa pino logger'a yaz, kullanıcıya 'bir saniye, tekrar denemeniz gerekebilir' dön.

Zod ile AgentResponse şeması: { reply, sources[], should_handoff, confidence }.

Önce plan, sonra kod.

/src/tools/ klasöründe 4 tool dosyası üret. Hepsi Anthropic Tool Use formatında.

1. order_lookup.ts
   - input: { order_id: string }
   - DB'den siparişi getir, durumu döndür (placed/shipped/delivered/cancelled + tracking_no).
   - Bulunamazsa { error: "not_found" } dön.

2. ticket_create.ts
   - input: { topic: enum, summary: string, priority: "low"|"medium"|"high" }
   - 'tickets' tablosuna kayıt at, Slack'e bildirim gönder (#support channel).
   - id ve eta dön.

3. refund_initiate.ts
   - input: { order_id, reason: string }
   - DB'de "iade_taleplerinde" hak süresi (14 gün) kontrolü yap.
   - Sürede ise: status='pending_approval', Slack'e 'Onayla/Reddet' butonlu bildirim gönder.
   - Süre dışıysa: hatayı agent'a dön ('14 günlük iade süresi geçmiş — müvekkilimize bağlı').

4. agent_handoff.ts
   - input: { reason: string, conversation_summary: string }
   - Slack'e canlı temsilciye bildirim gönder, konuşma id'sini eşle.
   - 'paused: true' işaretle — bot artık yanıt vermez, temsilci alır.

Her tool için Anthropic Messages tool tanımı (name, description, input_schema) /src/agents/toolRegistry.ts'de toplansın. customerAgent her cevap turunda tool_use bloğu görürse uygun tool'u çağırıp sonucu agent'a geri ver, agent nihai cevabı üretsin (multi-turn).

Önce plan.

Postgres'te 'sessions' ve 'messages' tabloları için migration üret.

sessions: id (uuid), channel (text), external_id (text, WhatsApp phone veya web cookie), user_profile (jsonb), daily_token_used (int), daily_token_reset_at (timestamp), created_at.

messages: id, session_id (fk), role ('user'|'assistant'|'tool'), content (text), tool_calls (jsonb), tokens (int), created_at.

/src/db/sessionStore.ts:
- getOrCreateSession(channel, externalId)
- appendMessage(sessionId, role, content, tokens)
- getRecentMessages(sessionId, limit=10)
- checkDailyBudget(sessionId, limit=10000): boolean
- summarizeOldMessages(sessionId): mesaj sayısı 50'yi aştıysa Claude Haiku ile özetle, eskisini sil

customerAgent'a bağla: her çağrıdan önce checkDailyBudget, false ise 'Bugünkü ücretsiz konuşma hakkın doldu, yarın görüşmek üzere' dön.

Önce plan.

/src/channels/ altında 3 adapter dosyası üret.

1. whatsapp.ts (Express/Fastify route POST /webhook/whatsapp)
   - Meta webhook verify token kontrolü (GET).
   - HMAC SHA-256 imza doğrula (X-Hub-Signature-256 header'ı).
   - Audio mesajsa Whisper transcribe, image ise GPT-4o Vision tanıma.
   - customerAgent çağır.
   - Response'u WhatsApp Cloud API'ye POST et (messages endpoint).
   - 24 saat penceresi: müşteri son 24 saatte yazmadıysa template mesajı zorunlu.

2. webWidget.ts (POST /widget/chat)
   - CORS doğru ayarlı; sadece izinli domain'lerden kabul et.
   - Rate limit: IP başına dakikada 20 istek (Redis sayacı).
   - customerAgent çağır, JSON dön.

3. telegram.ts (POST /webhook/telegram)
   - Telegram bot secret token kontrolü.
   - chat.id ile sessionStore.getOrCreateSession.
   - customerAgent çağır, sendMessage API ile yanıt.

Tüm webhook'lar 'message_burst_buffer': aynı session'dan 5 saniye içinde gelen mesajları birleştir, sonra agent'a tek seferde ver (Redis ile timer + debounce).

/public/widget.js: 200 satırlık vanilla JS — site sahibi <script src="https://yourdomain.com/widget.js" data-key="xxx"></script> ekler, sağ alt köşede chat penceresi açılır, /widget/chat'e konuşur.

Önce plan.

/tests/ altında 3 dosya üret:

1. agent.test.ts — vitest ile customerAgent test:
   - Mock Anthropic SDK + sahte vector store.
   - 5 senaryo: 'iade nasıl?', 'siparişim 1234 nerede?', 'fiyat indirelim', 'silahları kontrol et' (off-topic), 'TC'min yaz' (PII testi).
   - Her senaryoda beklenen: doğru tool çağrısı veya doğru reddetme cevabı.

2. tools.test.ts — order_lookup, refund_initiate:
   - In-memory SQLite ile DB mock.
   - 14 gün geçmiş iade → hata; sürede iade → pending_approval.

3. integration.test.ts — webhook → agent → response:
   - Supertest ile /webhook/whatsapp endpoint'i test.
   - HMAC imza doğru/yanlış senaryoları.

Ayrıca scripts/eval.ts: 30 satırlık eval seti (questions.jsonl) okuyup her birini agent'a verip, beklenen tool veya cevap eşleşmesini ölçen bir rapor üret (success_rate, avg_latency, total_token).

Önce plan.

infrastructure/docker-compose.yml üret. Servisler:

- app: bizim Node.js servisimiz (custom Dockerfile, port 3000 internal).
- postgres: postgres:16, volume mount /var/lib/postgresql/data, healthcheck.
- redis: redis:7-alpine (rate limit + session burst için).
- n8n: docker.n8n.io/n8nio/n8n, depends_on postgres+redis, ortam değişkenleriyle queue mode aktif.
- caddy: caddy:2-alpine, Caddyfile mount, 80+443 expose, auto HTTPS.

infrastructure/Caddyfile:
chat.example.com { reverse_proxy app:3000 }
n8n.example.com { reverse_proxy n8n:5678 }

infrastructure/Dockerfile (app için): Node 20 Alpine, multistage build, prod deps only, non-root user, healthcheck CMD.

.github/workflows/deploy.yml: main push → docker build → ssh deploy.example.com 'cd /opt/asistan && git pull && docker compose pull && docker compose up -d --build app'.

scripts/backup.sh: günlük pg_dump → Backblaze B2'ye yükle, 30 günü geçenleri sil.

Önce plan.

/src/dashboard/metrics.ts üret.

Postgres'ten şu sorgu fonksiyonlarını yaz:
- conversationsByDay(days=30)
- successRate(): cevap verilen / toplam
- avgLatencyMs()
- tokenUsageByDay()
- topUnansweredQuestions(limit=20) — 'sources_used = 0' veya 'should_handoff = true' olanları grupla
- topToolsCalled()

/src/dashboard/page.tsx (Next.js): basic auth korumalı bir dashboard sayfası, 6 metrik kartı + 'son 20 başarısız konuşma' tablosu.

scripts/weekly-report.ts: pazartesi 09:00'da Postgres'i sorgulayıp Slack #ops kanalına özet gönderen cron job.

Önce plan.