@yottagraph-app/aether-instructions 1.1.8 → 1.1.10

package/skills/data-model/wikipedia/DATA_DICTIONARY.md

@@ -0,0 +1,185 @@
+# Data Dictionary: Wikipedia
+
+## Source Overview
+
+Wikipedia is a multilingual open encyclopedia. This source extracts biographical, geographic, and organizational entities from English Wikipedia (`en.wikipedia.org`), producing a `wikipedia_summary` property containing the article's introductory paragraph.
+
+Entity classification is performed using the Wikidata truthy dump — each Wikipedia article links to a Wikidata item via a QID (e.g., Q42 = Douglas Adams), and the Wikidata P31 (instance of) property provides structured type information. Summaries are fetched via the MediaWiki API's `extracts` module, which returns clean plaintext intro sections.
+
+No LLM calls are used in this pipeline. All extraction is deterministic.
+
+| Pipeline | `Record.Source` |
+|----------|----------------|
+| All entities | `wikipedia` |
+
+**Update cadence:** Initial load processes a Wikidata truthy dump plus SQL dumps for classification (~1-2 hours offline), then fetches summaries via the MediaWiki API (~2 days for ~3-4M entities). Incremental updates poll the Wikipedia RecentChanges API on a configurable interval (e.g., daily) and re-fetch summaries for changed articles.
+
+---
+
+## Entity Types
+
+### `person`
+
+A human being with an English Wikipedia article, classified via Wikidata P31 = Q5 (human).
+
+- Primary key: `wikidata_qid`
+- Entity resolver: named entity, mergeable. Strong ID = `wikidata_qid`.
+
+### `location`
+
+A geographic entity (city, country, sovereign state, town, village, settlement, etc.) with an English Wikipedia article, classified via Wikidata P31 matching location-related types (Q515, Q6256, Q3624078, Q532, Q3957, Q486972, etc.).
+
+- Primary key: `wikidata_qid`
+- Entity resolver: named entity, mergeable. Strong ID = `wikidata_qid`.
+
+### `organization`
+
+A company, business, institution, or organizational entity with an English Wikipedia article, classified via Wikidata P31 matching organization-related types (Q43229, Q4830453, Q783794, Q6881511, Q891723, etc.).
+
+- Primary key: `wikidata_qid`
+- Entity resolver: named entity, mergeable. Strong ID = `wikidata_qid`.
+
+---
+
+## Properties
+
+### Shared Properties (all entity types)
+
+#### Identity
+
+* `wikidata_qid`
+  * Definition: Wikidata item identifier. Globally unique, stable, never reused.
+  * Examples: `"Q42"` (Douglas Adams), `"Q62"` (San Francisco), `"Q312"` (Apple Inc.)
+  * Derivation: From Wikidata truthy dump (initial load) or MediaWiki API `pageprops.wikibase_item` (incremental updates).
+
+* `wikibase_shortdesc`
+  * Definition: Short human-readable description from Wikidata, typically one line summarizing what the entity is.
+  * Examples: `"English author, humorist, and screenwriter"` (Q42), `"City and county in California, United States"` (Q62), `"American multinational technology company"` (Q312)
+  * Derivation: From `page_props.sql.gz` dump field `wikibase-shortdesc` (initial load) or MediaWiki API `pageprops` with `ppprop=wikibase-shortdesc` (incremental updates).
+
+#### Content
+
+* `wikipedia_summary`
+  * Definition: The first paragraph of the entity's English Wikipedia article intro, in plain text.
+  * Examples:
+    * (Douglas Adams) `"Douglas Noël Adams (11 March 1952 – 11 May 2001) was an English author, humorist, and screenwriter, best known as the creator of The Hitchhiker's Guide to the Galaxy. Originally a 1978 BBC radio comedy, The Hitchhiker's Guide to the Galaxy evolved into a \"trilogy\" of six books..."`
+    * (San Francisco) `"San Francisco, officially the City and County of San Francisco, is the fourth-most populous city in California and the 17th-most populous in the United States..."`
+  * Derivation: From the full intro text (MediaWiki API or XML dump extraction), split at the first paragraph break.
+
+* `wikipedia_extended_summary`
+  * Definition: The remaining paragraphs of the entity's English Wikipedia article intro beyond the first paragraph, in plain text. Empty for articles with only a single introductory paragraph.
+  * Examples:
+    * (Albert Einstein, paragraph 2) `"Born in the German Empire, Einstein moved to Switzerland in 1895, forsaking his German citizenship the following year..."`
+  * Derivation: Paragraphs 2+ of the intro text, after splitting off the first paragraph for `wikipedia_summary`.
+
+### Snippet
+
+The snippet combines the Wikidata short description with the first sentence(s) of the article in the format: `"{wikibase_shortdesc} | {first sentence(s)}"`. Sentences are accumulated until the total snippet reaches ~300 characters. This format gives immediate topical context from the short description plus grounding detail from the article itself.
+
+Example (Apple Inc.): `"American multinational technology company | Apple Inc. is an American multinational technology company headquartered in Cupertino, California, in Silicon Valley, best known for its consumer electronics, software and online services."`
+
+---
+
+## Entity Relationships
+
+Relationships are extracted from Wikidata P-properties in the truthy dump. Each
+relationship connects a subject entity to a target entity, both of which must be
+classified (person, location, or organization). All extraction is deterministic.
+
+### Person → Location
+
+| Relationship | P-property | Example |
+|---|---|---|
+| `born_in` | P19 (place of birth) | Albert Einstein → born_in → Ulm |
+| `died_in` | P20 (place of death) | Albert Einstein → died_in → Princeton |
+| `citizen_of` | P27 (country of citizenship) | Albert Einstein → citizen_of → Germany |
+| `resides_in` | P551 (residence) | Albert Einstein → resides_in → Princeton |
+
+### Person → Organization
+
+| Relationship | P-property | Example |
+|---|---|---|
+| `educated_at` | P69 (educated at) | Albert Einstein → educated_at → ETH Zurich |
+| `employed_by` | P108 (employer) | Albert Einstein → employed_by → Institute for Advanced Study |
+| `member_of` | P102, P54, P463 | Barack Obama → member_of → Democratic Party |
+
+### Person → Person
+
+| Relationship | P-property | Example |
+|---|---|---|
+| `has_father` | P22 (father) | — |
+| `has_mother` | P25 (mother) | — |
+| `spouse_of` | P26 (spouse) | — |
+| `parent_of` | P40 (child) | — |
+
+### Organization → Location
+
+| Relationship | P-property | Example |
+|---|---|---|
+| `headquartered_in` | P159 (headquarters location) | Apple Inc. → headquartered_in → Cupertino |
+| `in_country` | P17 (country) | Apple Inc. → in_country → United States |
+| `located_in` | P131, P276 (admin territory, location) | Berlin → located_in → Germany |
+
+### Organization → Organization
+
+| Relationship | P-property | Example |
+|---|---|---|
+| `subsidiary_of` | P749 (parent organization) | Instagram → subsidiary_of → Meta |
+| `parent_org_of` | P355 (subsidiary) | Meta → parent_org_of → Instagram |
+| `owned_by` | P127 (owned by) | — |
+
+### Organization → Person
+
+| Relationship | P-property | Example |
+|---|---|---|
+| `founded_by` | P112 (founded by) | Apple Inc. → founded_by → Steve Jobs |
+| `has_ceo` | P169 (CEO) | Apple Inc. → has_ceo → Tim Cook |
+
+### Location → Location
+
+| Relationship | P-property | Example |
+|---|---|---|
+| `in_country` | P17 (country) | Berlin → in_country → Germany |
+| `located_in` | P131 (admin territory) | Berlin → located_in → Brandenburg |
+| `has_capital` | P36 (capital) | Germany → has_capital → Berlin |
+| `contains` | P150 (contains admin territory) | Germany → contains → Bavaria |
+| `borders` | P47 (shares border with) | Germany → borders → France |
+
+---
+
+## Classification Reference
+
+### Person (P31 target types)
+
+| QID | Label |
+|-----|-------|
+| Q5 | human |
+
+### Location (P31 target types)
+
+| QID | Label |
+|-----|-------|
+| Q515 | city |
+| Q6256 | country |
+| Q3624078 | sovereign state |
+| Q35657 | state of the United States |
+| Q532 | village |
+| Q3957 | town |
+| Q486972 | human settlement |
+| Q1549591 | big city |
+| Q1093829 | city of the United States |
+
+### Organization (P31 target types)
+
+| QID | Label |
+|-----|-------|
+| Q43229 | organization |
+| Q4830453 | business |
+| Q783794 | company |
+| Q6881511 | enterprise |
+| Q891723 | public company |
+| Q161726 | multinational corporation |
+| Q163740 | nonprofit organization |
+| Q484652 | international organization |
+| Q3918 | university |
+| Q327333 | government agency |

