Updated the contracts endpoint to reflect real filters

Author: vdavez

README.md

@@ -106,30 +106,50 @@ contracts = client.list_contracts(
     limit=25,
     # Filter parameters
     keyword="software",
-    awarding_agency="GSA",
+    awarding_agency="4700",  # GSA agency code
     award_date_gte="2023-01-01",
-    award_amount_gte=100000,
+    fiscal_year=2024,
     naics_code="541511"
 )
 
 # Filter by specific agency
 contracts = client.list_contracts(
-    awarding_agency="DOD",
+    awarding_agency="4700",  # GSA
     limit=50
 )
 ```
 
 **Available Filter Parameters:**
 
-- `keyword` - Text search
-- `award_date_gte`, `award_date_lte` - Date range filters
-- `award_amount_gte`, `award_amount_lte` - Amount filters
-- `awarding_agency`, `funding_agency` - Agency filters
-- `recipient_name`, `recipient_uei` - Recipient filters
-- `naics_code`, `psc_code` - Classification codes
-- `place_of_performance_state`, `place_of_performance_zip` - Location filters
-- `fiscal_year` - Fiscal year filter
-- `contract_type`, `award_type`, `set_aside_type`, `extent_competed` - Type filters
+**Text Search:**
+- `keyword` - Search contract descriptions (mapped to 'search' API param)
+
+**Date Filters:**
+- `award_date_gte`, `award_date_lte` - Award date range
+- `pop_start_date_gte`, `pop_start_date_lte` - Period of performance start date range
+- `pop_end_date_gte`, `pop_end_date_lte` - Period of performance end date range
+- `expiring_gte`, `expiring_lte` - Contract expiration date range
+
+**Party Filters:**
+- `awarding_agency`, `funding_agency` - Agency codes
+- `recipient_name`, `recipient_uei` - Vendor/recipient filters
+
+**Classification:**
+- `naics_code`, `psc_code` - Industry/product codes
+- `set_aside_type` - Set-aside type
+
+**Type Filters:**
+- `fiscal_year`, `fiscal_year_gte`, `fiscal_year_lte` - Fiscal year filters
+- `award_type` - Award type code
+
+**Identifiers:**
+- `piid` - Procurement Instrument Identifier
+- `solicitation_identifier` - Solicitation ID
+
+**Sorting:**
+- `sort`, `order` - Sort results (e.g., `sort="award_date"`, `order="desc"`)
+
+**Response Options:**
 - `shape`, `flat`, `flat_lists` - Response shaping options
 
 ### Entities (Vendors/Recipients)

ROADMAP.md

@@ -0,0 +1,29 @@
+# ROADMAP
+
+## Now
+
+- [ ] Align existing API to the SDK
+    - [ ] Add in existing IDV endpoint
+    - [ ] Add in existing OTA endpoint
+    - [ ] Add in existing OTIDV endpoint
+    - [ ] Add in existing financial assistance endpoint
+    - [ ] Add in account usage endpoint
+    - [ ] Add in webhooks endpoint
+    - [ ] Add in subawards endpoint
+- [ ] Better Filter DX
+    - [ ] Dataclasses for search validation and typing
+- [ ] Docs improvements
+    - [ ] Document each endpoint separately to allow for easier information
+    - [ ] Some more targeted examples
+
+## Next
+
+- Better support for MCPs
+
+## Later
+
+- 
+
+## Maybe Someday
+
+- CLI support

docs/API_REFERENCE.md

@@ -114,24 +114,37 @@ contracts = client.list_contracts(
     flat=False,
     flat_lists=False,
     # Filter parameters (all optional)
-    keyword=None,
+    # Text search
+    keyword=None,  # Mapped to 'search' API param
+    # Date filters
     award_date_gte=None,
     award_date_lte=None,
-    award_amount_gte=None,
-    award_amount_lte=None,
+    pop_start_date_gte=None,
+    pop_start_date_lte=None,
+    pop_end_date_gte=None,
+    pop_end_date_lte=None,
+    expiring_gte=None,
+    expiring_lte=None,
+    # Party filters
     awarding_agency=None,
     funding_agency=None,
-    recipient_name=None,
-    recipient_uei=None,
-    naics_code=None,
-    psc_code=None,
-    place_of_performance_state=None,
-    place_of_performance_zip=None,
+    recipient_name=None,  # Mapped to 'recipient' API param
+    recipient_uei=None,  # Mapped to 'uei' API param
+    # Classification
+    naics_code=None,  # Mapped to 'naics' API param
+    psc_code=None,  # Mapped to 'psc' API param
+    set_aside_type=None,  # Mapped to 'set_aside' API param
+    # Type filters
     fiscal_year=None,
-    contract_type=None,
+    fiscal_year_gte=None,
+    fiscal_year_lte=None,
     award_type=None,
-    set_aside_type=None,
-    extent_competed=None,
+    # Identifiers
+    piid=None,
+    solicitation_identifier=None,
+    # Sorting
+    sort=None,  # Combined with 'order' into 'ordering' API param
+    order=None,  # 'asc' or 'desc'
 )
 ```
 
