wiseclaw/README.md

WiseClaw

🦉 WiseClaw, macOS üzerinde çalışan yerel-öncelikli bir kişisel asistan altyapısıdır. FastAPI backend, Telegram botu, React admin paneli, çoklu LLM sağlayıcı desteği, tarayıcı otomasyonu, araç çağırma, otomasyonlar ve AnythingLLM tabanlı "ikinci beyin" entegrasyonunu aynı projede bir araya getirir.

✨ Neler Yapabiliyor?

• 🤖 Telegram üzerinden konuşma, komut ve araç kullanımı
• 🧠 /tanisalim ile kalıcı kullanıcı profili ve iletişim tercihleri
• 🗂️ AnythingLLM tabanlı ikinci beyin sorguları
• 📝 /notlarima_ekle ile second brain notu ekleme ve otomatik senkron
• ⚙️ /otomasyon_ekle ile zamanlanmış görev oluşturma
• 🌐 Brave Search ile web ve görsel arama
• 🧭 browser_use ile gerçek tarayıcıda gezinme
• 🍎 Apple Notes üzerinde not oluşturma
• 📁 Dosya okuma/yazma
• 🖥️ Politika tabanlı terminal komut çalıştırma
• 🔀 Global model sağlayıcı seçimi:
  • Local (LM Studio)
  • Z.AI
• 📊 Admin panelden ayarlar, loglar, memory, profiller ve otomasyonları yönetme

🏗️ Mimari

• backend/ FastAPI uygulaması, orchestrator, tool'lar, Telegram botu ve scheduler
• frontend/ React tabanlı admin panel
• docs/ Mimari notlar ve brainstorm kayıtları

🧩 LLM Sağlayıcıları

WiseClaw tek bir global sağlayıcı ile çalışır:

• 🏠 Local (LM Studio) Yerel OpenAI-uyumlu endpoint üzerinden çalışır
• ☁️ Z.AI Anthropic-uyumlu API üzerinden glm-4.7 ve glm-5 modellerini kullanır

Admin panelden aktif sağlayıcı değiştirildiğinde yeni istekler seçili sağlayıcıya gider.

🛠️ Başlıca Tool'lar

• brave_search Web ve image search
• web_fetch Tekil URL çekme ve içerik okuma
• browser_use Gerçek browser otomasyonu
• apple_notes Apple Notes not oluşturma
• files Dosya/dizin erişimi
• terminal Güvenlik politikasıyla komut çalıştırma
• second_brain AnythingLLM workspace context sorgulama

🧠 İkinci Beyin Akışı

WiseClaw, AnythingLLM'yi ikinci beyin olarak kullanabilir.

Sorgulama

Telegram'da örnek:

Notlara bak, serkan ile ne zaman ve nerde buluştum?

WiseClaw bu isteği second_brain tool'una yönlendirir, AnythingLLM workspace'inden bağlam çeker ve kısa cevap üretir.

Not Ekleme

Telegram akışı:

/notlarima_ekle

Ardından gönderilen not:

1. SQLite veritabanına second_brain kaydı olarak yazılır
2. backend/second_brain.md dosyası yeniden üretilir
3. Eski second_brain.md AnythingLLM workspace'inden kaldırılır
4. Yeni dosya tekrar upload edilip workspace'e bağlanır

Bu yaklaşım belge tabanlı RAG akışına daha uygun olduğu için doğrudan DB -> AnythingLLM yazmaktan daha sağlamdır.

💬 Telegram Komutları

• /start
• /tanisalim
• /profilim
• /tercihlerim
• /tanisalim_sifirla
• /otomasyon_ekle
• /otomasyonlar
• /otomasyon_durdur <id>
• /otomasyon_baslat <id>
• /otomasyon_sil <id>
• /notlarima_ekle

⏱️ Otomasyonlar

WiseClaw backend içinde çalışan scheduler ile zamanlanmış görevleri destekler.

Desteklenen ilk sürüm sıklıkları:

• günlük
• hafta içi
• haftalık
• saatlik

Otomasyon sonuçları:

• Telegram'a gönderilir
• audit log'a yazılır

🧪 Admin Panel

Admin panelde şunları yönetebilirsin:

• Runtime settings
• Model provider
• Search provider
• Brave / Z.AI / AnythingLLM secret'ları
• Telegram whitelist
• User Profiles
• Automations
• Memory
• Recent Logs

Önemli endpointler:

• /admin/dashboard
• /admin/settings
• /admin/users
• /admin/profiles
• /admin/automations
• /admin/memory
• /admin/integrations/llm
• /admin/integrations/telegram

🚀 Kurulum

Backend

cd backend
python3.12 -m venv .venv312
source .venv312/bin/activate
pip install .
uvicorn app.main:app --reload

Frontend

cd frontend
npm install
npm run dev

🔐 Ortam Değişkenleri

.env.example dosyasını .env olarak kopyalayabilirsin.

Öne çıkan alanlar:

• WISECLAW_MODEL_PROVIDER
• WISECLAW_LOCAL_BASE_URL
• WISECLAW_LOCAL_MODEL
• WISECLAW_ZAI_BASE_URL
• WISECLAW_ZAI_MODEL
• WISECLAW_ANYTHINGLLM_BASE_URL
• WISECLAW_ANYTHINGLLM_WORKSPACE_SLUG
• WISECLAW_TELEGRAM_BOT_TOKEN
• WISECLAW_BRAVE_API_KEY
• WISECLAW_ZAI_API_KEY
• WISECLAW_ANYTHINGLLM_API_KEY

Not: secret'lar admin panelden daha sonra da kaydedilebilir.

✅ Hızlı Kontrol

Backend ayağa kalktıktan sonra:

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/bootstrap
curl http://127.0.0.1:8000/admin/integrations/llm
curl http://127.0.0.1:8000/admin/integrations/telegram

🔁 Restart

Projede tek komutluk restart script'i var:

cd /Users/wisecolt-macmini/Project/wiseclaw
zsh ./restart.sh

Bu script:

• eski backend sürecini kapatır
• yeni uvicorn sürecini başlatır
• log'u .wiseclaw/logs/backend.log içine yazar
• health check ile ayağa kalktığını doğrular

📌 Notlar

• LM Studio status: Reachable görünüp model is not installed uyarısı alıyorsan, endpoint açık ama seçili model adı yüklü modellerle birebir eşleşmiyor demektir.
• AnythingLLM tarafında görünen workspace adı ile gerçek slug farklı olabilir.
• Brave image search sonuçları Telegram'da medya grubu olarak gönderilebilir.
• Bazı browser görevleri captcha/anti-bot nedeniyle manuel müdahale isteyebilir.

🧭 Geliştirme Notu

Bu repo hızlı iterasyonla büyüdüğü için bazı alanlarda bilinçli teknik borçlar bulunur. Ana yön şu anda şudur:

• daha sağlam tool routing
• daha iyi approval akışları
• second brain retrieval kalitesini artırma
• admin panel kullanılabilirliğini geliştirme