@yottagraph-app/aether-instructions 1.1.3 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.3",
+    "version": "1.1.4",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/agents.mdc

@@ -168,8 +168,9 @@ Once deployed, the agent is reachable through the Portal Gateway:
 ```
 Chat UI (pages/chat.vue)
   → POST NUXT_PUBLIC_GATEWAY_URL/api/agents/{tenantId}/{agentId}/query
-  → Portal Gateway proxies to Vertex AI Agent Engine
-  → Agent runs, returns response
+  → Portal Gateway proxies to Vertex AI Agent Engine (streamQuery)
+  → Agent runs (may invoke tools, make multiple LLM calls)
+  → Gateway collects the ADK event stream, extracts final text
   → Chat UI displays it
 ```
 
@@ -177,6 +178,126 @@ The gateway URL and tenant ID come from `broadchurch.yaml` (injected as
 `NUXT_PUBLIC_GATEWAY_URL` and `NUXT_PUBLIC_TENANT_ORG_ID`). The chat page
 discovers available agents from the Portal config endpoint.
 
+### Gateway Request
+
+```
+POST {NUXT_PUBLIC_GATEWAY_URL}/api/agents/{tenantId}/{agentId}/query
+Content-Type: application/json
+
+{ "message": "Summarize the latest 8-K filing", "session_id": "optional-session-id" }
+```
+
+Omit `session_id` on the first message — the gateway auto-creates one.
+
+### Gateway Response Format
+
+```json
+{
+  "output": "The agent's final text response",
+  "session_id": "session-abc-123",
+  "events": [ /* raw ADK event stream */ ]
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `output` | `string \| any[]` | Usually the agent's final text. Falls back to the raw `events` array if the gateway couldn't extract text. |
+| `session_id` | `string` | Pass back on subsequent messages to continue the conversation. |
+| `events` | `any[]` | Full ADK event stream. Useful for debugging or building UIs that show intermediate agent steps. |
+
+**Important:** `output` is NOT always a string. When the agent's response
+involves complex tool chains, the gateway's server-side extraction may miss
+the text and return the raw events array instead. Always use
+`extractAgentText()` to parse `output` safely rather than treating it as a
+string directly.
+
+### ADK Event Stream Format
+
+The `events` array contains one object per step the agent took. Each event
+has `content.parts[]` where each part is one of:
+
+```json
+{ "text": "The agent's text response..." }
+{ "functionCall": { "name": "search", "args": { "q": "AAPL" } } }
+{ "functionResponse": { "name": "search", "response": { "results": [...] } } }
+```
+
+A typical stream for an agent that uses a tool:
+
+```json
+[
+  { "content": { "parts": [{ "functionCall": { "name": "search", "args": {"q": "AAPL 8-K"} } }], "role": "model" } },
+  { "content": { "parts": [{ "functionResponse": { "name": "search", "response": {"results": ["..."]} } }], "role": "tool" } },
+  { "content": { "parts": [{ "text": "Here is the summary of the 8-K filing..." }], "role": "model" } }
+]
+```
+
+The final text is the last `text` part that isn't in a `functionCall` or
+`functionResponse` event. Events may also arrive as JSON strings rather
+than objects — always handle both.
+
+### Parsing Agent Responses (Non-Streaming)
+
+For one-shot calls (server routes, background tasks) where streaming isn't
+needed, use the buffered `/query` endpoint with `extractAgentText`:
+
+```typescript
+import { extractAgentText } from '~/composables/useAgentChat';
+
+const response = await $fetch(url, { method: 'POST', body: { message } });
+const text = extractAgentText(response.output);
+```
+
+`extractAgentText` handles: plain strings, ADK event stream arrays (with
+JSON-string or object elements), single event objects, and several legacy
+Agent Engine response shapes. It skips `functionCall` / `functionResponse`
+events and returns the agent's final text.
+
+### Streaming Responses
+
+The gateway also exposes a streaming endpoint that returns Server-Sent
+Events as the agent executes. **The `useAgentChat` composable uses this by
+default** — it tries `/stream` first and falls back to `/query`
+automatically.
+
+```
+POST {NUXT_PUBLIC_GATEWAY_URL}/api/agents/{tenantId}/{agentId}/stream
+Content-Type: application/json
+
+{ "message": "Summarize the latest 8-K filing", "session_id": "optional" }
+```
+
+The response is an SSE stream with these event types:
+
+| Event | Data Shape | Description |
+|---|---|---|
+| `text` | `{ "text": "..." }` | Agent text output (replaces previous text) |
+| `function_call` | `{ "name": "...", "args": {...} }` | Agent is calling a tool |
+| `function_response` | `{ "name": "...", "response": {...} }` | Tool returned a result |
+| `error` | `{ "message": "..." }` | Error during processing |
+| `done` | `{ "session_id": "...", "text": "..." }` | Stream complete with final text |
+
+For custom agent UIs that need streaming, import `readSSE`:
+
+```typescript
+import { readSSE } from '~/composables/useAgentChat';
+
+const res = await fetch(streamUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message: 'Hello' }),
+});
+
+for await (const { event, data } of readSSE(res)) {
+    if (event === 'text') console.log('Agent says:', data.text);
+    if (event === 'function_call') console.log('Calling:', data.name);
+    if (event === 'done') console.log('Session:', data.session_id);
+}
+```
+
+The `done` event always includes the final extracted text, so you don't
+need to track text deltas yourself.
+
 ## Agent Design Guidelines
 
 - Keep agents focused: one agent per domain or task type

package/rules/api.mdc

@@ -51,6 +51,57 @@ Types are also imported from the client:
 import type { NamedEntityReport, GetNEIDResponse } from '@yottagraph-app/elemental-api/client';
 ```
 
