From 1a190fbc3edf1ef9c29a5cc1468aba9e45a34b77 Mon Sep 17 00:00:00 2001 From: saidsurucu Date: Tue, 24 Jun 2025 21:36:16 +0300 Subject: [PATCH] add model descriptions --- bedesten_mcp_module/models.py | 58 ++++++++++++++++++++++--------- yargitay_mcp_module/models.py | 64 ++++++++++++++++++++++++++++------- 2 files changed, 93 insertions(+), 29 deletions(-) diff --git a/bedesten_mcp_module/models.py b/bedesten_mcp_module/models.py index a9a4145..4289a65 100644 --- a/bedesten_mcp_module/models.py +++ b/bedesten_mcp_module/models.py @@ -33,10 +33,27 @@ DanistayBirimEnum = Literal[ # Search Request Models class BedestenSearchData(BaseModel): - pageSize: int - pageNumber: int - itemTypeList: List[str] - phrase: str + pageSize: int = Field(..., description="""Number of results per page. + Range: 1-100 results per page + Recommended: 10-50 for balanced performance + Higher values for comprehensive analysis""") + pageNumber: int = Field(..., description="""Page number to retrieve (1-indexed). + Start with 1 for first page + Calculate total pages from response.data.total / pageSize + Navigate: pageNumber=2 gets next set of results""") + itemTypeList: List[str] = Field(..., description="""Court type filter - determines which court decisions to search: + • ["YARGITAYKARARI"]: Yargıtay (Court of Cassation) - supreme court civil/criminal + • ["DANISTAYKARAR"]: Danıştay (Council of State) - administrative court decisions + • ["YERELHUKUK"]: Yerel Hukuk Mahkemesi - local civil court decisions + • ["ISTINAFHUKUK"]: İstinaf Hukuk Mahkemesi - civil appellate court decisions + • ["KYB"]: Kanun Yararına Bozma - extraordinary appeal decisions + Note: Use single-item list for specific court type targeting""") + phrase: str = Field(..., description="""Search phrase/keyword with advanced search support: + • Regular search: "mülkiyet kararı" - searches words separately + • Exact phrase: "\"mülkiyet kararı\"" - searches exact phrase (more precise) + • Legal concepts: "\"idari işlem\"", "\"sözleşme ihlali\"" + • Empty string: searches all documents (use with filters) + Exact phrases significantly reduce false positives""") birimAdi: Optional[Union[YargitayBirimEnum, DanistayBirimEnum]] = Field(None, description=""" Chamber/Board filter (optional). Available options depend on itemTypeList: @@ -54,18 +71,27 @@ class BedestenSearchData(BaseModel): - 'İçtihatları Birleştirme Kurulu', 'İdari İşler Kurulu', 'Başkanlar Kurulu' - Military courts: 'Askeri Yüksek İdare Mahkemesi' variants """) - kararTarihiStart: Optional[str] = Field(None, description=""" - Decision start date filter (optional). Format: YYYY-MM-DDTHH:MM:SS.000Z - Example: "2024-01-01T00:00:00.000Z" - Use with kararTarihiEnd for date range filtering - """) - kararTarihiEnd: Optional[str] = Field(None, description=""" - Decision end date filter (optional). Format: YYYY-MM-DDTHH:MM:SS.000Z - Example: "2024-12-31T23:59:59.999Z" - Use with kararTarihiStart for date range filtering - """) - sortFields: List[str] = ["KARAR_TARIHI"] - sortDirection: str = "desc" + kararTarihiStart: Optional[str] = Field(None, description="""Decision start date filter (optional). + Format: YYYY-MM-DDTHH:MM:SS.000Z (ISO 8601 with Z timezone) + Examples: + • "2024-01-01T00:00:00.000Z" - from beginning of 2024 + • "2023-06-15T00:00:00.000Z" - from June 15, 2023 + • "2024-03-01T00:00:00.000Z" - from March 1, 2024 + Use with kararTarihiEnd for date range, or alone for "from date" filtering""") + kararTarihiEnd: Optional[str] = Field(None, description="""Decision end date filter (optional). + Format: YYYY-MM-DDTHH:MM:SS.000Z (ISO 8601 with Z timezone) + Examples: + • "2024-12-31T23:59:59.999Z" - until end of 2024 + • "2023-12-31T23:59:59.999Z" - until end of 2023 + • "2024-06-30T23:59:59.999Z" - until end of June 2024 + Use with kararTarihiStart for date range, or alone for "until date" filtering""") + sortFields: List[str] = Field(default=["KARAR_TARIHI"], description="""Sorting field specification. + ["KARAR_TARIHI"]: Sort by decision date [DEFAULT] + Most common use case for chronological ordering""") + sortDirection: str = Field(default="desc", description="""Sort direction for results. + "desc": Descending order - newest decisions first [DEFAULT] + "asc": Ascending order - oldest decisions first + Recommended: "desc" for latest legal developments""")""") class BedestenSearchRequest(BaseModel): data: BedestenSearchData diff --git a/yargitay_mcp_module/models.py b/yargitay_mcp_module/models.py index da63bca..501ff26 100644 --- a/yargitay_mcp_module/models.py +++ b/yargitay_mcp_module/models.py @@ -34,7 +34,14 @@ class YargitayDetailedSearchRequest(BaseModel): to Yargitay's detailed search endpoint (e.g., /aramadetaylist). Based on the payload provided by the user. """ - arananKelime: Optional[str] = Field("", description="Keyword to search for.") + arananKelime: Optional[str] = Field("", description="""Keyword to search for with advanced operators support: + • Simple words: 'arsa payı' (OR logic - finds documents with ANY word) + • Exact phrases: '"arsa payı"' (finds exact phrase) + • AND logic: 'arsa+payı' (both words required) + • Wildcards: 'bozma*' (matches bozma, bozması, bozmanın, etc.) + • Multiple required: '+"arsa payı" +"bozma sebebi"' + • Exclusion: '+"arsa payı" -"inşaat sözleşmesi"' + Examples: arsa payı | "arsa payı" | +"property right" +"cancellation reason" | legal*""") # Department/Board selection - Complete Yargıtay chamber hierarchy birimYrgKurulDaire: YargitayBirimEnum = Field("", description=""" Yargıtay chamber/board selection. Options include: @@ -47,22 +54,53 @@ class YargitayDetailedSearchRequest(BaseModel): birimYrgHukukDaire: Optional[str] = Field("", description="Legacy field - use birimYrgKurulDaire instead") birimYrgCezaDaire: Optional[str] = Field("", description="Legacy field - use birimYrgKurulDaire instead") - esasYil: Optional[str] = Field("", description="Case year for 'Esas No'.") - esasIlkSiraNo: Optional[str] = Field("", description="Starting sequence number for 'Esas No'.") - esasSonSiraNo: Optional[str] = Field("", description="Ending sequence number for 'Esas No'.") + esasYil: Optional[str] = Field("", description="""Case year for 'Esas No' filtering. + Format: YYYY (e.g., '2024') + Use with sequence numbers for precise case targeting""") + esasIlkSiraNo: Optional[str] = Field("", description="""Starting sequence number for 'Esas No' range filtering. + Format: numeric string (e.g., '1', '100') + Use with esasSonSiraNo for range: cases 100-200 in specified year""") + esasSonSiraNo: Optional[str] = Field("", description="""Ending sequence number for 'Esas No' range filtering. + Format: numeric string (e.g., '500', '1000') + Creates range from esasIlkSiraNo to this number""") - kararYil: Optional[str] = Field("", description="Decision year for 'Karar No'.") - kararIlkSiraNo: Optional[str] = Field("", description="Starting sequence number for 'Karar No'.") - kararSonSiraNo: Optional[str] = Field("", description="Ending sequence number for 'Karar No'.") + kararYil: Optional[str] = Field("", description="""Decision year for 'Karar No' filtering. + Format: YYYY (e.g., '2024') + Filters decisions by the year they were issued""") + kararIlkSiraNo: Optional[str] = Field("", description="""Starting sequence number for 'Karar No' range filtering. + Format: numeric string (e.g., '1', '50') + Use with kararSonSiraNo for decision number ranges""") + kararSonSiraNo: Optional[str] = Field("", description="""Ending sequence number for 'Karar No' range filtering. + Format: numeric string (e.g., '100', '500') + Creates range from kararIlkSiraNo to this number""") - baslangicTarihi: Optional[str] = Field("", description="Start date for decision search (DD.MM.YYYY).") - bitisTarihi: Optional[str] = Field("", description="End date for decision search (DD.MM.YYYY).") + baslangicTarihi: Optional[str] = Field("", description="""Start date for decision search. + Format: DD.MM.YYYY (e.g., '01.01.2024') + Use with bitisTarihi for date range filtering + Examples: '01.01.2024', '15.06.2023'""") + bitisTarihi: Optional[str] = Field("", description="""End date for decision search. + Format: DD.MM.YYYY (e.g., '31.12.2024') + Creates date range from baslangicTarihi to this date + Examples: '31.12.2024', '30.06.2023'""")""") - siralama: Optional[str] = Field("3", description="Sorting criteria (1: Esas No, 2: Karar No, 3: Karar Tarihi).") # Default to 'Karar Tarihine Göre' - siralamaDirection: Optional[str] = Field("desc", description="Sorting direction ('asc' or 'desc').") # Default to 'Büyükten Küçüğe' + siralama: Optional[str] = Field("3", description="""Sorting criteria for search results: + • '1': Esas No (Case Number) - sorts by case registration order + • '2': Karar No (Decision Number) - sorts by decision issuance order + • '3': Karar Tarihi (Decision Date) - sorts by chronological order [DEFAULT] + Recommended: Use '3' for most recent decisions first""") + siralamaDirection: Optional[str] = Field("desc", description="""Sorting direction for results: + • 'desc': Descending order (newest/highest first) [DEFAULT] + • 'asc': Ascending order (oldest/lowest first) + Most common: 'desc' for latest decisions first""") - pageSize: int = Field(10, ge=1, le=100, description="Number of results per page.") - pageNumber: int = Field(1, ge=1, description="Page number to retrieve.") + pageSize: int = Field(10, ge=1, le=100, description="""Number of results per page. + Range: 1-100 results per page + Recommended: 10-50 for balanced performance and coverage + Large values (50-100) for comprehensive analysis""") + pageNumber: int = Field(1, ge=1, description="""Page number to retrieve (1-indexed). + Start with 1 for first page + Use with pageSize to navigate through large result sets + Example: pageSize=50, pageNumber=3 gets results 101-150""") class YargitayApiDecisionEntry(BaseModel): """Model for an individual decision entry from the Yargitay API search response."""