@yottagraph-app/elemental-api-skill 1.0.0

package/skill/find.md

@@ -0,0 +1,279 @@
+# Find (Expression Language)
+
+The `/elemental/find` endpoint searches for entities using a JSON expression language. Expressions can filter by entity type, compare property values, traverse relationships, and combine conditions with logical operators.
+
+## 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
+
+## Expression Structure
+
+Every expression is a JSON object with a `type` field that determines which other fields are required:
+
+```json
+{"type": "<expression_type>", "<expression_type>": { ... }}
+```
+
+Expressions are passed as URL-encoded form data in the `expression` parameter (NOT as a JSON request body).
+
+## Expression Types
+
+| Type | Description | Key Fields | Status |
+|------|-------------|------------|--------|
+| `is_type` | Filter entities by type (flavor) | `is_type.fid` (integer) | Implemented |
+| `comparison` | Compare a property value | `comparison.operator`, `comparison.pid`, `comparison.value` | Partial -- see operator table below |
+| `linked` | Find entities linked via relationships | `linked.distance`, `linked.to_entity`, `linked.pids` | Implemented |
+| `and` | All sub-expressions must match | `and` (array of expressions) | Implemented |
+| `or` | At least one sub-expression must match | `or` (array of expressions) | Implemented |
+| `not` | Negate an expression | `not` (single expression) | Implemented |
+
+### `is_type` -- Filter by Entity Type
+
+Returns all entities of a given flavor (type). Look up FIDs via `GET /elemental/metadata/schema` (see schema.md).
+
+```json
+{"type": "is_type", "is_type": {"fid": 1}}
+```
+
+### `comparison` -- Compare Property Values
+
+Compares a property (identified by PID) against a value. Look up PIDs via the schema endpoints (see schema.md).
+
+```json
+{"type": "comparison", "comparison": {"operator": "string_like", "pid": 8, "value": "PACIFIC"}}
+```
+
+**Fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| operator | string | yes | One of: `string_like`, `eq`, `lt`, `gt`, `regex`, `has_value` |
+| pid | integer | yes | Property ID to compare (must be non-zero) |
+| value | any | depends | Value to compare against (not required for `has_value`) |
+| accept_imputed | boolean | no | Include imputed (inferred) values in the comparison (default: false). Parsed but not yet used by any operator. |
+
+**Operators:**
+
+| Operator | Description | Value Type | Status |
+|----------|-------------|------------|--------|
+| `string_like` | Case-insensitive substring match | string | Implemented (name property only) |
+| `has_value` | Property has any value (value field not needed) | n/a | Implemented |
+| `eq` | Equal to | string, number, or boolean | Implemented (type-aware) |
+| `lt` | Less than | number | Implemented (numeric properties only) |
+| `gt` | Greater than | number | Implemented (numeric properties only) |
+| `regex` | Regular expression match | string (regex pattern) | Not yet implemented |
+
+### `linked` -- Relationship Traversal
+
+Finds entities linked to a target entity through the knowledge graph. See relationships.md for more on entity relationships.
+
+```json
+{"type": "linked", "linked": {"to_entity": "00416400910670863867", "distance": 1}}
+```
+
+**Fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| distance | integer | yes | Maximum relationship distance to traverse (minimum 1) |
+| to_entity | string | no | Target entity ID (20-character zero-padded) |
+| pids | integer[] | no | Property IDs defining which relationship types to follow |
+| direction | string | no | Direction of traversal: `"outgoing"` (default) follows subject->value edges, `"incoming"` follows reverse (value->subject) edges, `"both"` unions both directions |
+
+### `and` / `or` / `not` -- Logical Operators
+
+Combine expressions with standard boolean logic. `and` and `or` take arrays of sub-expressions; `not` takes a single sub-expression.
+
+```json
+{"type": "and", "and": [
+  {"type": "is_type", "is_type": {"fid": 1}},
+  {"type": "comparison", "comparison": {"operator": "string_like", "pid": 8, "value": "PACIFIC"}}
+]}
+```
+
+```json
+{"type": "or", "or": [
+  {"type": "is_type", "is_type": {"fid": 1}},
+  {"type": "is_type", "is_type": {"fid": 2}}
+]}
+```
+
+```json
+{"type": "not", "not": {"type": "is_type", "is_type": {"fid": 1}}}
+```
+
+## Examples
+
+### Find all organizations
+
+```
+POST /elemental/find
+Content-Type: application/x-www-form-urlencoded
+
+expression={"type":"is_type","is_type":{"fid":10}}&limit=100
+```
+
+### Find entities with "Apple" in the name
+
+```
+POST /elemental/find
+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)
+
+```
+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
+```
+
+### Find entities linked to a specific entity
+
+```
+POST /elemental/find
+Content-Type: application/x-www-form-urlencoded
+
+expression={"type":"linked","linked":{"to_entity":"00416400910670863867","distance":1}}
+```
+
+### Exclude a type from results (NOT)
+
+```
+POST /elemental/find
+Content-Type: application/x-www-form-urlencoded
+
+expression={"type":"and","and":[{"type":"comparison","comparison":{"operator":"string_like","pid":8,"value":"Apple"}},{"type":"not","not":{"type":"is_type","is_type":{"fid":1}}}]}
+```
+
+## Tips
+
+- Always look up FIDs and PIDs from the schema first (see schema.md) rather than hardcoding values
+- Use `limit` to control result size; the response sets `follow_up: true` if more results are available
+- Expressions can be deeply nested -- combine `and`, `or`, and `not` freely
+- The `string_like` operator currently only works on the "name" property
+- The `lt` and `gt` operators work on numeric properties (`data_int`, `data_float`) only; using them on non-numeric properties will return an error
+- The `regex` comparison operator is defined in the schema but not yet implemented; using it will return an error
+- The `accept_imputed` field is accepted on comparison expressions but has no effect yet
+
+<!-- BEGIN GENERATED CONTENT -->
+
+## Endpoints
+
+### 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"]}
+```
+
+## Types
+
+### FindResponse
+
+| Field | Type | Description |
+|-------|------|-------------|
+| find | `FindData` |  |
+
+### FindData
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **eids** | string[] | Array of 20-character entity IDs matching the search expression |
+
+### Expression
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **type** | string | Type of expression. One of: is_type (filter by entity type), comparison (compare property values), linked (relationship traversal), and (logical AND), or (logical OR), not (logical NOT) |
+
+### AndExpression
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **and** | `Expression`[] | Array of expressions that must all be true |
+
+### OrExpression
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **or** | `Expression`[] | Array of expressions where at least one must be true |
+
+### NotExpression
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **not** | `Expression` | Expression to negate |
+
+### ComparisonExpression
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **comparison** | `Comparison` |  |
+
+### IsTypeExpression
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **is_type** | `IsType` |  |
+
+### Comparison
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **operator** | string | Comparison operator. One of: string_like (case-insensitive substring match), eq (equal to), lt (less than), gt (greater than), regex (regular expression match), has_value (property has any value, no value field needed) |
+| **pid** | integer | Property identifier (PID) to compare against |
+| value | any | Value to compare with (not required for has_value operator) |
+| accept_imputed | boolean | Whether to include imputed property values in comparison |
+
+### IsType
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **fid** | integer | Flavor identifier (FID) representing entity type |
+
+<!-- END GENERATED CONTENT -->

