@yottagraph-app/aether-instructions 1.1.17 → 1.1.19

package/skills/elemental-api/relationships.md

@@ -1,310 +0,0 @@
-# Relationships
-
-Relationships (also called "links") represent connections between entities in the Knowledge Graph. These connections are derived from articles.
-
-## When to Use
-
-- You want to find entities connected to a given entity
-- You need to understand how two entities are related
-- You're exploring a network of connections (e.g., "Who is connected to this person?")
-- You need link counts or relationship strength between entities
-
-## Key Concepts
-
-- **Linked Entities**: Other entities that have a relationship with a given entity
-- **Link Strength**: Represents the significance of the relationship between two entities
-- **Link Counts**: Number of connections between entity pairs, useful for measuring relationship strength
-- **Relationship Types**: Common types include:
-  - `competes_with`
-  - `compares_to`
-  - `customer_of`
-  - `partnered_with`
-  - `trades_with`
-  - `invests_in`
-  - `is_related_to`
-  - `sues`
-  - `provides_support_to`
-
-## Tips
-
-- Relationships are bidirectional—if A links to B, B links to A
-- High link counts indicate stronger or more frequent connections in the news
-- Use with graph endpoints to visualize relationship networks
-- **`entity_type` filter limitation**: see the Guidance note on "Get linked entities" below — only three entity types are supported
-
-<!-- BEGIN GENERATED CONTENT -->
-
-## Endpoints
-
-### Get linked entities
-
-`GET /entities/{source_neid}/linked`
-
-Get list of entities linked to a source entity, optionally filtered by entity type and link type
-
-#### Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| source_neid | string | yes | Source entity NEID |
-| entity_type | string[] | no | Filter by entity type(s) |
-| link_type | string[] | no | Filter by link type(s) |
-
-#### Responses
-
-| Status | Description |
-|--------|-------------|
-| 200 | List of linked entity NEIDs (`GetLinkedEntitiesResponse`) |
-| 400 | Invalid parameters (`Error`) |
-| 404 | Source entity not found (`Error`) |
-| 500 | Internal server error (`Error`) |
-
-#### Example
-
-**Request:**
-
-```
-GET /entities/00416400910670863867/linked
-```
-
-**Response:**
-
-```json
-{"entities": ["00416400910670863867"]}
-```
-
----
-
-### Get links between entities
-
-`GET /entities/{source_neid}/links/{target_neid}`
-
-Get list of links between source and target entities, optionally filtered by link type
-
-#### Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| source_neid | string | yes | Source entity NEID |
-| target_neid | string | yes | Target entity NEID |
-| link_type | string[] | no | Filter by link type(s) |
-| include_mentions | boolean | no | Include mention details in response |
-| include_articles | boolean | no | Include article details in response |
-
-#### Responses
-
-| Status | Description |
-|--------|-------------|
-| 200 | List of entity links (`GetLinksResponse`) |
-| 400 | Invalid parameters (`Error`) |
-| 404 | Source or target entity not found (`Error`) |
-| 500 | Internal server error (`Error`) |
-
-#### Example
-
-**Request:**
-
-```
-GET /entities/00416400910670863867/links/04358848009837283240
-```
-
-**Response:**
-
-```json
-{"links": []}
-```
-
----
-
-### Get graph layout
-
-`GET /graph/{center_neid}/layout`
-
-Get nodes and edges layout data for visualizing a relationship graph. Response is cached for 5 minutes.
-
-#### Guidance
-
-Only use this endpoint if you care about graph-specific properties. Otherwise it is faster to use /entities/{source_neid}/links/{target_neid}. This should always be called with a non-empty list of neids. A typical pattern is to call /graph/{center_neid}/neighborhood and then use the returned NEIDs to call this endpoint.
-
-#### Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| center_neid | string | yes | Center entity NEID |
-| neid | string[] | no | Additional entity NEIDs to include in layout |
-| borderMinX | number | no | Minimum X border for layout |
-| borderMinY | number | no | Minimum Y border for layout |
-| borderMaxX | number | no | Maximum X border for layout |
-| borderMaxY | number | no | Maximum Y border for layout |
-
-#### Responses
-
-| Status | Description |
-|--------|-------------|
-| 200 | Graph layout with nodes and edges (`GraphLayoutResponse`) |
-| 400 | Invalid parameters (`Error`) |
-| 500 | Internal server error (`Error`) |
-
-#### Example
-
-**Request:**
-
-```
-GET /graph/00416400910670863867/layout?neid=04358848009837283240
-```
-
-**Response:**
-
-```json
-{"nodes": [{"neid": "00416400910670863867", "label": "organization|Apple|nationality: us...", "isCentralNode": true, "x": -333.33, "y": -200, "width": 666.67, "height": 266.67}], "edges": [{"source": "00416400910670863867", "target": "04358848009837283240", "label": "competes_with", "path": [{"X": 0, "Y": 0}, {"X": 0, "Y": 66.67}], "article_ids": ["02861951941133789623"], "snippets": ["Apple and Google are mentioned as companies..."], "weight": 0.0267}]}
-```
-
----
-
-### Get graph neighborhood
-
-`GET /graph/{center_neid}/neighborhood`
-
-Get list of neighboring entities in the relationship graph, optionally filtered by entity type. Response is cached for 5 minutes.
-
-#### Guidance
-
-Only use this endpoint if you care about graph-specific properties. Otherwise it is faster to use /entities/{source_neid}/linked. Response includes the center entity itself in the results with a weight of 1.0. The 'neighbors' and 'weights' arrays are parallel (same indices correspond).
-
-#### Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| center_neid | string | yes | Center entity NEID |
-| size | integer | no | Maximum number of neighbors to return |
-| type | string[] | no | Filter by entity type(s) |
-
-#### Responses
-
-| Status | Description |
-|--------|-------------|
-| 200 | Neighbors and their weights (`GraphNeighborhoodResponse`) |
-| 400 | Invalid parameters (`Error`) |
-| 404 | Center entity not found (`Error`) |
-| 500 | Internal server error (`Error`) |
-
-#### Example
-
-**Request:**
-
-```
-GET /graph/00416400910670863867/neighborhood?size=5
-```
-
-**Response:**
-
-```json
-{"neighbors": ["00416400910670863867", "04358848009837283240", "00315863961550087877"], "weights": [1, 0.0267, 0.0167]}
-```
-
----
-
-### Get link counts between entities
-
-`GET /graph/{source_neid}/links/{target_neid}/counts`
-
-Get counts of links between source and target entities over time
-
-#### Guidance
-
-Only use this endpoint if you care about graph-specific properties. Otherwise it is faster to use /entities/{source_neid}/links/{target_neid}. Returns link_counts object with relationship types as keys. Values are arrays of timestamps in Excel/OLE serial date format (days since 1899-12-30). Example: 46019.64453125 = 2025-12-28 15:28:07 UTC. The count for each relationship type is the array length (number of observations).
-
-#### Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| source_neid | string | yes | Source entity NEID |
-| target_neid | string | yes | Target entity NEID |
-
-#### Responses
-
-| Status | Description |
-|--------|-------------|
-| 200 | Link counts by type (`GetLinkCountsResponse`) |
-| 400 | Invalid parameters (`Error`) |
-| 500 | Internal server error (`Error`) |
-
-#### Example
-
-**Request:**
-
-```
-GET /graph/00416400910670863867/links/04358848009837283240/counts
-```
-
-**Response:**
-
-```json
-{"link_counts": {"compares_to": [46019.64453125, 45999.3515625], "competes_with": [45847.5625, 45850.60546875], "customer_of": [45836.9296875], "partnered_with": [], "trades_with": []}}
-```
-
-## Types
-
-### EntityLink
-
-A link between two entities
-
-| Field | Type | Description |
-|-------|------|-------------|
-| article_ids | string[] | Article IDs where this link was found |
-| recorded_at | string | Time when the link was recorded @Format date-time |
-| source | string | Source entity NEID |
-| target | string | Target entity NEID |
-| type | string | Type of link/relationship |
-
-### GetLinkCountsResponse
-
-Response containing link counts between entities
-
-| Field | Type | Description |
-|-------|------|-------------|
-| link_counts | object | Map of link type to count values |
-
-### GetLinkedEntitiesResponse
-
-Response containing linked entities
-
-| Field | Type | Description |
-|-------|------|-------------|
-| entities | string[] | List of linked entity NEIDs |
-
-### GetLinksResponse
-
-Response containing links between entities
-
-| Field | Type | Description |
-|-------|------|-------------|
-| articles | `ArticleDetail`[] | Articles tied to the returned links (only included when requested) |
-| links | `EntityLink`[] | List of entity links |
-| mentions | `MentionDetail`[] | Mentions tied to the returned links (only included when requested) |
-
-### GraphNeighborhoodResponse
-
-Response containing neighbors of an entity in the relationship graph
-
-| Field | Type | Description |
-|-------|------|-------------|
-| neighbors | string[] | List of neighbor NEIDs |
-| weights | number[] | Weights corresponding to each neighbor (same order as neighbors) |
-
-### LinkedExpression
-
-| Field | Type | Description |
-|-------|------|-------------|
-| **linked** | `Linked` |  |
-
-### Linked
-
-| Field | Type | Description |
-|-------|------|-------------|
-| **distance** | integer | Maximum relationship distance to traverse |
-| pids | integer[] | Property identifiers defining the relationship types to follow |
-| to_entity | string | Target entity ID for relationship traversal |
-| direction | string | Direction of relationship traversal. 'outgoing' (default) follows subject->value edges, 'incoming' follows value->subject (reverse) edges, 'both' unions outgoing and incoming results. |
-
-<!-- END GENERATED CONTENT -->

