@saibolla/ada 0.1.2

package/skills/usfiscaldata/references/parameters.md

@@ -0,0 +1,155 @@
+# Query Parameters — U.S. Treasury Fiscal Data API
+
+All parameters are optional. Combine them with `&` in the URL query string.
+
+## `fields=` — Select Columns
+
+Returns only the specified fields. Accepts a comma-separated list of field names.
+
+```
+?fields=record_date,tot_pub_debt_out_amt
+?fields=country_currency_desc,exchange_rate,record_date
+```
+
+- If omitted, all fields are returned
+- Invalid field names cause an error
+- Omitting some fields can trigger **automatic aggregation** (see below)
+
+### Aggregation / Auto-Sum
+
+When the `fields=` parameter excludes some non-numeric fields, the API automatically groups by the remaining fields and sums numeric values.
+
+```python
+# Returns sum of transaction amounts grouped by record_date and transaction_type
+params = {
+    "fields": "record_date,transaction_type,transaction_today_amt"
+}
+```
+
+## `filter=` — Filter Records
+
+Narrow results by field values. Multiple field filters are **comma-separated in a single `filter=` parameter**.
+
+### Filter Syntax
+
+```
+filter=<field>:<operator>:<value>
+filter=<field>:<operator>:<value>,<field>:<operator>:<value>
+```
+
+### Operators
+
+| Operator | Meaning | Example |
+|----------|---------|---------|
+| `eq` | Equal to | `filter=record_date:eq:2024-03-31` |
+| `lt` | Less than | `filter=exchange_rate:lt:1.5` |
+| `lte` | Less than or equal | `filter=record_date:lte:2024-12-31` |
+| `gt` | Greater than | `filter=record_fiscal_year:gt:2010` |
+| `gte` | Greater than or equal | `filter=record_date:gte:2024-01-01` |
+| `in` | Contained in set | `filter=country_currency_desc:in:(Canada-Dollar,Mexico-Peso)` |
+
+### Date Filters
+
+Use `YYYY-MM-DD` format for dates:
+
+```
+filter=record_date:gte:2024-01-01
+filter=record_date:gte:2023-01-01,record_date:lte:2023-12-31
+```
+
+### Multi-Field Filters
+
+```
+filter=country_currency_desc:in:(Canada-Dollar,Mexico-Peso),record_date:gte:2024-01-01
+```
+
+### Common Filter Fields
+
+Most endpoints have these standard date fields:
+- `record_date` — The date of the record (YYYY-MM-DD)
+- `record_fiscal_year` — Fiscal year (e.g., `2024`)
+- `record_fiscal_quarter` — Fiscal quarter (1-4)
+- `record_calendar_year` — Calendar year
+- `record_calendar_month` — Calendar month (01-12)
+
+## `sort=` — Sort Results
+
+Sort by one or more fields. Prefix `-` for descending order.
+
+```
+?sort=-record_date           # Most recent first
+?sort=record_date            # Oldest first
+?sort=-record_fiscal_year,-record_fiscal_quarter  # Nested sort
+```
+
+**Default:** Sorted by the first column (usually `record_date` ascending).
+
+## `format=` — Output Format
+
+```
+?format=json    # Default
+?format=csv     # Comma-separated values
+?format=xml     # XML
+```
+
+When using CSV or XML format, the response is the raw file content rather than JSON.
+
+## `page[size]=` and `page[number]=` — Pagination
+
+Controls how many records per page and which page to return.
+
+```
+?page[size]=100&page[number]=1    # Default (100 records, page 1)
+?page[size]=10000                  # Large page to reduce requests
+?page[number]=5&page[size]=50     # 50 records starting at page 5
+```
+
+- Default page size: **100**
+- Default page number: **1**
+- Use `meta.total-pages` in the response to know how many pages exist
+- Use `meta.total-count` for total record count
+
+### Fetch All Records
+
+```python
+import requests
+import pandas as pd
+
+def fetch_all(endpoint, params=None):
+    """Fetch all pages and return as DataFrame."""
+    params = dict(params or {})
+    params["page[size]"] = 10000
+    params["page[number]"] = 1
+    
+    base = "https://api.fiscaldata.treasury.gov/services/api/fiscal_service"
+    all_data = []
+    
+    while True:
+        resp = requests.get(f"{base}{endpoint}", params=params)
+        result = resp.json()
+        all_data.extend(result["data"])
+        
+        meta = result["meta"]
+        if params["page[number]"] >= meta["total-pages"]:
+            break
+        params["page[number]"] += 1
+    
+    return pd.DataFrame(all_data)
+```
+
+## Combining Parameters
+
+```python
+params = {
+    "fields": "country_currency_desc,exchange_rate,record_date",
+    "filter": "country_currency_desc:in:(Canada-Dollar,Euro),record_date:gte:2020-01-01",
+    "sort": "-record_date",
+    "format": "json",
+    "page[size]": 100,
+    "page[number]": 1
+}
+resp = requests.get(
+    "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v1/accounting/od/rates_of_exchange",
+    params=params
+)
+```

package/skills/usfiscaldata/references/response-format.md