package/skill/graph.md

@@ -0,0 +1,239 @@
+# 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.
+
+## When to Use
+
+- You want to explore the entities that are most directly related to a given center entity (the "neighborhood" of entities)
+- You want to understand the relationships between entities and their neighbors
+- You need to create a visual representation of entity relationships
+- You need layout coordinates for rendering a graph
+
+## Key Concepts
+
+- **Graph Layout**: Computed positions for nodes (entities) and edges (relationships)
+- **Neighborhood**: The set of entities directly connected to a focal entity
+- **Neighborhood History**: How the neighborhood has changed over time
+
+## Tips
+
+- Start with a single focal entity (center NEID) to get its immediate neighborhood
+- Graph endpoints return relationships between entities as well as layout data optimized for visualization
+
+<!-- BEGIN GENERATED CONTENT -->
+
+## Endpoints
+
+### 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 neighborhood history
+
+`GET /graph/{center_neid}/neighborhood/history`
+
+Get historical data about influential neighbors for an entity over time. Response is cached for 5 minutes.
+
+#### Guidance
+
+Response includes the center entity itself in each day's results with an influence of 1.0.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| center_neid | string | yes | Center entity NEID |
+| size | integer | no | Maximum number of neighbors per day to return |
+| type | string[] | no | Filter by entity type(s) |
+
+#### Responses
+
+| Status | Description |
+|--------|-------------|
+| 200 | Historical neighborhood data (`GraphNeighborhoodHistoryResponse`) |
+| 400 | Invalid parameters (`Error`) |
+| 404 | Center entity not found (`Error`) |
+| 500 | Internal server error (`Error`) |
+
+#### Example
+
+**Request:**
+
+```
+GET /graph/00416400910670863867/neighborhood/history?size=3
+```
+
+**Response:**
+
+```json
+{"history": [{"date": "2025-12-30T00:00:00Z", "neighbors": [{"neid": "00416400910670863867", "influence": 1}, {"neid": "04015955446548481006", "influence": 0.072}]}]}
+```
+
+## Types
+
+### GraphEdge
+
+An edge between two nodes in the graph
+
+| Field | Type | Description |
+|-------|------|-------------|
+| article_ids | string[] | Article IDs associated with this edge |
+| label | string | Display label for the edge |
+| path | `GraphVector`[] | Path points for rendering the edge |
+| snippets | string[] | Text snippets describing the relationship |
+| source | string | Source node NEID |
+| target | string | Target node NEID |
+| weight | number | Weight/strength of the edge |
+
+### GraphLayoutResponse
+
+Response containing graph layout for visualization
+
+| Field | Type | Description |
+|-------|------|-------------|
+| edges | `GraphEdge`[] | List of graph edges |
+| nodes | `GraphNode`[] | List of graph nodes |
+
+### GraphNeighborhoodHistoryResponse
+
+Response containing historical influential neighbor data over time
+
+| Field | Type | Description |
+|-------|------|-------------|
+| history | `NeighborhoodHistoryEntry`[] | List of historical neighborhood entries |
+
+### 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) |
+
+### GraphNode
+
+A node in the graph layout
+
+| Field | Type | Description |
+|-------|------|-------------|
+| height | number | Height of the node for rendering |
+| isCentralNode | boolean | Whether this is the central/focus node |
+| label | string | Display label for the node |
+| neid | string | Named Entity ID |
+| width | number | Width of the node for rendering |
+| x | number | X coordinate in the layout |
+| y | number | Y coordinate in the layout |
+
+### GraphVector
+
+A 2D point in the graph layout
+
+| Field | Type | Description |
+|-------|------|-------------|
+| X | number | X coordinate |
+| Y | number | Y coordinate |
+
+### InfluenceEntry
+
+A neighbor and their influence score
+
+| Field | Type | Description |
+|-------|------|-------------|
+| influence | number | Influence score |
+| neid | string | Named Entity ID |
+
+### NeighborhoodHistoryEntry
+
+Influential neighbors for a specific date
+
+| Field | Type | Description |
+|-------|------|-------------|
+| date | string | Date of the history entry @Format date-time |
+| neighbors | `InfluenceEntry`[] | List of influential neighbors on this date |
+
+<!-- END GENERATED CONTENT -->