package/skills/data-model/wikipedia/schema.yaml

@@ -0,0 +1,255 @@
+# Dataset schema for Wikipedia entity data.
+#
+# Entities are classified by type using Wikidata P31 (instance of) from the
+# truthy dump. Summaries are fetched via the MediaWiki API. All elements are
+# passive — deterministic extraction, no LLM.
+name: "wikipedia"
+description: "People, locations, and organizations from English Wikipedia with introductory summaries and Wikidata identifiers"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - name: "person"
+    description: "A real person as opposed to a fictional character, such as a CEO, politician, or public figure"
+    display_name: "Person"
+    mergeability: not_mergeable
+    strong_id_properties: ["wikidata_qid"]
+    passive: true
+
+  - name: "location"
+    description: "A specific named geographic location such as a city, country, region, or landmark"
+    display_name: "Location"
+    mergeability: not_mergeable
+    strong_id_properties: ["wikidata_qid"]
+    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: ["wikidata_qid"]
+    passive: true
+
+properties:
+  - name: "wikidata_qid"
+    type: string
+    description: "Wikidata item identifier, globally unique and stable"
+    display_name: "Wikidata QID"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "location", "organization"]
+    examples: ["Q42", "Q62", "Q312"]
+    passive: true
+
+  - name: "wikibase_shortdesc"
+    type: string
+    description: "Short human-readable description from Wikidata summarizing what the entity is"
+    display_name: "Short Description"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "location", "organization"]
+    examples: ["English author, humorist, and screenwriter", "City and county in California, United States", "American multinational technology company"]
+    passive: true
+
+  - name: "wikipedia_summary"
+    type: string
+    description: "First paragraph of the entity's English Wikipedia article intro in plain text"
+    display_name: "Wikipedia Summary"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "location", "organization"]
+    passive: true
+
+  - name: "wikipedia_extended_summary"
+    type: string
+    description: "Remaining paragraphs of the Wikipedia article intro beyond the first paragraph, in plain text"
+    display_name: "Wikipedia Extended Summary"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "location", "organization"]
+    passive: true
+
+relationships:
+  # Person → Location
+  - name: "born_in"
+    description: "Place where the person was born (Wikidata P19)"
+    display_name: "Born In"
+    mergeability: not_mergeable
+    domain_flavors: ["person"]
+    target_flavors: ["location"]
+    passive: true
+
+  - name: "died_in"
+    description: "Place where the person died (Wikidata P20)"
+    display_name: "Died In"
+    mergeability: not_mergeable
+    domain_flavors: ["person"]
+    target_flavors: ["location"]
+    passive: true
+
+  - name: "citizen_of"
+    description: "Country of citizenship (Wikidata P27)"
+    display_name: "Citizen Of"
+    mergeability: not_mergeable
+    domain_flavors: ["person"]
+    target_flavors: ["location"]
+    passive: true
+
+  - name: "resides_in"
+    description: "Place of residence (Wikidata P551)"
+    display_name: "Resides In"
+    mergeability: not_mergeable
+    domain_flavors: ["person"]
+    target_flavors: ["location"]
+    passive: true
+
+  # Person → Organization
+  - name: "educated_at"
+    description: "Educational institution attended (Wikidata P69)"
+    display_name: "Educated At"
+    mergeability: not_mergeable
+    domain_flavors: ["person"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "employed_by"
+    description: "Organization that employs or employed the person (Wikidata P108)"
+    display_name: "Employed By"
+    mergeability: not_mergeable
+    domain_flavors: ["person"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "member_of"
+    description: "Organization the person is or was a member of, including political parties and sports teams (Wikidata P102, P54, P463)"
+    display_name: "Member Of"
+    mergeability: not_mergeable
+    domain_flavors: ["person"]
+    target_flavors: ["organization"]
+    passive: true
+
+  # Person → Person
+  - name: "has_father"
+    description: "The person's father (Wikidata P22)"
+    display_name: "Has Father"
+    mergeability: not_mergeable
+    domain_flavors: ["person"]
+    target_flavors: ["person"]
+    passive: true
+
+  - name: "has_mother"
+    description: "The person's mother (Wikidata P25)"
+    display_name: "Has Mother"
+    mergeability: not_mergeable
+    domain_flavors: ["person"]
+    target_flavors: ["person"]
+    passive: true
+
+  - name: "spouse_of"
+    description: "The person's spouse or partner (Wikidata P26)"
+    display_name: "Spouse Of"
+    mergeability: not_mergeable
+    domain_flavors: ["person"]
+    target_flavors: ["person"]
+    passive: true
+
+  - name: "parent_of"
+    description: "The person's child (Wikidata P40)"
+    display_name: "Parent Of"
+    mergeability: not_mergeable
+    domain_flavors: ["person"]
+    target_flavors: ["person"]
+    passive: true
+
+  # Organization/Location → Location
+  - name: "headquartered_in"
+    description: "Location of the organization's headquarters (Wikidata P159)"
+    display_name: "Headquartered In"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["location"]
+    passive: true
+
+  - name: "in_country"
+    description: "Country the entity is associated with (Wikidata P17)"
+    display_name: "In Country"
+    mergeability: not_mergeable
+    domain_flavors: ["organization", "location"]
+    target_flavors: ["location"]
+    passive: true
+
+  - name: "located_in"
+    description: "Administrative territory or location the entity is situated in (Wikidata P131, P276)"
+    display_name: "Located In"
+    mergeability: not_mergeable
+    domain_flavors: ["organization", "location"]
+    target_flavors: ["location"]
+    passive: true
+
+  # Organization → Organization
+  - name: "subsidiary_of"
+    description: "Parent organization (Wikidata P749)"
+    display_name: "Subsidiary Of"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "parent_org_of"
+    description: "Subsidiary organization (Wikidata P355)"
+    display_name: "Parent Org Of"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "owned_by"
+    description: "Owner of the organization (Wikidata P127)"
+    display_name: "Owned By"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["organization", "person"]
+    passive: true
+
+  # Organization → Person
+  - name: "founded_by"
+    description: "Person who founded the organization (Wikidata P112)"
+    display_name: "Founded By"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["person"]
+    passive: true
+
+  - name: "has_ceo"
+    description: "Chief executive officer of the organization (Wikidata P169)"
+    display_name: "Has CEO"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["person"]
+    passive: true
+
+  # Location → Location
+  - name: "has_capital"
+    description: "Capital city or seat of government (Wikidata P36)"
+    display_name: "Has Capital"
+    mergeability: not_mergeable
+    domain_flavors: ["location"]
+    target_flavors: ["location"]
+    passive: true
+
+  - name: "contains"
+    description: "Administrative territory contained within this location (Wikidata P150)"
+    display_name: "Contains"
+    mergeability: not_mergeable
+    domain_flavors: ["location"]
+    target_flavors: ["location"]
+    passive: true
+
+  - name: "borders"
+    description: "Location that shares a border with this one (Wikidata P47)"
+    display_name: "Borders"
+    mergeability: not_mergeable
+    domain_flavors: ["location"]
+    target_flavors: ["location"]
+    passive: true

package/skills/elemental-api/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: elemental-api
+description: Query the Elemental API for entity discovery, search, and metadata. Use with the Lovelace News Query Server.
+---
+
+# Elemental API
+
+This skill provides documentation for the Lovelace Elemental API, the primary interface for querying the Lovelace Knowledge Graph.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Look up entities (companies, people, organizations) by name or ID
+- Get sentiment analysis for entities over time
+- Find news mentions and articles about entities
+- Explore relationships and connections between entities
+- Retrieve events involving specific entities
+- Build knowledge graphs of entity networks
+
+## Quick Start
+
+1. **Find an entity**: Use `entities.md` to look up a company or person by name and get their NEID (Named Entity ID)
+2. **Get information**: Use the NEID to query sentiment, mentions, relationships, or events
+3. **Dive deeper**: Retrieve full article details or explore connected entities
+
+## Files in This Skill
+
+See [overview.md](overview.md) for descriptions of each endpoint category:
+- `entities.md` - Entity search, details, and properties
+- `find.md` - Expression language for searching entities by type, property values, and relationships
+- `schema.md` - Data model: entity types (flavors), properties, and schema endpoints
+- `sentiment.md` - Sentiment analysis
+- `articles.md` - Articles mentioning entities and full article content
+- `events.md` - Events involving entities
+- `relationships.md` - Entity connections
+- `graph.md` - Visual graph generation
+- `server.md` - Server status and health