seattle-open-data 0.1.0__py3-none-any.whl

seattle_open_data/__init__.py

@@ -0,0 +1,5 @@
+"""Agent-friendly MCP server for Seattle Open Data."""
+
+from importlib.metadata import version
+
+__version__ = version("seattle-open-data")

seattle_open_data/constants.py

@@ -0,0 +1,129 @@
+"""Seattle portal facts (docs/design.md: Scope).
+
+Extract a `Portal` type only when a second portal arrives.
+"""
+
+from __future__ import annotations
+
+from zoneinfo import ZoneInfo
+
+SERVER_NAME = "seattle-open-data"
+TOOL_PREFIX = "seattle_data_"
+URI_SCHEME = "seattle-data"
+
+PUBLIC_HOST = "data.seattle.gov"
+#: The Discovery API indexes Seattle under this name; `domains=data.seattle.gov` returns nothing.
+CATALOG_DOMAIN = "cos-data.seattle.gov"
+DISCOVERY_API = "https://api.us.socrata.com/api/catalog/v1"
+
+SEATTLE_TZ = ZoneInfo("America/Los_Angeles")
+
+DATASET_ID_PATTERN = r"^[a-z0-9]{4}-[a-z0-9]{4}$"
+
+SEARCH_PAGE_SIZE_MAX = 50
+QUERY_PAGE_SIZE_MAX = 500
+QUERY_LOGICAL_CAP = 10_000
+QUERY_TEXT_MAX_BYTES = 4096
+SAMPLE_ROWS_MAX = 5
+
+RESULT_BYTE_BUDGET = 24 * 1024
+TOOLS_LIST_BYTE_BUDGET = 24 * 1024
+
+CACHE_TTL_SECONDS = 3600
+
+INSTRUCTIONS_SENTINEL = "END SEATTLE OPEN DATA INSTRUCTIONS"
+
+UPSTREAM_TIMEOUT_SECONDS = 30.0
+DESCRIBE_AGGREGATE_TIMEOUT_SECONDS = 10.0
+UPSTREAM_MAX_BYTES = 8 * 1024 * 1024
+CURSOR_TTL_SECONDS = 3600
+
+#: Values publishers use instead of null in text place fields (docs/upstream-facts.md).
+PLACEHOLDER_VALUES = frozenset({"-", "UNKNOWN", "NULL", "OOJ", "FK ERROR", "X", "0", ""})
+
+#: Computed-region layers seen on Seattle datasets; label columns and dates verified 2026-10-15.
+REGION_LAYERS: dict[str, dict[str, str]] = {
+    "ru88-fbhk": {
+        "kind": "neighborhood",
+        "label_column": "name",
+        "vintage": "SPD Micro Community Policing Plan Areas, updated 2016-03-03",
+        "reliability": "ok",
+    },
+    "kuhn-3gp2": {
+        "kind": "beat",
+        "label_column": "name",
+        "vintage": "SPD Beats, updated 2015-07-17 (51 beats; current SPD beats differ)",
+        "reliability": "partial",
+        "reason": "2015 beat boundaries; current SPD beats differ.",
+    },
+    "q256-3sug": {
+        "kind": "zip",
+        "label_column": "zcta5ce10",
+        "vintage": "2010 ZIP Code Tabulation Areas (national), updated 2015-02-19",
+        "reliability": "ok",
+    },
+    "cyqu-gs94": {
+        "kind": "council_district",
+        "label_column": "c_district",
+        "vintage": "City Council Districts, updated 2015-07-20 (predates 2022 redistricting)",
+        "reliability": "unreliable",
+        "reason": "Mostly null, only districts 1-3 appear, and the boundaries predate 2022.",
+    },
+    "2day-rhn5": {
+        "kind": "census_tract",
+        "label_column": "name10",
+        "vintage": "2010 Census Tracts, updated 2015-05-16",
+        "reliability": "unreliable",
+        "reason": "Mostly null on Seattle datasets; 2010 tracts.",
+    },
+}
+
+#: Text place fields per dataset, with reliability from the 2026-10-15 probe
+#: (docs/upstream-facts.md).
+PLACE_FIELDS: dict[str, dict[str, dict[str, str]]] = {
+    "33kz-ixgy": {
+        "dispatch_neighborhood": {"kind": "neighborhood", "reliability": "ok"},
+        "dispatch_precinct": {"kind": "precinct", "reliability": "ok"},
+        "dispatch_sector": {"kind": "sector", "reliability": "ok"},
+        "dispatch_beat": {"kind": "beat", "reliability": "ok"},
+    },
+    "tazs-3rd5": {
+        "neighborhood": {
+            "kind": "neighborhood",
+            "reliability": "partial",
+            "reason": "Placeholder ('-') for nearly all offenses before 2017; 1-4% missing since. "
+            "Do not use for 2008-2016.",
+        },
+        "precinct": {"kind": "precinct", "reliability": "ok"},
+        "sector": {"kind": "sector", "reliability": "ok"},
+        "beat": {"kind": "beat", "reliability": "ok"},
+    },
+    "ppi5-g2bj": {
+        "precinct": {"kind": "precinct", "reliability": "ok"},
+        "sector": {"kind": "sector", "reliability": "ok"},
+        "beat": {"kind": "beat", "reliability": "ok"},
+    },
+    "76t5-zqzr": {
+        "originalzip": {"kind": "zip", "reliability": "ok"},
+    },
+}
+
+#: Timezone evidence per dataset column; absent means unknown, never assumed.
+TIME_EVIDENCE: dict[str, dict[str, dict[str, str]]] = {
+    "kzjm-xkqj": {
+        "datetime": {
+            "timezone": "America/Los_Angeles",
+            "evidence": "max(datetime) tracked Pacific wall-clock time when probed 2026-10-15.",
+        },
+    },
+}
+
+GEO_TYPES = frozenset({"point", "location"})
+TIME_TYPES = frozenset({"floating_timestamp", "calendar_date", "fixed_timestamp", "date"})
+
+#: Upper bound written into download_url; SODA2 accepted it when probed 2026-10-15.
+DOWNLOAD_LIMIT = 1_000_000_000
+URL_MAX_CHARS = 2048
+#: Whole-call deadlines, metadata fetch included; tool descriptions state these.
+QUERY_DEADLINE_SECONDS = 30.0
+DESCRIBE_DEADLINE_SECONDS = 30.0

