@yottagraph-app/aether-instructions 1.1.22 → 1.1.24

package/skills/elemental-api/overview.md

@@ -1,6 +1,27 @@
 # Elemental API Overview
 
-The Elemental API provides access to the Lovelace Knowledge Graph through the Query Server. This document explains core concepts and guides you to the right endpoint documentation.
+The Elemental API provides access to the Lovelace Knowledge Graph through the
+Query Server. This document explains core concepts and guides you to the right
+documentation.
+
+## Access Paths
+
+The knowledge graph is accessible via two interfaces:
+
+- **MCP Tools** — Agent-friendly tools with built-in entity resolution, fuzzy
+  matching on all names, and automatic citation tracking. Ideal for interactive
+  exploration and Cursor agent workflows. See [mcp.md](mcp.md).
+- **REST API** — Programmatic endpoints for building app features with
+  `useElementalClient()`. Requires manual PID lookups, NEID zero-padding, and
+  expression construction. See the endpoint files below.
+
+Both access the same data. Choose based on your context: MCP when tools are
+connected, REST when building application code.
+
+**Recommended workflow when building features:**
+1. **MCP first** — explore the schema and test data access interactively
+2. **curl/CLI** — verify exact REST request/response shapes (especially for `/elemental/find` expressions)
+3. **Implement** — write application code with confidence in the API behavior
 
 ## Core Concepts
 
@@ -9,43 +30,57 @@ The Elemental API provides access to the Lovelace Knowledge Graph through the Qu
 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")