package/skills/elemental-api/sentiment.md

@@ -1,93 +0,0 @@
-# Sentiment
-
-Sentiment analysis measures how positively or negatively an entity is portrayed in news coverage. The API provides both daily aggregate scores and scores for individual articles.
-
-## When to Use
-
-- You want to know if news coverage about an entity is positive or negative
-- You need sentiment trends over time (e.g., "How has sentiment changed this month?")
-- You're comparing sentiment between entities or time periods
-
-## Key Concepts
-
-- **Sentiment Score**: Ranges from -1 (very negative) to +1 (very positive), with 0 being neutral.
-  - Individual article/mention scores are discrete values: `-1`, `-0.75`, `-0.5`, `0`, `0.5`, `0.75`, `1`
-  - Daily aggregate scores can be any value between -1 and 1 (continuous)
-- **Entity-level vs. Mention-level**: Aggregate sentiment for an entity vs. sentiment of a specific mention
-
-## Tips
-
-- Sentiment without a time range returns recent data; always specify dates for historical analysis
-- High mention volume with neutral sentiment may indicate routine coverage
-- Sudden sentiment shifts often correlate with specific events
-
-<!-- BEGIN GENERATED CONTENT -->
-
-## Endpoints
-
-### Get entity sentiment data
-
-`GET /graph/{neid}/sentiment`
-
-Get sentiment analysis data for a named entity including scores, timestamps, and daily averages. Response is cached for 5 minutes.
-
-#### Guidance
-
-Response is wrapped in a 'sentiment' container object. The sentiment_scores field is a flat array of numbers (not timestamped objects). The time interval for the scores is provided separately in time_interval.start and time_interval.end.
-
-#### Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| neid | string | yes | Named Entity ID |
-
-#### Responses
-
-| Status | Description |
-|--------|-------------|
-| 200 | Sentiment data for the entity (`GetNamedEntitySentimentResponse`) |
-| 400 | Invalid NEID (`Error`) |
-| 404 | Entity not found (`Error`) |
-| 500 | Internal server error (`Error`) |
-
-#### Example
-
-**Request:**
-
-```
-GET /graph/00416400910670863867/sentiment
-```
-
-**Response:**
-
-```json
-{"sentiment": {"neid": "00416400910670863867", "time_interval": {"start": "2026-01-04T03:02:25.384Z", "end": "2026-02-03T03:02:25.384Z"}, "num_mentions": 28662, "sentiment_scores": [0.5, 0.5, 0.5, 0, 0.5, -0.5, 1]}}
-```
-
-## Types
-
-### GetNamedEntitySentimentResponse
-
-Response containing sentiment data for a named entity
-
-| Field | Type | Description |
-|-------|------|-------------|
-| sentiment | `NamedEntitySentiment` |  |
-
-### NamedEntitySentiment
-
-The sentiment data
-
-| Field | Type | Description |
-|-------|------|-------------|
-| daily_timestamps | string[] | Timestamps associated with each daily sentiment trend |
-| direct_sentiment_daily_averages | number[] | The average direct sentiment score for the entity for each day in the time interval |
-| neid | string | Named Entity ID |
-| num_mentions | integer | Number of times the entity has been directly mentioned in an article |
-| propagated_sentiment_daily_averages | number[] | The average propagated sentiment score for the entity for each day in the time interval |
-| sentiment_article_nindexes | string[] | Nindexes of the articles that correspond to each direct sentiment score |
-| sentiment_scores | number[] | All direct sentiment scores for the entity |
-| sentiment_timestamps | string[] | Timestamps associated with each direct sentiment score |
-| time_interval | `TimeInterval` |  |
-
-<!-- END GENERATED CONTENT -->

