@yottagraph-app/data-model-skill 0.0.31 → 0.0.33

package/package.json

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

package/skill/companieshouse/DATA_DICTIONARY.md

@@ -0,0 +1,145 @@
+# Data Dictionary: Companies House Accounts
+
+## Source Overview
+
+UK Companies House Accounts Bulk Data Product — daily ZIP files containing iXBRL (.html) and XBRL (.xml) annual accounts filings submitted by UK-registered companies.
+
+- Data source: `https://download.companieshouse.gov.uk/en_accountsdata.html`
+- Publisher: Companies House (UK government registrar)
+- Cadence: daily bulk ZIPs, each containing filings processed that day
+- Coverage: all companies filing annual accounts with Companies House (primarily small and micro companies using iXBRL templates; large companies with bespoke filings may have sparse financial data)
+
+Financial figures are extracted from iXBRL/XBRL taxonomies (UK GAAP, FRS 102, IFRS). Not all companies report all fields — micro accounts may only include balance sheet totals, while full accounts include profit/loss and employee data. All monetary values are in GBP (£).
+
+| Pipeline | `Record.Source` |
+|----------|----------------|
+| Accounts filings | `companieshouse` |
+
+---
+
+## Entity Types
+
+### `organization`
+
+A UK-registered company that has filed annual accounts with Companies House.
+
+- Primary key: `companies_house_number` (8-character alphanumeric, e.g. `"00000006"`, `"SC123456"`)
+- Entity resolver: named entity, mergeable. Strong ID = `companies_house_number`. Disambiguation via company name and registered address.
+
+### `companieshouse::accounts_filing`
+
+An annual accounts filing document submitted to Companies House, identified by the combination of company number and balance sheet date.
+
+- Primary key: `filing_id` (format: `"{company_number}-{YYYY-MM-DD}"`)
+- Entity resolver: named entity, not mergeable. Strong ID = `filing_id`.
+
+---
+
+## Properties
+
+### Organization Properties
+
+#### Identity
+
+* `companies_house_number`
+  * Definition: Companies House registered company number uniquely identifying a UK company.
+  * Examples: `"00000006"`, `"12345678"`, `"SC123456"`
+  * Derivation: extracted from the `UKCompaniesHouseRegisteredNumber` or `EntityRegistrationNumber` XBRL concept in the filing, or parsed from the bulk data filename pattern `Prod{NNN}_{NNN}_{CCCCCCCC}_{YYYYMMDD}` where `CCCCCCCC` is the company number.
+
+* `registered_address`
+  * Definition: registered office address of the company as reported in the accounts filing.
+  * Examples: `"10 Downing Street, London, SW1A 2AA"`
+  * Derivation: composed from XBRL address concepts `AddressLine1`, `AddressLine2`, `AddressLine3`, `PrincipalLocation-CityOrTown`, `CountyRegion`, and `PostalCodeZip` (from the `bus:` namespace). Empty components are omitted; the result is a comma-separated string.
+
+### Accounts Filing Properties
+
+#### Filing Metadata
+
+* `filing_id`
+  * Definition: unique identifier for the accounts filing, composed of the company number and balance sheet date.
+  * Examples: `"12345678-2024-12-31"`, `"SC123456-2025-03-31"`
+  * Derivation: constructed as `"{company_number}-{balance_sheet_date}"`. The balance sheet date is extracted from the bulk data filename.
+
+* `balance_sheet_date`
+  * Definition: balance sheet date of the filed accounts, as YYYY-MM-DD.
+  * Examples: `"2025-03-31"`, `"2024-12-31"`
+  * Derivation: extracted from the bulk data filename pattern `Prod{NNN}_{NNN}_{CCCCCCCC}_{YYYYMMDD}`.
+
+#### Balance Sheet
+
+* `total_assets`
+  * Definition: total assets reported on the balance sheet.
+  * Examples: `1500000.0` (£1,500,000)
+  * Derivation: XBRL concept `TotalAssets`. Unit: GBP.
+
+* `total_liabilities`
+  * Definition: total liabilities reported on the balance sheet.
+  * Examples: `800000.0` (£800,000)
+  * Derivation: XBRL concept `TotalLiabilities`. Unit: GBP.
+
+* `net_assets`
+  * Definition: net assets or liabilities, equal to total assets minus total liabilities.
+  * Examples: `700000.0` (£700,000)
+  * Derivation: XBRL concepts `NetAssetsLiabilities`, `NetAssets`, or `TotalAssetsLessCurrentLiabilities` (first available). Unit: GBP.
+
+* `fixed_assets`
+  * Definition: total fixed (non-current) assets including tangible, intangible, and investment assets.
+  * Examples: `350000.0` (£350,000)
+  * Derivation: XBRL concepts `FixedAssets`, `TotalFixedAssets`, `NonCurrentAssets`, or `TotalNonCurrentAssets` (first available). Unit: GBP.
+
+* `current_assets`
+  * Definition: total current assets including cash, debtors, and stock.
+  * Examples: `250000.0` (£250,000)
+  * Derivation: XBRL concepts `CurrentAssets` or `TotalCurrentAssets` (first available). Unit: GBP.
+
+* `shareholders_equity`
+  * Definition: total stockholders' or shareholders' equity.
+  * Examples: `500000.0` (£500,000)
+  * Derivation: XBRL concepts `ShareholderFunds`, `TotalShareholdersFunds`, `ShareholdersFunds`, or `Equity` (first available). Unit: GBP.
+
+* `creditors_due_within_one_year`
+  * Definition: total creditors falling due within one year (current liabilities).
+  * Examples: `120000.0` (£120,000)
+  * Derivation: XBRL concepts `CreditorsDueWithinOneYear` or `CurrentLiabilities` (first available). Unit: GBP.
+
+* `creditors_due_after_one_year`
+  * Definition: total creditors falling due after more than one year (non-current liabilities).
+  * Examples: `200000.0` (£200,000)
+  * Derivation: XBRL concepts `CreditorsDueAfterOneYear` or `NonCurrentLiabilities` (first available). Unit: GBP.
+
+* `called_up_share_capital`
+  * Definition: called up share capital of the company.
+  * Examples: `100.0` (£100)
+  * Derivation: XBRL concepts `CalledUpShareCapital` or `CalledUpShareCapitalNotPaid` (first available). Unit: GBP.
+
+#### Profit and Loss
+
+* `revenue`
+  * Definition: total revenue or turnover for the reporting period.
+  * Examples: `2000000.0` (£2,000,000)
+  * Derivation: XBRL concepts `TurnoverRevenue`, `Turnover`, `TurnoverGrossOperatingRevenue`, or `Revenue` (first available). Unit: GBP.
+  * Note: many small company filings do not include a profit and loss account, so this field is frequently absent.
+
+* `net_income`
+  * Definition: net income or loss for the reporting period.
+  * Examples: `150000.0` (£150,000), `-50000.0` (£-50,000 loss)
+  * Derivation: XBRL concepts `ProfitLoss`, `ProfitLossOnOrdinaryActivitiesBeforeTax`, `ProfitLossForPeriod`, or `ProfitLossForFinancialYear` (first available). Unit: GBP.
+  * Note: frequently absent for micro and abbreviated accounts.
+
+#### Workforce
+
+* `average_number_of_employees`
+  * Definition: average number of employees during the reporting period (headcount average, not FTE).
+  * Examples: `42.0`, `3.0`, `1250.0`
+  * Derivation: XBRL concepts `AverageNumberEmployeesDuringPeriod` or `EmployeesTotal` (first available).
+  * Note: only disclosed in filings that include employee information per FRS 102 / Companies Act 2006 requirements. Small companies are often exempt.
+
+---
+
+## Entity Relationships Summary
+
+```
+organization ──[companieshouse::filed]──→ companieshouse::accounts_filing
+```
+
+The `filed` relationship links a company to each of its annual accounts filings. One organization may have multiple `filed` edges (one per annual filing). The relationship is namespaced to `companieshouse` to distinguish it from the SEC `filed` relationship at the storage layer.

