[SDK: Python] Add Vehicles endpoints/interface

.gitignore

@@ -144,3 +144,7 @@ dmypy.json
 # OS
 .DS_Store
 Thumbs.db
+
+# other
+/yoni
+.cursor/*

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Vehicles endpoints: `list_vehicles`, `get_vehicle`, and `list_vehicle_awardees` (supports shaping + flattening). (refs `makegov/tango#1328`)
+- IDV endpoints: `list_idvs`, `get_idv`, `list_idv_awards`, `list_idv_child_idvs`, `list_idv_transactions`, `get_idv_summary`, `list_idv_summary_awards`. (refs `makegov/tango#1328`)
+
+### Changed
+- Expanded explicit schemas to support common IDV shaping expansions (award offices, officers, period of performance, etc.).
+
 ## [0.2.0] - 2025-11-16
 
-- Entirely refactored SDK
+- Entirely refactored SDK

docs/API_REFERENCE.md

@@ -7,6 +7,8 @@ Complete reference for all Tango Python SDK methods and functionality.
 - [Client Initialization](#client-initialization)
 - [Agencies](#agencies)
 - [Contracts](#contracts)
+- [IDVs](#idvs)
+- [Vehicles](#vehicles)
 - [Entities](#entities)
 - [Forecasts](#forecasts)
 - [Opportunities](#opportunities)
@@ -271,6 +273,119 @@ contracts = client.list_contracts(
 
 ---
 
+## Vehicles
+
+Vehicles provide a solicitation-centric way to discover groups of related IDVs and (optionally) expand into the underlying awards via shaping.
+
+### list_vehicles()
+
+List vehicles with optional vehicle-level full-text search.
+
+```python
+vehicles = client.list_vehicles(
+    page=1,
+    limit=25,
+    search="GSA schedule",
+    shape=ShapeConfig.VEHICLES_MINIMAL,
+    flat=False,
+    flat_lists=False,
+)
+```
+
+**Parameters:**
+- `page` (int): Page number (default: 1)
+- `limit` (int): Results per page (default: 25, max: 100)
+- `search` (str, optional): Vehicle-level search term
+- `shape` (str, optional): Shape string (defaults to `ShapeConfig.VEHICLES_MINIMAL`)
+- `flat` (bool): Flatten nested objects in shaped response
+- `flat_lists` (bool): Flatten arrays using indexed keys
+- `joiner` (str): Joiner used when `flat=True` (default: `"."`)
+
+**Returns:** [PaginatedResponse](#paginatedresponse) with vehicle dictionaries
+
+### get_vehicle()
+
+Get a single vehicle by UUID.
+
+```python
+vehicle = client.get_vehicle(
+    uuid="00000000-0000-0000-0000-000000000001",
+    shape=ShapeConfig.VEHICLES_COMPREHENSIVE,
+)
+```
+
+**Notes:**
+- On the vehicle detail endpoint, `search` filters **expanded awardees** when your `shape` includes `awardees(...)` (it does not filter the vehicle itself).
+
+### list_vehicle_awardees()
+
+List the IDV awardees for a vehicle.
+
+```python
+awardees = client.list_vehicle_awardees(
+    uuid="00000000-0000-0000-0000-000000000001",
+    shape=ShapeConfig.VEHICLE_AWARDEES_MINIMAL,
+)
+```
+
+---
+
+## IDVs
+
+IDVs (indefinite delivery vehicles) are the parent “vehicle award” records that can have child awards/orders under them.
+
+### list_idvs()
+
+```python
+idvs = client.list_idvs(
+    limit=25,
+    cursor=None,
+    shape=ShapeConfig.IDVS_MINIMAL,
+    awarding_agency="4700",
+)
+```
+
+Notes:
+
+- This endpoint uses **keyset pagination** (`cursor` + `limit`) rather than page numbers.
+
+### get_idv()
+
+```python
+idv = client.get_idv("SOME_IDV_KEY", shape=ShapeConfig.IDVS_COMPREHENSIVE)
+```
+
+### list_idv_awards()
+
+Lists child awards (contracts) under an IDV.
+
+```python
+awards = client.list_idv_awards("SOME_IDV_KEY", limit=25)
+```
+
+### list_idv_child_idvs()
+
+Lists child IDVs under an IDV.
+
+```python
+children = client.list_idv_child_idvs("SOME_IDV_KEY", limit=25)
+```
+
+### list_idv_transactions()
+
+```python
+tx = client.list_idv_transactions("SOME_IDV_KEY", limit=100)
+```
+
+### get_idv_summary() / list_idv_summary_awards()
+
+```python
+summary = client.get_idv_summary("SOLICITATION_IDENTIFIER")
+awards = client.list_idv_summary_awards("SOLICITATION_IDENTIFIER", limit=25)
+```
+
+---
+
 ## Entities
 
 Vendors, recipients, and organizations doing business with the government.

pyproject.toml

@@ -97,6 +97,7 @@ markers = [
     "live: Tests that always use live API (skip cassettes)",
     "cached: Tests that only run with cached responses",
     "slow: Tests that are slow to execute",
+    "production: Production API smoke tests that run against live API",
 ]
 
 [tool.coverage.run]

scripts/README.md

@@ -4,10 +4,73 @@ This directory contains utility scripts used during development and maintenance
 
 ## Scripts
 
+### Schema and API Tools
+
 - **`fetch_api_schema.py`** - Fetches the OpenAPI schema from the Tango API and saves it locally
 - **`generate_schemas_from_api.py`** - Generates schema definitions from the API reference (outputs to stdout)
 
+### Testing and Validation
+
+- **`test_production.py`** - Runs production API smoke tests against the live API
+- **`pr_review.py`** - Runs configurable validation checks for PR review (linting, type checking, tests)
+
 ## Usage
 
-These scripts are primarily for maintainers and are not part of the public API. They require:
-- `TANGO_API_KEY` environment variable
+These scripts are primarily for maintainers and are not part of the public API.
+
+### Production API Testing
+
+Run smoke tests against the production API:
+
+```bash
+# Requires TANGO_API_KEY environment variable
+uv run python scripts/test_production.py
+```
+
+This runs fast smoke tests (~30-60 seconds) that validate core SDK functionality against the live production API.
+
+### PR Review Validation
+
+Run validation checks for PR review. **Automatically detects PR context** from GitHub Actions, GitHub CLI, or git branch.
+
+```bash
+# Auto-detect PR and run validation (default: production mode)
+uv run python scripts/pr_review.py
+
+# Review a specific PR number
+uv run python scripts/pr_review.py --pr-number 123
+
+# Smoke tests only
+uv run python scripts/pr_review.py --mode smoke
+
+# Quick validation (linting + type checking, no tests)
+uv run python scripts/pr_review.py --mode quick
+
+# Full validation (all checks including all tests)
+uv run python scripts/pr_review.py --mode full
+
+# Check only changed files (auto-enabled when PR is detected)
+uv run python scripts/pr_review.py --mode production --changed-files-only
+```
+
+**Validation Modes:**
+- `smoke` - Production API smoke tests only
+- `quick` - Linting + type checking (no tests)
+- `full` - All checks (linting + type checking + all tests)
+- `production` - Production API smoke tests + linting + type checking (default)
+
+**PR Detection:**
+The script automatically detects PR information from:
+- GitHub Actions environment variables (`GITHUB_EVENT_PATH`, `GITHUB_PR_NUMBER`)
+- GitHub CLI (`gh pr view` - requires `gh auth login`)
+- Current git branch
+
+When a PR is detected, the script displays PR information and automatically:
+- Detects the base branch from the PR
+- Checks only changed files
+- Shows PR URL in summary
+
+## Requirements
+
+- `TANGO_API_KEY` environment variable (required for production API tests)
+- All dependencies installed: `uv sync --all-extras`