package/skills/test-api-queries/SKILL.md

@@ -1,63 +0,0 @@
----
-name: test-api-queries
-description: Test Elemental API queries before integrating into app code. Use when writing code that calls the query server.
----
-
-# Test API Queries
-
-**When writing code that calls the Query Server, test queries with this CLI tool before integrating them into app code.**
-
-This prevents wasted iteration cycles from incorrect assumptions about API responses.
-
-## Workflow
-
-1. **Test the query** using the CLI tool below
-2. **Verify the response** matches what you expect
-3. **Then write the app code** with confidence
-
-## CLI Tool
-
-Location: `~/.cursor/skills/test-api-queries/query-api.js`
-
-### Requirements
-
-The CLI reads these from the project's `.env` file or shell environment:
-
-- `AUTH0_M2M_DEV_TOKEN` - Auth0 M2M dev token for API access
-- `NUXT_PUBLIC_QUERY_SERVER_ADDRESS` - Query server URL
-
-**Before using this tool**, check that both variables are set in the project's `.env` file. If either is missing or empty, add them to `.env` (see `.env.example` for the format). Tell the user to ask the engineering team for the token value if they don't have it.
-
-### Usage
-
-```bash
-node ~/.cursor/skills/test-api-queries/query-api.js <METHOD> <ENDPOINT> [JSON_PARAMS]
-```
-
-### Examples
-
-```bash
-# Search for entities by name
-node ~/.cursor/skills/test-api-queries/query-api.js POST /entities/search \
-  '{"queries":[{"queryId":1,"query":"Apple"}],"maxResults":3}'
-
-# Get entity details by ID
-node ~/.cursor/skills/test-api-queries/query-api.js GET /entities/00416400910670863867
-
-# Find entities by type
-node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/find \
-  '{"expression":{"type":"is_type","is_type":{"fid":10}},"limit":5}'
-
-# Find entities with a specific property
-node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/find \
-  '{"expression":{"type":"comparison","comparison":{"operator":"has_value","pid":313}},"limit":10}'
-
-# Get entity properties
-node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/entities/properties \
-  '{"eids":["00416400910670863867"],"pids":[8,313]}'
-```
-
-### Notes
-
-- Run from the project directory so the `.env` file is found
-- `/elemental/find` and `/elemental/entities/properties` require form-encoded bodies—the tool handles this automatically