seattle_open_data/core/arguments.py

@@ -0,0 +1,96 @@
+"""Cross-argument rules the JSON Schema cannot express portably (docs/design.md: Primitives).
+
+Single-field constraints (types, enums, ranges, patterns, empty strings) live in
+the published inputSchema; only combinations are checked here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from seattle_open_data.constants import QUERY_TEXT_MAX_BYTES
+from seattle_open_data.core import cursor as cursors
+from seattle_open_data.core.errors import ErrorCode, ErrorDetails, Repair, SeattleDataError
+
+CLAUSE_ARGS = ("select", "where", "group_by", "having", "order_by", "search_text", "near")
+
+
+def _provided(args: dict[str, Any]) -> list[str]:
+    return [name for name, value in args.items() if value is not None]
+
+
+def _reject(fields: list[str], reason: str, *, tool: str, repair: Repair | None = None) -> None:
+    details = (
+        ErrorDetails(field=fields[0], reason=reason)
+        if len(fields) == 1
+        else ErrorDetails(fields=fields, reason=reason)
+    )
+    raise SeattleDataError(
+        ErrorCode.INVALID_ARGUMENT,
+        f"Invalid argument combination for {tool}.",
+        details=details,
+        repair=repair,
+    )
+
+
+def check_continuation(args: dict[str, Any], *, allowed: set[str], tool: str) -> None:
+    if args.get("cursor") is None:
+        return
+    extra = sorted(set(_provided(args)) - allowed - {"cursor"})
+    if extra:
+        _reject(
+            extra,
+            "A cursor continues the original query; send only "
+            + ", ".join(sorted(allowed | {"cursor"}))
+            + ".",
+            tool=tool,
+        )
+
+
+def check_search(args: dict[str, Any]) -> None:
+    check_continuation(args, allowed={"detail", "page_size"}, tool="seattle_data_search_datasets")
+
+
+def check_query(args: dict[str, Any]) -> None:
+    tool = "seattle_data_query_dataset"
+    check_continuation(args, allowed={"dataset_id", "detail", "page_size"}, tool=tool)
+    if args.get("cursor") is not None:
+        return
+    mode = args.get("mode") or "clauses"
+    if mode == "soql":
+        if args.get("soql") is None:
+            _reject(["soql"], "mode='soql' requires soql.", tool=tool)
+        clauses = [name for name in CLAUSE_ARGS if args.get(name) is not None]
+        if clauses:
+            _reject(
+                clauses,
+                "mode='soql' runs soql verbatim; clause arguments are not allowed.",
+                tool=tool,
+            )
+        return
+    if args.get("soql") is not None:
+        _reject(["soql"], "soql requires mode='soql'.", tool=tool)
+    # Measured as a cursor stores the clauses, so the cap also bounds the cursor (≤ 6 KiB).
+    present = {n: _plain(args[n]) for n in CLAUSE_ARGS if args.get(n) is not None}
+    if len(cursors.dump(present)) > QUERY_TEXT_MAX_BYTES:
+        _reject(
+            list(present),
+            f"Clause arguments exceed {QUERY_TEXT_MAX_BYTES} bytes in total, measured as JSON.",
+            tool=tool,
+        )
+
+
+def check_reference(args: dict[str, Any]) -> None:
+    tool = "seattle_data_get_reference"
+    topic = args.get("topic") or "index"
+    if args.get("item_id") is not None and topic in ("index", "capabilities"):
+        _reject(
+            ["topic", "item_id"],
+            f"Topic '{topic}' has no items; item_id needs soql, errors, or guides.",
+            tool=tool,
+            repair=Repair(next_step="list_topics", tool=tool, arguments={}),
+        )
+
+
+def _plain(value: Any) -> Any:
+    return value.model_dump() if hasattr(value, "model_dump") else value

seattle_open_data/core/catalog.py

@@ -0,0 +1,217 @@
+"""Catalog search over the Socrata Discovery API (docs/design.md: tool 1)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+from urllib.parse import urlsplit, urlunsplit
+
+from seattle_open_data.constants import (
+    CATALOG_DOMAIN,
+    DISCOVERY_API,
+    PUBLIC_HOST,
+)
+from seattle_open_data.core import cursor as cursors
+from seattle_open_data.core.context import make_source
+from seattle_open_data.core.errors import Repair
+from seattle_open_data.core.guides import BY_DATASET
+from seattle_open_data.core.http import shape_error
+from seattle_open_data.core.models import DatasetSummary, Detail, Queryability, SearchResult
+from seattle_open_data.core.reference import topic_uri
+from seattle_open_data.core.text import clean, html_to_text
+
+if TYPE_CHECKING:
+    from seattle_open_data.core.http import SodaClient
+
+AssetScope = Literal["tabular", "all"]
+
+_SUPPORTED = frozenset({"dataset", "filter"})
+_EXTERNAL = frozenset({"federated_href", "href"})
+#: Views that render a parent dataset; search folds them into that parent.
+_FOLDED = frozenset({"map", "chart", "visualization", "calendar", "form"})
+
+_DEFAULT_PAGE_SIZE = 10
+#: Bounds cursor size; a duplicate can reappear only after this many results.
+_SEEN_CAP = 200
+_RESTART = Repair(next_step="restart_search", tool="seattle_data_search_datasets", arguments={})
+
+
+def _catalog_body(body: Any) -> dict[str, Any]:
+    """An unexpected catalog shape must not read as "no datasets match"."""
+    if (
+        not isinstance(body, dict)
+        or not isinstance(body.get("results"), list)
+        or not str(body.get("resultSetSize", "")).isdigit()
+    ):
+        raise shape_error("Expected a Discovery API result object.")
+    return body
+
+
+def queryability(asset_type: str) -> Queryability:
+    if asset_type in _SUPPORTED:
+        return "supported"
+    if asset_type in _EXTERNAL:
+        return "external"
+    if asset_type in {"file", "story", "measure"}:
+        return "unsupported"
+    return "unknown"
+
+
+def public_url(url: str | None) -> str | None:
+    """Catalog links can use the alias host; agents should see data.seattle.gov."""
+    if not url:
+        return None
+    parts = urlsplit(url)
+    if parts.netloc == CATALOG_DOMAIN:
+        parts = parts._replace(netloc=PUBLIC_HOST)
+    return urlunsplit(parts)
+
+
+async def search(
+    client: SodaClient,
+    *,
+    query: str | None,
+    asset_scope: AssetScope,
+    category: str | None,
+    page_size: int | None,
+    cursor: str | None,
+    detail: Detail,
+) -> SearchResult:
+    if cursor is not None:
+        state = cursors.decode(cursor, "search", restart=_RESTART)
+        query, asset_scope, category = state["q"], state["scope"], state["cat"]
+        offset = int(state["off"])
+        page_size = page_size or int(state.get("ps", _DEFAULT_PAGE_SIZE))
+        earlier = [str(i) for i in state.get("seen", [])]
+    else:
+        offset = 0
+        earlier = []
+    page_size = page_size or _DEFAULT_PAGE_SIZE
+
+    params: dict[str, Any] = {
+        "domains": CATALOG_DOMAIN,
+        "search_context": PUBLIC_HOST,
+        "limit": page_size,
+        "offset": offset,
+    }
+    if query:
+        params["q"] = query
+    else:
+        params["order"] = "page_views_total"
+    if category:
+        params["categories"] = category
+    if asset_scope == "tabular":
+        # Maps and charts are requested only to be folded into their parent datasets.
+        params["only"] = "dataset,filter,map,chart"
+
+    body = _catalog_body(await client.get_json(DISCOVERY_API, params))
+    results = body["results"]
+    total = int(body["resultSetSize"])
+
+    datasets = await _fold(client, results, detail, already=set(earlier))
+    next_offset = offset + len(results)
+    has_more = bool(results) and next_offset < total
+    next_cursor = (
+        cursors.encode(
+            "search",
+            {
+                "q": query,
+                "scope": asset_scope,
+                "cat": category,
+                "off": next_offset,
+                "ps": page_size,
+                # Folded map views can repeat a dataset from an earlier page; remember recent ids.
+                "seen": [*earlier, *(d.dataset_id for d in datasets)][-_SEEN_CAP:],
+            },
+        )
+        if has_more
+        else None
+    )
+    return SearchResult(
+        datasets=datasets,
+        has_more=has_more,
+        next_cursor=next_cursor,
+        source=make_source(retrieved=True),
+    )
+
+
+def _access_point(item: dict[str, Any]) -> str | None:
+    points = (item.get("metadata") or {}).get("access_points") or {}
+    url = next((str(u) for u in points.values() if str(u).startswith("https://")), None)
+    return url or public_url(item.get("link"))
+
+
+async def _fold(
+    client: SodaClient, results: list[Any], detail: Detail, *, already: set[str]
+) -> list[DatasetSummary]:
+    """Replace each map or chart match with its parent dataset, once, at its first rank.
+
+    `already` holds datasets emitted on earlier pages, which are not repeated.
+    """
+    slots: list[DatasetSummary | str] = []
+    for item in results:
+        resource = item.get("resource") or {}
+        if str(resource.get("type")) in _FOLDED:
+            parents = resource.get("parent_fxf") or []
+            if parents:
+                slots.append(str(parents[0]))
+        else:
+            slots.append(_summarize(item, detail))
+    # Seeding with this page's summaries lets a map ranked above its own parent keep that rank.
+    parents: dict[str, DatasetSummary] = {
+        s.dataset_id: s for s in slots if isinstance(s, DatasetSummary)
+    }
+    missing = sorted(
+        {s for s in slots if isinstance(s, str) and s not in parents and s not in already}
+    )
+    if missing:
+        body = await client.get_json(
+            DISCOVERY_API,
+            {
+                "domains": CATALOG_DOMAIN,
+                "search_context": PUBLIC_HOST,
+                "ids": missing,
+                "limit": len(missing),
+            },
+        )
+        for item in _catalog_body(body)["results"]:
+            summary = _summarize(item, detail)
+            parents[summary.dataset_id] = summary
+    out: list[DatasetSummary] = []
+    seen = set(already)
+    for slot in slots:
+        summary = parents.get(slot) if isinstance(slot, str) else slot
+        if summary is not None and summary.dataset_id not in seen:
+            seen.add(summary.dataset_id)
+            out.append(summary)
+    return out
+
+
+def _guide_uri(dataset_id: str, parents: list[str]) -> str | None:
+    guide = BY_DATASET.get(dataset_id) or next(
+        (BY_DATASET[p] for p in parents if p in BY_DATASET), None
+    )
+    return topic_uri("guides", guide.guide_id) if guide else None
+
+
+def _summarize(item: dict[str, Any], detail: Detail) -> DatasetSummary:
+    resource = item.get("resource") or {}
+    asset_type = str(resource.get("type") or "unknown")
+    dataset_id = str(resource.get("id", ""))
+    reach = queryability(asset_type)
+    parents = resource.get("parent_fxf") or []
+    classification = item.get("classification") or {}
+    return DatasetSummary(
+        dataset_id=dataset_id,
+        title=clean(resource.get("name"), limit=200) or dataset_id,
+        asset_type=asset_type,
+        queryability=reach,
+        portal_url=public_url(item.get("permalink")) or f"https://{PUBLIC_HOST}/d/{dataset_id}",
+        updated_at=resource.get("data_updated_at") or resource.get("updatedAt"),
+        derived_from=parents[0] if asset_type == "filter" and parents else None,
+        guide_uri=_guide_uri(dataset_id, parents),
+        external_url=_access_point(item) if reach == "external" else None,
+        category=clean(classification.get("domain_category")),
+        description=html_to_text(resource.get("description"), limit=1000)
+        if detail == "full"
+        else None,
+    )