+### Client Method Quick Reference
+
+All methods return data directly and throw on non-2xx responses.
+
+**Entity search and lookup:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getNEID` | `(params: { entityName, maxResults?, includeNames? })` | Lookup entity by name |
+| `findEntities` | `(body: FindEntitiesBody)` | Expression-based search (see `find.md`) |
+| `getNamedEntityReport` | `(neid: string)` | Entity details (name, aliases, type) |
+| `getEntityDetails` | `(neid: string)` | Alias for entity reports |
+
+**Properties and schema:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getSchema` | `()` | All entity types (flavors) and properties (PIDs) |
+| `getPropertyValues` | `(body: { eids: string, pids: string })` | Property values (eids/pids are JSON-stringified arrays!) |
+| `summarizeProperty` | `(pid: number)` | Summary stats for a property |
+
+**Relationships and graph:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getLinkedEntities` | `(neid, params?: { entity_type?, link_type? })` | Linked entities (person/org/location only) |
+| `getLinks` | `(sourceNeid, targetNeid, params?)` | Links between two specific entities |
+| `getLinkCounts` | `(sourceNeid, targetNeid)` | Link counts between entities |
+| `getNeighborhood` | `(centerNeid, params?)` | Neighboring entities |
+| `getGraphLayout` | `(centerNeid, params?)` | Graph layout for visualization |
+
+**News, events, and sentiment:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getArticle` | `(artid: string)` | Article by ID |
+| `getArticleText` | `(artid: string)` | Article full text |
+| `getEvent` | `(eveid: string)` | Event by ID |
+| `getEventsForEntity` | `(params: { neid, startTime?, endTime? })` | Events involving an entity |
+| `getMentions` | `(params: { neid, startTime?, endTime? })` | Mention codes for entities |
+| `getMentionCounts` | `(params: { neid, ... })` | Bucketed mention counts |
+| `getNamedEntitySentiment` | `(neid: string)` | Sentiment for an entity |
+
+**Other:**
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `getHealth` | `()` | Health check |
+| `getStatus` | `()` | Server status and capabilities |
+| `adaMessage` | `(body: AdaMessageBody)` | Ada AI chat |
+
 ## Discovery-First Pattern
 
 The knowledge graph contains many entity types and properties, and new datasets
@@ -81,17 +132,27 @@ knowledge of what's in the graph.
 
 ## API Gotchas
 
