@yottagraph-app/elemental-api-skill 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottagraph-app/elemental-api-skill",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Elemental API skill documentation for AI agents",
   "repository": {
     "type": "git",

package/skill/SKILL.md

@@ -23,6 +23,44 @@ Use this skill when you need to:
 2. **Get information**: Use the NEID to query sentiment, mentions, relationships, or events
 3. **Dive deeper**: Retrieve full article details or explore connected entities
 
+## Common Workflows
+
+These examples show how to combine endpoints for multi-step data exploration.
+Properties with value type `data_nindex` are entity IDs — resolve them with
+another properties query to traverse the knowledge graph.
+
+### Explore a new dataset (schema-first discovery)
+
+New data sources are added regularly. Don't hardcode entity types or property
+names. Instead, discover them at runtime:
+
+1. Call `getSchema()` to list all entity types (flavors) and properties (PIDs)
+2. Find entities of the type you're interested in using `findEntities()` with an `is_type` expression
+3. Call `getPropertyValues()` to fetch data for those entities
+
+See `schema.md` for the schema endpoints, `find.md` for the expression language.
+
+### Get Edgar filings for a company
+
+Edgar filings are linked to companies via properties. A company entity has a
+`filings` property whose values are entity IDs for individual filing documents.
+
+1. Search for the company: `POST /entities/search` with the company name → get NEID
+2. Get the company's filing entities: `POST /elemental/entities/properties` with the NEID and the `filings` property → returns entity IDs for each filing
+3. For each filing entity, get its details: `POST /elemental/entities/properties` with the filing entity IDs and properties like `filing_date`, `form_type`
+4. Display the results
+
+This pattern — entity → property (returns entity IDs) → query those entities —
+works for any `data_nindex` property, not just filings. See `entities.md` for
+details on property chaining.
+
+### Find connected entities via relationships
+
+1. Search for the starting entity → get NEID
+2. Use `findEntities()` with a `linked` expression to find entities connected to it (see `find.md`)
+3. Or use `getLinkedEntities()` for direct relationship traversal (see `relationships.md`)
+4. Get properties for the connected entities
+
 ## Files in This Skill
 
 See [overview.md](overview.md) for descriptions of each endpoint category:

package/skill/entities.md

@@ -123,6 +123,41 @@ Each Match contains:
 }
 ```
 
+## Property Chaining (`data_nindex`)
+
+Some properties have value type `data_nindex`, meaning their values are entity
+IDs rather than simple strings or numbers. This lets you traverse the knowledge
+graph through properties:
+
+1. Query an entity's properties → get values that are entity IDs
+2. Query those entity IDs for *their* properties → get the next level of data
+
+**Example: Edgar filings**
+
+A company entity has a `filings` property. Each value is the entity ID of a
+filing document. Each filing document entity has its own properties like
+`filing_date` and `form_type`.
+
+```
+Company (NEID: 00416400910670863867)
+  → property "filings" (data_nindex)
+    → Filing entity (NEID: 12345678901234567890)
+      → property "filing_date" → "2026-01-15"
+      → property "form_type" → "10-K"
+    → Filing entity (NEID: 09876543210987654321)
+      → property "filing_date" → "2025-07-20"
+      → property "form_type" → "10-Q"
+```
+
+To resolve this chain, make two `POST /elemental/entities/properties` calls:
+first with the company NEID and `filings` property, then with the returned
+filing entity IDs and `filing_date` + `form_type` properties.
+
+**How to identify `data_nindex` properties:** Use `GET /schema` (see
+`schema.md`) and look for properties with `value_type: "data_nindex"`. The
+schema also tells you which entity types (`domain_findexes`) have each property
+and what entity types (`target_findexes`) the values point to.
+
 ## Schema and Property Lookup
 
 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.

package/skill/overview.md

@@ -39,13 +39,39 @@ Most endpoints accept `start` and `end` parameters for filtering by date.
 | [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 |
 
+## Discovery-First Approach
+
+The knowledge graph contains many entity types and properties, and new datasets
+are added regularly (e.g. Edgar filings, shipping data, financial instruments).
+Do not hardcode entity types or property names. Instead:
+
+1. **Get the schema first** — `GET /schema` returns all entity types (flavors)
+   and properties. See `schema.md`.
+2. **Search by type or property** — use the expression language in `find.md`
+   to search for entities matching criteria from the schema.
+3. **Get property values** — `POST /elemental/entities/properties` fetches
+   data. Properties with type `data_nindex` are entity IDs — query them again
+   to traverse the graph. See `entities.md` for details.
+
+This pattern lets you work with any dataset without prior knowledge of what's
+in the graph.
+
 ## 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
+
+### "What Edgar filings does Apple have?"
+1. `entities.md` → Search for "Apple" to get NEID
+2. `entities.md` → Get property values with the `filings` property (returns entity IDs)
+3. `entities.md` → Get `filing_date` and `form_type` for each filing entity
+
+### "What types of data are available?"
+1. `schema.md` → Get the full schema (flavors + properties)
+2. `find.md` → Search for entities of a specific type
+3. `entities.md` → Get properties for those entities