package/skills/test-api-queries/query-api.js

@@ -1,172 +0,0 @@
-#!/usr/bin/env node
-/**
- * Simple CLI tool to query the Elemental API.
- *
- * Auth: set AUTH0_M2M_DEV_TOKEN as an env var or in your .env file.
- * Server: set NUXT_PUBLIC_QUERY_SERVER_ADDRESS in your .env file.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const FORM_ENCODED_ENDPOINTS = ['/elemental/find', '/elemental/entities/properties'];
-
-function loadEnvFile() {
-    // Try current working directory first (project .env), then script directory
-    const envPaths = [path.join(process.cwd(), '.env'), path.join(__dirname, '.env')];
-
-    for (const envPath of envPaths) {
-        try {
-            const contents = fs.readFileSync(envPath, 'utf8');
-            for (const line of contents.split('\n')) {
-                const trimmed = line.trim();
-                if (!trimmed || trimmed.startsWith('#')) continue;
-                const eqIndex = trimmed.indexOf('=');
-                if (eqIndex === -1) continue;
-                const key = trimmed.slice(0, eqIndex).trim();
-                const value = trimmed.slice(eqIndex + 1).trim();
-                if (!process.env[key]) {
-                    process.env[key] = value;
-                }
-            }
-            return; // Stop after first successful load
-        } catch {
-            // Try next path
-        }
-    }
-}
-
-function requiresFormEncoding(endpoint) {
-    return FORM_ENCODED_ENDPOINTS.some((e) => endpoint.startsWith(e));
-}
-
-function buildFormBody(endpoint, params) {
-    const formParams = new URLSearchParams();
-    for (const [key, value] of Object.entries(params)) {
-        if (typeof value === 'object') {
-            formParams.append(key, JSON.stringify(value));
-        } else {
-            formParams.append(key, String(value));
-        }
-    }
-    return formParams.toString();
-}
-
-async function main() {
-    loadEnvFile();
-
-    const args = process.argv.slice(2);
-
-    if (args.length < 2 || args[0] === '--help' || args[0] === '-h') {
-        console.log(`
-Elemental API Query Tool
-
-Usage:
-  node query-api.js <METHOD> <ENDPOINT> [JSON_PARAMS]
-
-Examples:
-  # Search for entities (JSON body)
-  node query-api.js POST /entities/search '{"queries":[{"queryId":1,"query":"Apple"}],"maxResults":3}'
-
-  # Get entity details
-  node query-api.js GET /entities/00416400910670863867
-
-  # Find entities by expression (auto form-encoded)
-  node query-api.js POST /elemental/find '{"expression":{"type":"is_type","is_type":{"fid":10}},"limit":5}'
-
-  # Find entities with a property value
-  node query-api.js POST /elemental/find '{"expression":{"type":"comparison","comparison":{"operator":"has_value","pid":313}},"limit":10}'
-
-  # Get entity properties (auto form-encoded)
-  node query-api.js POST /elemental/entities/properties '{"eids":["00416400910670863867"],"pids":[8,313]}'
-
-Environment variables (required):
-  AUTH0_M2M_DEV_TOKEN                Bearer token for API auth
-  NUXT_PUBLIC_QUERY_SERVER_ADDRESS     Query server URL (e.g. https://query.news.prod.g.lovelace.ai)
-
-Setup:
-  1. Get a dev token from your team
-  2. Add AUTH0_M2M_DEV_TOKEN to your .env file or export in your shell
-     (NUXT_PUBLIC_QUERY_SERVER_ADDRESS should already be in your .env from project init)
-
-Note: /elemental/find and /elemental/entities/properties require form-encoded bodies.
-      This tool automatically handles the encoding for these endpoints.
-`);
-        process.exit(0);
-    }
-
-    const [method, endpoint, jsonParams] = args;
-
-    const token = process.env.AUTH0_M2M_DEV_TOKEN;
-    if (!token) {
-        console.error('Error: AUTH0_M2M_DEV_TOKEN is not set.');
-        console.error('Add it to your .env file or export it in your shell.');
-        console.error('Run: node query-api.js --help');
-        process.exit(1);
-    }
-
-    let params = {};
-    if (jsonParams) {
-        try {
-            params = JSON.parse(jsonParams);
-        } catch (err) {
-            console.error('Error: Invalid JSON parameters');
-            console.error(err.message);
-            process.exit(1);
-        }
-    }
-
-    const server = process.env.NUXT_PUBLIC_QUERY_SERVER_ADDRESS;
-    if (!server) {
-        console.error('Error: NUXT_PUBLIC_QUERY_SERVER_ADDRESS is not set.');
-        console.error('Add it to your .env file or export it in your shell.');
-        console.error('Run: node query-api.js --help');
-        process.exit(1);
-    }
-
-    const normalizedEndpoint = endpoint.startsWith('/') ? endpoint : '/' + endpoint;
-    let url = `${server}${normalizedEndpoint}`;
-
-    const useFormEncoding = requiresFormEncoding(normalizedEndpoint);
-    const fetchOptions = {
-        method: method.toUpperCase(),
-        headers: {
-            Authorization: `Bearer ${token}`,
-            'Content-Type': useFormEncoding
-                ? 'application/x-www-form-urlencoded'
-                : 'application/json',
-            Accept: 'application/json',
-        },
-    };
-
-    if (method.toUpperCase() === 'GET' && Object.keys(params).length > 0) {
-        const queryString = new URLSearchParams(params).toString();
-        url = `${url}?${queryString}`;
-    } else if (method.toUpperCase() !== 'GET' && Object.keys(params).length > 0) {
-        if (useFormEncoding) {
-            fetchOptions.body = buildFormBody(normalizedEndpoint, params);
-        } else {
-            fetchOptions.body = JSON.stringify(params);
-        }
-    }
-
-    console.error(`\n📡 ${method.toUpperCase()} ${url}\n`);
-
-    try {
-        const response = await fetch(url, fetchOptions);
-        const data = await response.json();
-
-        if (!response.ok) {
-            console.error(`❌ Error ${response.status}: ${response.statusText}`);
-        } else {
-            console.error(`✅ Success (${response.status})\n`);
-        }
-
-        console.log(JSON.stringify(data, null, 2));
-    } catch (err) {
-        console.error('❌ Request failed:', err.message);
-        process.exit(1);
-    }
-}
-
-main();