-> **WARNING -- `getSchema()` response nesting**: The generated TypeScript types
-> put `flavors` and `properties` at the top level, but the actual API response
-> nests them under a `schema` key. Using `response.properties` directly will
-> crash with `Cannot read properties of undefined`. Always use:
+### `getSchema()` response is nested — WILL crash if you don't handle it
+
+The generated TypeScript types suggest `response.properties` and
+`response.flavors` exist at the top level. **They don't.** The API nests
+them under `response.schema`. This mismatch between types and reality
+causes `Cannot read properties of undefined` every time.
 
 ```typescript
+// WRONG — will crash at runtime despite TypeScript compiling fine:
+const res = await client.getSchema();
+const props = res.properties; // undefined!
+
+// CORRECT — always access through .schema:
 const res = await client.getSchema();
 const properties = res.schema?.properties ?? (res as any).properties ?? [];
 const flavors = res.schema?.flavors ?? (res as any).flavors ?? [];
 ```
 
+The `(res as any).properties` fallback is there in case the API is ever
+fixed to match the types. Use this pattern every time.
+
 > **WARNING -- `getPropertyValues()` takes JSON-stringified arrays**: The `eids`
 > and `pids` parameters must be JSON-encoded strings, NOT native arrays. The
 > TypeScript type is `string`, not `string[]`. Passing a raw array will silently
@@ -139,6 +200,48 @@ See the **cookbook** rule for a full "Get filings for a company" recipe.
   (`POST /elemental/find`). Best for filtered searches (by type, property,
   relationship). See `find.md` for the expression language.
 
+## Common Entity Relationships
+
+The knowledge graph connects entities through relationship properties
+(`data_nindex` PIDs). These are the most common patterns:
+
+| From | PID | To | How to traverse |
+|---|---|---|---|
+| Organization | `filed` | Document (filings) | `getPropertyValues` with the `filed` PID on the org's NEID |
+| Organization | `employs` | Person | `getLinkedEntities` (person is a graph node type) |
+| Person | `employed_by` | Organization | `getLinkedEntities` (organization is a graph node type) |
+| Organization | `headquartered_in` | Location | `getLinkedEntities` (location is a graph node type) |
+| Any entity | `related_to` | Any entity | `getLinkedEntities` for person/org/location; `getPropertyValues` for others |
+
+**Key constraint:** `getLinkedEntities` only works for three target types:
+**person**, **organization**, **location**. For documents, filings,
+articles, financial instruments, and events, use `getPropertyValues` with
+the relationship PID. See the cookbook rule (recipe #7) for a full filings
+example.
+
+**Traversal pattern for non-graph-node types:**
+
+```typescript
+// 1. Get the PID for the relationship
+const schema = await client.getSchema();
+const pids = schema.schema?.properties ?? [];
+const filedPid = pids.find((p: any) => p.name === 'filed')?.pid;
+
+// 2. Get linked entity IDs via getPropertyValues
+const res = await client.getPropertyValues({
+    eids: JSON.stringify([orgNeid]),
+    pids: JSON.stringify([filedPid]),
+});
+
+// 3. Pad IDs to 20 chars to form valid NEIDs
+const docNeids = res.values.map((v: any) => String(v.value).padStart(20, '0'));
+
+// 4. Get details for each linked entity
+const reports = await Promise.all(
+    docNeids.map((neid: string) => client.getNamedEntityReport(neid)),
+);
+```
+
 ## Error Handling
 
 ```typescript

package/rules/architecture.mdc

@@ -133,9 +133,17 @@ Tenant-specific configuration generated during provisioning. Contains GCP projec
 
 ## Built-in Pages
 
-These pages ship with the template and can be kept, modified, or removed based on the app's needs:
-
-- `pages/chat.vue` -- Agent chat UI. Talks to deployed ADK agents through the Portal Gateway. Keep if the app uses AI agents.
-- `pages/mcp.vue` -- MCP Explorer. Browse and test MCP server tools. Keep if the app uses MCP servers.
-- `pages/entity-lookup.vue` -- Entity search tool. Useful for looking up NEIDs. Keep or remove based on the app.
+These pages ship with the template and can be kept, modified, or removed
+based on the app's needs:
+
+- `pages/chat.vue` -- Agent chat UI. Talks to deployed ADK agents through
+  the Portal Gateway with streaming support. Keep if the app uses AI agents.
+- `pages/mcp.vue` -- MCP Explorer. Browse and test MCP server tools. Keep
+  if the app uses MCP servers.
+- `pages/entity-lookup.vue` -- Entity search tool. Useful for looking up
+  NEIDs. Keep or remove based on the app.
+
+If any of these pages are missing from your project, your project may have
+been created from an older template version. Copy them from the latest
+aether-dev source or run `/update_instructions` to check for updates.