Skip to main content

Ipsa Verba

v3.0.0 — 12 core + 36 extended MCP tools (48 total) · 152 CLI commands · 80 test files · 49 source modules

CI DOI

Proje sayfası: avfatihsozer.com/projeler/ipsa-verba · English: README.en.md

Resmi ve kamuya açık Türk hukuk kaynaklarında (emsal kararlar ve mevzuat) citation-safe arama, araştırma ve belge hazırlık için MCP sunucusu.

Proje 2.0.0 sürümünde emsal-mcp'den Dayanak'a, 3.0.0 sürümünde Ipsa Verba (ipsa-verba) adına geçti. Eski dayanak ve emsal-mcp paketleri artık ipsa-verba'yı kurar; eski DAYANAK_* / EMSAL_* ortam değişkenleri ile ~/.dayanak ve ~/.emsal_mcp veri dizinleri okunmaya devam eder.

İki şekilde çalışır:

  • Yerel korpus — 11,1 milyon karar ve güncel mevzuatın tamamı tek bir SQLite dosyasında; FTS5 tam metin + FAISS anlamsal arama. Ağ gerekmez.
  • Canlı kaynaklar — Bedesten/Yargıtay, AYM, Danıştay, Uyuşmazlık, Rekabet, Sayıştay, GİB, mevzuat.gov.tr, Resmî Gazete, KVKK adaptörleri.

Kırmızı çizgiler

  • Karar, metadata, tarih, esas/karar no, daire, atıf veya kanun maddesi uydurulmaz.
  • full_text / html_markdown içeriği olmayan belgeler quote/draft için kullanılmaz.
  • quoteUsable ve draftUsable sadece tam metin/HTML markdown varsa true olur.
  • Rate-limit bilinçli olarak muhafazakâr değildir; tek kullanıcı/tek bilgisayar hedeflenmiştir.

Korpus

Ölçüm tarihi 16 Eylül 2026, canlı korpus (cache.sqlite3, 72 GB).

Katman Ölçü
Kararlar 11.108.242 belge (documents_v2). Taban: HF hamzabagirsakci/turkish-court-decisions (11.045.085, CC0), üstüne günlük Bedesten crawl'ı.
Mevzuat belgeleri 14.298 kayıt / 14.171 güncel sürüm: 916 kanun, 63 KHK, 33 CBK, 8.840 yönetmelik (8.830 güncel), 4.446 tebliğ (4.329 güncel)
Mevzuat maddeleri 303.454 madde, 96.186 değişiklik kaydı
Karar anlamsal indeksi 29.554.075 parça vektörü — intfloat/multilingual-e5-small (384 boyut), FAISS IVF16384,PQ64 + fp16 sidecar refine, nprobe=128, chunking v2
Mevzuat anlamsal indeksi 423.920 parça vektörü (303.454 maddeden), aynı model ve indeks tipi

Ayrıntı ve ölçümler: docs/BULK_INDEX.md.

Kurulum

Hızlı kurulum (korpussuz)

Ipsa Verba, 11 milyon kararlık yerel korpus olmadan da çalışır. Bu durumda karar ve mevzuat aramaları resmî kaynaklardan (Bedesten, mevzuat.gov.tr, AYM, Danıştay ve diğerleri) canlı yapılır, kararın tam metni de canlı getirilir. Yalnız yerel korpusta arayan araçlar (search_local_corpus, mevzuat_korpus_ara, mevzuat_madde_getir) boş sonuç döndürür ve canlı araca yönlendirir. Python 3.11 ya da üstü gerekir.

# Kurmadan doğrudan çalıştırmak için (uv gerekir)
uvx --from ipsa-verba ipsa-verba-server

# ya da kalıcı kurulum
pipx install ipsa-verba

Claude Code'a eklemek için:

claude mcp add ipsa-verba -- uvx --from ipsa-verba ipsa-verba-server

Claude Desktop ya da başka bir MCP istemcisi için yapılandırma:

