@yottagraph-app/aether-instructions 1.1.17 → 1.1.19

package/skills/elemental-api/entities.md

@@ -2,6 +2,10 @@
 
 Entities are the core objects in the Knowledge Graph: companies, people, organizations, products, and other named things that appear in the news. Each entity has a unique **Named Entity ID (NEID)**.
 
+NEIDs are stable and can be persisted long-term, but may occasionally change if the database is rebuilt or the application switches databases. When an NEID becomes invalid (e.g., resolution returns no results), re-resolve the entity using its canonical name from the previous query result, then redo any downstream operations that depended on it. NEIDs should NEVER be hardcoded in source code.
+
+**Looking for property-based search?** To search for entities by type, property values, or relationships using the expression language, see [find.md](find.md).
+
 ## When to Use
 
 - You have an entity name and need to find its NEID
@@ -16,28 +20,24 @@ Entities are the core objects in the Knowledge Graph: companies, people, organiz
   - Example: `00416400910670863867`
   - Always pad with leading zeros to exactly 20 characters when normalizing
 - **EID**: The term EID is sometimes used interchangeably with NEID.
+- **nindex**: The term nindex is sometimes used interchangeably with NEID.
 - **Entity Resolution**: The same real-world entity may have multiple names (e.g., "Apple", "Apple Inc.", "AAPL"). The API resolves these to a single NEID.
-- **Entity Types (Flavors)**: Each entity has a type identified by a Flavor ID (FID) (ex. type "ship" is FID 1).
+- **Flavors (Entity Types)**: Each entity has a type identified by a Flavor ID (FID).
 
 ## Tips
 
 - Always start by searching for the entity to get the correct NEID
-- After resolving an entity to an NEID, it's best to display the canonical entity name to the user to help them identify if something went wrong with the resolution.
+- After resolving an entity to an NEID, save and use the the canonical entity name going forward.
 - It's typically safe to resolve an entity to the top matching NEID. However, sometimes a useful pattern is to let the user give input that the resolution was incorrect, show them a longer list of matches, and let them choose a different resolution.
 - Entity names are case-insensitive
 
 ## Key Endpoints
 
-| What you need | Endpoint | Client method | Returns |
-|---------------|----------|---------------|---------|
-| Find entities by expression | `POST /elemental/find` | `findEntities()` | Entity IDs matching expression |
-| Find entity by name (simple lookup) | `GET /entities/lookup` | `getNEID()` | NEIDs matching a single name query |
-| Basic info (name, aliases, type) | `GET /entities/{neid}` | — | Quick summary for display |
-| Full property values | `POST /elemental/entities/properties` | `getPropertyValues()` | All properties with PIDs, values, timestamps |
-
-**`findEntities()` vs `getNEID()` for entity search**:
-- **`findEntities()`** → `POST /elemental/find` — expression-based search. Supports filtering by type, property value, relationship, and complex nested queries. See `find.md` for the expression language. **Use this for filtered or batch searches.**
-- **`getNEID()`** → `GET /entities/lookup` — simple single-entity name lookup via query parameters (`entityName`, `maxResults`). Best for resolving one company/person name quickly.
+| What you need | Endpoint | Returns |
+|---------------|----------|---------|
+| Find entity by name (batch, scored) | `POST /entities/search` | Ranked matches with NEIDs and scores |
+| Basic info (name, aliases, type) | `GET /entities/{neid}` | Quick summary for display |
+| Full property values | `POST /elemental/entities/properties` | All properties with PIDs, values, timestamps |
 
 **Important**: When a user asks for "entity properties," clarify which they mean:
 - Basic info/metadata → use `/entities/{neid}`
@@ -160,57 +160,42 @@ The same pattern applies to the `expression` parameter on `POST /elemental/find`
 
 For understanding entity types (flavors), properties, and the data model, see **schema.md**. You'll need the schema because many API responses return only FIDs and PIDs — use it to translate these to human-readable names.
 
+## Properties Return Multiple Timestamped Values
 
