tango-python 1.5.1__tar.gz → 1.6.0__tar.gz

{tango_python-1.5.1 → tango_python-1.6.0}/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-09-10
+
+### Added
+- **`attachments(extracted_text)` — SLED document bodies on the Small plan and above** (Tango API 4.25.1). Re-vendored the contract and regenerated the shape overlay, so `shape="...,attachments(name,extracted_text)"` now validates instead of being rejected client-side. Three properties are documented on the model and in `docs/API_REFERENCE.md`, because each is otherwise a support question: the leaf must be **named** (neither `SLED_OPPORTUNITIES_MINIMAL` nor `SLED_OPPORTUNITIES_COMPREHENSIVE` includes it, and `attachments(*)` does not carry it, because the API only resolves the body for a caller who asked); the **key is absent rather than null** when the text is not being served, so read it with `.get()`; and a **contested document never returns text at any plan**. Searching document text stays ungated on every plan and returns no fragment of it — buying the body does not change search.
+- **State, local and education (SLED) procurement** (Tango API 4.25.0). Six methods over the new `/api/sled/` namespace: `list_sled_opportunities()`, `get_sled_opportunity()`, `list_sled_opportunity_revisions()`, `get_sled_coverage()`, `list_sled_forecasts()`, `get_sled_forecast()`, plus `SledOpportunity` / `SledOpportunityRevision` / `SledForecast` schemas and five `ShapeConfig` defaults. Every one of the API's 27 solicitation filters and 13 forecast filters is an explicit named parameter.
+
+  Four behaviors are documented on the methods themselves because each misleads a caller who assumes federal semantics. **Passing neither `status` nor `active` returns open solicitations only** — that default is the API's, and the SDK deliberately does not synthesize a `status` param, since doing so would make `active=False` unreachable (pinned by a test). **`status` is Tango-derived and refreshed every fifteen minutes**; the portal's own word is served as `source_status`, is frozen at last capture, and is not a liveness filter. **Category scheme tagging is mid-migration**, so `naics=` matches only the small tagged share and `category_code=` is the escape hatch. And **`meta.attachment_count` can be lower than `len(attachments)`**, because an auto-generated portal cover sheet is listed and flagged `is_generated_summary` but excluded from the count.
+
+  `SLED_REVISIONS_MINIMAL` omits `changes` on purpose: the per-field before/after needs a Small plan, so naming it by default would 403 a Free caller. `changed_fields` is in the default and available at every plan.
+- **`previous_uii` on `list_itdashboard_investments()`.** The Tango API has accepted this filter for a while — it resolves a retired UII forward to whatever superseded it — and the SDK never picked it up, so it was a silent no-op for anyone who passed it through. Ungated, unlike its analytical neighbours on that endpoint. Found by the SDK's own filter-conformance check, not by SLED work.
+
+### Changed
+- Re-vendored `contracts/filter_shape_contract.json` (schema_version 2, 48 resources) and regenerated `tango/shapes/generated_overlay.py` from it — 535 fields across 33 containers, 84 nested schemas. Besides the SLED expands this closes three entity gaps the older contract could not see: `relationships(confidence, verification_method)` and the whole `workforce(*)` expand were reachable on the API and rejected client-side by the SDK's schema.
+- Baselined 14 reverse-shape-coverage gaps in `contracts/shape_coverage_baseline.json`. All 14 are nested sub-resource routes the newer contract publishes for the first time (`entities_contracts`, `idvs_awards`, `vehicles_orders`, and similar); none is SLED, and none is a regression — they are pre-existing SDK gaps that only became visible with the re-vendored contract. The gate reports 0 new drift.
+
+### Documentation
+- New **State & Local (SLED)** section in `docs/API_REFERENCE.md` covering all six methods, both defaults that surprise people, and the five new `ShapeConfig` constants.
+- Corrected `docs/WEBHOOKS.md`. It stated flatly that "nothing fires when a record merely lapses"; that is now false for exactly one query type. `alerts.sled_opportunity.match` **does** fire on a closing, because SLED liveness is a stored column a fifteen-minute sweep writes rather than a query-time derivation. Also documented that there is no `sled_forecast` query type and that SLED revisions and attachments are not separately alertable.
+
 ## [1.5.1] - 2026-08-10
 
 ### Documentation