@@ -0,0 +1,176 @@
+# Response Format — U.S. Treasury Fiscal Data API
+
+## Response Structure (JSON)
+
+```json
+{
+  "data": [
+    {
+      "record_date": "2024-03-31",
+      "tot_pub_debt_out_amt": "34589629941.12"
+    }
+  ],
+  "meta": {
+    "count": 100,
+    "labels": {
+      "record_date": "Record Date",
+      "tot_pub_debt_out_amt": "Total Public Debt Outstanding"
+    },
+    "dataTypes": {
+      "record_date": "DATE",
+      "tot_pub_debt_out_amt": "CURRENCY"
+    },
+    "dataFormats": {
+      "record_date": "YYYY-MM-DD",
+      "tot_pub_debt_out_amt": "10.2"
+    },
+    "total-count": 3790,
+    "total-pages": 38
+  },
+  "links": {
+    "self": "&page%5Bnumber%5D=1&page%5Bsize%5D=100",
+    "first": "&page%5Bnumber%5D=1&page%5Bsize%5D=100",
+    "prev": null,
+    "next": "&page%5Bnumber%5D=2&page%5Bsize%5D=100",
+    "last": "&page%5Bnumber%5D=38&page%5Bsize%5D=100"
+  }
+}
+```
+
+## `meta` Object
+
+| Field | Description |
+|-------|-------------|
+| `count` | Number of records in this response page |
+| `total-count` | Total records matching the query (all pages) |
+| `total-pages` | Total pages available at current page size |
+| `labels` | Human-readable column labels |
+| `dataTypes` | Logical data type: `STRING`, `NUMBER`, `DATE`, `CURRENCY`, `INTEGER`, `PERCENTAGE` |
+| `dataFormats` | Format hints: `YYYY-MM-DD`, `10.2` (10 digits, 2 decimal), `String` |
+
+## `links` Object
+
+Use the `links` object to navigate pagination programmatically:
+
+| Field | Value |
+|-------|-------|
+| `self` | Current page query params |
+| `first` | First page |
+| `prev` | Previous page (null if on first page) |
+| `next` | Next page (null if on last page) |
+| `last` | Last page |
+
+## `data` Object
+
+Array of row objects. All values are **strings**, regardless of logical type.
+
+## Response Codes
+
+| Code | Meaning |
+|------|---------|
+| 200 | OK — successful GET |
+| 304 | Not Modified — cached response |
+| 400 | Bad Request — malformed URL or invalid parameter |
+| 403 | Forbidden — invalid API key (N/A; no key required) |
+| 404 | Not Found — endpoint does not exist |
+| 405 | Method Not Allowed — non-GET request |
+| 429 | Too Many Requests — rate limited |
+| 500 | Internal Server Error |
+
+## Error Object
+
+When an error occurs, the response contains an error object instead of `data`:
+
+```json
+{
+  "error": "Invalid Query Param",
+  "message": "Invalid query parameter 'sorts' with value '[-record_date]'. For more information please see the documentation."
+}
+```
+
+```python
+resp = requests.get(url, params=params)
+result = resp.json()
+
+if "error" in result:
+    print(f"API Error: {result['error']}")
+    print(f"Message: {result['message']}")
+elif resp.status_code != 200:
+    print(f"HTTP {resp.status_code}: {resp.text}")
+else:
+    data = result["data"]
+```
+
+## Common Error Causes
+
+- Invalid field name in `fields=` parameter
+- Invalid filter operator (use `eq`, `gte`, `lte`, `gt`, `lt`, `in`)
+- Wrong date format (must be `YYYY-MM-DD`)
+- Accessing a v2 endpoint with `/v1/` in the URL
+- `sort` field not available in the endpoint
+
+## Parsing Responses
+
+```python
+import requests
+import pandas as pd
+
+def api_to_dataframe(endpoint, params=None):
+    """Fetch API data and return a typed DataFrame."""
+    base = "https://api.fiscaldata.treasury.gov/services/api/fiscal_service"
+    resp = requests.get(f"{base}{endpoint}", params=params)
+    resp.raise_for_status()
+    result = resp.json()
+    
+    df = pd.DataFrame(result["data"])
+    meta = result["meta"]
+    
+    # Apply type conversions using metadata
+    for col, dtype in meta["dataTypes"].items():
+        if col not in df.columns:
+            continue
+        if dtype in ("NUMBER", "CURRENCY", "PERCENTAGE"):
+            df[col] = pd.to_numeric(df[col].replace("null", None), errors="coerce")
+        elif dtype == "DATE":
+            df[col] = pd.to_datetime(df[col].replace("null", None), errors="coerce")
+        elif dtype == "INTEGER":
+            df[col] = pd.to_numeric(df[col].replace("null", None), errors="coerce").astype("Int64")
+    
+    return df, meta
+
+# Usage
+df, meta = api_to_dataframe(
+    "/v2/accounting/od/debt_to_penny",
+    params={"sort": "-record_date", "page[size]": 30}
+)
+print(f"Total records available: {meta['total-count']}")
+print(df[["record_date", "tot_pub_debt_out_amt"]].head())
+```
+
+## CSV Format Response
+
+When `format=csv` is specified, the response body is plain CSV text (not JSON):
+
+```python
+import io
+
+resp = requests.get(
+    "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_to_penny",
+    params={"format": "csv", "sort": "-record_date", "page[size]": 100}
+)
+df = pd.read_csv(io.StringIO(resp.text))
+```
+
+## XML Format Response
+
+When `format=xml` is specified, the response body is XML:
+
+```python
+import xml.etree.ElementTree as ET
+
+resp = requests.get(
+    "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_to_penny",
+    params={"format": "xml", "page[size]": 10}
+)
+root = ET.fromstring(resp.text)
+```