+- **Flavor** — the entity type (e.g. "organization", "person", "financial_instrument", "fund_account", "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.
+Every entity in the system has a unique identifier called a NEID. REST API calls
+require a NEID, so your first step is usually looking up an entity by name. MCP
+tools accept names directly and resolve them automatically.
 
 **Format**: 20-character numeric string with zero-padding. Example: `00416400910670863867`
 
-When normalizing NEIDs, always pad with leading zeros to exactly 20 characters.
+When normalizing NEIDs for the REST API, always pad with leading zeros to exactly
+20 characters. MCP tools handle this automatically.
 
 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.
+**Note**: The terms "eid", "neid", and "nindex" are interchangeable throughout
+the system. Some endpoints use `neid`, others use `eid`, and internal tools may
+use `nindex` — they all refer to the same entity identifier.
 
 ### Properties
 
-Key-value facts attached to entities, scoped by flavor.
+Timestamped key-value facts attached to entities, scoped by flavor. Each property
+value records **when** it was observed (`recorded_at`), so entities can have
+multiple values for the same property over time — one per filing, extraction, or
+data ingestion event.
 
-Examples: nationality, birth_date, industry, total_revenue, employee_count.
+Examples: nationality, birth_date, industry, total_revenue, employee_count,
+sources_of_funds, computation_date_valuation, internal_rate_of_return.
 
-Use the schema to discover which properties are available for
-a given entity type.
+Use the schema to discover which properties are available for a given entity type.
+Property names are fuzzy-matched in MCP tools (e.g. "revenue" matches
+"total_revenue"); the REST API requires exact PIDs from the schema.
 
-## Relationships
+### Relationships
 
 Directed, typed edges between two entities:
-- **Type** — e.g. "owns", "board_member_of", "subsidiary_of", "appears_in"
+- **Type** — e.g. "owns", "board_member_of", "subsidiary_of", "trustee_of", "appears_in"
 - **Direction** — relationships go from source (subject) to target (object)
 
-## Attributes
+In the schema, relationships are properties with type `data_nindex` — the value is
+another entity's identifier. See [relationships.md](relationships.md) for
+traversal patterns using both MCP and REST.
+
+### 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
+### Events
 
 Structured occurrences extracted from source data, each with:
 - **Category** — e.g. "Bankruptcy", "IPO", "Layoffs", "Acquisition"
@@ -54,22 +89,40 @@ Structured occurrences extracted from source data, each with:
 - **Likelihood** — temporal status: confirmed, ongoing, likely, or speculative
 - **Participants** — entities involved, each with a role and sentiment score
 
-## Endpoint Categories
+### Citations
+
+Property values and relationships carry **citation markers** (e.g. `[1]`, `[2]`)
+referencing the data sources that back each fact. Citations are tracked
+automatically in MCP sessions. Retrieve the full bibliography (titles, URLs,
+publication dates) with `elemental_get_bibliography` or by reading the
+`session://elemental/bibliography` resource.
+
+## File Guide
 
 | File | Use When You Need To... |
 |------|------------------------|
-| [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 |
+| [mcp.md](mcp.md) | Use MCP tools for interactive exploration (tools, resources, prompts) |
+| [entities.md](entities.md) | Look up entities by name, get details and properties (REST) |
+| [find.md](find.md) | Search for entities by type, property values, or relationships (REST expression language) |
 | [schema.md](schema.md) | Understand the data model: entity types (flavors), properties, and their metadata |
+| [relationships.md](relationships.md) | Traverse entity relationships (both MCP and REST patterns) |
 | [graph.md](graph.md) | Generate visual network graphs |
 | [server.md](server.md) | Check server status and capabilities |
 
 ## Common Workflows
 
+### "What data is available for a bond / financial instrument?"
+- **MCP**: `elemental_get_schema(flavor: "financial_instrument")` → see all properties and relationships
+- **REST**: `GET /schema` → find the FID for "financial_instrument", then inspect its properties
+
 ### "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
+- **MCP**: `elemental_get_related(entity: "sector name", related_flavor: "organization")`
+- **REST**: `schema.md` → find PIDs; `find.md` → search by property values
 
 ### "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
+- **MCP**: `elemental_get_related(entity: "Apple", related_flavor: "organization")`
+- **REST**: `entities.md` → look up "Apple" to get NEID; `find.md` → linked expression
+
+### "Who is the trustee of this bond?"
+- **MCP**: `elemental_get_related(entity_id: {id_type: "neid", id: "08242646876499346416"}, related_flavor: "organization", relationship_types: ["trustee_of"], direction: "incoming")`
+- **REST**: See [relationships.md](relationships.md) for the multi-step traversal pattern

package/skills/elemental-api/relationships.md

@@ -0,0 +1,163 @@
+# Relationships
+
+Relationships are directed, typed edges between entities in the knowledge graph.
+They connect a **source** (subject) entity to a **target** (object) entity via a
+named relationship type.
+
+## When to Use
+
+- You need to find entities connected to a given entity (e.g. "who owns this company?")
+- You need to determine how two entities are connected
+- You need to traverse the graph along specific relationship types
+
+## Key Concepts
+
+### Relationship Properties
+
+In the schema, relationships are properties with type `data_nindex` — the value
+is another entity's identifier rather than a scalar. Use `elemental_get_schema`
+(MCP) or `GET /schema` (REST) to discover which relationships exist for a flavor:
+
+- **domain_flavors** — which entity types can be the source of this relationship
+- **target_flavors** — which entity types can be the target
+
+For example, `trustee_of` might have domain `["organization"]` and target
+`["financial_instrument"]`, meaning organizations can be trustees of financial
+instruments.
+
+### Direction
+
+Relationships are directional. When querying, direction controls which side of
+the edge you're searching from:
+
+| Direction | Meaning | Example |
+|-----------|---------|---------|
+| `outgoing` | Center entity is the **subject** | "What does Apple own?" (Apple → owns → target) |
+| `incoming` | Center entity is the **object** | "Who owns Apple?" (source → owns → Apple) |
+| `both` | Union of outgoing and incoming | "All ownership relationships involving Apple" |
+
+### Common Relationship Types
+
+Relationship types vary by dataset. Use schema discovery to find what's available.
+Common examples:
+
+- `owns`, `owns_stake_in` — ownership
+- `board_member_of`, `is_director`, `is_officer` — corporate governance
+- `subsidiary_of` — corporate structure
+- `trustee_of` — fiduciary relationships
+- `appears_in` — entity appears in an article
+- `participant` — entity participates in an event
+
+## Traversal via MCP Tools
+
+MCP tools handle PID resolution, NEID formatting, and entity name lookup automatically.
+
+### Find connected entities
+
+Use `elemental_get_related` to find entities connected to a center entity:
+
+```
+elemental_get_related(
+  entity: "Apple",
+  related_flavor: "person",
+  relationship_types: ["is_officer"],
+  direction: "incoming",
+  related_properties: ["nationality"]
+)
+```
+
+This finds people who are officers of Apple, with their nationality.
+
+### Get relationship counts between two entities
+
+Use `elemental_get_relationships` to see how two specific entities are connected:
+
+```
+elemental_get_relationships(
+  source: {entity: "Bank of New York Mellon"},
+  target: {entity_id: {id_type: "neid", id: "08242646876499346416"}}
+)
+```
+
+Returns relationship types (e.g. `trustee_of`) with temporal counts showing
+when the relationship was observed.
+
+### Discover available relationships
+
+Use `elemental_get_schema` to find what relationship types exist for a flavor:
+
+```
+elemental_get_schema(flavor: "organization")
+→ relationships: [{name: "owns", target_flavors: ["organization"]}, ...]
+
+elemental_get_schema(flavor: "organization", query: "trustee")
+→ relationships: [{name: "trustee_of", target_flavors: ["financial_instrument"]}, ...]
+```
+
+## Traversal via REST API
+
+The REST API requires manual PID lookups, NEID zero-padding, and expression
+construction. See find.md for the full expression language and entities.md for
+property value retrieval.
+
+### Graph-layer traversal (linked expression)
+
+For entity types that are first-class graph nodes (person, organization, location),
+use `POST /elemental/find` with a `linked` expression:
+
+```
+POST /elemental/find
+Content-Type: application/x-www-form-urlencoded
+
+expression={"type":"linked","linked":{"to_entity":"00416400910670863867","distance":1,"pids":[42],"direction":"incoming"}}&limit=50
+```
+
+The `pids` array specifies which relationship types to follow (e.g. PID 42 for
+`is_officer`). Look up PIDs via `GET /schema`.
+
+Combine with `is_type` to filter results by flavor:
+
+```json
+{
+  "type": "and",
+  "and": [
+    {"type": "linked", "linked": {"to_entity": "00416400910670863867", "distance": 1, "direction": "incoming"}},
+    {"type": "is_type", "is_type": {"fid": 9}}
+  ]
+}
+```
+
+### Property-layer traversal (getPropertyValues)
+
+For entity types that are attached as property values (documents, filings,
+financial instruments), use `POST /elemental/entities/properties` with the
+relationship PID:
+
+```
+POST /elemental/entities/properties
+Content-Type: application/x-www-form-urlencoded
+
+eids=["00416400910670863867"]&pids=[203]
+```
+
+Relationship property values (`data_nindex` type) are raw entity identifiers.
+**You must zero-pad them to 20 characters** to form valid NEIDs for subsequent
+API calls:
+
+```typescript
+const rawValue = "4926132345040704022";  // 19 chars
+const neid = rawValue.padStart(20, '0'); // "04926132345040704022"
+```
+
+MCP tools handle this padding automatically — this is only needed with the REST API.
+
+## Tips
+
+- Always discover relationship types from the schema first — don't hardcode
+  relationship names or PIDs.
+- Use `direction` deliberately. "Who owns X?" is `incoming`; "What does X own?"
+  is `outgoing`. The default `both` is convenient but may return noisy results.
+- Relationship property values from the REST API need NEID zero-padding.
+  MCP tools handle this automatically.
+- When combining relationship traversal with type filtering, wrap the `linked`
+  expression in an `and` with `is_type` (see find.md for the expression language).

package/skills/elemental-api/schema.md

@@ -19,15 +19,16 @@ The schema defines the data model: what **entity types** (flavors) exist and wha
   - A name (e.g., "name", "length", "mailing_address", "acquires")
   - A data type (e.g., "data_cat" for text, "data_float" for numbers)
   - Domain flavors — which entity types can have this property
+- **Attribute Types** = Metadata that can be attached to property values (e.g., sentiment scores, URLs, snippets). When `getPropertyValues` returns `include_attributes=true`, the attribute keys are numeric strings representing Attribute IDs (AIDs). **AIDs are a separate namespace from PIDs** — for example, PID 15 is "industry" but AID 15 is "sentiment". Use the schema `attributes` array to resolve these.
 
 ## Choosing a Schema Endpoint
 
 There are two schema endpoints with different levels of detail:
 
-| Endpoint | Flavors include | Properties include |
-|----------|-----------------|-------------------|
-| `GET /schema` | findex, name, singular/plural display names | pid, name, display_name, unit, value_type, domain_findexes, target_findexes |
-| `GET /elemental/metadata/schema` | fid, name only | pid, name, type only |
+| Endpoint | Flavors include | Properties include | Attributes include |
+|----------|-----------------|-------------------|--------------------|
+| `GET /schema` | findex, name, singular/plural display names | pid, name, display_name, unit, value_type, domain_findexes, target_findexes | aid, name, atype, applicable_properties, description |
+| `GET /elemental/metadata/schema` | fid, name only | pid, name, type only | aid, name, atype, applicable_properties, description |
 
 **Use `/schema`** (recommended) when you need:
 - Human-readable display names (e.g., "Organization" vs "organization")
@@ -39,9 +40,30 @@ There are two schema endpoints with different levels of detail:
 ## Tips
 
 - Many API responses return only FIDs and PIDs (not names) — use the schema to translate these to human-readable names
+- When `getPropertyValues` returns attributes with numeric keys (e.g., `"15": -0.3`), look up the key in the schema `attributes` array by `aid` to find the name (e.g., `aid: 15` → "sentiment")
 - Cache schema results; the data model changes infrequently
 - Use `/elemental/metadata/properties/{pid}/summary` to understand value distributions before filtering
 
+### Flavor ID field names: `findex` vs `fid`
+
+The flavor identifier field has **different names** depending on the endpoint:
+
+| Endpoint | Field name | Example |
+|----------|-----------|---------|
+| `GET /schema` | `findex` | `{"findex": 12, "name": "article"}` |
+| `GET /elemental/metadata/schema` | `fid` | `{"fid": 12, "name": "article"}` |
+
+These contain the same value — just different keys. When writing code that
+consumes schema responses, always handle both:
+
+```typescript
+const articleFlavor = flavors.find(f => f.name === 'article');
+const articleFid = articleFlavor?.fid ?? articleFlavor?.findex ?? null;
+```
+
+The `is_type` expression in `find.md` always uses `fid` regardless of which
+schema endpoint you used to discover the value.
+
 ## Common Workflow
 
 1. **Get the schema** → `GET /schema` to learn available flavors and properties
@@ -56,11 +78,11 @@ There are two schema endpoints with different levels of detail:
 
 `GET /schema`
 
-Returns detailed schema information including entity types (flavors) with display names and properties with display names, units, and domain/target relationships. This endpoint provides more detail than /elemental/metadata/schema.
+Returns detailed schema information including entity types (flavors) with display names, properties with display names, units, and domain/target relationships, and quad attribute types. This endpoint provides more detail than /elemental/metadata/schema.
 
 #### Guidance
 
-This endpoint returns richer metadata than /elemental/metadata/schema, including display names, units, and relationship domains. Use this when you need human-readable names or property metadata.
+This endpoint returns richer metadata than /elemental/metadata/schema, including display names, units, relationship domains, and attribute type definitions. Use this when you need human-readable names or property metadata. The attributes array maps numeric attribute IDs (AIDs) to names — use it to resolve the numeric keys returned by getPropertyValues with include_attributes=true.
 
 #### Responses
 
@@ -80,7 +102,7 @@ GET /schema
 **Response:**
 
 ```json
-{"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"}]}
+{"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"}], "attributes": [{"aid": 15, "name": "sentiment", "atype": "float", "applicable_properties": ["appears_in", "participant", "sentiment"], "description": "A sentiment score in [-1, +1]."}]}
 ```
 
 ---
@@ -251,6 +273,18 @@ GET /elemental/metadata/properties/8/summary
 
 ## Types
 
+### SchemaAttribute
+
+Quad attribute type used as keys in property value attributes
+
+| Field | Type | Description |
+|-------|------|-------------|
+| aid | integer | Unique attribute type identifier. Appears as a string key (e.g., "15") in property value attributes. |
+| applicable_properties | string[] | Property names that commonly carry this attribute (e.g., ["appears_in", "participant"]) |
+| atype | string | Attribute data type: "float", "int", "bool", or "blob" (string values) |
+| description | string | Semantic description of what this attribute represents |
+| name | string | Attribute name (e.g., "sentiment", "url", "snippet") |
+
 ### SchemaFlavor
 
 Entity type (flavor) with human-readable display names
@@ -280,10 +314,11 @@ Property with display name, unit, and domain information
 
 ### SchemaResponse
 
-Detailed schema response with entity types (flavors) and properties including display names, units, and domains
+Detailed schema response with entity types (flavors), properties, and quad attribute types
 
 | Field | Type | Description |
 |-------|------|-------------|
+| attributes | `SchemaAttribute`[] | Array of quad attribute types that appear as keys in property value attributes (when include_attributes=true). These use a separate ID namespace (AID) from property PIDs. |
 | flavors | `SchemaFlavor`[] | Array of entity types (flavors) with display names |
 | properties | `SchemaProperty`[] | Array of properties with display names, units, and domain information |
 
@@ -328,6 +363,17 @@ Detailed schema response with entity types (flavors) and properties including di
 |-------|------|-------------|
 | **flavors** | `Flavor`[] | Array of entity types (flavors) available in the system |
 | **properties** | `Property`[] | Array of properties available in the system |
+| attributes | `Attribute`[] | Array of quad attribute types. These map the numeric keys in property value attributes (from include_attributes=true) to human-readable names. AIDs are a separate namespace from property PIDs. |
+
+### Attribute
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **aid** | integer | Unique attribute type identifier. Appears as a string key (e.g., "15") in property value attributes. |
+| **name** | string | Attribute name |
+| **atype** | string | Attribute data type. Values: `float`, `int`, `bool`, `blob` |
+| applicable_properties | string[] | Property names that commonly carry this attribute |
+| description | string | Semantic description of what this attribute represents |
 
 ### Flavor