seattle_open_data/core/context.py

@@ -0,0 +1,33 @@
+"""Per-call provenance: request id and Seattle wall-clock time."""
+
+from __future__ import annotations
+
+import uuid
+from contextvars import ContextVar
+from datetime import UTC, datetime
+
+from seattle_open_data.constants import SEATTLE_TZ
+from seattle_open_data.core.models import Source
+
+_request_id: ContextVar[str | None] = ContextVar("request_id", default=None)
+
+
+def new_request_id() -> str:
+    request_id = uuid.uuid4().hex[:16]
+    _request_id.set(request_id)
+    return request_id
+
+
+def current_request_id() -> str:
+    return _request_id.get() or new_request_id()
+
+
+def make_source(*, retrieved: bool = False) -> Source:
+    now = datetime.now(UTC)
+    return Source(
+        request_id=current_request_id(),
+        now_local=now.astimezone(SEATTLE_TZ).isoformat(timespec="seconds"),
+        retrieved_at=now.isoformat(timespec="seconds").replace("+00:00", "Z")
+        if retrieved
+        else None,
+    )

seattle_open_data/core/cursor.py

@@ -0,0 +1,91 @@
+"""Stateless, HMAC-signed cursors (docs/design.md: Query engine).
+
+The key lives in process memory only.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+import time
+from typing import Any
+
+from seattle_open_data.constants import CURSOR_TTL_SECONDS
+from seattle_open_data.core.errors import ErrorCode, ErrorDetails, Repair, SeattleDataError
+
+_KEY = secrets.token_bytes(32)
+_VERSION = 1
+
+
+def _b64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+
+
+def _unb64(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+def dump(data: Any) -> bytes:
+    """Compact UTF-8 JSON; non-ASCII stays raw so it costs its UTF-8 size, not `\\uXXXX`."""
+    return json.dumps(data, separators=(",", ":"), sort_keys=True, ensure_ascii=False).encode()
+
+
+def encode(kind: str, state: dict[str, Any]) -> str:
+    payload = dump({"v": _VERSION, "k": kind, "t": int(time.time()), "s": state})
+    signature = hmac.new(_KEY, payload, hashlib.sha256).digest()[:16]
+    return f"{_b64(payload)}.{_b64(signature)}"
+
+
+def decode(cursor: str, kind: str, *, restart: Repair) -> dict[str, Any]:
+    """Verify and unpack.
+
+    A bad signature is `cursor_expired`: a server restart rotates the in-memory key.
+    """
+    try:
+        payload_part, signature_part = cursor.split(".", 1)
+        payload = _unb64(payload_part)
+        signature = _unb64(signature_part)
+        data = json.loads(payload)
+    except (ValueError, json.JSONDecodeError) as exc:
+        raise _error(
+            ErrorCode.INVALID_CURSOR,
+            "The cursor is malformed.",
+            "It could not be decoded.",
+            restart,
+        ) from exc
+    expected = hmac.new(_KEY, payload, hashlib.sha256).digest()[:16]
+    if not hmac.compare_digest(signature, expected):
+        raise _error(
+            ErrorCode.CURSOR_EXPIRED,
+            "The cursor has expired or the server restarted.",
+            "Its signature does not match: cursors do not survive a server restart.",
+            restart,
+        )
+    if data.get("v") != _VERSION:
+        raise _error(
+            ErrorCode.INVALID_CURSOR,
+            "The cursor uses an unsupported format.",
+            "It was issued by a different server version.",
+            restart,
+        )
+    if data.get("k") != kind:
+        raise _error(
+            ErrorCode.INVALID_CURSOR,
+            "The cursor belongs to a different tool.",
+            "Use a cursor only with the tool that returned it.",
+            restart,
+        )
+    if time.time() - int(data.get("t", 0)) > CURSOR_TTL_SECONDS:
+        raise _error(
+            ErrorCode.CURSOR_EXPIRED, "The cursor has expired.", "Cursors last 1 hour.", restart
+        )
+    return data["s"]
+
+
+def _error(code: ErrorCode, message: str, reason: str, restart: Repair) -> SeattleDataError:
+    return SeattleDataError(
+        code, message, details=ErrorDetails(field="cursor", reason=reason), repair=restart
+    )