package/skill/companieshouse/schema.yaml

@@ -0,0 +1,190 @@
+# Dataset schema for Companies House Accounts (UK).
+#
+# Architecture:
+#   Each iXBRL/XBRL accounts filing produces TWO records:
+#     1. An organization record (the company) with identity properties
+#        (company number, name) and a "filed" relationship to the accounts.
+#     2. An accounts_filing record (the document) carrying the balance sheet
+#        date and financial figures.
+#
+# All elements are passive — created by the atomizer from parsed iXBRL/XBRL
+# filings, not by LLM extraction.
+#
+# Source identifier: "companieshouse-source"
+name: "companieshouse"
+description: "UK company financial accounts filed with Companies House — balance sheet data, profit/loss, and company identity extracted from filings"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - 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: ["companies_house_number"]
+    passive: true
+
+  - name: "accounts_filing"
+    namespace: "companieshouse"
+    description: "An annual accounts filing submitted to Companies House, identified by company number and balance sheet date"
+    display_name: "Accounts Filing"
+    mergeability: not_mergeable
+    strong_id_properties: ["filing_id"]
+    passive: true
+
+# --- Identity properties (on organization) ---
+
+properties:
+  - name: "companies_house_number"
+    type: string
+    description: "Companies House registered company number uniquely identifying a UK company"
+    display_name: "Companies House Number"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["00000006", "12345678", "SC123456"]
+    passive: true
+
+  - name: "registered_address"
+    type: string
+    description: "Registered office address of the company as reported in the accounts filing"
+    display_name: "Registered Address"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["10 Downing Street, London, SW1A 2AA"]
+    passive: true
+
+  # --- Filing metadata (on accounts_filing) ---
+
+  - name: "filing_id"
+    type: string
+    description: "Unique identifier for the accounts filing, composed of the company number and balance sheet date (e.g. '12345678-2024-12-31')"
+    display_name: "Filing ID"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    examples: ["12345678-2024-12-31", "SC123456-2025-03-31"]
+    passive: true
+
+  - name: "balance_sheet_date"
+    type: string
+    description: "Balance sheet date of the filed accounts, as YYYY-MM-DD"
+    display_name: "Balance Sheet Date"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    examples: ["2025-03-31", "2024-12-31"]
+    passive: true
+
+  # --- Financial properties (on accounts_filing) ---
+
+  - name: "total_assets"
+    type: float
+    description: "Total assets"
+    display_name: "Total Assets"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+  - name: "total_liabilities"
+    type: float
+    description: "Total liabilities"
+    display_name: "Total Liabilities"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+  - name: "shareholders_equity"
+    type: float
+    description: "Total stockholders' or shareholders' equity"
+    display_name: "Shareholders Equity"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+  - name: "net_assets"
+    type: float
+    description: "Net assets or liabilities of the company, equal to total assets minus total liabilities"
+    display_name: "Net Assets"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+  - name: "fixed_assets"
+    type: float
+    description: "Total fixed (non-current) assets including tangible, intangible, and investment assets"
+    display_name: "Fixed Assets"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+  - name: "current_assets"
+    type: float
+    description: "Total current assets including cash, debtors, and stock"
+    display_name: "Current Assets"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+  - name: "creditors_due_within_one_year"
+    type: float
+    description: "Total creditors falling due within one year (current liabilities)"
+    display_name: "Creditors Due Within One Year"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+  - name: "creditors_due_after_one_year"
+    type: float
+    description: "Total creditors falling due after more than one year (non-current liabilities)"
+    display_name: "Creditors Due After One Year"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+  - name: "revenue"
+    type: float
+    description: "Total revenue or turnover for the reporting period"
+    display_name: "Revenue"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+  - name: "net_income"
+    type: float
+    description: "Net income or loss for the reporting period"
+    display_name: "Net Income"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+  - name: "called_up_share_capital"
+    type: float
+    description: "Called up share capital of the company"
+    display_name: "Called Up Share Capital"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+  - name: "average_number_of_employees"
+    type: float
+    description: "Average number of employees during the reporting period"
+    display_name: "Number of Employees"
+    mergeability: not_mergeable
+    domain_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+# --- Relationships ---
+
+relationships:
+  - name: "filed"
+    description: "Link from a company or person to a regulatory filing document they filed, or from a sub-record to its parent filing"
+    display_name: "Filed"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["companieshouse::accounts_filing"]
+    passive: true
+
+attributes: []

