@yottagraph-app/aether-instructions 1.1.18 → 1.1.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/commands/build_my_app.md +4 -1
- package/package.json +1 -1
- package/rules/aether.mdc +1 -1
- package/rules/agents.mdc +151 -2
- package/rules/api.mdc +108 -85
- package/rules/architecture.mdc +13 -8
- package/rules/cookbook.mdc +56 -18
- package/rules/design.mdc +3 -1
- package/rules/mcp-servers.mdc +1 -1
- package/rules/pref.mdc +16 -20
- package/rules/server.mdc +104 -0
- package/skills/data-model/newsdata/schema.yaml +10 -0
- package/skills/elemental-api/SKILL.md +4 -10
- package/skills/elemental-api/entities.md +37 -112
- package/skills/elemental-api/find.md +19 -4
- package/skills/elemental-api/graph.md +3 -3
- package/skills/elemental-api/overview.md +46 -22
- package/skills/elemental-api/schema.md +10 -30
- package/skills/elemental-api/articles.md +0 -386
- package/skills/elemental-api/events.md +0 -145
- package/skills/elemental-api/llm.md +0 -18
- package/skills/elemental-api/relationships.md +0 -310
- package/skills/elemental-api/sentiment.md +0 -93
|
@@ -12,7 +12,7 @@ The schema defines the data model: what **entity types** (flavors) exist and wha
|
|
|
12
12
|
## Key Concepts
|
|
13
13
|
|
|
14
14
|
- **Flavors** = Entity types. Each entity belongs to exactly one flavor.
|
|
15
|
-
- Examples: "
|
|
15
|
+
- Examples: "organization" (FID 10), "person" (FID 9), "financial_instrument" (FID 3)
|
|
16
16
|
- Identified by a Flavor ID (FID) — a small integer
|
|
17
17
|
- **Properties** = Attributes that entities can have. Each property has:
|
|
18
18
|
- A Property ID (PID) — a small integer
|
|
@@ -30,8 +30,8 @@ There are two schema endpoints with different levels of detail:
|
|
|
30
30
|
| `GET /elemental/metadata/schema` | fid, name only | pid, name, type only |
|
|
31
31
|
|
|
32
32
|
**Use `/schema`** (recommended) when you need:
|
|
33
|
-
- Human-readable display names (e.g., "
|
|
34
|
-
- Units of measurement (e.g., "m", "kg"
|
|
33
|
+
- Human-readable display names (e.g., "Organization" vs "organization")
|
|
34
|
+
- Units of measurement (e.g., "m", "kg")
|
|
35
35
|
- Which flavors a property applies to (`domain_findexes`)
|
|
36
36
|
|
|
37
37
|
**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:
|
|
|
48
48
|
2. **Find entities of a type** → `POST /elemental/find` with `is_type` expression
|
|
49
49
|
3. **Get property values** → `POST /elemental/entities/properties` to fetch values for those entities
|
|
50
50
|
|
|
51
|
-
## Common Properties by Entity Type
|
|
52
|
-
|
|
53
|
-
This is a quick-reference for writing first-pass code. **The schema endpoint
|
|
54
|
-
is the source of truth** — always call `GET /schema` to get actual PIDs and
|
|
55
|
-
confirm which properties exist in a given deployment. Property availability
|
|
56
|
-
varies by dataset.
|
|
57
|
-
|
|
58
|
-
| Entity Type | Common Properties |
|
|
59
|
-
|---|---|
|
|
60
|
-
| **organization** | `name`, `country`, `ticker`, `industry`, `business_sector`, `sic_code`, `state_of_incorporation`, `mailing_address`, `business_phone`, `company_cik` |
|
|
61
|
-
| **person** | `name`, `country`, `nationality`, `birth_date`, `position`, `person_cik`, `job_title` |
|
|
62
|
-
| **financial_instrument** | `name`, `ticker`, `security_type`, `instrument_type`, `cusip_number` |
|
|
63
|
-
| **document** (SEC filings) | `name`, `title`, `form_type`, `filing_date`, `report_date`, `accession_number`, `form_type_detail` |
|
|
64
|
-
| **article** | `name`, `title`, `sentiment` |
|
|
65
|
-
| **event** | `name`, `category`, `date`, `description`, `likelihood` |
|
|
66
|
-
| **location** | `name`, `fixedLatitude`, `fixedLongitude` |
|
|
67
|
-
|
|
68
|
-
**Relationship properties** (type `data_nindex`) link entities to each other.
|
|
69
|
-
Common ones for organizations: `acquires`, `owns`, `competes_with`,
|
|
70
|
-
`partnered_with`, `does_business_with`, `is_part_of`, `issues`, `has_subsidiary`.
|
|
71
|
-
For people: `works_at`, `head_of`, `is_director`, `is_officer`, `is_colleague_of`.
|
|
72
|
-
|
|
73
51
|
<!-- BEGIN GENERATED CONTENT -->
|
|
74
52
|
|
|
75
53
|
## Endpoints
|
|
@@ -102,7 +80,7 @@ GET /schema
|
|
|
102
80
|
**Response:**
|
|
103
81
|
|
|
104
82
|
```json
|
|
105
|
-
{"flavors": [{"findex":
|
|
83
|
+
{"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"}]}
|
|
106
84
|
```
|
|
107
85
|
|
|
108
86
|
---
|
|
@@ -210,7 +188,7 @@ Returns comprehensive schema information including all entity types (flavors), p
|
|
|
210
188
|
|
|
211
189
|
#### Guidance
|
|
212
190
|
|
|
213
|
-
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., '
|
|
191
|
+
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').
|
|
214
192
|
|
|
215
193
|
#### Responses
|
|
216
194
|
|
|
@@ -231,7 +209,7 @@ GET /elemental/metadata/schema
|
|
|
231
209
|
**Response:**
|
|
232
210
|
|
|
233
211
|
```json
|
|
234
|
-
{"op_id": "40dc4cd9-f1b2-4b5c-85d0-c7c61256e5d9", "follow_up": false, "schema": {"flavors": [{"fid":
|
|
212
|
+
{"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"}]}}
|
|
235
213
|
```
|
|
236
214
|
|
|
237
215
|
---
|
|
@@ -279,10 +257,11 @@ Entity type (flavor) with human-readable display names
|
|
|
279
257
|
|
|
280
258
|
| Field | Type | Description |
|
|
281
259
|
|-------|------|-------------|
|
|
260
|
+
| description | string | Semantic description of what this flavor represents |
|
|
282
261
|
| findex | integer | Unique flavor identifier (same as fid in other endpoints) |
|
|
283
262
|
| name | string | Flavor name (internal identifier) |
|
|
284
|
-
| plural_display_name | string | Human-readable plural name (e.g., "
|
|
285
|
-
| singular_display_name | string | Human-readable singular name (e.g., "
|
|
263
|
+
| plural_display_name | string | Human-readable plural name (e.g., "People") |
|
|
264
|
+
| singular_display_name | string | Human-readable singular name (e.g., "Person") |
|
|
286
265
|
|
|
287
266
|
### SchemaProperty
|
|
288
267
|
|
|
@@ -290,6 +269,7 @@ Property with display name, unit, and domain information
|
|
|
290
269
|
|
|
291
270
|
| Field | Type | Description |
|
|
292
271
|
|-------|------|-------------|
|
|
272
|
+
| description | string | Semantic description of what this property represents |
|
|
293
273
|
| display_name | string | Human-readable property name |
|
|
294
274
|
| domain_findexes | integer[] | Flavor IDs (findexes) that can have this property |
|
|
295
275
|
| name | string | Property name (internal identifier) |
|
|
@@ -1,386 +0,0 @@
|
|
|
1
|
-
# Articles & Mentions
|
|
2
|
-
|
|
3
|
-
Articles are one significant source of data for the Knowledge Graph. A **mention** is a specific reference to an entity within an article, capturing the context and sentiment of that reference.
|
|
4
|
-
|
|
5
|
-
## When to Use
|
|
6
|
-
|
|
7
|
-
- You need to find news coverage about an entity
|
|
8
|
-
- You want mention counts or volume over time
|
|
9
|
-
- You have a specific article ID (ARTID) or mention code (MCODE) and need full details
|
|
10
|
-
- You want to read the actual text or summary of an article
|
|
11
|
-
- You need article metadata: publication name, date, URL, trustworthiness scores
|
|
12
|
-
|
|
13
|
-
## Key Concepts
|
|
14
|
-
|
|
15
|
-
- **ARTID**: Unique identifier for each article.
|
|
16
|
-
- Format: 20-character numeric string (same format as NEIDs)
|
|
17
|
-
- Example: `05433395856363393596`
|
|
18
|
-
- **MCODE**: A unique identifier for each mention, linking entity + article + context.
|
|
19
|
-
- Format: `{neid}:{artid}` with colon separator
|
|
20
|
-
- Example: `00416400910670863867:05433395856363393596`
|
|
21
|
-
- **Mention Detail**: Includes the snippet, publication, sentiment, and other metadata
|
|
22
|
-
- **Mention Counts**: Aggregated counts over time buckets, useful for tracking media attention
|
|
23
|
-
- **Article Detail**: Full metadata including title, summary, publication info, and scores
|
|
24
|
-
- **Article Text**: The actual content of the article (when available)
|
|
25
|
-
|
|
26
|
-
## Important Limitations
|
|
27
|
-
|
|
28
|
-
⚠️ **Volume Warning**: A single entity may have tens of thousands of associated articles. Avoid querying all articles for an entity over long time periods.
|
|
29
|
-
|
|
30
|
-
**Recommended approach:**
|
|
31
|
-
1. Start with mention counts to understand volume
|
|
32
|
-
2. Use mention endpoints to identify specific mentions of interest
|
|
33
|
-
3. Then retrieve full article details only for those specific articles
|
|
34
|
-
|
|
35
|
-
## Tips
|
|
36
|
-
|
|
37
|
-
- Start with mention counts to understand volume, then drill into specific mentions
|
|
38
|
-
- Filter by time range to avoid overwhelming results for high-profile entities
|
|
39
|
-
- Use neighborhood mentions to see what else was mentioned alongside your target entity
|
|
40
|
-
- Article text may not be available for all articles (depends on licensing)
|
|
41
|
-
- Use trustworthiness and page rank scores to assess source quality
|
|
42
|
-
|
|
43
|
-
<!-- BEGIN GENERATED CONTENT -->
|
|
44
|
-
|
|
45
|
-
## Endpoints
|
|
46
|
-
|
|
47
|
-
### Get article detail
|
|
48
|
-
|
|
49
|
-
`GET /articles/{artid}`
|
|
50
|
-
|
|
51
|
-
Get detailed information about an article by its ID. Response is cached for 1 hour (articles are immutable).
|
|
52
|
-
|
|
53
|
-
#### Guidance
|
|
54
|
-
|
|
55
|
-
Response is wrapped in a 'detail' container object. Access article data via response.detail.
|
|
56
|
-
|
|
57
|
-
#### Parameters
|
|
58
|
-
|
|
59
|
-
| Name | Type | Required | Description |
|
|
60
|
-
|------|------|----------|-------------|
|
|
61
|
-
| artid | string | yes | Article ID |
|
|
62
|
-
|
|
63
|
-
#### Responses
|
|
64
|
-
|
|
65
|
-
| Status | Description |
|
|
66
|
-
|--------|-------------|
|
|
67
|
-
| 200 | Article detail (`GetArticleResponse`) |
|
|
68
|
-
| 400 | Invalid ARTID (`Error`) |
|
|
69
|
-
| 404 | Article not found (`Error`) |
|
|
70
|
-
| 500 | Internal server error (`Error`) |
|
|
71
|
-
|
|
72
|
-
#### Example
|
|
73
|
-
|
|
74
|
-
**Request:**
|
|
75
|
-
|
|
76
|
-
```
|
|
77
|
-
GET /articles/05433395856363393596
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
**Response:**
|
|
81
|
-
|
|
82
|
-
```json
|
|
83
|
-
{"detail": {"artid": "05433395856363393596", "publication_date": "2026-01-28T15:56:47Z", "title": "Apple's Cook says he's 'heartbroken' by Minneapolis events...", "summary": "The article details two fatal shootings by federal agents...", "batch": "7f302ee6808d7c45a09aed07c93ec785", "source": "7f302ee6808d7c45a09aed07c93ec785", "url": "https://www.cnbc.com/2026/01/28/...", "mentions": [{"neid": "00315863961550087877", "artid": "05433395856363393596"}], "topics": [], "events": ["00526686651102446795", "01090525413205193094"], "publication_name": "cnbc.com", "publication_home_url": "http://www.cnbc.com", "trustworthiness": 0.664, "original_publication_name": "CNBC", "tone": "neutral", "title_factuality": "accurate", "tone_objectivity_score": 0.533, "title_factuality_score": 7.133, "syndication_score": 1}}
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
---
|
|
87
|
-
|
|
88
|
-
### Get article text
|
|
89
|
-
|
|
90
|
-
`GET /articles/{artid}/text`
|
|
91
|
-
|
|
92
|
-
Get the full text content of an article by its ID. Response is cached for 10 minutes.
|
|
93
|
-
|
|
94
|
-
#### Guidance
|
|
95
|
-
|
|
96
|
-
This endpoint returns plain text, NOT JSON. Parse the response as text, not as a JSON object.
|
|
97
|
-
|
|
98
|
-
#### Parameters
|
|
99
|
-
|
|
100
|
-
| Name | Type | Required | Description |
|
|
101
|
-
|------|------|----------|-------------|
|
|
102
|
-
| artid | string | yes | Article ID |
|
|
103
|
-
|
|
104
|
-
#### Responses
|
|
105
|
-
|
|
106
|
-
| Status | Description |
|
|
107
|
-
|--------|-------------|
|
|
108
|
-
| 200 | Article text |
|
|
109
|
-
| 400 | Invalid ARTID (`Error`) |
|
|
110
|
-
| 500 | Internal server error (`Error`) |
|
|
111
|
-
|
|
112
|
-
#### Example
|
|
113
|
-
|
|
114
|
-
**Request:**
|
|
115
|
-
|
|
116
|
-
```
|
|
117
|
-
GET /articles/05433395856363393596/text
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
**Response:**
|
|
121
|
-
|
|
122
|
-
```
|
|
123
|
-
Apple CEO Tim Cook said he was "heartbroken" by the situation in Minneapolis...
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
---
|
|
127
|
-
|
|
128
|
-
### Get mentions for entities
|
|
129
|
-
|
|
130
|
-
`GET /mentions/lookup`
|
|
131
|
-
|
|
132
|
-
Get list of mention codes (MCODEs) for named entities in a neighborhood within a time interval. Response is cached for 5 minutes.
|
|
133
|
-
|
|
134
|
-
#### Parameters
|
|
135
|
-
|
|
136
|
-
| Name | Type | Required | Description |
|
|
137
|
-
|------|------|----------|-------------|
|
|
138
|
-
| interval_start | string | yes | Start time of interval (RFC3339) |
|
|
139
|
-
| interval_end | string | yes | End time of interval (RFC3339) |
|
|
140
|
-
| neid | string[] | yes | Named Entity ID(s) in the neighborhood |
|
|
141
|
-
|
|
142
|
-
#### Responses
|
|
143
|
-
|
|
144
|
-
| Status | Description |
|
|
145
|
-
|--------|-------------|
|
|
146
|
-
| 200 | List of mention codes (`GetMentionsResponse`) |
|
|
147
|
-
| 400 | Invalid parameters (`Error`) |
|
|
148
|
-
| 500 | Internal server error (`Error`) |
|
|
149
|
-
|
|
150
|
-
#### Example
|
|
151
|
-
|
|
152
|
-
**Request:**
|
|
153
|
-
|
|
154
|
-
```
|
|
155
|
-
GET /mentions/lookup?interval_start=2026-01-01T00:00:00Z&interval_end=2026-02-01T00:00:00Z&neid=00416400910670863867
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
**Response:**
|
|
159
|
-
|
|
160
|
-
```json
|
|
161
|
-
{"mcodes": [{"neid": "00416400910670863867", "artid": "05433395856363393596"}, {"neid": "00416400910670863867", "artid": "02706389331155211812"}]}
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
---
|
|
165
|
-
|
|
166
|
-
### Get mention counts over time
|
|
167
|
-
|
|
168
|
-
`GET /mentions/lookup/counts`
|
|
169
|
-
|
|
170
|
-
Get bucketed counts of mentions for entities in a neighborhood within a time interval
|
|
171
|
-
|
|
172
|
-
#### Parameters
|
|
173
|
-
|
|
174
|
-
| Name | Type | Required | Description |
|
|
175
|
-
|------|------|----------|-------------|
|
|
176
|
-
| interval_start | string | yes | Start time of interval (RFC3339) |
|
|
177
|
-
| interval_end | string | yes | End time of interval (RFC3339) |
|
|
178
|
-
| neid | string[] | yes | Named Entity ID(s) in the neighborhood |
|
|
179
|
-
| numBuckets | integer | no | Number of time buckets |
|
|
180
|
-
|
|
181
|
-
#### Responses
|
|
182
|
-
|
|
183
|
-
| Status | Description |
|
|
184
|
-
|--------|-------------|
|
|
185
|
-
| 200 | Bucketed mention counts (`GetMentionCountsResponse`) |
|
|
186
|
-
| 400 | Invalid parameters (`Error`) |
|
|
187
|
-
| 500 | Internal server error (`Error`) |
|
|
188
|
-
|
|
189
|
-
#### Example
|
|
190
|
-
|
|
191
|
-
**Request:**
|
|
192
|
-
|
|
193
|
-
```
|
|
194
|
-
GET /mentions/lookup/counts?interval_start=2026-01-15T00:00:00Z&interval_end=2026-01-20T00:00:00Z&neid=00416400910670863867&numBuckets=5
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
**Response:**
|
|
198
|
-
|
|
199
|
-
```json
|
|
200
|
-
{"buckets": [{"start": "2026-01-15T00:00:00Z", "width_hours": 24, "count": 51}, {"start": "2026-01-16T00:00:00Z", "width_hours": 24, "count": 28}]}
|
|
201
|
-
```
|
|
202
|
-
|
|
203
|
-
---
|
|
204
|
-
|
|
205
|
-
### Get mention details for a neighborhood
|
|
206
|
-
|
|
207
|
-
`GET /mentions/lookup/detail`
|
|
208
|
-
|
|
209
|
-
Get detailed information about all mentions for entities in a neighborhood within a time interval. Response is cached for 15 minutes.
|
|
210
|
-
|
|
211
|
-
#### Parameters
|
|
212
|
-
|
|
213
|
-
| Name | Type | Required | Description |
|
|
214
|
-
|------|------|----------|-------------|
|
|
215
|
-
| interval_start | string | yes | Start time of interval (RFC3339) |
|
|
216
|
-
| interval_end | string | yes | End time of interval (RFC3339) |
|
|
217
|
-
| neid | string[] | yes | Named Entity ID(s) in the neighborhood |
|
|
218
|
-
|
|
219
|
-
#### Responses
|
|
220
|
-
|
|
221
|
-
| Status | Description |
|
|
222
|
-
|--------|-------------|
|
|
223
|
-
| 200 | List of mention details (`GetMentionLookupDetailResponse`) |
|
|
224
|
-
| 400 | Invalid parameters (`Error`) |
|
|
225
|
-
| 500 | Internal server error (`Error`) |
|
|
226
|
-
|
|
227
|
-
#### Example
|
|
228
|
-
|
|
229
|
-
**Request:**
|
|
230
|
-
|
|
231
|
-
```
|
|
232
|
-
GET /mentions/lookup/detail?interval_start=2026-01-28T00:00:00Z&interval_end=2026-01-29T00:00:00Z&neid=00416400910670863867
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
**Response:**
|
|
236
|
-
|
|
237
|
-
```json
|
|
238
|
-
{"details": [{"neid": "00416400910670863867", "artid": "06794762728091918955", "publication_date": "2026-01-28T14:01:17Z", "snippet": "...stiff competition from other major players such as YouTube and Apple...", "sentiment": 0, "explanation": "Apple is mentioned as a competitor in the music-streaming market...", "topics": [], "trustworthiness": 0.508, "original_publication_name": "Spotify", "tone": "Neutral", "title_factuality": "True", "tone_objectivity_score": 0.563, "title_factuality_score": 3.889, "events": ["06942391178010057368"]}]}
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
---
|
|
242
|
-
|
|
243
|
-
### Get mention detail
|
|
244
|
-
|
|
245
|
-
`GET /mentions/{mcode}/detail`
|
|
246
|
-
|
|
247
|
-
Get detailed information about a specific mention by its MCODE. Response is cached for 15 minutes.
|
|
248
|
-
|
|
249
|
-
#### Guidance
|
|
250
|
-
|
|
251
|
-
Response is wrapped in a 'detail' container object. Access mention data via response.detail.
|
|
252
|
-
|
|
253
|
-
#### Parameters
|
|
254
|
-
|
|
255
|
-
| Name | Type | Required | Description |
|
|
256
|
-
|------|------|----------|-------------|
|
|
257
|
-
| mcode | string | yes | Mention code in format NEID:ARTID |
|
|
258
|
-
|
|
259
|
-
#### Responses
|
|
260
|
-
|
|
261
|
-
| Status | Description |
|
|
262
|
-
|--------|-------------|
|
|
263
|
-
| 200 | Mention detail (`GetMentionDetailResponse`) |
|
|
264
|
-
| 400 | Invalid MCODE format (`Error`) |
|
|
265
|
-
| 404 | Mention not found (`Error`) |
|
|
266
|
-
| 500 | Internal server error (`Error`) |
|
|
267
|
-
|
|
268
|
-
#### Example
|
|
269
|
-
|
|
270
|
-
**Request:**
|
|
271
|
-
|
|
272
|
-
```
|
|
273
|
-
GET /mentions/00416400910670863867:05433395856363393596/detail
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
**Response:**
|
|
277
|
-
|
|
278
|
-
```json
|
|
279
|
-
{"detail": {"neid": "00416400910670863867", "artid": "05433395856363393596", "publication_date": "2026-01-28T15:56:47Z", "snippet": "Apple CEO Tim Cook said he was 'heartbroken'...", "sentiment": -0.75, "explanation": "CEO Tim Cook expressed heartbreak...", "topics": [], "trustworthiness": 0.664, "original_publication_name": "CNBC", "tone": "neutral", "title_factuality": "accurate", "tone_objectivity_score": 0.533, "title_factuality_score": 7.133, "events": ["07189853443333370710", "07880710486873721498"]}}
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
## Types
|
|
283
|
-
|
|
284
|
-
### ArticleDetail
|
|
285
|
-
|
|
286
|
-
The article detail
|
|
287
|
-
|
|
288
|
-
| Field | Type | Description |
|
|
289
|
-
|-------|------|-------------|
|
|
290
|
-
| artid | string | Article ID |
|
|
291
|
-
| batch | string | Processing batch identifier |
|
|
292
|
-
| events | string[] | Event IDs mentioned in this article |
|
|
293
|
-
| mentions | `Mcode`[] | List of entity mentions in article |
|
|
294
|
-
| moz_rank_score | number | Publisher's Moz rank value (0 to 1) @Minimum 0 @Maximum 1 |
|
|
295
|
-
| original_publication_name | string | Original publication name when known (e.g., when article is syndicated) |
|
|
296
|
-
| page_rank_score | number | Publisher's page rank value (0 to 1) @Minimum 0 @Maximum 1 |
|
|
297
|
-
| publication_date | string | Publication date of the article @Format date-time |
|
|
298
|
-
| publication_home_url | string | Home URL of the publication in which the article was published @Format uri |
|
|
299
|
-
| publication_name | string | Name of the publication in which the article was published |
|
|
300
|
-
| source | string | Article source identifier |
|
|
301
|
-
| summary | string | Article summary |
|
|
302
|
-
| syndication_score | integer | Syndication score indicating article distribution |
|
|
303
|
-
| title | string | Article title |
|
|
304
|
-
| title_factuality | string | Article title factuality classification |
|
|
305
|
-
| title_factuality_score | number | Publisher's title factuality score (0 to 1) @Minimum 0 @Maximum 1 |
|
|
306
|
-
| tone | string | Article tone classification |
|
|
307
|
-
| tone_objectivity_score | number | Publisher's tone objectivity score (0 to 1) @Minimum 0 @Maximum 1 |
|
|
308
|
-
| topics | `ArticleTopic`[] | Topics associated with this article |
|
|
309
|
-
| trustworthiness | number | Trustworthiness score (0 to 1) @Minimum 0 @Maximum 1 |
|
|
310
|
-
| url | string | Original article URL @Format uri |
|
|
311
|
-
|
|
312
|
-
### GetArticleResponse
|
|
313
|
-
|
|
314
|
-
Response containing detailed information about an article
|
|
315
|
-
|
|
316
|
-
| Field | Type | Description |
|
|
317
|
-
|-------|------|-------------|
|
|
318
|
-
| detail | `ArticleDetail` | |
|
|
319
|
-
|
|
320
|
-
### GetMentionCountsResponse
|
|
321
|
-
|
|
322
|
-
Response containing bucketed mention counts over time
|
|
323
|
-
|
|
324
|
-
| Field | Type | Description |
|
|
325
|
-
|-------|------|-------------|
|
|
326
|
-
| buckets | `Bucket`[] | Time buckets with mention counts |
|
|
327
|
-
|
|
328
|
-
### GetMentionDetailResponse
|
|
329
|
-
|
|
330
|
-
Response containing detailed information about a mention
|
|
331
|
-
|
|
332
|
-
| Field | Type | Description |
|
|
333
|
-
|-------|------|-------------|
|
|
334
|
-
| detail | `MentionDetail` | |
|
|
335
|
-
|
|
336
|
-
### GetMentionLookupDetailResponse
|
|
337
|
-
|
|
338
|
-
Response containing detailed information about multiple mentions
|
|
339
|
-
|
|
340
|
-
| Field | Type | Description |
|
|
341
|
-
|-------|------|-------------|
|
|
342
|
-
| details | `MentionDetail`[] | List of mention details |
|
|
343
|
-
|
|
344
|
-
### GetMentionsResponse
|
|
345
|
-
|
|
346
|
-
Response containing mention codes for a lookup query
|
|
347
|
-
|
|
348
|
-
| Field | Type | Description |
|
|
349
|
-
|-------|------|-------------|
|
|
350
|
-
| mcodes | `Mcode`[] | List of mention codes (NEID, ARTID pairs) |
|
|
351
|
-
|
|
352
|
-
### Mcode
|
|
353
|
-
|
|
354
|
-
A tuple of (NEID, ARTID) representing one or more mentions of a Named Entity in an Article
|
|
355
|
-
|
|
356
|
-
| Field | Type | Description |
|
|
357
|
-
|-------|------|-------------|
|
|
358
|
-
| artid | string | Article ID |
|
|
359
|
-
| neid | string | Named Entity ID |
|
|
360
|
-
|
|
361
|
-
### MentionDetail
|
|
362
|
-
|
|
363
|
-
The mention detail
|
|
364
|
-
|
|
365
|
-
| Field | Type | Description |
|
|
366
|
-
|-------|------|-------------|
|
|
367
|
-
| artid | string | Article ID |
|
|
368
|
-
| events | string[] | Event IDs that this mention is associated with |
|
|
369
|
-
| explanation | string | Explanation of sentiment analysis |
|
|
370
|
-
| moz_rank_score | number | Publisher's Moz rank value (0 to 1) @Minimum 0 @Maximum 1 |
|
|
371
|
-
| neid | string | Named Entity ID |
|
|
372
|
-
| original_publication_name | string | Original publication name when known (e.g., when article is syndicated) |
|
|
373
|
-
| other_neid | string | NEID of the other entity in a relationship mention |
|
|
374
|
-
| other_relation_type | string | Type of relationship with the other entity |
|
|
375
|
-
| page_rank_score | number | Publisher's page rank value (0 to 1) @Minimum 0 @Maximum 1 |
|
|
376
|
-
| publication_date | string | Publication date of the article @Format date-time |
|
|
377
|
-
| sentiment | number | Sentiment score for the mention (-1 to 1) @Minimum -1 @Maximum 1 |
|
|
378
|
-
| snippet | string | Text snippet containing the mention |
|
|
379
|
-
| title_factuality | string | Article title factuality classification |
|
|
380
|
-
| title_factuality_score | number | Publisher's title factuality score (0 to 1) @Minimum 0 @Maximum 1 |
|
|
381
|
-
| tone | string | Article tone classification |
|
|
382
|
-
| tone_objectivity_score | number | Publisher's tone objectivity score (0 to 1) @Minimum 0 @Maximum 1 |
|
|
383
|
-
| topics | `ArticleTopic`[] | Topics associated with the article |
|
|
384
|
-
| trustworthiness | number | Trustworthiness score (0 to 1) @Minimum 0 @Maximum 1 |
|
|
385
|
-
|
|
386
|
-
<!-- END GENERATED CONTENT -->
|
|
@@ -1,145 +0,0 @@
|
|
|
1
|
-
# Events
|
|
2
|
-
|
|
3
|
-
Events are significant occurrences involving entities: mergers, acquisitions, lawsuits, executive changes, product launches, and other newsworthy happenings. Events are extracted from article content and link multiple entities and articles together.
|
|
4
|
-
|
|
5
|
-
## When to Use
|
|
6
|
-
|
|
7
|
-
- You want to know what happened to/with an entity (not just mentions)
|
|
8
|
-
- You want to see how different articles reference the same event(s), and understand that many articles may duplicate information about the same event(s).
|
|
9
|
-
- You want to see what entities participated in an event, and what their roles were.
|
|
10
|
-
|
|
11
|
-
## Key Concepts
|
|
12
|
-
|
|
13
|
-
- **Event ID (EVEID)**: Unique identifier for each event.
|
|
14
|
-
- Format: 20-character numeric string (same format as NEIDs)
|
|
15
|
-
- Example: `08640179941787350436`
|
|
16
|
-
- **Event Roles**: Entities participate in events with roles (e.g., acquirer, target, plaintiff)
|
|
17
|
-
- **Event Summary**: Brief description of what occurred
|
|
18
|
-
- **Event Date**: When the event happened (may differ from article publication date)
|
|
19
|
-
|
|
20
|
-
## Tips
|
|
21
|
-
|
|
22
|
-
- Multiple articles may reference the same event
|
|
23
|
-
- Check entity roles to understand the nature of involvement
|
|
24
|
-
|
|
25
|
-
<!-- BEGIN GENERATED CONTENT -->
|
|
26
|
-
|
|
27
|
-
## Endpoints
|
|
28
|
-
|
|
29
|
-
### Get events for an entity
|
|
30
|
-
|
|
31
|
-
`GET /events/lookup`
|
|
32
|
-
|
|
33
|
-
Get list of event IDs (EVEIDs) where an entity participates within a time interval. Response is cached for 5 minutes.
|
|
34
|
-
|
|
35
|
-
#### Guidance
|
|
36
|
-
|
|
37
|
-
Event IDs returned may not all be immediately retrievable via /events/{eveid}. Some events may return 404 due to event processing timing or data availability. Handle 404 responses gracefully.
|
|
38
|
-
|
|
39
|
-
#### Parameters
|
|
40
|
-
|
|
41
|
-
| Name | Type | Required | Description |
|
|
42
|
-
|------|------|----------|-------------|
|
|
43
|
-
| interval_start | string | yes | Start time of interval (RFC3339) |
|
|
44
|
-
| interval_end | string | yes | End time of interval (RFC3339) |
|
|
45
|
-
| neid | string | yes | Named Entity ID |
|
|
46
|
-
|
|
47
|
-
#### Responses
|
|
48
|
-
|
|
49
|
-
| Status | Description |
|
|
50
|
-
|--------|-------------|
|
|
51
|
-
| 200 | List of event IDs (`GetEventsForEntityResponse`) |
|
|
52
|
-
| 400 | Invalid parameters (`Error`) |
|
|
53
|
-
| 500 | Internal server error (`Error`) |
|
|
54
|
-
|
|
55
|
-
#### Example
|
|
56
|
-
|
|
57
|
-
**Request:**
|
|
58
|
-
|
|
59
|
-
```
|
|
60
|
-
GET /events/lookup?interval_start=2026-01-28T00:00:00Z&interval_end=2026-01-29T00:00:00Z&neid=00416400910670863867
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
**Response:**
|
|
64
|
-
|
|
65
|
-
```json
|
|
66
|
-
{"event_ids": ["07880710486873721498", "07189853443333370710", "01188063638449369172"]}
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
---
|
|
70
|
-
|
|
71
|
-
### Get event detail
|
|
72
|
-
|
|
73
|
-
`GET /events/{eveid}`
|
|
74
|
-
|
|
75
|
-
Get detailed information about an event by its ID. Response is cached for 15 minutes.
|
|
76
|
-
|
|
77
|
-
#### Guidance
|
|
78
|
-
|
|
79
|
-
Response is wrapped in a 'detail' container object. Access event data via response.detail.
|
|
80
|
-
|
|
81
|
-
#### Parameters
|
|
82
|
-
|
|
83
|
-
| Name | Type | Required | Description |
|
|
84
|
-
|------|------|----------|-------------|
|
|
85
|
-
| eveid | string | yes | Event ID |
|
|
86
|
-
|
|
87
|
-
#### Responses
|
|
88
|
-
|
|
89
|
-
| Status | Description |
|
|
90
|
-
|--------|-------------|
|
|
91
|
-
| 200 | Event detail (`GetEventResponse`) |
|
|
92
|
-
| 400 | Invalid EVEID (`Error`) |
|
|
93
|
-
| 404 | Event not found (`Error`) |
|
|
94
|
-
| 500 | Internal server error (`Error`) |
|
|
95
|
-
|
|
96
|
-
#### Example
|
|
97
|
-
|
|
98
|
-
**Request:**
|
|
99
|
-
|
|
100
|
-
```
|
|
101
|
-
GET /events/08640179941787350436
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
**Response:**
|
|
105
|
-
|
|
106
|
-
```json
|
|
107
|
-
{"detail": {"eveid": "08640179941787350436", "name": "event|Apple plans to release a foldable device...|2026", "date": "2026", "description": "The new design and engineering changes in the iPhone Air could pave the way...", "category": "Product Development", "likelihood": "Medium", "severity": 0, "speculative": false, "participants": [{"neid": "00416400910670863867", "sentiment": 0.5, "explanation": "The launch of new products...", "role": "company", "snippet": "Apple is gearing up for the most extensive refresh...", "artid": "07521758285625650094"}]}}
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
## Types
|
|
111
|
-
|
|
112
|
-
### EventDetail
|
|
113
|
-
|
|
114
|
-
The event detail
|
|
115
|
-
|
|
116
|
-
| Field | Type | Description |
|
|
117
|
-
|-------|------|-------------|
|
|
118
|
-
| artids | string[] | Article IDs where this event was found |
|
|
119
|
-
| category | string | Category of the event |
|
|
120
|
-
| date | string | Date of the event |
|
|
121
|
-
| description | string | Description of the event |
|
|
122
|
-
| eveid | string | Event ID |
|
|
123
|
-
| likelihood | string | Likelihood assessment of the event |
|
|
124
|
-
| name | string | Name of the event |
|
|
125
|
-
| participants | `EventParticipant`[] | Participants in the event |
|
|
126
|
-
| severity | integer | Severity level of the event |
|
|
127
|
-
| speculative | boolean | Whether the event is speculative |
|
|
128
|
-
|
|
129
|
-
### GetEventResponse
|
|
130
|
-
|
|
131
|
-
Response containing detailed information about an event
|
|
132
|
-
|
|
133
|
-
| Field | Type | Description |
|
|
134
|
-
|-------|------|-------------|
|
|
135
|
-
| detail | `EventDetail` | |
|
|
136
|
-
|
|
137
|
-
### GetEventsForEntityResponse
|
|
138
|
-
|
|
139
|
-
Response containing event IDs for an entity
|
|
140
|
-
|
|
141
|
-
| Field | Type | Description |
|
|
142
|
-
|-------|------|-------------|
|
|
143
|
-
| event_ids | string[] | List of event IDs |
|
|
144
|
-
|
|
145
|
-
<!-- END GENERATED CONTENT -->
|
|
@@ -1,18 +0,0 @@
|
|
|
1
|
-
# LLM (Ada)
|
|
2
|
-
|
|
3
|
-
Ada is the AI assistant integrated into the Query Server, capable of answering natural language questions about the Knowledge Graph.
|
|
4
|
-
|
|
5
|
-
## Status: Not Currently Available
|
|
6
|
-
|
|
7
|
-
⚠️ 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.
|
|
8
|
-
|
|
9
|
-
## Intended Use Cases (Future)
|
|
10
|
-
|
|
11
|
-
- Natural language queries about entities ("Tell me about Apple's recent news")
|
|
12
|
-
- Conversational exploration of the Knowledge Graph
|
|
13
|
-
- AI-assisted analysis and summarization
|
|
14
|
-
|
|
15
|
-
<!-- BEGIN GENERATED CONTENT -->
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
<!-- END GENERATED CONTENT -->
|