{tango_python-1.5.1 → tango_python-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: tango-python
-Version: 1.5.1
+Version: 1.6.0
 Summary: Python SDK for the Tango API
 Project-URL: Homepage, https://github.com/makegov/tango-python
 Project-URL: Documentation, https://docs.makegov.com/tango-python

{tango_python-1.5.1 → tango_python-1.6.0}/docs/API_REFERENCE.md

@@ -18,6 +18,7 @@ Complete reference for all Tango Python SDK methods and functionality.
 - [Forecasts](#forecasts)
 - [Opportunities](#opportunities)
 - [Notices](#notices)
+- [State \& Local (SLED)](#state--local-sled)
 - [Grants](#grants)
 - [GSA eLibrary Contracts](#gsa-elibrary-contracts)
 - [Protests](#protests)
@@ -1213,6 +1214,203 @@ protest = client.get_protest(
 
 ---
 
+## State & Local (SLED)
+
+State, local and education procurement — solicitations that never appear on SAM.gov because they were never federal. **Beta**: coverage is partial and grows one jurisdiction at a time.
+
+This data does not join to the federal data. There is no UEI, no PIID, no agency-hierarchy key and no NAICS/PSC crosswalk; `organization(*)` here is three strings, not the federal 7-key office payload.
+
+### list_sled_opportunities()
+
+List SLED solicitations with filtering and shaping.
+
+```python
+solicitations = client.list_sled_opportunities(
+    page=1,
+    limit=25,
+    shape=ShapeConfig.SLED_OPPORTUNITIES_MINIMAL,
+    # Filter parameters (all optional)
+    state=None,
+    jurisdiction=None,
+    status=None,
+    active=None,
+    agency=None,
+    solicitation_number=None,
+    solicitation_type=None,
+    has_documents=None,
+    revision_kind=None,
+    naics=None,
+    nigp=None,
+    unspsc=None,
+    category=None,
+    category_code=None,
+    posted_after=None,
+    posted_before=None,
+    response_deadline_after=None,
+    response_deadline_before=None,
+    first_seen_after=None,
+    first_seen_before=None,
+    change_seen_after=None,
+    modified_after=None,
+    modified_before=None,
+    search=None,
+    ordering=None,
+)
+```
+
+**Two defaults worth knowing before your first call:**
+
+- **Passing neither `status` nor `active` returns open solicitations only.** Only about a fifth of the corpus is open, and a portal drops a closed solicitation rather than restating it, so the API defaults the list to `status=open`. Pass an explicit `status` to page the whole corpus. `status="unknown"` (standing rosters, dateless RFIs) is hidden by that default — reach it with `status="open|unknown"`. `get_sled_opportunity()` returns the solicitation whatever its status.
+- **`status` is Tango's answer, not the portal's.** It is derived from the portal's word, the deadline and the clock, and refreshed every fifteen minutes. The portal's own word is served as `source_status` and is frozen at last capture — most of what it calls open already has a passed deadline. Never filter liveness on it.
+
+**Filter Parameters:**
+- `state` - Two-letter state or territory code. Multi-value: `"TX|OK"`
+- `jurisdiction` - `"state"`, `"local"`, `"education"`, or `"unknown"` for aggregator rows that cannot tell state from local
+- `status` - `"open"`, `"closed"`, `"awarded"`, `"cancelled"`, `"unknown"`
+- `active` - Sugar for federal-shaped callers: `True` is `status="open"`; `False` is its complement, so it includes `unknown`
+- `agency` - Substring match on the buyer's published text (min 2 characters); no code resolution behind it
+- `solicitation_number` - The number a human would quote; null on roughly a third of the corpus
+- `solicitation_type` - `"rfp"`, `"ifb"`, `"rfq"`, `"rfi"`, `"itb"`, `"sole_source"`, `"grant"`, `"other"`. `"null"` (portal states no type) is a distinct answer from `"other"`
+- `has_documents` - Whether the solicitation advertises at least one document
+- `revision_kind` - Kind of the most recent substantive revision
+- `naics` / `nigp` / `unspsc` / `category` - Exact match within one category scheme. **`naics` is thin on purpose**: scheme tagging is mid-migration, so only a small share of entries are tagged NAICS
+- `category_code` - Match a code under ANY scheme, including the untagged pre-migration strings. The escape hatch when a scheme-specific filter returns less than expected
+- `posted_after` / `posted_before` - Posted-date range
+- `response_deadline_after` / `response_deadline_before` - Deadline range
+- `first_seen_after` / `first_seen_before` - When Tango first observed it. The polling primitive
+- `change_seen_after` - When Tango *observed* the last substantive change. A scrape date, not an amendment date
+- `modified_after` / `modified_before` - When the Tango row last changed
+- `platform` / `native_id` / `external_id` - Support filters for reproducing a record with us. Not in any response shape and not stable values
+- `search` - Ranked full-text search over title, agency, identifiers, category labels and description, widened by the solicitations whose *attachment text* matched (min 2 characters)
+- `ordering` - `rank`, `response_deadline`, `posted_date`, `first_seen_at`, `last_seen_at`, `last_change_seen_at`, `modified`. `rank` requires a non-empty `search`
+
+**Returns:** [PaginatedResponse](#paginatedresponse) with solicitation dictionaries
+
+**Example:**
+```python
+# Open Texas solicitations closing this month, newest first
+page = client.list_sled_opportunities(
+    state="TX",
+    response_deadline_before="2026-10-01",
+    ordering="response_deadline",
+    limit=25,
+)
+
+for row in page.results:
+    print(f"{row['state']} {row.get('solicitation_number') or '—'}: {row['title']}")
+
+# Full-text search puts the matching passage on each row that matched on its body
+hits = client.list_sled_opportunities(
+    search="environmental mitigation",
+    shape="opportunity_id,title,state,snippet,response_deadline",
+)
+```
+
+`snippet` is present only under `search=`, and only on rows that matched on their description — a title-or-agency match honestly carries none. Attachment matching contributes ids only: a caller learns *that* a document matched, never what it said.
+
+### get_sled_opportunity()
+
+Get a single solicitation by `opportunity_id`, whatever its status.
+
+```python
+row = client.get_sled_opportunity(
+    "OPPORTUNITY_UUID",
+    shape="opportunity_id,title,status,attachments(*),revisions(*)",
+)
+```
+
+**Notes:**
+- `meta.attachment_count` can be **lower** than `len(row["attachments"])`. Some portals auto-generate a cover sheet alongside the real documents; it is listed and flagged `is_generated_summary`, but excluded from the count and from `has_documents`. The count answers "does this hold its solicitation package"; the array answers "what files exist".
+- `size_bytes` and `char_count` only mean something as a pair — 3 MB that yielded no characters is a scan awaiting OCR.
+- `raw(*)` needs a Small plan or above, and is explicitly unstable: its shape varies by portal platform.
+
+**Reading a document body — `attachments(extracted_text)`:**
+
+```python
+row = client.get_sled_opportunity(
+    opportunity_id,
+    shape="opportunity_id,attachments(name,size_bytes,extracted_text)",
+)
+```
+
+Needs a **Small plan or above**, and Tango API 4.25.1 or later (`client.get_version()` reports what you are calling). Three rules:
+
+- **You have to name it.** `attachments(*)` does not carry the body, and neither default shape names it — the API only resolves it for a caller who asked, so a default would make every detail fetch pay for a document nobody wanted to read.
+- **The key is absent, not null**, whenever the text is not being served to you: below Small (where it is withheld and named in `meta.upgrade_hints`), on a contested document, or where the text cannot be resolved. Use `attachment.get("extracted_text")`.
+- **A contested document never returns text**, at any plan — its stored bytes disagree with what the record advertised, so its text is not reliably that record's.
+
+Searching document text and reading it are separate things. `search=` matches inside attachment text on **every plan** and returns no fragment of it; `extracted_text` is a per-record read on Small and above. Buying the body does not change search.
+
+### list_sled_opportunity_revisions()
+
+List one solicitation's observed revision history.
+
+```python
+revisions = client.list_sled_opportunity_revisions(
+    "OPPORTUNITY_UUID",
+    kind=None,
+    source_declared=None,
+    observed_after=None,
+    observed_before=None,
+)
+```
+
+**Notes:**
+- `observed_at` is the scrape that saw the change, not the date the agency made it. No state portal emits amendment notices, so `kind` is Tango's inference from the diff on about 95% of revisions, resolution is that state's crawl cadence, and history starts when Tango began reading the jurisdiction.
+- Unlike the `revisions(*)` expand, this route serves `enrichment` rows — Tango's own detail fetch filling in coverage rather than an agency amendment. Pass `kind="enrichment"` for only those.
+- `changes` (the per-field before and after) needs a Small plan; it is left out of the default shape for that reason. `changed_fields` names what moved at every plan.
+
+### get_sled_coverage()
+
+Get the per-state coverage rollup. Takes no parameters; not shaped or paginated.
+
+```python
+coverage = client.get_sled_coverage()
+print(coverage["totals"])
+for row in coverage["states"]:
+    print(row["state"], row["total_count"], row["by_status"], row["last_change_observed_at"])
+```
+
+**Call this before treating a per-state count as market size.** A thin result for a state is at least as likely to be a portal Tango does not read as a quiet market, and that is the ambiguity this endpoint exists to resolve. Every state row carries all five status buckets whether or not they have rows, so a total and two buckets never invite subtraction.
+
+### list_sled_forecasts()
+
+List planned state procurements.
+
+```python
+forecasts = client.list_sled_forecasts(
+    state=None,
+    agency=None,
+    procurement_category=None,
+    procurement_method=None,
+    contract_number=None,
+    incumbent_name=None,
+    advertisement_after=None,
+    advertisement_before=None,
+    first_seen_after=None,
+    first_seen_before=None,
+    modified_after=None,
+    modified_before=None,
+    search=None,
+    ordering=None,
+)
+```
+
+**Notes:**
+- **Forecasts carry no liveness at all** — no deadline to have passed, so there is no `status` field, no `active` filter, and no open-only default. Currency is the caller's call from `estimated_advertisement_date`.
+- `estimated_advertisement_date` is the **start of the published quarter**, not a posting date. `estimated_advertisement_raw` keeps the portal's own words (`"Q3 (Jan.-March 2027)"`), and a large share of rows publish no quarter at all.
+- `estimated_value(min,max,raw)` is parsed from a free-text award band at serve time. **A band naming one number is a floor, so `max` is `None`** — never read a missing `max` as an unbounded ceiling. `raw` is always there to check the parse against.
+- `incumbent_name` is published text, not a resolved Tango entity.
+- `ordering`: `rank`, `estimated_advertisement_date`, `first_seen_at`, `last_seen_at`, `modified`.
+
+### get_sled_forecast()
+
+```python
+forecast = client.get_sled_forecast("FORECAST_UUID")
+```
+
+---
+
 ## Budget
 
 Federal account × fiscal year budget rollups, covering the full budget lifecycle (requested → enacted → apportioned → obligated → outlayed), pre-computed ratios and trends, the contract / assistance / unlinked breakdown, and request-vs-actual spend.
@@ -2012,6 +2210,11 @@ entity = client.get_entity("UEI_KEY", shape=ShapeConfig.ENTITIES_COMPREHENSIVE)
 | `VEHICLE_ORDERS_MINIMAL` | `list_vehicle_orders` | key, piid, award_date, recipient(display_name,uei), total_contract_value, obligated |
 | `ITDASHBOARD_INVESTMENTS_MINIMAL` | `list_itdashboard_investments` | Minimal IT Dashboard investment fields |
 | `ITDASHBOARD_INVESTMENTS_COMPREHENSIVE` | `get_itdashboard_investment` | Full investment fields: uii, agency_code, agency_name, bureau_code, bureau_name, investment_title, type_of_investment, part_of_it_portfolio, updated_time, url |
+| `SLED_OPPORTUNITIES_MINIMAL` | `list_sled_opportunities` | opportunity_id, solicitation_number, solicitation_type, title, state, jurisdiction, agency, status, status_reason, posted_date, response_deadline, source_url, has_documents, first_seen_at, last_change_seen_at (no `description` — detail-only on the API) |
+| `SLED_OPPORTUNITIES_COMPREHENSIVE` | `get_sled_opportunity` | Full solicitation with description, the raw portal status, both deadlines, bid opening, category codes, and organization / contact / meta / attachments / revisions |
+| `SLED_REVISIONS_MINIMAL` | `list_sled_opportunity_revisions` | observed_at, sequence, kind, changed_fields, source_declared (omits `changes`, which needs a Small plan) |
+| `SLED_FORECASTS_MINIMAL` | `list_sled_forecasts` | forecast_id, state, agency, title, estimated_advertisement_date, estimated_advertisement_raw, procurement_category, procurement_method, contract_number, incumbent_name, source_url, estimated_value(*) |
+| `SLED_FORECASTS_COMPREHENSIVE` | `get_sled_forecast` | Full forecast with description, contract_term, mbe_dbe_goal, delivery_location, and organization / contact / estimated_value |
 
 All predefined shapes are validated at SDK release time (see [Developer Guide](DEVELOPERS.md#sdk-conformance-maintainers)). For custom shapes, see the [Shaping Guide](SHAPES.md).
 

{tango_python-1.5.1 → tango_python-1.6.0}/docs/WEBHOOKS.md

@@ -87,6 +87,7 @@ tango webhooks list-event-types
 # alerts.exclusion.match     SAM.gov exclusion matched a saved alert
 # alerts.dibbs_rfq.match     DLA DIBBS RFQ matched a saved alert
 # alerts.dibbs_rfp.match     DLA DIBBS RFP matched a saved alert
+# alerts.sled_opportunity.match  State/local/education solicitation matched a saved alert
 ```
 
 This list is served by the API, so it is always current — the SDK does not hardcode
@@ -97,11 +98,20 @@ Two things that surprise people:
 
 - **DIBBS awards are not alertable.** There is no `alerts.dibbs_award.match`;
   only RFQs and RFPs emit alerts.
-- **Nothing fires when a record merely lapses.** An exclusion reaching its
-  termination date, or an RFQ/RFP passing its close date, emits no event.
-  Alerts fire on a record matching your saved search, not on the passage of
-  time. Poll with `list_exclusions(active=...)` / `list_dibbs_rfqs(open=...)`
-  if you need to observe expiry.
+- **Nothing fires when a record merely lapses — except SLED.** An exclusion
+  reaching its termination date, or an RFQ/RFP passing its close date, emits no
+  event: open/closed and in-force are derived at query time, so no stored row
+  changes. Poll with `list_exclusions(active=...)` /
+  `list_dibbs_rfqs(open=...)` if you need to observe expiry.
+
+  `sled_opportunity` is the exception, and the only one. A SLED solicitation's
+  liveness is a stored `status` column that Tango recomputes every fifteen
+  minutes rather than deriving per request, so a deadline passing **is** a write
+  and `alerts.sled_opportunity.match` can follow it. There is no
+  `sled_forecast` query type — a forecast has no deadline, so nothing
+  transitions — and SLED revisions and attachments are not separately
+  alertable: subscribe to `sled_opportunity` and filter on
+  `change_seen_after` or `revision_kind`.
 
 ### 2. See what a payload looks like
 

{tango_python-1.5.1 → tango_python-1.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tango-python"
-version = "1.5.1"
+version = "1.6.0"
 description = "Python SDK for the Tango API"
 readme = "README.md"
 requires-python = ">=3.12"

{tango_python-1.5.1 → tango_python-1.6.0}/scripts/check_filter_shape_conformance.py

@@ -74,6 +74,8 @@ RESOURCE_TO_METHOD: dict[str, str | None] = {
     "exclusions": "list_exclusions",
     "sbir/topics": "list_sbir_topics",
     "sbir/solicitations": "list_sbir_solicitations",
+    "sled/opportunities": "list_sled_opportunities",
+    "sled/forecasts": "list_sled_forecasts",
     "protests": "list_protests",
     "offices": "list_offices",
     "psc": "list_psc",

{tango_python-1.5.1 → tango_python-1.6.0}/scripts/check_shape_coverage.py

@@ -79,6 +79,8 @@ RESOURCE_TO_MODEL: dict[str, str] = {
     "exclusions": "Exclusion",
     "sbir/topics": "SbirTopic",
     "sbir/solicitations": "SbirSolicitation",
+    "sled/opportunities": "SledOpportunity",
+    "sled/forecasts": "SledForecast",
     "mas_sins": "MasSin",
     "events": "Event",
     "news": "News",

{tango_python-1.5.1 → tango_python-1.6.0}/tango/__init__.py

@@ -24,6 +24,9 @@ from .models import (
     SbirTopic,
     SearchFilters,
     ShapeConfig,
+    SledForecast,
+    SledOpportunity,
+    SledOpportunityRevision,
     ValidateResult,
     Vehicle,
     VehicleMetrics,
@@ -50,7 +53,7 @@ from .webhooks import (
 )
 from .webhooks.receiver import Delivery, WebhookReceiver
 
-__version__ = "1.5.1"
+__version__ = "1.6.0"
 __all__ = [
     "TangoClient",
     "TangoAPIError",
@@ -73,6 +76,9 @@ __all__ = [
     "PaginatedResponse",
     "SearchFilters",
     "ShapeConfig",
+    "SledForecast",
+    "SledOpportunity",
+    "SledOpportunityRevision",
     "ValidateResult",
     "Vehicle",
     "VehicleMetrics",