package/skill/companieshousepsc/DATA_DICTIONARY.md

@@ -0,0 +1,99 @@
+# Data Dictionary: Companies House PSC
+
+## Source Overview
+
+UK Companies House People with Significant Control (PSC) Snapshot — a daily bulk download containing the full register of persons and entities with significant control over UK-registered companies.
+
+- Data source: `https://download.companieshouse.gov.uk/en_pscdata.html`
+- Publisher: Companies House (UK government registrar)
+- Cadence: daily full snapshot, updated before 10am GMT
+- Format: newline-delimited JSON (JSONL) inside ZIP archives; available as a single large file or ~32 smaller part files
+- Coverage: all PSC records held by Companies House, including active and ceased entries; approximately 11 million records across ~8 million companies
+- Limitations: "super-secure" PSC entries (protected persons) are redacted and skipped. Address data is a service address, not necessarily a residential address. Date of birth is limited to month and year.
+
+| Pipeline | `Record.Source` |
+|----------|----------------|
+| PSC snapshot | `companieshousepsc` |
+
+---
+
+## Entity Types
+
+### `organization`
+
+A UK-registered company that has one or more persons with significant control, or a corporate entity that itself has significant control over another company.
+
+- Primary key: `companies_house_number` (8-character alphanumeric, e.g. `"09145694"`, `"SC123456"`) for controlled companies; `registration_number` for corporate PSC entities.
+- Entity resolver: named entity, mergeable. Strong ID = `companies_house_number` or `registration_number`. Controlled companies merge with the same company from the `companieshouse` accounts dataset.
+
+### `person`
+
+An individual person with significant control over a UK company.
+
+- Primary key: none (resolved by name). Persons are mergeable entities identified by name and contextual snippets (address).
+- Entity resolver: named entity, mergeable. No strong ID — relies on name-based resolution.
+
+---
+
+## Properties
+
+### Organization Properties (controlled company)
+
+#### Identity
+
+* `companies_house_number`
+  * Definition: Companies House registered company number uniquely identifying a UK company.
+  * Examples: `"09145694"`, `"00001234"`, `"SC123456"`
+  * Derivation: `company_number` field from the top-level JSON record.
+
+### Organization Properties (corporate PSC)
+
+#### Identity
+
+* `registration_number`
+  * Definition: registration number of a corporate entity PSC as provided in their identification details.
+  * Examples: `"98765432"`, `"HRB 12345"`
+  * Derivation: `data.identification.registration_number` field from the JSON record. Only present for corporate-entity PSCs that provide identification.
+
+### Person Properties (individual PSC)
+
+#### Identity and Background
+
+* `nationality`
+  * Definition: nationality of an individual person with significant control.
+  * Examples: `"British"`, `"American"`, `"German"`
+  * Derivation: `data.nationality` field from the JSON record. Only present for individual PSCs.
+
+* `country_of_residence`
+  * Definition: country of residence of an individual person with significant control.
+  * Examples: `"England"`, `"Scotland"`, `"United States"`
+  * Derivation: `data.country_of_residence` field from the JSON record. Only present for individual PSCs.
+
+---
+
+## Entity Relationships Summary
+
+```
+person/organization (PSC) ──[controls]──→ organization (company)
+```
+
+The `controls` relationship links a person or corporate entity directly to the company they have significant control over. One PSC may control multiple companies (multiple `controls` edges from the same entity). One company may be controlled by multiple PSCs (multiple `controls` edges from different entities pointing to the same company).
+
+---
+
+## Attributes (on the `controls` relationship)
+
+* `natures_of_control`
+  * Definition: semicolon-separated list describing the nature of significant control, such as share ownership bands, voting rights, or the right to appoint/remove directors.
+  * Examples: `"ownership of shares 50 to 75 percent"`, `"ownership of shares 75 to 100 percent; right to appoint and remove directors"`
+  * Derivation: `data.natures_of_control` array from the JSON record. Each entry has hyphens replaced with spaces; multiple entries are joined with `"; "`.
+
+* `notified_on`
+  * Definition: date on which Companies House was notified of this person with significant control, as YYYY-MM-DD.
+  * Examples: `"2016-04-06"`, `"2023-01-15"`
+  * Derivation: `data.notified_on` field from the JSON record. The PSC regime started on 2016-04-06, so most entries are notified on or after that date.
+
+* `ceased_on`
+  * Definition: date on which this person ceased to have significant control, as YYYY-MM-DD. Absent for active PSCs.
+  * Examples: `"2024-06-01"`, `"2023-12-31"`
+  * Derivation: `data.ceased_on` field from the JSON record. Only present for ceased PSCs.