{
  "mcpServers": {
    "ipsa-verba": {
      "command": "uvx",
      "args": ["--from", "ipsa-verba", "ipsa-verba-server"]
    }
  }
}

Varsayılan araç profili 12 temel araçtır; tamamı için IPSA_VERBA_TOOL_PROFILE=full ortam değişkenini verin. Çekilen belgeler ~/.ipsa-verba/cache.sqlite3 dosyasında önbelleğe alınır (IPSA_VERBA_CACHE_PATH ile değişir).

Geliştirme kurulumu (korpusla)

# Windows
cd <repo-dizini>
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev,mcp,embeddings]"

# macOS / Linux
cd <repo-dizini>
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,mcp,embeddings]"

ipsa-verba version

Anlamsal aramanın toplu FAISS indeksini kullanabilmesi için ayrıca pip install faiss-cpu gerekir. Ayrıntılı kurulum: INSTALL.md.

Çalıştırma

HTTP (streamable-http) sunucusu

Canlı kurulumda sunucu scripts\mcp_http_sunucu.cmd ile başlar; bu betik ortam değişkenlerini kendi içinde kurar ve logu %LOCALAPPDATA%\ipsa-verba\mcp_http.log dosyasına yazar.

.\scripts\mcp_http_sunucu.cmd

Windows'ta EmsalMcpHttp zamanlanmış görevi aynı betiği oturum açılışında çalıştırır. Uç nokta: http://<host>:<port>/mcp.

stdio sunucusu

call .\scripts\ipsa-verba-env.cmd
ipsa-verba-server

Ortam değişkenleri

Değişken Ne işe yarar Örnek değer
IPSA_VERBA_CACHE_PATH Korpus SQLite dosyası <veri-dizini>\cache.sqlite3
IPSA_VERBA_BULK_VEC_DIR fp16 vektör sidecar'ları (refine için) <bench-dizini>\vec
IPSA_VERBA_EMBEDDING_PROVIDER Gömme sağlayıcısı fastembed-multilingual-e5
IPSA_VERBA_EMBEDDING_CACHE_DIR ONNX model önbelleği <veri-dizini>\models\fastembed
IPSA_VERBA_MCP_TRANSPORT stdio (varsayılan) veya streamable-http streamable-http
IPSA_VERBA_MCP_HOST / IPSA_VERBA_MCP_PORT HTTP dinleme adresi 127.0.0.1 / 8790
IPSA_VERBA_TOOL_PROFILE core (varsayılan) veya full core
IPSA_VERBA_TOOL_THREADS Sync araçları için thread havuzu (0 = kapalı) 6
IPSA_VERBA_TOOL_TIMEOUT Araç başına saniye sınırı 180

Tek seferlik CLI çağrıları için scripts\ipsa-verba-env.cmd aynı değişkenleri kurar (call .\scripts\ipsa-verba-env.cmd && .venv\Scripts\ipsa-verba ...).

