@yottagraph-app/data-model-skill 0.0.23 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottagraph-app/data-model-skill",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "description": "Data model skill documentation for AI agents - entity types, properties, and schemas from Lovelace fetch sources",
   "repository": {
     "type": "git",

package/skill/lda/DATA_DICTIONARY.md

@@ -0,0 +1,101 @@
+# Data Dictionary: LDA (Lobbying Disclosure Act)
+
+Last updated: 2026-05-04
+
+## Source Overview
+
+Lobbying Disclosure Act filings (registrations, quarterly activity, etc.) from the **unified LDA.gov REST API**. The streamer polls `GET /api/v1/filings/`, stores raw JSON pages, and emits v2 `FetchMessage` records.
+
+| Item | Value |
+|------|--------|
+| Pipeline / stream | Configured in `streams.yaml` (see deployment) |
+| `Record.Source` | `lda` |
+
+Anonymous access is rate-limited; optional API token improves throughput.
+
+---
+
+## Entity Types
+
+### `lda_filing`
+
+One disclosure identified by API `filing_uuid`.
+
+- **Subject name:** `filing_uuid` (stable, unique per disclosure).
+- **Strong id:** `lda_filing_uuid` on the filing subject.
+- **Resolver:** `NOT_MERGEABLE` passive filing entity.
+- **Timestamp:** Parsed from `dt_posted` only (no wall-clock fallback). If `dt_posted` is missing or invalid, the filing is not atomized.
+
+### `organization`
+
+Either the **registrant** (lobbying firm) or **client** on a filing.
+
+- **Subject name:** API `name` (legal / display name).
+- **Strong ids:** `lda_registrant_id` (registrant rows) or `lda_client_internal_id` (client rows).
+- **Role:** Property `lda_party_role` = `registrant` or `client` on the organization **record** (not on the filing).
+- **Resolver:** Named-entity info is `MERGEABLE` (resolver / recordeval ER search) while retaining LDA **strong ids**; flavor-level resolver info remains `NOT_MERGEABLE` per passive schema.
+- **Snippets:** Formatted **address** only when present (no LDA filing UUID prefix).
+
+### `location`
+
+Geographic label derived from registrant or client address fields for `is_located_at` edges.
+
+- **Name:** Typically `City, State` or `City, State, Country`; when city is absent, `State, Country` or state-only per atomizer rules.
+- **Resolver:** `MERGEABLE` named entity (no strong id), for soft clustering with other sources.
+
+---
+
+## Properties
+
+### Filing
+
+| Property | Description |
+|----------|-------------|
+| `lda_filing_uuid` | API `filing_uuid`. |
+| `lda_filing_type` | Machine code (`filing_type`), e.g. `RR`, `Q1`. |
+| `lda_filing_type_display` | Human label (`filing_type_display`). |
+| `lda_filing_year` | Reporting year (float in schema). |
+| `lda_filing_period_display` | Period label, e.g. quarter. |
+| `lda_income` | Income string when present. |
+| `lda_expenses` | Expenses string when present. |
+| `lda_dt_posted` | Raw ISO `dt_posted` from API. |
+| `lda_filing_document_url` | Public document URL. |
+| `lda_posted_by_name` | Poster name when present. |
+| `lda_lobbying_causes` | Repeated **once per** `lobbying_activities[]` row (`CODE (Display)`). Same pattern as patent **`cpc_code`**: narrative text is quad attribute **`lda_lobbying_cause_description`** on that atom (API `description` field). **Only on filing**; omitted if activities array is empty. |
+
+### Organization
+
+| Property | Description |
+|----------|-------------|
+| `lda_party_role` | `registrant` or `client`. |
+| `lda_registrant_id` | Registrant API id as string. |
+| `lda_client_internal_id` | Client row id (`client.id`) as string. |
+| `address` | Single-line formatted address (street/city/state/zip + country). |
+
+---
+
+## Entity Relationships
+
+```
+lda_filing  ──[lda_registrant]──→  organization (registrant)
+lda_filing  ──[lda_client]──────→  organization (client)
+
+organization  ──[is_located_at]──→  location
+```
+
+- **`lda_registrant` / `lda_client`:** Target atoms on the **`lda_filing`** record point at the same organization identities emitted as separate **organization** records for that page (strong ids + properties).
+- **`is_located_at`:** On each **organization** record when the atomizer can derive a location name from city/state/country rules.
+
+---
+
+## Records Per Filing
+
+For a typical filing with registrant and client, atomization yields **up to three** records: one filing, one registrant organization, one client organization. Either org may be omitted if required API fields are missing.
+
+---
+
+## Citations
+
+Primary citation text is the filing `url` when present; otherwise a synthetic label referencing `filing_uuid`.
+
+---

package/skill/lda/schema.yaml

@@ -0,0 +1,209 @@
+# Dataset schema for U.S. Lobbying Disclosure Act (LDA) filings from the
+# Congress/Senate unified REST API (https://lda.gov/api/).
+#
+# Atomizer output uses Record.Source "lda". Filings are passive filing entities
+# keyed by lda_filing_uuid; registrant and client are organization entities linked
+# from the filing via lda_registrant / lda_client relationships.
+name: "lda"
+description: "Lobbying Disclosure Act LD-1/LD-2 filings (registrations and quarterly activity) from the LDA.gov REST API"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - name: "lda_filing"
+    description: "A lobbying disclosure (registration or quarterly activity) identified by filing_uuid"
+    display_name: "LDA filing"
+    mergeability: not_mergeable
+    strong_id_properties: ["lda_filing_uuid"]
+    passive: true
+
+  - name: "organization"
+    description: "A particular business, institution, or organization such as a corporation, university, government agency, or non-profit"
+    display_name: "Organization"
+    mergeability: not_mergeable
+    strong_id_properties: ["lda_registrant_id", "lda_client_internal_id"]
+    passive: true
+
+  - name: "location"
+    description: "A specific named geographic location such as a city, country, region, or landmark"
+    display_name: "Location"
+    mergeability: not_mergeable
+    examples: ["Washington, DC, US", "Arlington, VA, US"]
+    passive: true
+
+properties:
+  - name: "lda_filing_uuid"
+    type: string
+    description: "Stable UUID of the filing in the LDA REST API"
+    display_name: "LDA Filing UUID"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_filing_type"
+    type: string
+    description: "Machine filing type code (e.g. RR, Q1) from the API filing_type field; human label is attribute lda_filing_type_display when present"
+    display_name: "LDA Filing Type Code"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_filing_year"
+    type: float
+    description: "Reporting year associated with the filing"
+    display_name: "LDA Filing Year"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_filing_period"
+    type: string
+    description: "Reporting period code from filing_period (string or number in JSON); human label is attribute lda_filing_period_display when present"
+    display_name: "LDA Filing Period Code"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_income"
+    type: string
+    description: "Income amount reported on the filing when present (API decimal as string)"
+    display_name: "LDA Reported Income"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_expenses"
+    type: string
+    description: "Expenses amount reported on the filing when present (API decimal as string)"
+    display_name: "LDA Reported Expenses"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_dt_posted"
+    type: string
+    description: "Date and time the filing was posted (dt_posted), ISO-8601 string from the API"
+    display_name: "LDA Date Posted"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_filing_document_url"
+    type: string
+    description: "Public URL of the filing document (HTML/PDF) from filing_document_url"
+    display_name: "LDA Filing Document URL"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_posted_by_name"
+    type: string
+    description: "Name of the individual who posted the filing (posted_by_name)"
+    display_name: "LDA Posted By"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    passive: true
+
+  - name: "lda_lobbying_causes"
+    type: string
+    description: >-
+      One atom per lobbying_activities row: "CODE (Display)" from general_issue_code and
+      general_issue_code_display. Narrative text is attribute lda_lobbying_cause_description on the
+      same atom when present (same pattern as patent cpc_code + cpc_description).
+    display_name: "LDA Lobbying Causes"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    examples:
+      - "BUD (Budget/Appropriations)"
+      - "HCR (Health Issues)"
+    passive: true
+
+  - name: "lda_party_role"
+    type: string
+    description: "Whether this organization row is the lobbying registrant or the client on the linked LDA filing"
+    display_name: "LDA Party Role"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["registrant", "client"]
+    passive: true
+
+  - name: "lda_registrant_id"
+    type: string
+    description: "Stable LDA API registrant id (registrant.id) as a string, for entity resolution"
+    display_name: "LDA Registrant ID"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "lda_client_internal_id"
+    type: string
+    description: "Stable LDA API internal client row id (client.id) as a string, for entity resolution"
+    display_name: "LDA Client Internal ID"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "address"
+    type: string
+    description: "Physical street address of the entity"
+    display_name: "Address"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+relationships:
+  - name: "lda_registrant"
+    description: "The lobbying registrant firm that filed this LDA disclosure"
+    display_name: "LDA Registrant"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "lda_client"
+    description: "The client organization on whose behalf lobbying is reported for this LDA filing"
+    display_name: "LDA Client"
+    mergeability: not_mergeable
+    domain_flavors: ["lda_filing"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "is_located_at"
+    description: "An entity is located at, operates in, resides in, is headquartered in, was born in, visits, or died in a location"
+    display_name: "Located At"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["location"]
+    passive: true
+
+attributes:
+  - property: "lda_filing_period"
+    name: "lda_filing_period_display"
+    type: string
+    description: "Human-readable reporting period label from filing_period_display on the same atom as the period code"
+    display_name: "LDA Filing Period"
+    mergeability: not_mergeable
+
+  - property: "lda_filing_type"
+    name: "lda_filing_type_display"
+    type: string
+    description: "Human-readable filing type label from filing_type_display on the same atom as the type code"
+    display_name: "LDA Filing Type"
+    mergeability: not_mergeable
+
+# Narrative for one lobbying issue row. Stored as a quad attribute on each lda_lobbying_causes atom.
+  - property: "lda_lobbying_causes"
+    name: "lda_lobbying_cause_description"
+    type: string
+    description: >-
+      lobbying_activities[].description for that row (optional trailing posted timestamp stripped).
+      Omitted as an attribute when the description is empty.
+    display_name: "LDA Lobbying Cause Description"
+    mergeability: not_mergeable
+
+events: []