@@ -145,36 +158,42 @@ contracts = client.list_contracts(
 **Filter Parameters:**
 
 **Text Search:**
-- `keyword` - Search contract descriptions and titles
+- `keyword` - Search contract descriptions (automatically mapped to API's 'search' parameter)
 
 **Date Filters:**
 - `award_date_gte` - Awarded on or after date (YYYY-MM-DD)
 - `award_date_lte` - Awarded on or before date (YYYY-MM-DD)
-
-**Amount Filters:**
-- `award_amount_gte` - Minimum award amount
-- `award_amount_lte` - Maximum award amount
+- `pop_start_date_gte` - Period of performance start date ≥
+- `pop_start_date_lte` - Period of performance start date ≤
+- `pop_end_date_gte` - Period of performance end date ≥
+- `pop_end_date_lte` - Period of performance end date ≤
+- `expiring_gte` - Expiring on or after date
+- `expiring_lte` - Expiring on or before date
 
 **Party Filters:**
-- `awarding_agency` - Agency code awarding the contract
-- `funding_agency` - Agency code funding the contract
-- `recipient_name` - Vendor/recipient name (partial match)
-- `recipient_uei` - Vendor UEI (exact match)
+- `awarding_agency` - Agency code (e.g., "4700" for GSA)
+- `funding_agency` - Funding agency code
+- `recipient_name` - Vendor/recipient name (mapped to 'recipient' API param)
+- `recipient_uei` - Vendor UEI (mapped to 'uei' API param)
 
 **Classification:**
-- `naics_code` - NAICS industry code
-- `psc_code` - Product/Service code
-
-**Location:**
-- `place_of_performance_state` - State code (e.g., "CA", "NY")
-- `place_of_performance_zip` - ZIP code
+- `naics_code` - NAICS industry code (mapped to 'naics' API param)
+- `psc_code` - Product/Service code (mapped to 'psc' API param)
+- `set_aside_type` - Set-aside type (mapped to 'set_aside' API param)
 
 **Type Filters:**
-- `fiscal_year` - Federal fiscal year
-- `contract_type` - Type of contract
-- `award_type` - Award type
-- `set_aside_type` - Small business set-aside type
-- `extent_competed` - Competition extent
+- `fiscal_year` - Federal fiscal year (exact match)
+- `fiscal_year_gte` - Fiscal year ≥
+- `fiscal_year_lte` - Fiscal year ≤
+- `award_type` - Award type code
+
+**Identifiers:**
+- `piid` - Procurement Instrument Identifier (exact match)
+- `solicitation_identifier` - Solicitation ID
+
+**Sorting:**
+- `sort` - Field to sort by (e.g., "award_date", "obligated")
+- `order` - Sort order: "asc" or "desc" (default: "asc")
 
 **Returns:** [PaginatedResponse](#paginatedresponse) with contract dictionaries
 
@@ -186,7 +205,13 @@ contracts = client.list_contracts(limit=10)
 
 # Filter by agency
 contracts = client.list_contracts(
-    awarding_agency="GSA",
+    awarding_agency="4700",  # GSA agency code
+    limit=50
+)
+
+# Text search
+contracts = client.list_contracts(
+    keyword="software development",
     limit=50
 )
 
@@ -197,25 +222,34 @@ contracts = client.list_contracts(
     limit=100
 )
 
-# Amount range
+# Expiring contracts
 contracts = client.list_contracts(
-    award_amount_gte=100000,
-    award_amount_lte=1000000,
+    expiring_gte="2025-01-01",
+    expiring_lte="2025-12-31",
     limit=50
 )
 
 # Multiple filters
 contracts = client.list_contracts(
-    awarding_agency="DOD",
-    naics_code="541511",  # IT services
+    keyword="IT services",
+    awarding_agency="4700",  # GSA
     fiscal_year=2024,
+    naics_code="541511",
     limit=100
 )
 
 # With shaping for performance
 contracts = client.list_contracts(
     shape="key,piid,recipient(display_name),total_contract_value,award_date",
-    awarding_agency="GSA",
+    awarding_agency="4700",
+    fiscal_year=2024,
+    limit=100
+)
+
+# Sorting results
+contracts = client.list_contracts(
+    sort="award_date",
+    order="desc",
     limit=100
 )
 ```

tango/client.py

@@ -396,27 +396,73 @@ def list_contracts(
             flat_lists: If True, flatten arrays using indexed keys (e.g., items.0.field)
             filters: Optional SearchFilters object or dict for backward compatibility.
                     Filter parameters can also be passed as keyword arguments.
-            **kwargs: Filter parameters (keyword, award_date_gte, award_date_lte,
-                    award_amount_gte, award_amount_lte, awarding_agency, funding_agency,
-                    recipient_name, recipient_uei, naics_code, psc_code,
-                    place_of_performance_state, place_of_performance_zip, cfda_number,
-                    contract_type, award_type, set_aside_type, extent_competed,
-                    fiscal_year, sort, order)
+            **kwargs: Filter parameters
+
+                    Text search:
+                    - keyword: Search contract descriptions (mapped to 'search' API param)
+
+                    Date filters:
+                    - award_date_gte: Award date >= (YYYY-MM-DD)
+                    - award_date_lte: Award date <= (YYYY-MM-DD)
+                    - pop_start_date_gte: Period of performance start date >=
+                    - pop_start_date_lte: Period of performance start date <=
+                    - pop_end_date_gte: Period of performance end date >=
+                    - pop_end_date_lte: Period of performance end date <=
+                    - expiring_gte: Expiring on or after date
+                    - expiring_lte: Expiring on or before date
+
+                    Party filters:
+                    - awarding_agency: Awarding agency code (e.g., "4700" for GSA)
+                    - funding_agency: Funding agency code
+                    - recipient_name: Vendor/recipient name (mapped to 'recipient' API param)
+                    - recipient_uei: Vendor UEI (mapped to 'uei' API param)
+
+                    Classification filters:
+                    - naics_code: NAICS code (mapped to 'naics' API param)
+                    - psc_code: PSC code (mapped to 'psc' API param)
+                    - set_aside_type: Set-aside type (mapped to 'set_aside' API param)
+
+                    Type filters:
+                    - fiscal_year: Fiscal year (exact match)
+                    - fiscal_year_gte: Fiscal year >=
+                    - fiscal_year_lte: Fiscal year <=
+                    - award_type: Award type code
+
+                    Identifiers:
+                    - piid: Procurement Instrument Identifier
+                    - solicitation_identifier: Solicitation ID
+
+                    Sorting:
+                    - sort: Field to sort by (combined with 'order')
+                    - order: Sort order ('asc' or 'desc', default 'asc')
 
         Examples:
             >>> # Simple usage
             >>> contracts = client.list_contracts(limit=10)
 
             >>> # With keyword arguments
             >>> contracts = client.list_contracts(
-            ...     awarding_agency="GSA",
+            ...     awarding_agency="4700",  # GSA
             ...     award_date_gte="2023-01-01",
             ...     limit=25
             ... )
 
-            >>> # With SearchFilters object
-            >>> filters = SearchFilters(keyword="IT", awarding_agency="GSA")
+            >>> # Text search
+            >>> contracts = client.list_contracts(keyword="software development")
+
+            >>> # With SearchFilters object (legacy)
+            >>> filters = SearchFilters(
+            ...     keyword="IT",
+            ...     awarding_agency="4700",
+            ...     fiscal_year=2024
+            ... )
             >>> contracts = client.list_contracts(filters=filters)
+
+            >>> # Using new date range filters
+            >>> contracts = client.list_contracts(
+            ...     expiring_gte="2025-01-01",
+            ...     expiring_lte="2025-12-31"
+            ... )
         """
         # Start with explicit parameters
         params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
@@ -471,21 +517,31 @@ def list_contracts(
         # Map Python parameter names to API parameter names
         # The API may expect different parameter names than our Python interface
         api_param_mapping = {
-            "naics_code": "naics",  # API expects 'naics' not 'naics_code' for filtering
+            "naics_code": "naics",  # API expects 'naics' not 'naics_code'
+            "keyword": "search",  # API expects 'search' not 'keyword'
+            "psc_code": "psc",  # API expects 'psc' not 'psc_code'
+            "recipient_name": "recipient",  # API expects 'recipient' not 'recipient_name'
+            "recipient_uei": "uei",  # API expects 'uei' not 'recipient_uei'
+            "set_aside_type": "set_aside",  # API expects 'set_aside' not 'set_aside_type'
         }
 
+        # Handle sort + order → ordering conversion
+        # API expects single 'ordering' parameter with '-' prefix for descending
+        sort_field = filter_params.pop("sort", None)
+        sort_order = filter_params.pop("order", None)
+        if sort_field:
+            # Prefix with '-' for descending order
+            prefix = "-" if sort_order == "desc" else ""
+            filter_params["ordering"] = f"{prefix}{sort_field}"
+
         # Apply parameter name mapping and process values
         api_params = {}
         for key, value in filter_params.items():
             if value is None:
                 continue  # Skip None values
             # Map to API parameter name if needed
             api_key = api_param_mapping.get(key, key)
-            # Convert Decimal/numeric values to strings for award amounts
-            if key in ("award_amount_gte", "award_amount_lte"):
-                api_params[api_key] = str(value)
-            else:
-                api_params[api_key] = value
+            api_params[api_key] = value
 
         # Update params with all filter parameters
         # This is the same pattern as other endpoints use