Makineye özel değerler (veri dizini, dinleme adresi, yedek hedefi) repoda tutulmaz: scripts\yerel-ayar.ornek.cmd dosyasını scripts\yerel-ayar.cmd adıyla kopyalayıp doldurun (.gitignore'dadır). ipsa-verba-env.cmd, crawl_incremental.ps1 ve Python betikleri (scripts/_yollar.py) bu dosyayı okur; boş bırakılan her yol ~/.ipsa-verba altından türetilir.

MCP araçları

Varsayılan profil core — 12 araç kayıtlı gelir. Geri kalanı çalışan sunucuya load_extended_tools ile kategori kategori eklenir. Sözleşmeler: docs/MCP_CONTRACTS.md.

Core (12):

Araç Ne yapar
search_decisions Canlı kaynaklarda karar araması (yönlendirme dahil)
get_document Tek belge getirme
search_local_corpus Yerel 11 M karar korpusunda FTS5 + anlamsal arama
search_legislation mevzuat.gov.tr üzerinde mevzuat araması
get_legislation Mevzuat metni / madde getirme
mevzuat_korpus_ara Yerel mevzuat korpusunda madde bazlı arama
mevzuat_madde_getir Yerel korpustan tek madde
mevzuat_degisiklik_haritasi Bir değişiklik kanununun hangi maddeleri değiştirdiği ve işlenme durumu
research_topic Konu araştırması paketi (bundle + kalite panosu)
export_document Belge dışa aktarma
load_extended_tools Extended kategorileri çalışırken yükleme
health_check Kaynak/breaker/indeks/zamanlanmış iş sağlığı

Extended (36), kategori bazında:

Kategori Araç sayısı Araçlar
legislation 1 mevzuat_degisiklik_raporu
drafting 2 citation_check, prepare_petition
files 1 read_legal_file
meta 2 list_sources, legal_research_guide
health_admin 4 circuit_breaker_status, source_health, source_smoke, check_government_servers_health
watch 4 watch_add, watch_list, watch_run, watch_remove
privacy 3 privacy_scan, privacy_redact, privacy_audit
chambers 4 chamber_overview, profile_chamber, chamber_timeline, find_similar_chambers
indexing 1 index_status
drafting_advanced 10 draft_document, export_bundle, inspect_petition_pack, build_multi_issue_pack, inspect_multi_issue_pack, list_petition_templates, get_petition_template, build_argument_chain, score_argument, get_argument_strength_report
udf_admin 4 udf_toolkit_status, udf_authoring_instructions, pdf_toolkit_status, promote_pdf_to_full_text

Core profilin docstring bütçesi (20.000 karakter) dolduğu için citation_check, prepare_petition, read_legal_file, list_sources ve legal_research_guide 6 Eylül 2026'da extended'a alındı; load_extended_tools ile geri gelirler.

CLI örnekleri

ipsa-verba sources
ipsa-verba search bedesten "muvazaa" --limit 5
ipsa-verba get bedesten DOCUMENT_ID
ipsa-verba semantic bulk-status
ipsa-verba mevzuat korpus-ara "tahliye taahhüdü"
ipsa-verba smoke --offline

Korpus crawl + panel

Uzun soluklu korpus taraması (Bedesten'den yıl yıl karar indirme) bir master script ile yürür, durumu tarayıcıdan izlenir.

.\scripts\kur-otomatik-baslatma.ps1          # oturum açılışına ekler (yönetici gerekmez)
.\scripts\kur-otomatik-baslatma.ps1 -Durum   # ne çalışıyor?
.\scripts\kur-otomatik-baslatma.ps1 -Kaldir  # geri al
Parça Ne yapar
crawl_master.ps1 Yılları sırayla tarar. Tek örnek kilidi (mutex), crawl_logs\crawl_state.json'a checkpoint yazar — PC kapanırsa kaldığı yıl ve sayfadan devam eder.
scripts\panel.py http://127.0.0.1:8799 — canlı crawl durumu, yıl hedefleri, kütüphane dağılımı, hız/tahmin. Ek bağımlılık yok.
Zamanlanmış görevler EmsalCrawlMaster (oturum + 1 dk), EmsalPanel (oturum + 20 sn).

Notlar:

  • Rate limit IPSA_VERBA_RATE_LIMIT_MAX=12. Ölçüldü: 12'de 429 yok (~2.800 belge/saat), 15'te 429 cooldown döngüsüne girip hız sıfırlanıyor.
  • Panel, cache.sqlite3 üzerinde yıl sayımı yapmaz — tek bir yıl sorgusu tam tablo taraması yüzünden ~60 sn sürüyor. Sayımlar ~/.ipsa-verba/panel_stats.sqlite3 içinde artımlı (yalnız yeni rowid'ler) tutulur, günde bir kez tam sayım yapılır.
  • Yıl hedefleri Bedesten'in total alanından ölçülür (crawl_logs\hedefler.json), tahmin edilmez.

İşletim

Zamanlanmış işler (Windows Görev Zamanlayıcı, korpus sunucusu):

Görev Zaman Betik Ne yapar
EmsalMcpHttp oturum açılışı scripts\mcp_http_sunucu.cmd MCP sunucusunu yayınlar
EmsalCrawlDaily her gün 04:30 scripts\crawl_incremental.ps1 Artımlı karar crawl'ı
EmsalMevzuatWeekly Pazar 03:00 scripts\mevzuat_weekly.cmd Mevzuat güncellemesi (+ art-işlem mevzuat_semantic.cmd)
EmsalMonthlyMerge ayın 1'i 02:00 scripts\monthly_merge.cmd Delta vektörlerini toplu FAISS indeksine katar

health_check aracı bu işlerin son koşusunu scheduled_jobs bloğunda raporlar: schtasks çağırmaz, işlerin kendi log dosyalarına yazdığı bitiş işaretini ve dosya zaman damgasını okur. Bir iş gecikmişse ya da rc != 0 ile bitmişse overall "degraded" döner (src/ipsa_verba/ops_status.py). Aynı çıktıda tool_runtime bloğu thread havuzu / zaman aşımı sayaçlarını verir; runaway > 0 ise sunucu yeniden başlatılmalıdır.

Belgeler

Belge İçerik
docs/BULK_INDEX.md Toplu korpus kurulumu, FAISS indeks yapısı, chunking v2, ölçümler, tuzaklar
docs/MCP_CONTRACTS.md MCP araç sözleşmeleri, profiller, kategoriler
docs/COOKBOOK.md Kopyala-çalıştır iş akışı reçeteleri
docs/JSON_CONTRACTS.md Genel API fonksiyonlarının JSON çıktı sözleşmeleri
docs/ERROR_CATALOG.md Hata kodları ve önerilen eylemler
docs/INDEX.md Tüm belgelerin dizini
CHANGELOG.md Sürüm geçmişi

Test

.venv\Scripts\python.exe -X utf8 -m pytest tests -q
ruff check src tests scripts

Canlı kaynağa giden testler varsayılan olarak atlanır; açmak için IPSA_VERBA_LIVE_TESTS=1.

Lisans

GNU Affero Genel Kamu Lisansı sürüm 3 ile lisanslanmıştır (AGPL-3.0-only); tam metin LICENSE dosyasındadır. Yazılımı değiştirip ağ üzerinden başkalarına hizmet olarak sunarsanız, değiştirdiğiniz kaynak kodu da o kullanıcılara aynı lisansla sunmanız gerekir. Güvenlik açıklarının nasıl bildirileceği SECURITY.md dosyasında anlatılıyor.

Telif hakkı © 2026 Alpaslan Fatih Sözer

Metadata

Release files for ipsa-verba 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ipsa-verba 3.0.0
File Size Uploaded Provenance Actions
ipsa_verba-3.0.0.tar.gz 652.7 kB With provenance Details for ipsa_verba-3.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ipsa-verba 3.0.0
File Interpreter ABI Platform Actions
ipsa_verba-3.0.0-py3-none-any.whl Python 3 none any Details for ipsa_verba-3.0.0-py3-none-any.whl

Total release size: 1.1 MB

Release files / ipsa_verba-3.0.0.tar.gz

Download URL ipsa_verba-3.0.0.tar.gz
Size 652.7 kB
Tags Source
SHA-256 checksum
How to use checksums
7eded94262fef67869806b95582b5c7784cc5cffa44a15ab7124a7feb6b6bf82
BLAKE2b-256 checksum
How to use checksums
b30de3ce6eb5787ddbf4c93be149b2dbc3fafabc8e48e7df8ca804c5bcbab96f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / ipsa_verba-3.0.0-py3-none-any.whl

Download URL ipsa_verba-3.0.0-py3-none-any.whl
Size 431.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1e7b4dbeb13db62ea9b6fe9449be106bdcc683d442ee1074cb83bedac46e90ec
BLAKE2b-256 checksum
How to use checksums
33b02f7609259f83e4b5999cb279769cb5535f39916859b1a9805576e0c416d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for ipsa-verba 3.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ipsa_verba-3.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page