package/skill/llm.md

@@ -0,0 +1,18 @@
+# LLM (Ada)
+
+Ada is the AI assistant integrated into the Query Server, capable of answering natural language questions about the Knowledge Graph.
+
+## Status: Not Currently Available
+
+⚠️ The LLM/Ada endpoints are currently **excluded** from this skill because they are not functional in the current deployment. This documentation is a placeholder for when the feature becomes available.
+
+## Intended Use Cases (Future)
+
+- Natural language queries about entities ("Tell me about Apple's recent news")
+- Conversational exploration of the Knowledge Graph
+- AI-assisted analysis and summarization
+
+<!-- BEGIN GENERATED CONTENT -->
+
+
+<!-- END GENERATED CONTENT -->

package/skill/overview.md

@@ -0,0 +1,51 @@
+# 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.
+
+## Core Concepts
+
+### 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.
+
+**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.
+
+**Format**: `{neid}:{artid}` with colon separator. Example: `00416400910670863867:05433395856363393596`
+
+### Time Ranges
+Most endpoints accept `start` and `end` parameters for filtering by date.
+
+**Required format**: Full ISO 8601 with timezone.
+- Correct: `2026-01-28T00:00:00Z`
+- Incorrect: `2026-01-28` (missing time and timezone)
+
+## Endpoint Categories
+
+| 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 |
+| [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 |
+| [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 |
+
+## 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
+
+
+### "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