-<!-- BEGIN GENERATED CONTENT -->
-
-## Endpoints
-
-### Get entity details
-
-`GET /entities/{neid}`
-
-Get details about a named entity including name, aliases, and type. This is an alias for /reports/{neid}. Response is cached for 5 minutes.
-
-#### Guidance
-
-Response is wrapped in a 'report' container object. Access entity data via response.report.
-
-#### Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| neid | string | yes | Named Entity ID |
+`getPropertyValues` returns **all** recorded values for a property, not just the latest. A single entity and property (e.g. Apple's `company_cik`) may return dozens of rows with different `recorded_at` timestamps — one per filing or data ingestion event. For display, take the first (or latest) value and deduplicate by PID:
 
-#### Responses
+```typescript
+const byPid = new Map<number, string>();
+for (const v of values) {
+    if (!byPid.has(v.pid)) byPid.set(v.pid, v.value);
+}
+```
 
-| Status | Description |
-|--------|-------------|
-| 200 | Entity details (`GetNamedEntityReportResponse`) |
-| 400 | Invalid NEID (`Error`) |
-| 404 | Entity not found (`Error`) |
-| 500 | Internal server error (`Error`) |
+## `include_attributes` Parameter
 
-#### Example
+`getPropertyValues` accepts an `include_attributes` parameter (set to `'true'` as a string) that returns additional metadata on each value. This is essential for relationship properties like `appears_in`, where attributes carry entity-level sentiment scores and article URLs.
 
-**Request:**
+**Note:** The generated TypeScript client types don't include `include_attributes` in the parameter type. Pass it as an extra property — the API accepts it:
 
-```
-GET /entities/00416400910670863867
+```typescript
+const res = await client.getPropertyValues({
+    eids: JSON.stringify([neid]),
+    pids: JSON.stringify([appearsInPid]),
+    include_attributes: 'true',  // Not in TS types, but API accepts it
+} as any);
 ```
 
-**Response:**
+Attribute values are keyed by **numeric PID**, not by name. Resolve attribute names to PIDs via the schema before accessing them.
 
-```json
-{"report": {"neid": "00416400910670863867", "name": "Apple", "aliases": ["AAPL", "APPLE", "APPLE INC", "Apple Inc"], "type": "organization"}}
-```
+<!-- BEGIN GENERATED CONTENT -->
 
----
+## Endpoints
 
-### Get entity report
+### Get entity details
 
-`GET /reports/{neid}`
+`GET /entities/{neid}`
 
-Get a report about a named entity including name, aliases, and type. Response is cached for 5 minutes.
+Get details about a named entity including name, aliases, and type. This is an alias for /reports/{neid}. Response is cached for 5 minutes.
 
 #### Guidance
 
@@ -226,7 +211,7 @@ Response is wrapped in a 'report' container object. Access entity data via respo
 
 | Status | Description |
 |--------|-------------|
-| 200 | Entity report (`GetNamedEntityReportResponse`) |
+| 200 | Entity details (`GetNamedEntityReportResponse`) |
 | 400 | Invalid NEID (`Error`) |
 | 404 | Entity not found (`Error`) |
 | 500 | Internal server error (`Error`) |
@@ -236,7 +221,7 @@ Response is wrapped in a 'report' container object. Access entity data via respo
 **Request:**
 
 ```
-GET /reports/00416400910670863867
+GET /entities/00416400910670863867
 ```
 
 **Response:**
@@ -247,54 +232,6 @@ GET /reports/00416400910670863867
 
 ---
 
-### Find entities by expression
-
-`POST /elemental/find`
-
-Search for entities using a powerful expression language. The expression parameter supports complex nested queries with logical operators, geographic constraints, property comparisons, and more.
-
-#### Guidance
-
-CRITICAL: This endpoint REQUIRES Content-Type: application/x-www-form-urlencoded. Sending a JSON body will fail with 400 error. The expression parameter must be URL-encoded form data, not a JSON request body. For the full expression language reference including all expression types, comparison operators, and examples, see find.md.
-
-#### Request Body
-
-**Content-Type:** `application/x-www-form-urlencoded`
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| expression | string | yes | JSON-encoded expression object defining the search criteria |
-| deadline | any | no | Response deadline in milliseconds or duration format |
-| limit | integer | no | Maximum number of entity IDs to return in first response |
-
-#### Responses
-
-| Status | Description |
-|--------|-------------|
-| 200 | Find operation successful (`FindResponse`) |
-| 400 | Bad request - invalid parameters or malformed expression (`Error`) |
-| 500 | Internal server error (`Error`) |
-| 501 | Elemental API capability not enabled (`Error`) |
-
-#### Example
-
-**Request:**
-
-```
-POST /elemental/find
-Content-Type: application/x-www-form-urlencoded
-
-expression={"type":"is_type","is_type":{"fid":10}}&limit=5
-```
-
-**Response:**
-
-```json
-{"op_id": "98cc54e9-0108-4361-9c96-18ea97cda7a2", "follow_up": true, "eids": ["01601807036815568643", "08115040994665529432", "02045070050429461063"]}
-```
-
----
-
 ### Get property values for entities
 
 `POST /elemental/entities/properties`
@@ -361,18 +298,6 @@ The named entity report
 | neid | string | Named Entity ID |
 | type | string | Entity type (flavor) |
 
-### FindResponse
-
-| Field | Type | Description |
-|-------|------|-------------|
-| find | `FindData` |  |
-
-### FindData
-
-| Field | Type | Description |
-|-------|------|-------------|
-| **eids** | string[] | Array of 20-character entity IDs matching the search expression |
-
 ### GetPropertyValuesResponse
 
 | Field | Type | Description |

package/skills/elemental-api/find.md

@@ -5,8 +5,8 @@ The `/elemental/find` endpoint searches for entities using a JSON expression lan
 ## When to Use
 
 - You need to search for entities matching specific criteria (type, property values, relationships)
-- You need to combine multiple filters (e.g., "ships with name containing PACIFIC")
-- You need to find entities connected to a given entity via the knowledge graph
+- You need to combine multiple filters
+- You need to find entities connected to a given entity via the relationship links
 
 ## Expression Structure
 
@@ -124,13 +124,13 @@ Content-Type: application/x-www-form-urlencoded
 expression={"type":"comparison","comparison":{"operator":"string_like","pid":8,"value":"Apple"}}
 ```
 
-### Find ships with "PACIFIC" in the name (combined AND)
+### Find organizations with "Global" in the name (combined AND)
 
 ```
 POST /elemental/find
 Content-Type: application/x-www-form-urlencoded
 
-expression={"type":"and","and":[{"type":"is_type","is_type":{"fid":1}},{"type":"comparison","comparison":{"operator":"string_like","pid":8,"value":"PACIFIC"}}]}&limit=50
+expression={"type":"and","and":[{"type":"is_type","is_type":{"fid":10}},{"type":"comparison","comparison":{"operator":"string_like","pid":8,"value":"Global"}}]}&limit=50
 ```
 
 ### Find entities linked to a specific entity
@@ -261,6 +261,12 @@ expression={"type":"is_type","is_type":{"fid":10}}&limit=5
 |-------|------|-------------|
 | **is_type** | `IsType` |  |
 
+### LinkedExpression
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **linked** | `Linked` |  |
+
 ### Comparison
 
 | Field | Type | Description |
@@ -276,4 +282,13 @@ expression={"type":"is_type","is_type":{"fid":10}}&limit=5
 |-------|------|-------------|
 | **fid** | integer | Flavor identifier (FID) representing entity type |
 
+### 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/graph.md

@@ -1,6 +1,6 @@
 # Graph
 
-The graph endpoints are focused on "graph analysis", providing insights into relationships between different entities. This includes, but is not limited to, visual rendering of a graph.
+The graph endpoints are focused on "graph analysis". This includes, but is not limited to, visual rendering of a graph.
 
 ## When to Use
 
@@ -32,7 +32,7 @@ Get nodes and edges layout data for visualizing a relationship graph. Response i
 
 #### 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.
+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
 
@@ -77,7 +77,7 @@ Get list of neighboring entities in the relationship graph, optionally filtered
 
 #### 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).
+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
 

package/skills/elemental-api/overview.md

@@ -4,26 +4,55 @@ The Elemental API provides access to the Lovelace Knowledge Graph through the Qu
 
 ## Core Concepts
 
-### Named Entity ID (NEID)
+### Entities
+
+Every entity has:
+- **NEID** — a unique Named Entity ID (stable identifier)
+- **Name** — human-readable label (may have aliases)
+- **Flavor** — the entity type (e.g. "organization", "person", "country", "vessel", "event")
+
+#### Named Entity ID (NEID)
+
 Every entity in the system has a unique identifier called a NEID. Most API calls require a NEID, so your first step is usually looking up an entity by name to get its NEID.
 
 **Format**: 20-character numeric string with zero-padding. Example: `00416400910670863867`
 
 When normalizing NEIDs, always pad with leading zeros to exactly 20 characters.
 
+NEIDs are stable and can be persisted long-term, but may occasionally change if the database is rebuilt or the application switches databases. When an NEID becomes invalid (e.g., resolution returns no results), re-resolve the entity using its canonical name from the previous query result, then redo any downstream operations that depended on it. NEIDs should NEVER be hardcoded in source code.
+
 **Note**: The terms "eid" and "neid" are interchangeable throughout the API. Some endpoints use `neid` and others use `eid`, but they refer to the same entity identifier.
 
-### Mention Code (MCODE)
-A mention is a specific reference to an entity in an article. Each mention has a unique MCODE that links the entity, article, and context together.
+### Properties
+
+Key-value facts attached to entities, scoped by flavor.
+
+Examples: nationality, birth_date, industry, total_revenue, employee_count.
+
+Use the schema to discover which properties are available for
+a given entity type.
 
-**Format**: `{neid}:{artid}` with colon separator. Example: `00416400910670863867:05433395856363393596`
+## Relationships
 
-### Time Ranges
-Most endpoints accept `start` and `end` parameters for filtering by date.
+Directed, typed edges between two entities:
+- **Type** — e.g. "owns", "board_member_of", "subsidiary_of", "appears_in"
+- **Direction** — relationships go from source (subject) to target (object)
 
-**Required format**: Full ISO 8601 with timezone.
-- Correct: `2026-01-28T00:00:00Z`
-- Incorrect: `2026-01-28` (missing time and timezone)
+## Attributes
+
+Metadata attached to relationships. For example, the "participant" relationship
+connecting an entity to an event carries:
+- **role** — the entity's role in the event (e.g. "acquirer", "target", "plaintiff")
+- **sentiment** — an impact score for the entity's involvement
+
+## Events
+
+Structured occurrences extracted from source data, each with:
+- **Category** — e.g. "Bankruptcy", "IPO", "Layoffs", "Acquisition"
+- **Date** — when the event occurred (YYYY-MM-DD, or YYYY-MM / YYYY for partial dates)
+- **Description** — detailed, objective description of the event
+- **Likelihood** — temporal status: confirmed, ongoing, likely, or speculative
+- **Participants** — entities involved, each with a role and sentiment score
 
 ## Endpoint Categories
 
@@ -31,21 +60,16 @@ Most endpoints accept `start` and `end` parameters for filtering by date.
 |------|------------------------|
 | [entities.md](entities.md) | Look up entities by name, get details and properties |
 | [find.md](find.md) | Search for entities by type, property values, or relationships using the expression language |
-| [sentiment.md](sentiment.md) | Get sentiment scores and trends for an entity |
-| [articles.md](articles.md) | Get articles that mention an entity, article content, titles, summaries |
-| [events.md](events.md) | Find events involving an entity (mergers, lawsuits, etc.) |
-| [relationships.md](relationships.md) | Find connections between entities |
+| [schema.md](schema.md) | Understand the data model: entity types (flavors), properties, and their metadata |
 | [graph.md](graph.md) | Generate visual network graphs |
-| [server.md](server.md) | Check server status and capabilities, as well as schema info including flavors and properties. |
-| [llm.md](llm.md) | (Not currently available) AI-assisted queries |
+| [server.md](server.md) | Check server status and capabilities |
 
 ## Common Workflows
 
-### "What's the sentiment for Apple?"
-1. `entities.md` → Look up "Apple" to get NEID
-2. `sentiment.md` → Query sentiment with the NEID
-
+### "Find all organizations in a specific sector"
+1. `schema.md` → Check available properties and flavors
+2. `find.md` → Use the expression language to search by property values
 
-### "How are Microsoft and OpenAI connected?"
-1. `entities.md` → Look up both companies to get NEIDs
-2. `relationships.md` → Query links between the two NEIDs
+### "What companies are related to Apple?"
+1. `entities.md` → Look up "Apple" to get NEID
+2. `find.md` → Query linked entities to find related entities

package/skills/elemental-api/schema.md

@@ -12,7 +12,7 @@ The schema defines the data model: what **entity types** (flavors) exist and wha
 ## Key Concepts
 
 - **Flavors** = Entity types. Each entity belongs to exactly one flavor.
-  - Examples: "ship" (FID 1), "organization" (FID 10), "person" (FID 9)
+  - Examples: "organization" (FID 10), "person" (FID 9), "financial_instrument" (FID 3)
   - Identified by a Flavor ID (FID) — a small integer
 - **Properties** = Attributes that entities can have. Each property has:
   - A Property ID (PID) — a small integer
@@ -30,8 +30,8 @@ There are two schema endpoints with different levels of detail:
 | `GET /elemental/metadata/schema` | fid, name only | pid, name, type only |
 
 **Use `/schema`** (recommended) when you need:
-- Human-readable display names (e.g., "Ship" vs "ship")
-- Units of measurement (e.g., "m", "kg", "knots")
+- Human-readable display names (e.g., "Organization" vs "organization")
+- Units of measurement (e.g., "m", "kg")
 - Which flavors a property applies to (`domain_findexes`)
 
 **Use `/elemental/metadata/schema`** when you just need basic FID/PID to name mappings.
@@ -48,28 +48,6 @@ There are two schema endpoints with different levels of detail:
 2. **Find entities of a type** → `POST /elemental/find` with `is_type` expression
 3. **Get property values** → `POST /elemental/entities/properties` to fetch values for those entities
 
-## Common Properties by Entity Type
-
-This is a quick-reference for writing first-pass code. **The schema endpoint
-is the source of truth** — always call `GET /schema` to get actual PIDs and
-confirm which properties exist in a given deployment. Property availability
-varies by dataset.
-
-| Entity Type | Common Properties |
-|---|---|
-| **organization** | `name`, `country`, `ticker`, `industry`, `business_sector`, `sic_code`, `state_of_incorporation`, `mailing_address`, `business_phone`, `company_cik` |
-| **person** | `name`, `country`, `nationality`, `birth_date`, `position`, `person_cik`, `job_title` |
-| **financial_instrument** | `name`, `ticker`, `security_type`, `instrument_type`, `cusip_number` |
-| **document** (SEC filings) | `name`, `title`, `form_type`, `filing_date`, `report_date`, `accession_number`, `form_type_detail` |
-| **article** | `name`, `title`, `sentiment` |
-| **event** | `name`, `category`, `date`, `description`, `likelihood` |
-| **location** | `name`, `fixedLatitude`, `fixedLongitude` |
-
-**Relationship properties** (type `data_nindex`) link entities to each other.
-Common ones for organizations: `acquires`, `owns`, `competes_with`,
-`partnered_with`, `does_business_with`, `is_part_of`, `issues`, `has_subsidiary`.
-For people: `works_at`, `head_of`, `is_director`, `is_officer`, `is_colleague_of`.
-
 <!-- BEGIN GENERATED CONTENT -->
 
 ## Endpoints
@@ -102,7 +80,7 @@ GET /schema
 **Response:**
 
 ```json
-{"flavors": [{"findex": 1, "name": "ship", "singular_display_name": "Ship", "plural_display_name": "Ships"}, {"findex": 10, "name": "organization", "singular_display_name": "Organization", "plural_display_name": "Organizations"}], "properties": [{"pid": 8, "name": "name", "display_name": "Name", "value_type": "data_cat"}, {"pid": 22, "name": "length", "display_name": "Length", "unit": "m", "value_type": "data_float"}]}
+{"flavors": [{"findex": 9, "name": "person", "singular_display_name": "Person", "plural_display_name": "People"}, {"findex": 10, "name": "organization", "singular_display_name": "Organization", "plural_display_name": "Organizations"}], "properties": [{"pid": 8, "name": "name", "display_name": "Name", "value_type": "data_cat"}, {"pid": 15, "name": "industry", "display_name": "Industry", "value_type": "data_cat"}]}
 ```
 
 ---
@@ -210,7 +188,7 @@ Returns comprehensive schema information including all entity types (flavors), p
 
 #### Guidance
 
-Response is wrapped in a 'schema' container object. Access flavors and properties via response.schema.flavors and response.schema.properties. Flavors contain: fid (unique identifier), name (e.g., 'ship', 'aircraft'). Properties contain: pid (unique identifier), name (e.g., 'latitude', 'name'), type (e.g., 'data_float', 'data_int', 'data_cat', 'data_nindex').
+Response is wrapped in a 'schema' container object. Access flavors and properties via response.schema.flavors and response.schema.properties. Flavors contain: fid (unique identifier), name (e.g., 'organization', 'person'). Properties contain: pid (unique identifier), name (e.g., 'name', 'industry'), type (e.g., 'data_float', 'data_int', 'data_cat', 'data_nindex').
 
 #### Responses
 
@@ -231,7 +209,7 @@ GET /elemental/metadata/schema
 **Response:**
 
 ```json
-{"op_id": "40dc4cd9-f1b2-4b5c-85d0-c7c61256e5d9", "follow_up": false, "schema": {"flavors": [{"fid": 1, "name": "ship"}, {"fid": 2, "name": "handset"}, {"fid": 10, "name": "organization"}], "properties": [{"pid": 1, "name": "mmsi", "type": "data_cat"}, {"pid": 8, "name": "name", "type": "data_cat"}]}}
+{"op_id": "40dc4cd9-f1b2-4b5c-85d0-c7c61256e5d9", "follow_up": false, "schema": {"flavors": [{"fid": 9, "name": "person"}, {"fid": 10, "name": "organization"}, {"fid": 3, "name": "financial_instrument"}], "properties": [{"pid": 8, "name": "name", "type": "data_cat"}, {"pid": 15, "name": "industry", "type": "data_cat"}]}}
 ```
 
 ---
@@ -279,10 +257,11 @@ Entity type (flavor) with human-readable display names
 
 | Field | Type | Description |
 |-------|------|-------------|
+| description | string | Semantic description of what this flavor represents |
 | findex | integer | Unique flavor identifier (same as fid in other endpoints) |
 | name | string | Flavor name (internal identifier) |
-| plural_display_name | string | Human-readable plural name (e.g., "Ships") |
-| singular_display_name | string | Human-readable singular name (e.g., "Ship") |
+| plural_display_name | string | Human-readable plural name (e.g., "People") |
+| singular_display_name | string | Human-readable singular name (e.g., "Person") |
 
 ### SchemaProperty
 
@@ -290,6 +269,7 @@ Property with display name, unit, and domain information
 
 | Field | Type | Description |
 |-------|------|-------------|
+| description | string | Semantic description of what this property represents |
 | display_name | string | Human-readable property name |
 | domain_findexes | integer[] | Flavor IDs (findexes) that can have this property |
 | name | string | Property name (internal identifier) |