mirror of
https://github.com/kennethnym/aris.git
synced 2026-03-20 17:11:17 +00:00
Compare commits
1 Commits
f3db2e35e7
...
feat/agent
| Author | SHA1 | Date | |
|---|---|---|---|
|
243e84622a
|
@@ -16,8 +16,8 @@ Examples of feed items:
|
||||
## Design Principles
|
||||
|
||||
1. **Extensibility**: The core must support different data sources, including third-party sources.
|
||||
2. **Separation of concerns**: Core handles data and UI description. The client is a thin renderer.
|
||||
3. **Dependency graph**: Sources declare dependencies on other sources. The engine resolves the graph and runs independent sources in parallel.
|
||||
2. **Separation of concerns**: Core handles data only. UI rendering is a separate system.
|
||||
3. **Parallel execution**: Sources run in parallel; no inter-source dependencies.
|
||||
4. **Graceful degradation**: Failed sources are skipped; partial results are returned.
|
||||
|
||||
## Architecture
|
||||
@@ -25,28 +25,26 @@ Examples of feed items:
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Backend │
|
||||
│ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ aris-core │ │ Sources │ │
|
||||
│ │ │ │ (plugins) │ │
|
||||
│ │ - FeedEngine│◄───│ - Calendar │ │
|
||||
│ │ - Context │ │ - Weather │ │
|
||||
│ │ - FeedItem │ │ - TfL │ │
|
||||
│ │ - Actions │ │ - Spotify │ │
|
||||
│ └─────────────┘ └─────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ Feed items (data + ui trees + slots) │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
|
||||
│ │ aris-core │ │ Sources │ │ UI Registry │ │
|
||||
│ │ │ │ (plugins) │ │ (schemas from │ │
|
||||
│ │ - Reconciler│◄───│ - Calendar │ │ third parties)│ │
|
||||
│ │ - Context │ │ - Weather │ │ │ │
|
||||
│ │ - FeedItem │ │ - Spotify │ │ │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ Feed (data only) UI Schemas (JSON) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼ (WebSocket / JSON-RPC)
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Client (React Native) │
|
||||
│ Frontend │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ json-render + twrnc component map │ │
|
||||
│ │ - Receives feed items with ui trees │ │
|
||||
│ │ - Renders using registered RN components + twrnc │ │
|
||||
│ │ - User interactions trigger source actions │ │
|
||||
│ │ - Bespoke native components for rich interactions │ │
|
||||
│ │ Renderer │ │
|
||||
│ │ - Receives feed items │ │
|
||||
│ │ - Fetches UI schema by item type │ │
|
||||
│ │ - Renders using json-render or similar │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
@@ -56,16 +54,15 @@ Examples of feed items:
|
||||
The core is responsible for:
|
||||
|
||||
- Defining the context and feed item interfaces
|
||||
- Providing a `FeedEngine` that orchestrates sources via a dependency graph
|
||||
- Providing a reconciler that orchestrates data sources
|
||||
- Returning a flat list of prioritized feed items
|
||||
- Routing action execution to the correct source
|
||||
|
||||
### Key Concepts
|
||||
|
||||
- **Context**: Time and location (with accuracy) passed to all sources. Sources can contribute to context (e.g., location source provides coordinates, weather source provides conditions).
|
||||
- **FeedItem**: Has an ID (source-generated, stable), type, timestamp, JSON-serializable data, optional actions, an optional `ui` tree, and optional `slots` for LLM-fillable content.
|
||||
- **FeedSource**: Interface that first and third parties implement to provide context, feed items, and actions. Uses reverse-domain IDs (e.g., `aris.weather`, `com.spotify`).
|
||||
- **FeedEngine**: Orchestrates sources respecting their dependency graph, runs independent sources in parallel, returns items and any errors. Routes action execution to the correct source.
|
||||
- **Context**: Time and location (with accuracy) passed to all sources
|
||||
- **FeedItem**: Has an ID (source-generated, stable), type, priority, timestamp, and JSON-serializable data
|
||||
- **DataSource**: Interface that third parties implement to provide feed items
|
||||
- **Reconciler**: Orchestrates sources, runs them in parallel, returns items and any errors
|
||||
|
||||
## Data Sources
|
||||
|
||||
@@ -74,13 +71,10 @@ Key decisions:
|
||||
- Sources receive the full context and decide internally what to use
|
||||
- Each source returns a single item type (e.g., separate "Calendar Source" and "Location Suggestion Source" rather than a combined "Google Source")
|
||||
- Sources live in separate packages, not in the core
|
||||
- Sources declare dependencies on other sources (e.g., weather depends on location)
|
||||
- Sources are responsible for:
|
||||
- Transforming their domain data into feed items
|
||||
- Assigning priority based on domain logic (e.g., "event starting in 10 minutes" = high priority)
|
||||
- Returning empty arrays when nothing is relevant
|
||||
- Providing a `ui` tree for each feed item
|
||||
- Declaring and handling actions (e.g., RSVP, complete task, play/pause)
|
||||
|
||||
### Configuration
|
||||
|
||||
@@ -89,39 +83,26 @@ Configuration is passed at source registration time, not per reconcile call. Sou
|
||||
## Feed Output
|
||||
|
||||
- Flat list of `FeedItem` objects
|
||||
- Items carry data, an optional `ui` field describing their layout, and optional `slots` for LLM enhancement
|
||||
- No UI information (no icons, card types, etc.)
|
||||
- Items are a discriminated union by `type` field
|
||||
- Reconciler sorts by priority; can act as tiebreaker
|
||||
|
||||
## UI Rendering: Server-Driven UI
|
||||
## UI Rendering (Separate from Core)
|
||||
|
||||
The UI for feed items is **server-driven**. Sources describe how their items look using a JSON tree (the `ui` field on `FeedItem`). The client renders these trees using [json-render](https://json-render.dev/) with a registered set of React Native components styled via [twrnc](https://github.com/jaredh159/tailwind-react-native-classnames).
|
||||
The core does not handle UI. For extensible third-party UI:
|
||||
|
||||
### How it works
|
||||
1. Third-party apps register their UI schemas through the backend (UI Registry)
|
||||
2. Frontend fetches UI schemas from the backend
|
||||
3. Frontend matches feed items to schemas by `type` and renders accordingly
|
||||
|
||||
1. Sources return feed items with a `ui` field — a JSON tree describing the card layout using Tailwind class strings.
|
||||
2. The client passes a component map to json-render. Each component wraps a React Native primitive and resolves `className` via twrnc.
|
||||
3. json-render walks the tree and renders native components. twrnc parses Tailwind classes at runtime — no build step, arbitrary values work.
|
||||
4. User interactions (tap, etc.) map to source actions via the `actions` field on `FeedItem`. The client sends action requests to the backend, which routes them to the correct source via `FeedEngine.executeAction()`.
|
||||
This approach:
|
||||
|
||||
### Styling
|
||||
- Keeps the core focused on data
|
||||
- Works across platforms (web, React Native)
|
||||
- Avoids the need for third parties to inject code into the app
|
||||
- Uses a json-render style approach for declarative UI from JSON schemas
|
||||
|
||||
- Sources use Tailwind CSS class strings via the `className` prop (e.g., `"p-4 bg-white dark:bg-black rounded-xl"`).
|
||||
- twrnc resolves classes to React Native style objects at runtime. Supports arbitrary values (`mt-[31px]`, `bg-[#eaeaea]`), dark mode (`dark:bg-black`), and platform prefixes (`ios:pt-4 android:pt-2`).
|
||||
- Custom colors and spacing are configured via `tailwind.config.js` on the client.
|
||||
- No compile-time constraint — all styles resolve at runtime.
|
||||
|
||||
### Two tiers of UI
|
||||
|
||||
- **Server-driven (default):** Any source can return a `ui` tree. Covers most cards — weather, tasks, alerts, package tracking, news, etc. Simple interactions go through source actions. This is the default path for both first-party and third-party sources.
|
||||
- **Bespoke native:** For cards that need rich client interaction (gestures, animations, real-time updates), a native React Native component is registered in the json-render component map and referenced by type. Third parties that need this level of richness work with the ARIS team to get it integrated.
|
||||
|
||||
### Why server-driven
|
||||
|
||||
- Feed items are inherently server-driven — the data comes from sources on the backend. Attaching the layout alongside the data is a natural extension.
|
||||
- Card designs can be updated without shipping an app update.
|
||||
- Third-party sources can ship their own UI without bundling anything new into the app.
|
||||
|
||||
Reference: https://json-render.dev/
|
||||
Reference: https://github.com/vercel-labs/json-render
|
||||
|
||||
## Feed Items with UI and Slots
|
||||
|
||||
@@ -403,9 +384,9 @@ function mergeEnhancement(
|
||||
|
||||
## Open Questions
|
||||
|
||||
- How third parties authenticate/register their sources
|
||||
- Exact set of React Native components exposed in the json-render component map
|
||||
- Validation/sandboxing of third-party ui trees
|
||||
- How synthetic items define their UI (full json-render tree vs. registered component)
|
||||
- Exact schema format for UI registry
|
||||
- How third parties authenticate/register their sources and UI schemas
|
||||
- JsonRenderNode type definition and component vocabulary
|
||||
- How synthetic items define their UI (full json-render tree vs. registered schema)
|
||||
- Should slots support rich content (json-render nodes) in the future, or stay text-only?
|
||||
- How to handle slot content that references other items (e.g., "your dinner at The Ivy" linking to the calendar card)
|
||||
|
||||
@@ -125,7 +125,7 @@ interface FeedSource<TItem extends FeedItem = FeedItem> {
|
||||
|
||||
### Changes to FeedItem
|
||||
|
||||
Optional fields added for actions, server-driven UI, and LLM slots.
|
||||
One optional field added.
|
||||
|
||||
```typescript
|
||||
interface FeedItem<
|
||||
@@ -140,12 +140,6 @@ interface FeedItem<
|
||||
|
||||
/** Actions the user can take on this item. */
|
||||
actions?: readonly ItemAction[]
|
||||
|
||||
/** Server-driven UI tree rendered by json-render on the client. */
|
||||
ui?: JsonRenderNode
|
||||
|
||||
/** Named slots for LLM-fillable content. See architecture-draft.md. */
|
||||
slots?: Record<string, Slot>
|
||||
}
|
||||
```
|
||||
|
||||
@@ -228,25 +222,6 @@ class SpotifySource implements FeedSource<SpotifyFeedItem> {
|
||||
{ actionId: "skip-track" },
|
||||
{ actionId: "like-track", params: { trackId: track.id } },
|
||||
],
|
||||
ui: {
|
||||
type: "View",
|
||||
className: "flex-row items-center p-3 gap-3 bg-white dark:bg-black rounded-xl",
|
||||
children: [
|
||||
{
|
||||
type: "Image",
|
||||
source: { uri: track.albumArt },
|
||||
className: "w-12 h-12 rounded-lg",
|
||||
},
|
||||
{
|
||||
type: "View",
|
||||
className: "flex-1",
|
||||
children: [
|
||||
{ type: "Text", className: "font-semibold text-black dark:text-white", text: track.name },
|
||||
{ type: "Text", className: "text-sm text-gray-500 dark:text-gray-400", text: track.artist },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
]
|
||||
}
|
||||
@@ -261,8 +236,6 @@ class SpotifySource implements FeedSource<SpotifyFeedItem> {
|
||||
4. `FeedSource.listActions()` is a required method returning `Record<string, ActionDefinition>` (empty record if no actions)
|
||||
5. `FeedSource.executeAction()` is a required method (no-op for sources without actions)
|
||||
6. `FeedItem.actions` is an optional readonly array of `ItemAction`
|
||||
6b. `FeedItem.ui` is an optional json-render tree describing server-driven UI
|
||||
6c. `FeedItem.slots` is an optional record of named LLM-fillable slots
|
||||
7. `FeedEngine.executeAction()` routes to correct source, returns `ActionResult`
|
||||
8. `FeedEngine.listActions()` aggregates actions from all sources
|
||||
9. Existing tests pass unchanged (all changes are additive)
|
||||
|
||||
@@ -18,9 +18,9 @@ import type { FeedItem } from "./feed"
|
||||
* return [{
|
||||
* id: `weather-${Date.now()}`,
|
||||
* type: this.type,
|
||||
* priority: 0.5,
|
||||
* timestamp: context.time,
|
||||
* data: { temp: data.temperature },
|
||||
* signals: { urgency: 0.5, timeRelevance: "ambient" },
|
||||
* }]
|
||||
* }
|
||||
* }
|
||||
|
||||
@@ -3,7 +3,7 @@ import { describe, expect, test } from "bun:test"
|
||||
import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"
|
||||
|
||||
import { FeedEngine } from "./feed-engine"
|
||||
import { TimeRelevance, UnknownActionError, contextKey, contextValue } from "./index"
|
||||
import { UnknownActionError, contextKey, contextValue } from "./index"
|
||||
|
||||
// No-op action methods for test sources
|
||||
const noActions = {
|
||||
@@ -100,12 +100,12 @@ function createWeatherSource(
|
||||
{
|
||||
id: `weather-${Date.now()}`,
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: {
|
||||
temperature: weather.temperature,
|
||||
condition: weather.condition,
|
||||
},
|
||||
signals: { urgency: 0.5, timeRelevance: TimeRelevance.Ambient },
|
||||
},
|
||||
]
|
||||
},
|
||||
@@ -131,9 +131,9 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
|
||||
{
|
||||
id: "alert-storm",
|
||||
type: "alert",
|
||||
priority: 1.0,
|
||||
timestamp: new Date(),
|
||||
data: { message: "Storm warning!" },
|
||||
signals: { urgency: 1.0, timeRelevance: TimeRelevance.Imminent },
|
||||
},
|
||||
]
|
||||
}
|
||||
@@ -322,7 +322,7 @@ describe("FeedEngine", () => {
|
||||
expect(items[0]!.type).toBe("weather")
|
||||
})
|
||||
|
||||
test("returns items in source graph order (no engine-level sorting)", async () => {
|
||||
test("sorts items by priority descending", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
@@ -338,12 +338,8 @@ describe("FeedEngine", () => {
|
||||
const { items } = await engine.refresh()
|
||||
|
||||
expect(items).toHaveLength(2)
|
||||
// Items returned in topological order (weather before alert)
|
||||
expect(items[0]!.type).toBe("weather")
|
||||
expect(items[1]!.type).toBe("alert")
|
||||
// Signals are preserved for post-processors to consume
|
||||
expect(items[0]!.signals?.urgency).toBe(0.5)
|
||||
expect(items[1]!.signals?.urgency).toBe(1.0)
|
||||
expect(items[0]!.type).toBe("alert") // priority 1.0
|
||||
expect(items[1]!.type).toBe("weather") // priority 0.5
|
||||
})
|
||||
|
||||
test("handles missing upstream context gracefully", async () => {
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
import type { ActionDefinition } from "./action"
|
||||
import type { Context } from "./context"
|
||||
import type { FeedItem } from "./feed"
|
||||
import type { FeedPostProcessor, ItemGroup } from "./feed-post-processor"
|
||||
import type { FeedSource } from "./feed-source"
|
||||
|
||||
export interface SourceError {
|
||||
@@ -13,8 +12,6 @@ export interface FeedResult<TItem extends FeedItem = FeedItem> {
|
||||
context: Context
|
||||
items: TItem[]
|
||||
errors: SourceError[]
|
||||
/** Item groups produced by post-processors */
|
||||
groupedItems?: ItemGroup[]
|
||||
}
|
||||
|
||||
export type FeedSubscriber<TItem extends FeedItem = FeedItem> = (result: FeedResult<TItem>) => void
|
||||
@@ -69,7 +66,6 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
|
||||
private subscribers = new Set<FeedSubscriber<TItems>>()
|
||||
private cleanups: Array<() => void> = []
|
||||
private started = false
|
||||
private postProcessors: FeedPostProcessor[] = []
|
||||
|
||||
private readonly cacheTtlMs: number
|
||||
private cachedResult: FeedResult<TItems> | null = null
|
||||
@@ -112,23 +108,6 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* Registers a post-processor. Processors run in registration order
|
||||
* after items are collected, on every update path.
|
||||
*/
|
||||
registerPostProcessor(processor: FeedPostProcessor): this {
|
||||
this.postProcessors.push(processor)
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* Unregisters a post-processor by reference.
|
||||
*/
|
||||
unregisterPostProcessor(processor: FeedPostProcessor): this {
|
||||
this.postProcessors = this.postProcessors.filter((p) => p !== processor)
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* Refreshes the feed by running all sources in dependency order.
|
||||
* Calls fetchContext() then fetchItems() on each source.
|
||||
@@ -171,20 +150,12 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
|
||||
}
|
||||
}
|
||||
|
||||
// Sort by priority descending
|
||||
items.sort((a, b) => b.priority - a.priority)
|
||||
|
||||
this.context = context
|
||||
|
||||
const {
|
||||
items: processedItems,
|
||||
groupedItems,
|
||||
errors: postProcessorErrors,
|
||||
} = await this.applyPostProcessors(items as TItems[], errors)
|
||||
|
||||
const result: FeedResult<TItems> = {
|
||||
context,
|
||||
items: processedItems,
|
||||
errors: postProcessorErrors,
|
||||
...(groupedItems.length > 0 ? { groupedItems } : {}),
|
||||
}
|
||||
const result: FeedResult<TItems> = { context, items: items as TItems[], errors }
|
||||
this.updateCache(result)
|
||||
|
||||
return result
|
||||
@@ -292,58 +263,6 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
|
||||
return actions
|
||||
}
|
||||
|
||||
private async applyPostProcessors(
|
||||
items: TItems[],
|
||||
errors: SourceError[],
|
||||
): Promise<{ items: TItems[]; groupedItems: ItemGroup[]; errors: SourceError[] }> {
|
||||
let currentItems = items
|
||||
const allGroupedItems: ItemGroup[] = []
|
||||
const allErrors = [...errors]
|
||||
|
||||
for (const processor of this.postProcessors) {
|
||||
const snapshot = currentItems
|
||||
try {
|
||||
const enhancement = await processor(currentItems)
|
||||
|
||||
if (enhancement.additionalItems?.length) {
|
||||
// Post-processors operate on FeedItem[] without knowledge of TItems.
|
||||
// Additional items are merged untyped — this is intentional. The
|
||||
// processor contract is "FeedItem in, FeedItem out"; type narrowing
|
||||
// is the caller's responsibility when consuming FeedResult.
|
||||
currentItems = [...currentItems, ...(enhancement.additionalItems as TItems[])]
|
||||
}
|
||||
|
||||
if (enhancement.suppress?.length) {
|
||||
const suppressSet = new Set(enhancement.suppress)
|
||||
currentItems = currentItems.filter((item) => !suppressSet.has(item.id))
|
||||
}
|
||||
|
||||
if (enhancement.groupedItems?.length) {
|
||||
allGroupedItems.push(...enhancement.groupedItems)
|
||||
}
|
||||
} catch (err) {
|
||||
const sourceId = processor.name || "anonymous"
|
||||
allErrors.push({
|
||||
sourceId,
|
||||
error: err instanceof Error ? err : new Error(String(err)),
|
||||
})
|
||||
currentItems = snapshot
|
||||
}
|
||||
}
|
||||
|
||||
// Remove stale item IDs from groups and drop empty groups
|
||||
const itemIds = new Set(currentItems.map((item) => item.id))
|
||||
const validGroups = allGroupedItems.reduce<ItemGroup[]>((acc, group) => {
|
||||
const ids = group.itemIds.filter((id) => itemIds.has(id))
|
||||
if (ids.length > 0) {
|
||||
acc.push({ ...group, itemIds: ids })
|
||||
}
|
||||
return acc
|
||||
}, [])
|
||||
|
||||
return { items: currentItems, groupedItems: validGroups, errors: allErrors }
|
||||
}
|
||||
|
||||
private ensureGraph(): SourceGraph {
|
||||
if (!this.graph) {
|
||||
this.graph = buildGraph(Array.from(this.sources.values()))
|
||||
@@ -395,17 +314,12 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
|
||||
}
|
||||
}
|
||||
|
||||
const {
|
||||
items: processedItems,
|
||||
groupedItems,
|
||||
errors: postProcessorErrors,
|
||||
} = await this.applyPostProcessors(items as TItems[], errors)
|
||||
items.sort((a, b) => b.priority - a.priority)
|
||||
|
||||
const result: FeedResult<TItems> = {
|
||||
context: this.context,
|
||||
items: processedItems,
|
||||
errors: postProcessorErrors,
|
||||
...(groupedItems.length > 0 ? { groupedItems } : {}),
|
||||
items: items as TItems[],
|
||||
errors,
|
||||
}
|
||||
this.updateCache(result)
|
||||
|
||||
|
||||
@@ -1,443 +0,0 @@
|
||||
import { describe, expect, mock, test } from "bun:test"
|
||||
|
||||
import type { ActionDefinition, FeedItem, FeedPostProcessor, FeedSource } from "./index"
|
||||
|
||||
import { FeedEngine } from "./feed-engine"
|
||||
import { UnknownActionError } from "./index"
|
||||
|
||||
// No-op action methods for test sources
|
||||
const noActions = {
|
||||
async listActions(): Promise<Record<string, ActionDefinition>> {
|
||||
return {}
|
||||
},
|
||||
async executeAction(actionId: string): Promise<void> {
|
||||
throw new UnknownActionError(actionId)
|
||||
},
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// FEED ITEMS
|
||||
// =============================================================================
|
||||
|
||||
type WeatherItem = FeedItem<"weather", { temp: number }>
|
||||
type CalendarItem = FeedItem<"calendar", { title: string }>
|
||||
|
||||
function weatherItem(id: string, temp: number): WeatherItem {
|
||||
return { id, type: "weather", timestamp: new Date(), data: { temp } }
|
||||
}
|
||||
|
||||
function calendarItem(id: string, title: string): CalendarItem {
|
||||
return { id, type: "calendar", timestamp: new Date(), data: { title } }
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// TEST SOURCES
|
||||
// =============================================================================
|
||||
|
||||
function createWeatherSource(items: WeatherItem[]) {
|
||||
return {
|
||||
id: "aris.weather",
|
||||
...noActions,
|
||||
async fetchContext() {
|
||||
return null
|
||||
},
|
||||
async fetchItems(): Promise<WeatherItem[]> {
|
||||
return items
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
function createCalendarSource(items: CalendarItem[]) {
|
||||
return {
|
||||
id: "aris.calendar",
|
||||
...noActions,
|
||||
async fetchContext() {
|
||||
return null
|
||||
},
|
||||
async fetchItems(): Promise<CalendarItem[]> {
|
||||
return items
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// REGISTRATION
|
||||
// =============================================================================
|
||||
|
||||
describe("FeedPostProcessor", () => {
|
||||
describe("registration", () => {
|
||||
test("registerPostProcessor is chainable", () => {
|
||||
const engine = new FeedEngine()
|
||||
const processor: FeedPostProcessor = async () => ({})
|
||||
const result = engine.registerPostProcessor(processor)
|
||||
expect(result).toBe(engine)
|
||||
})
|
||||
|
||||
test("unregisterPostProcessor is chainable", () => {
|
||||
const engine = new FeedEngine()
|
||||
const processor: FeedPostProcessor = async () => ({})
|
||||
const result = engine.unregisterPostProcessor(processor)
|
||||
expect(result).toBe(engine)
|
||||
})
|
||||
|
||||
test("unregistered processor does not run", async () => {
|
||||
const processor = mock(async () => ({}))
|
||||
|
||||
const engine = new FeedEngine()
|
||||
.register(createWeatherSource([weatherItem("w1", 20)]))
|
||||
.registerPostProcessor(processor)
|
||||
.unregisterPostProcessor(processor)
|
||||
|
||||
await engine.refresh()
|
||||
expect(processor).not.toHaveBeenCalled()
|
||||
})
|
||||
})
|
||||
|
||||
// =============================================================================
|
||||
// ADDITIONAL ITEMS
|
||||
// =============================================================================
|
||||
|
||||
describe("additionalItems", () => {
|
||||
test("injects additional items into the feed", async () => {
|
||||
const extra = calendarItem("c1", "Meeting")
|
||||
|
||||
const engine = new FeedEngine()
|
||||
.register(createWeatherSource([weatherItem("w1", 20)]))
|
||||
.registerPostProcessor(async () => ({ additionalItems: [extra] }))
|
||||
|
||||
const result = await engine.refresh()
|
||||
expect(result.items).toHaveLength(2)
|
||||
expect(result.items.find((i) => i.id === "c1")).toBeDefined()
|
||||
})
|
||||
})
|
||||
|
||||
// =============================================================================
|
||||
// SUPPRESS
|
||||
// =============================================================================
|
||||
|
||||
describe("suppress", () => {
|
||||
test("removes suppressed items from the feed", async () => {
|
||||
const engine = new FeedEngine()
|
||||
.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
|
||||
.registerPostProcessor(async () => ({ suppress: ["w1"] }))
|
||||
|
||||
const result = await engine.refresh()
|
||||
expect(result.items).toHaveLength(1)
|
||||
expect(result.items[0].id).toBe("w2")
|
||||
})
|
||||
|
||||
test("suppressing nonexistent ID is a no-op", async () => {
|
||||
const engine = new FeedEngine()
|
||||
.register(createWeatherSource([weatherItem("w1", 20)]))
|
||||
.registerPostProcessor(async () => ({ suppress: ["nonexistent"] }))
|
||||
|
||||
const result = await engine.refresh()
|
||||
expect(result.items).toHaveLength(1)
|
||||
})
|
||||
})
|
||||
|
||||
// =============================================================================
|
||||
// GROUPED ITEMS
|
||||
// =============================================================================
|
||||
|
||||
describe("groupedItems", () => {
|
||||
test("accumulates grouped items on FeedResult", async () => {
|
||||
const engine = new FeedEngine()
|
||||
.register(
|
||||
createCalendarSource([calendarItem("c1", "Meeting A"), calendarItem("c2", "Meeting B")]),
|
||||
)
|
||||
.registerPostProcessor(async () => ({
|
||||
groupedItems: [{ itemIds: ["c1", "c2"], summary: "Busy afternoon" }],
|
||||
}))
|
||||
|
||||
const result = await engine.refresh()
|
||||
expect(result.groupedItems).toEqual([{ itemIds: ["c1", "c2"], summary: "Busy afternoon" }])
|
||||
})
|
||||
|
||||
test("multiple processors accumulate groups", async () => {
|
||||
const engine = new FeedEngine()
|
||||
.register(
|
||||
createCalendarSource([calendarItem("c1", "Meeting A"), calendarItem("c2", "Meeting B")]),
|
||||
)
|
||||
.registerPostProcessor(async () => ({
|
||||
groupedItems: [{ itemIds: ["c1"], summary: "Group A" }],
|
||||
}))
|
||||
.registerPostProcessor(async () => ({
|
||||
groupedItems: [{ itemIds: ["c2"], summary: "Group B" }],
|
||||
}))
|
||||
|
||||
const result = await engine.refresh()
|
||||
expect(result.groupedItems).toEqual([
|
||||
{ itemIds: ["c1"], summary: "Group A" },
|
||||
{ itemIds: ["c2"], summary: "Group B" },
|
||||
])
|
||||
})
|
||||
|
||||
test("stale item IDs are removed from groups after suppression", async () => {
|
||||
const engine = new FeedEngine()
|
||||
.register(
|
||||
createCalendarSource([calendarItem("c1", "Meeting A"), calendarItem("c2", "Meeting B")]),
|
||||
)
|
||||
.registerPostProcessor(async () => ({
|
||||
groupedItems: [{ itemIds: ["c1", "c2"], summary: "Afternoon" }],
|
||||
}))
|
||||
.registerPostProcessor(async () => ({ suppress: ["c1"] }))
|
||||
|
||||
const result = await engine.refresh()
|
||||
expect(result.groupedItems).toEqual([{ itemIds: ["c2"], summary: "Afternoon" }])
|
||||
})
|
||||
|
||||
test("groups with all items suppressed are dropped", async () => {
|
||||
const engine = new FeedEngine()
|
||||
.register(createCalendarSource([calendarItem("c1", "Meeting A")]))
|
||||
.registerPostProcessor(async () => ({
|
||||
groupedItems: [{ itemIds: ["c1"], summary: "Solo" }],
|
||||
}))
|
||||
.registerPostProcessor(async () => ({ suppress: ["c1"] }))
|
||||
|
||||
const result = await engine.refresh()
|
||||
expect(result.groupedItems).toBeUndefined()
|
||||
})
|
||||
|
||||
test("groupedItems is omitted when no processors produce groups", async () => {
|
||||
const engine = new FeedEngine()
|
||||
.register(createWeatherSource([weatherItem("w1", 20)]))
|
||||
.registerPostProcessor(async () => ({}))
|
||||
|
||||
const result = await engine.refresh()
|
||||
expect(result.groupedItems).toBeUndefined()
|
||||
})
|
||||
})
|
||||
|
||||
// =============================================================================
|
||||
// PIPELINE ORDERING
|
||||
// =============================================================================
|
||||
|
||||
describe("pipeline ordering", () => {
|
||||
test("each processor sees items as modified by the previous processor", async () => {
|
||||
const seen: string[] = []
|
||||
|
||||
const engine = new FeedEngine()
|
||||
.register(createWeatherSource([weatherItem("w1", 20)]))
|
||||
.registerPostProcessor(async () => ({
|
||||
additionalItems: [calendarItem("c1", "Injected")],
|
||||
}))
|
||||
.registerPostProcessor(async (items) => {
|
||||
seen.push(...items.map((i) => i.id))
|
||||
return {}
|
||||
})
|
||||
|
||||
await engine.refresh()
|
||||
expect(seen).toEqual(["w1", "c1"])
|
||||
})
|
||||
|
||||
test("suppression in first processor affects second processor", async () => {
|
||||
const seen: string[] = []
|
||||
|
||||
const engine = new FeedEngine()
|
||||
.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
|
||||
.registerPostProcessor(async () => ({ suppress: ["w1"] }))
|
||||
.registerPostProcessor(async (items) => {
|
||||
seen.push(...items.map((i) => i.id))
|
||||
return {}
|
||||
})
|
||||
|
||||
await engine.refresh()
|
||||
expect(seen).toEqual(["w2"])
|
||||
})
|
||||
})
|
||||
|
||||
// =============================================================================
|
||||
// ERROR HANDLING
|
||||
// =============================================================================
|
||||
|
||||
describe("error handling", () => {
|
||||
test("throwing processor is recorded in errors and pipeline continues", async () => {
|
||||
const seen: string[] = []
|
||||
|
||||
async function failingProcessor(): Promise<never> {
|
||||
throw new Error("processor failed")
|
||||
}
|
||||
|
||||
const engine = new FeedEngine()
|
||||
.register(createWeatherSource([weatherItem("w1", 20)]))
|
||||
.registerPostProcessor(failingProcessor)
|
||||
.registerPostProcessor(async (items) => {
|
||||
seen.push(...items.map((i) => i.id))
|
||||
return {}
|
||||
})
|
||||
|
||||
const result = await engine.refresh()
|
||||
|
||||
const ppError = result.errors.find((e) => e.sourceId === "failingProcessor")
|
||||
expect(ppError).toBeDefined()
|
||||
expect(ppError!.error.message).toBe("processor failed")
|
||||
|
||||
// Pipeline continued — observer still saw the original item
|
||||
expect(seen).toEqual(["w1"])
|
||||
expect(result.items).toHaveLength(1)
|
||||
})
|
||||
|
||||
test("anonymous throwing processor uses 'anonymous' as sourceId", async () => {
|
||||
const engine = new FeedEngine()
|
||||
.register(createWeatherSource([weatherItem("w1", 20)]))
|
||||
.registerPostProcessor(async () => {
|
||||
throw new Error("anon failed")
|
||||
})
|
||||
|
||||
const result = await engine.refresh()
|
||||
const ppError = result.errors.find((e) => e.sourceId === "anonymous")
|
||||
expect(ppError).toBeDefined()
|
||||
})
|
||||
|
||||
test("non-Error throw is wrapped", async () => {
|
||||
async function failingProcessor(): Promise<never> {
|
||||
throw "string error"
|
||||
}
|
||||
|
||||
const engine = new FeedEngine()
|
||||
.register(createWeatherSource([weatherItem("w1", 20)]))
|
||||
.registerPostProcessor(failingProcessor)
|
||||
|
||||
const result = await engine.refresh()
|
||||
const ppError = result.errors.find((e) => e.sourceId === "failingProcessor")
|
||||
expect(ppError).toBeDefined()
|
||||
expect(ppError!.error).toBeInstanceOf(Error)
|
||||
})
|
||||
})
|
||||
|
||||
// =============================================================================
|
||||
// REACTIVE PATHS
|
||||
// =============================================================================
|
||||
|
||||
describe("reactive updates", () => {
|
||||
test("post-processors run during reactive context updates", async () => {
|
||||
let callCount = 0
|
||||
|
||||
let triggerUpdate: ((update: Record<string, unknown>) => void) | null = null
|
||||
|
||||
const source: FeedSource = {
|
||||
id: "aris.reactive",
|
||||
...noActions,
|
||||
async fetchContext() {
|
||||
return null
|
||||
},
|
||||
async fetchItems() {
|
||||
return [weatherItem("w1", 20)]
|
||||
},
|
||||
onContextUpdate(callback, _getContext) {
|
||||
triggerUpdate = callback
|
||||
return () => {
|
||||
triggerUpdate = null
|
||||
}
|
||||
},
|
||||
}
|
||||
|
||||
const engine = new FeedEngine()
|
||||
.register(source)
|
||||
.registerPostProcessor(async () => {
|
||||
callCount++
|
||||
return {}
|
||||
})
|
||||
|
||||
engine.start()
|
||||
|
||||
// Wait for initial periodic refresh
|
||||
await new Promise((resolve) => setTimeout(resolve, 50))
|
||||
const countAfterStart = callCount
|
||||
|
||||
// Trigger a reactive context update
|
||||
triggerUpdate!({ foo: "bar" })
|
||||
await new Promise((resolve) => setTimeout(resolve, 50))
|
||||
|
||||
expect(callCount).toBeGreaterThan(countAfterStart)
|
||||
|
||||
engine.stop()
|
||||
})
|
||||
|
||||
test("post-processors run during reactive item updates", async () => {
|
||||
let callCount = 0
|
||||
|
||||
let triggerItemsUpdate: (() => void) | null = null
|
||||
|
||||
const source: FeedSource = {
|
||||
id: "aris.reactive",
|
||||
...noActions,
|
||||
async fetchContext() {
|
||||
return null
|
||||
},
|
||||
async fetchItems() {
|
||||
return [weatherItem("w1", 20)]
|
||||
},
|
||||
onItemsUpdate(callback, _getContext) {
|
||||
triggerItemsUpdate = callback
|
||||
return () => {
|
||||
triggerItemsUpdate = null
|
||||
}
|
||||
},
|
||||
}
|
||||
|
||||
const engine = new FeedEngine()
|
||||
.register(source)
|
||||
.registerPostProcessor(async () => {
|
||||
callCount++
|
||||
return {}
|
||||
})
|
||||
|
||||
engine.start()
|
||||
|
||||
await new Promise((resolve) => setTimeout(resolve, 50))
|
||||
const countAfterStart = callCount
|
||||
|
||||
// Trigger a reactive items update
|
||||
triggerItemsUpdate!()
|
||||
await new Promise((resolve) => setTimeout(resolve, 50))
|
||||
|
||||
expect(callCount).toBeGreaterThan(countAfterStart)
|
||||
|
||||
engine.stop()
|
||||
})
|
||||
})
|
||||
|
||||
// =============================================================================
|
||||
// NO PROCESSORS = NO CHANGE
|
||||
// =============================================================================
|
||||
|
||||
describe("no processors", () => {
|
||||
test("engine without post-processors returns raw items unchanged", async () => {
|
||||
const items = [weatherItem("w1", 20), weatherItem("w2", 25)]
|
||||
const engine = new FeedEngine().register(createWeatherSource(items))
|
||||
|
||||
const result = await engine.refresh()
|
||||
expect(result.items).toHaveLength(2)
|
||||
expect(result.items[0].id).toBe("w1")
|
||||
expect(result.items[1].id).toBe("w2")
|
||||
expect(result.groupedItems).toBeUndefined()
|
||||
})
|
||||
})
|
||||
|
||||
// =============================================================================
|
||||
// COMBINED ENHANCEMENT
|
||||
// =============================================================================
|
||||
|
||||
describe("combined enhancement", () => {
|
||||
test("single processor can use all enhancement fields at once", async () => {
|
||||
const engine = new FeedEngine()
|
||||
.register(createWeatherSource([weatherItem("w1", 20), weatherItem("w2", 25)]))
|
||||
.registerPostProcessor(async () => ({
|
||||
additionalItems: [calendarItem("c1", "Injected")],
|
||||
suppress: ["w2"],
|
||||
groupedItems: [{ itemIds: ["w1", "c1"], summary: "Related" }],
|
||||
}))
|
||||
|
||||
const result = await engine.refresh()
|
||||
|
||||
// w2 suppressed, c1 injected → w1 + c1
|
||||
expect(result.items).toHaveLength(2)
|
||||
expect(result.items.map((i) => i.id)).toEqual(["w1", "c1"])
|
||||
|
||||
// Groups on result
|
||||
expect(result.groupedItems).toEqual([{ itemIds: ["w1", "c1"], summary: "Related" }])
|
||||
})
|
||||
})
|
||||
})
|
||||
@@ -1,23 +0,0 @@
|
||||
import type { FeedItem } from "./feed"
|
||||
|
||||
export interface ItemGroup {
|
||||
/** IDs of items to present together */
|
||||
itemIds: string[]
|
||||
/** Summary text for the group */
|
||||
summary: string
|
||||
}
|
||||
|
||||
export interface FeedEnhancement {
|
||||
/** New items to inject into the feed */
|
||||
additionalItems?: FeedItem[]
|
||||
/** Groups of items to present together with a summary */
|
||||
groupedItems?: ItemGroup[]
|
||||
/** Item IDs to remove from the feed */
|
||||
suppress?: string[]
|
||||
}
|
||||
|
||||
/**
|
||||
* A function that transforms feed items and produces enhancement directives.
|
||||
* Use named functions for meaningful error attribution.
|
||||
*/
|
||||
export type FeedPostProcessor = (items: FeedItem[]) => Promise<FeedEnhancement>
|
||||
@@ -2,7 +2,7 @@ import { describe, expect, test } from "bun:test"
|
||||
|
||||
import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"
|
||||
|
||||
import { TimeRelevance, UnknownActionError, contextKey, contextValue } from "./index"
|
||||
import { UnknownActionError, contextKey, contextValue } from "./index"
|
||||
|
||||
// No-op action methods for test sources
|
||||
const noActions = {
|
||||
@@ -99,12 +99,12 @@ function createWeatherSource(
|
||||
{
|
||||
id: `weather-${Date.now()}`,
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: {
|
||||
temperature: weather.temperature,
|
||||
condition: weather.condition,
|
||||
},
|
||||
signals: { urgency: 0.5, timeRelevance: TimeRelevance.Ambient },
|
||||
},
|
||||
]
|
||||
},
|
||||
@@ -130,9 +130,9 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
|
||||
{
|
||||
id: "alert-storm",
|
||||
type: "alert",
|
||||
priority: 1.0,
|
||||
timestamp: new Date(),
|
||||
data: { message: "Storm warning!" },
|
||||
signals: { urgency: 1.0, timeRelevance: TimeRelevance.Imminent },
|
||||
},
|
||||
]
|
||||
}
|
||||
@@ -226,6 +226,9 @@ async function refreshGraph(graph: SourceGraph): Promise<{ context: Context; ite
|
||||
}
|
||||
}
|
||||
|
||||
// Sort by priority descending
|
||||
items.sort((a, b) => b.priority - a.priority)
|
||||
|
||||
return { context, items }
|
||||
}
|
||||
|
||||
@@ -438,12 +441,8 @@ describe("FeedSource", () => {
|
||||
const { items } = await refreshGraph(graph)
|
||||
|
||||
expect(items).toHaveLength(2)
|
||||
// Items returned in topological order (weather before alert)
|
||||
expect(items[0]!.type).toBe("weather")
|
||||
expect(items[1]!.type).toBe("alert")
|
||||
// Signals preserved for post-processors
|
||||
expect(items[0]!.signals?.urgency).toBe(0.5)
|
||||
expect(items[1]!.signals?.urgency).toBe(1.0)
|
||||
expect(items[0]!.type).toBe("alert") // priority 1.0
|
||||
expect(items[1]!.type).toBe("weather") // priority 0.5
|
||||
})
|
||||
|
||||
test("source without location context returns empty items", async () => {
|
||||
|
||||
@@ -1,28 +1,3 @@
|
||||
/**
|
||||
* Source-provided hints for post-processors.
|
||||
*
|
||||
* Sources express domain-specific relevance without determining final ranking.
|
||||
* Post-processors consume these signals alongside other inputs (user affinity,
|
||||
* time of day, interaction history) to produce the final feed order.
|
||||
*/
|
||||
export const TimeRelevance = {
|
||||
/** Needs attention now (e.g., event starting in minutes, severe alert) */
|
||||
Imminent: "imminent",
|
||||
/** Relevant soon (e.g., event in the next hour, approaching deadline) */
|
||||
Upcoming: "upcoming",
|
||||
/** Background information (e.g., daily forecast, low-priority status) */
|
||||
Ambient: "ambient",
|
||||
} as const
|
||||
|
||||
export type TimeRelevance = (typeof TimeRelevance)[keyof typeof TimeRelevance]
|
||||
|
||||
export interface FeedItemSignals {
|
||||
/** Source-assessed urgency (0-1). Post-processors use this as one ranking input. */
|
||||
urgency?: number
|
||||
/** How time-sensitive this item is relative to now. */
|
||||
timeRelevance?: TimeRelevance
|
||||
}
|
||||
|
||||
/**
|
||||
* A single item in the feed.
|
||||
*
|
||||
@@ -33,9 +8,9 @@ export interface FeedItemSignals {
|
||||
* const item: WeatherItem = {
|
||||
* id: "weather-123",
|
||||
* type: "weather",
|
||||
* priority: 0.5,
|
||||
* timestamp: new Date(),
|
||||
* data: { temp: 18, condition: "cloudy" },
|
||||
* signals: { urgency: 0.5, timeRelevance: "ambient" },
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
@@ -47,10 +22,10 @@ export interface FeedItem<
|
||||
id: string
|
||||
/** Item type, matches the data source type */
|
||||
type: TType
|
||||
/** Sort priority (higher = more important, shown first) */
|
||||
priority: number
|
||||
/** When this item was generated */
|
||||
timestamp: Date
|
||||
/** Type-specific payload */
|
||||
data: TData
|
||||
/** Source-provided hints for post-processors. Optional — omit if no signals apply. */
|
||||
signals?: FeedItemSignals
|
||||
}
|
||||
|
||||
@@ -7,15 +7,11 @@ export type { ActionDefinition } from "./action"
|
||||
export { UnknownActionError } from "./action"
|
||||
|
||||
// Feed
|
||||
export type { FeedItem, FeedItemSignals } from "./feed"
|
||||
export { TimeRelevance } from "./feed"
|
||||
export type { FeedItem } from "./feed"
|
||||
|
||||
// Feed Source
|
||||
export type { FeedSource } from "./feed-source"
|
||||
|
||||
// Feed Post-Processor
|
||||
export type { FeedEnhancement, FeedPostProcessor, ItemGroup } from "./feed-post-processor"
|
||||
|
||||
// Feed Engine
|
||||
export type { FeedEngineConfig, FeedResult, FeedSubscriber, SourceError } from "./feed-engine"
|
||||
export { FeedEngine } from "./feed-engine"
|
||||
|
||||
@@ -72,6 +72,8 @@ export class Reconciler<TItems extends FeedItem = never> {
|
||||
}
|
||||
})
|
||||
|
||||
items.sort((a, b) => b.priority - a.priority)
|
||||
|
||||
return { items, errors } as ReconcileResult<TItems>
|
||||
}
|
||||
}
|
||||
|
||||
@@ -190,22 +190,21 @@ describe("query() with mocked client", () => {
|
||||
expect(imperialTemp).toBeCloseTo(expectedImperial, 2)
|
||||
})
|
||||
|
||||
test("assigns signals based on weather conditions", async () => {
|
||||
test("assigns priority based on weather conditions", async () => {
|
||||
const dataSource = new WeatherKitDataSource({ client: mockClient })
|
||||
const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
|
||||
|
||||
const items = await dataSource.query(context)
|
||||
|
||||
for (const item of items) {
|
||||
expect(item.signals).toBeDefined()
|
||||
expect(item.signals!.urgency).toBeGreaterThanOrEqual(0)
|
||||
expect(item.signals!.urgency).toBeLessThanOrEqual(1)
|
||||
expect(item.signals!.timeRelevance).toBeDefined()
|
||||
expect(item.priority).toBeGreaterThanOrEqual(0)
|
||||
expect(item.priority).toBeLessThanOrEqual(1)
|
||||
}
|
||||
|
||||
const currentItem = items.find((i) => i.type === WeatherFeedItemType.current)
|
||||
expect(currentItem).toBeDefined()
|
||||
expect(currentItem!.signals!.urgency).toBeGreaterThanOrEqual(0.5)
|
||||
// Base priority for current is 0.5, may be adjusted for conditions
|
||||
expect(currentItem!.priority).toBeGreaterThanOrEqual(0.5)
|
||||
})
|
||||
|
||||
test("generates unique IDs for each item", async () => {
|
||||
|
||||
@@ -1,6 +1,4 @@
|
||||
import type { Context, DataSource, FeedItemSignals } from "@aris/core"
|
||||
|
||||
import { TimeRelevance } from "@aris/core"
|
||||
import type { Context, DataSource } from "@aris/core"
|
||||
|
||||
import {
|
||||
WeatherFeedItemType,
|
||||
@@ -107,7 +105,7 @@ export class WeatherKitDataSource implements DataSource<WeatherFeedItem, Weather
|
||||
}
|
||||
}
|
||||
|
||||
const BASE_URGENCY = {
|
||||
const BASE_PRIORITY = {
|
||||
current: 0.5,
|
||||
hourly: 0.3,
|
||||
daily: 0.2,
|
||||
@@ -136,17 +134,17 @@ const MODERATE_CONDITIONS = new Set<ConditionCode>([
|
||||
ConditionCode.BlowingSnow,
|
||||
])
|
||||
|
||||
function adjustUrgencyForCondition(baseUrgency: number, conditionCode: ConditionCode): number {
|
||||
function adjustPriorityForCondition(basePriority: number, conditionCode: ConditionCode): number {
|
||||
if (SEVERE_CONDITIONS.has(conditionCode)) {
|
||||
return Math.min(1, baseUrgency + 0.3)
|
||||
return Math.min(1, basePriority + 0.3)
|
||||
}
|
||||
if (MODERATE_CONDITIONS.has(conditionCode)) {
|
||||
return Math.min(1, baseUrgency + 0.15)
|
||||
return Math.min(1, basePriority + 0.15)
|
||||
}
|
||||
return baseUrgency
|
||||
return basePriority
|
||||
}
|
||||
|
||||
function adjustUrgencyForAlertSeverity(severity: Severity): number {
|
||||
function adjustPriorityForAlertSeverity(severity: Severity): number {
|
||||
switch (severity) {
|
||||
case Severity.Extreme:
|
||||
return 1
|
||||
@@ -155,29 +153,7 @@ function adjustUrgencyForAlertSeverity(severity: Severity): number {
|
||||
case Severity.Moderate:
|
||||
return 0.75
|
||||
case Severity.Minor:
|
||||
return BASE_URGENCY.alert
|
||||
}
|
||||
}
|
||||
|
||||
function timeRelevanceForCondition(conditionCode: ConditionCode): TimeRelevance {
|
||||
if (SEVERE_CONDITIONS.has(conditionCode)) {
|
||||
return TimeRelevance.Imminent
|
||||
}
|
||||
if (MODERATE_CONDITIONS.has(conditionCode)) {
|
||||
return TimeRelevance.Upcoming
|
||||
}
|
||||
return TimeRelevance.Ambient
|
||||
}
|
||||
|
||||
function timeRelevanceForAlertSeverity(severity: Severity): TimeRelevance {
|
||||
switch (severity) {
|
||||
case Severity.Extreme:
|
||||
case Severity.Severe:
|
||||
return TimeRelevance.Imminent
|
||||
case Severity.Moderate:
|
||||
return TimeRelevance.Upcoming
|
||||
case Severity.Minor:
|
||||
return TimeRelevance.Ambient
|
||||
return BASE_PRIORITY.alert
|
||||
}
|
||||
}
|
||||
|
||||
@@ -221,14 +197,12 @@ function createCurrentWeatherFeedItem(
|
||||
timestamp: Date,
|
||||
units: Units,
|
||||
): CurrentWeatherFeedItem {
|
||||
const signals: FeedItemSignals = {
|
||||
urgency: adjustUrgencyForCondition(BASE_URGENCY.current, current.conditionCode),
|
||||
timeRelevance: timeRelevanceForCondition(current.conditionCode),
|
||||
}
|
||||
const priority = adjustPriorityForCondition(BASE_PRIORITY.current, current.conditionCode)
|
||||
|
||||
return {
|
||||
id: `weather-current-${timestamp.getTime()}`,
|
||||
type: WeatherFeedItemType.current,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
conditionCode: current.conditionCode,
|
||||
@@ -245,7 +219,6 @@ function createCurrentWeatherFeedItem(
|
||||
windGust: convertSpeed(current.windGust, units),
|
||||
windSpeed: convertSpeed(current.windSpeed, units),
|
||||
},
|
||||
signals,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -255,14 +228,12 @@ function createHourlyWeatherFeedItem(
|
||||
timestamp: Date,
|
||||
units: Units,
|
||||
): HourlyWeatherFeedItem {
|
||||
const signals: FeedItemSignals = {
|
||||
urgency: adjustUrgencyForCondition(BASE_URGENCY.hourly, hourly.conditionCode),
|
||||
timeRelevance: timeRelevanceForCondition(hourly.conditionCode),
|
||||
}
|
||||
const priority = adjustPriorityForCondition(BASE_PRIORITY.hourly, hourly.conditionCode)
|
||||
|
||||
return {
|
||||
id: `weather-hourly-${timestamp.getTime()}-${index}`,
|
||||
type: WeatherFeedItemType.hourly,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
forecastTime: new Date(hourly.forecastStart),
|
||||
@@ -279,7 +250,6 @@ function createHourlyWeatherFeedItem(
|
||||
windGust: convertSpeed(hourly.windGust, units),
|
||||
windSpeed: convertSpeed(hourly.windSpeed, units),
|
||||
},
|
||||
signals,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -289,14 +259,12 @@ function createDailyWeatherFeedItem(
|
||||
timestamp: Date,
|
||||
units: Units,
|
||||
): DailyWeatherFeedItem {
|
||||
const signals: FeedItemSignals = {
|
||||
urgency: adjustUrgencyForCondition(BASE_URGENCY.daily, daily.conditionCode),
|
||||
timeRelevance: timeRelevanceForCondition(daily.conditionCode),
|
||||
}
|
||||
const priority = adjustPriorityForCondition(BASE_PRIORITY.daily, daily.conditionCode)
|
||||
|
||||
return {
|
||||
id: `weather-daily-${timestamp.getTime()}-${index}`,
|
||||
type: WeatherFeedItemType.daily,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
forecastDate: new Date(daily.forecastStart),
|
||||
@@ -311,19 +279,16 @@ function createDailyWeatherFeedItem(
|
||||
temperatureMax: convertTemperature(daily.temperatureMax, units),
|
||||
temperatureMin: convertTemperature(daily.temperatureMin, units),
|
||||
},
|
||||
signals,
|
||||
}
|
||||
}
|
||||
|
||||
function createWeatherAlertFeedItem(alert: WeatherAlert, timestamp: Date): WeatherAlertFeedItem {
|
||||
const signals: FeedItemSignals = {
|
||||
urgency: adjustUrgencyForAlertSeverity(alert.severity),
|
||||
timeRelevance: timeRelevanceForAlertSeverity(alert.severity),
|
||||
}
|
||||
const priority = adjustPriorityForAlertSeverity(alert.severity)
|
||||
|
||||
return {
|
||||
id: `weather-alert-${alert.id}`,
|
||||
type: WeatherFeedItemType.alert,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
alertId: alert.id,
|
||||
@@ -337,6 +302,5 @@ function createWeatherAlertFeedItem(alert: WeatherAlert, timestamp: Date): Weath
|
||||
source: alert.source,
|
||||
urgency: alert.urgency,
|
||||
},
|
||||
signals,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import type { Context } from "@aris/core"
|
||||
|
||||
import { TimeRelevance, contextValue } from "@aris/core"
|
||||
import { contextValue } from "@aris/core"
|
||||
import { describe, expect, test } from "bun:test"
|
||||
import { readFileSync } from "node:fs"
|
||||
import { join } from "node:path"
|
||||
@@ -15,7 +15,7 @@ import type {
|
||||
} from "./types.ts"
|
||||
|
||||
import { CalendarKey } from "./calendar-context.ts"
|
||||
import { CalendarSource, computeSignals } from "./calendar-source.ts"
|
||||
import { CalendarSource, computePriority } from "./calendar-source.ts"
|
||||
|
||||
function loadFixture(name: string): string {
|
||||
return readFileSync(join(import.meta.dir, "..", "fixtures", name), "utf-8")
|
||||
@@ -185,7 +185,7 @@ describe("CalendarSource", () => {
|
||||
expect(items[0]!.timestamp).toEqual(now)
|
||||
})
|
||||
|
||||
test("assigns signals based on event proximity", async () => {
|
||||
test("assigns priority based on event proximity", async () => {
|
||||
const objects: Record<string, CalendarDAVObject[]> = {
|
||||
"/cal/work": [
|
||||
{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
|
||||
@@ -203,10 +203,8 @@ describe("CalendarSource", () => {
|
||||
const standup = items.find((i) => i.data.title === "Team Standup")
|
||||
const holiday = items.find((i) => i.data.title === "Company Holiday")
|
||||
|
||||
expect(standup!.signals!.urgency).toBe(0.7) // within 2 hours
|
||||
expect(standup!.signals!.timeRelevance).toBe(TimeRelevance.Upcoming)
|
||||
expect(holiday!.signals!.urgency).toBe(0.3) // all-day
|
||||
expect(holiday!.signals!.timeRelevance).toBe(TimeRelevance.Ambient)
|
||||
expect(standup!.priority).toBe(0.7) // within 2 hours
|
||||
expect(holiday!.priority).toBe(0.3) // all-day
|
||||
})
|
||||
|
||||
test("handles calendar with non-string displayName", async () => {
|
||||
@@ -380,7 +378,7 @@ describe("CalendarSource.fetchContext", () => {
|
||||
})
|
||||
})
|
||||
|
||||
describe("computeSignals", () => {
|
||||
describe("computePriority", () => {
|
||||
const now = new Date("2026-01-15T12:00:00Z")
|
||||
|
||||
function makeEvent(overrides: Partial<CalendarEventData>): CalendarEventData {
|
||||
@@ -403,83 +401,73 @@ describe("computeSignals", () => {
|
||||
}
|
||||
}
|
||||
|
||||
test("all-day events get urgency 0.3 and ambient relevance", () => {
|
||||
test("all-day events get priority 0.3", () => {
|
||||
const event = makeEvent({ isAllDay: true })
|
||||
const signals = computeSignals(event, now)
|
||||
expect(signals.urgency).toBe(0.3)
|
||||
expect(signals.timeRelevance).toBe(TimeRelevance.Ambient)
|
||||
expect(computePriority(event, now)).toBe(0.3)
|
||||
})
|
||||
|
||||
test("events starting within 30 minutes get urgency 0.9 and imminent relevance", () => {
|
||||
test("events starting within 30 minutes get priority 0.9", () => {
|
||||
const event = makeEvent({
|
||||
startDate: new Date("2026-01-15T12:20:00Z"),
|
||||
})
|
||||
const signals = computeSignals(event, now)
|
||||
expect(signals.urgency).toBe(0.9)
|
||||
expect(signals.timeRelevance).toBe(TimeRelevance.Imminent)
|
||||
expect(computePriority(event, now)).toBe(0.9)
|
||||
})
|
||||
|
||||
test("events starting exactly at 30 minutes get urgency 0.9", () => {
|
||||
test("events starting exactly at 30 minutes get priority 0.9", () => {
|
||||
const event = makeEvent({
|
||||
startDate: new Date("2026-01-15T12:30:00Z"),
|
||||
})
|
||||
expect(computeSignals(event, now).urgency).toBe(0.9)
|
||||
expect(computePriority(event, now)).toBe(0.9)
|
||||
})
|
||||
|
||||
test("events starting within 2 hours get urgency 0.7 and upcoming relevance", () => {
|
||||
test("events starting within 2 hours get priority 0.7", () => {
|
||||
const event = makeEvent({
|
||||
startDate: new Date("2026-01-15T13:00:00Z"),
|
||||
})
|
||||
const signals = computeSignals(event, now)
|
||||
expect(signals.urgency).toBe(0.7)
|
||||
expect(signals.timeRelevance).toBe(TimeRelevance.Upcoming)
|
||||
expect(computePriority(event, now)).toBe(0.7)
|
||||
})
|
||||
|
||||
test("events later today get urgency 0.5", () => {
|
||||
test("events later today get priority 0.5", () => {
|
||||
const event = makeEvent({
|
||||
startDate: new Date("2026-01-15T20:00:00Z"),
|
||||
})
|
||||
expect(computeSignals(event, now).urgency).toBe(0.5)
|
||||
expect(computePriority(event, now)).toBe(0.5)
|
||||
})
|
||||
|
||||
test("in-progress events get urgency 0.8 and imminent relevance", () => {
|
||||
test("in-progress events get priority 0.8", () => {
|
||||
const event = makeEvent({
|
||||
startDate: new Date("2026-01-15T11:00:00Z"),
|
||||
endDate: new Date("2026-01-15T13:00:00Z"),
|
||||
})
|
||||
const signals = computeSignals(event, now)
|
||||
expect(signals.urgency).toBe(0.8)
|
||||
expect(signals.timeRelevance).toBe(TimeRelevance.Imminent)
|
||||
expect(computePriority(event, now)).toBe(0.8)
|
||||
})
|
||||
|
||||
test("fully past events get urgency 0.2 and ambient relevance", () => {
|
||||
test("fully past events get priority 0.2", () => {
|
||||
const event = makeEvent({
|
||||
startDate: new Date("2026-01-15T09:00:00Z"),
|
||||
endDate: new Date("2026-01-15T10:00:00Z"),
|
||||
})
|
||||
const signals = computeSignals(event, now)
|
||||
expect(signals.urgency).toBe(0.2)
|
||||
expect(signals.timeRelevance).toBe(TimeRelevance.Ambient)
|
||||
expect(computePriority(event, now)).toBe(0.2)
|
||||
})
|
||||
|
||||
test("events on future days get urgency 0.2", () => {
|
||||
test("events on future days get priority 0.2", () => {
|
||||
const event = makeEvent({
|
||||
startDate: new Date("2026-01-16T10:00:00Z"),
|
||||
})
|
||||
expect(computeSignals(event, now).urgency).toBe(0.2)
|
||||
expect(computePriority(event, now)).toBe(0.2)
|
||||
})
|
||||
|
||||
test("urgency boundaries are correct", () => {
|
||||
test("priority boundaries are correct", () => {
|
||||
// 31 minutes from now should be 0.7 (within 2 hours, not within 30 min)
|
||||
const event31min = makeEvent({
|
||||
startDate: new Date("2026-01-15T12:31:00Z"),
|
||||
})
|
||||
expect(computeSignals(event31min, now).urgency).toBe(0.7)
|
||||
expect(computePriority(event31min, now)).toBe(0.7)
|
||||
|
||||
// 2 hours 1 minute from now should be 0.5 (later today, not within 2 hours)
|
||||
const event2h1m = makeEvent({
|
||||
startDate: new Date("2026-01-15T14:01:00Z"),
|
||||
})
|
||||
expect(computeSignals(event2h1m, now).urgency).toBe(0.5)
|
||||
expect(computePriority(event2h1m, now)).toBe(0.5)
|
||||
})
|
||||
})
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import type { ActionDefinition, Context, FeedItemSignals, FeedSource } from "@aris/core"
|
||||
import type { ActionDefinition, Context, FeedSource } from "@aris/core"
|
||||
import { UnknownActionError } from "@aris/core"
|
||||
|
||||
import { TimeRelevance, UnknownActionError } from "@aris/core"
|
||||
import { DAVClient } from "tsdav"
|
||||
|
||||
import type {
|
||||
@@ -202,9 +202,9 @@ function computeTimeRange(now: Date, lookAheadDays: number): { start: Date; end:
|
||||
return { start, end }
|
||||
}
|
||||
|
||||
export function computeSignals(event: CalendarEventData, now: Date): FeedItemSignals {
|
||||
export function computePriority(event: CalendarEventData, now: Date): number {
|
||||
if (event.isAllDay) {
|
||||
return { urgency: 0.3, timeRelevance: TimeRelevance.Ambient }
|
||||
return 0.3
|
||||
}
|
||||
|
||||
const msUntilStart = event.startDate.getTime() - now.getTime()
|
||||
@@ -212,41 +212,40 @@ export function computeSignals(event: CalendarEventData, now: Date): FeedItemSig
|
||||
// Event already started
|
||||
if (msUntilStart < 0) {
|
||||
const isInProgress = now.getTime() < event.endDate.getTime()
|
||||
return isInProgress
|
||||
? { urgency: 0.8, timeRelevance: TimeRelevance.Imminent }
|
||||
: { urgency: 0.2, timeRelevance: TimeRelevance.Ambient }
|
||||
// Currently happening events are high priority; fully past events are low
|
||||
return isInProgress ? 0.8 : 0.2
|
||||
}
|
||||
|
||||
// Starting within 30 minutes
|
||||
if (msUntilStart <= 30 * 60 * 1000) {
|
||||
return { urgency: 0.9, timeRelevance: TimeRelevance.Imminent }
|
||||
return 0.9
|
||||
}
|
||||
|
||||
// Starting within 2 hours
|
||||
if (msUntilStart <= 2 * 60 * 60 * 1000) {
|
||||
return { urgency: 0.7, timeRelevance: TimeRelevance.Upcoming }
|
||||
return 0.7
|
||||
}
|
||||
|
||||
// Later today
|
||||
// Later today (within 24 hours from start of day)
|
||||
const startOfDay = new Date(now)
|
||||
startOfDay.setUTCHours(0, 0, 0, 0)
|
||||
const endOfDay = new Date(startOfDay)
|
||||
endOfDay.setUTCDate(endOfDay.getUTCDate() + 1)
|
||||
|
||||
if (event.startDate.getTime() < endOfDay.getTime()) {
|
||||
return { urgency: 0.5, timeRelevance: TimeRelevance.Upcoming }
|
||||
return 0.5
|
||||
}
|
||||
|
||||
// Future days
|
||||
return { urgency: 0.2, timeRelevance: TimeRelevance.Ambient }
|
||||
return 0.2
|
||||
}
|
||||
|
||||
function createFeedItem(event: CalendarEventData, now: Date): CalendarFeedItem {
|
||||
return {
|
||||
id: `calendar-event-${event.uid}${event.recurrenceId ? `-${event.recurrenceId}` : ""}`,
|
||||
type: "calendar-event",
|
||||
priority: computePriority(event, now),
|
||||
timestamp: now,
|
||||
data: event,
|
||||
signals: computeSignals(event, now),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { TimeRelevance, contextValue, type Context } from "@aris/core"
|
||||
import { contextValue, type Context } from "@aris/core"
|
||||
import { describe, expect, test } from "bun:test"
|
||||
|
||||
import type { ApiCalendarEvent, GoogleCalendarClient, ListEventsOptions } from "./types"
|
||||
@@ -81,17 +81,16 @@ describe("GoogleCalendarSource", () => {
|
||||
expect(allDayItems.length).toBe(1)
|
||||
})
|
||||
|
||||
test("ongoing events get highest urgency (1.0)", async () => {
|
||||
test("ongoing events get highest priority (1.0)", async () => {
|
||||
const source = new GoogleCalendarSource({ client: defaultMockClient() })
|
||||
const items = await source.fetchItems(createContext())
|
||||
|
||||
const ongoing = items.find((i) => i.data.eventId === "evt-ongoing")
|
||||
expect(ongoing).toBeDefined()
|
||||
expect(ongoing!.signals!.urgency).toBe(1.0)
|
||||
expect(ongoing!.signals!.timeRelevance).toBe(TimeRelevance.Imminent)
|
||||
expect(ongoing!.priority).toBe(1.0)
|
||||
})
|
||||
|
||||
test("upcoming events get higher urgency when sooner", async () => {
|
||||
test("upcoming events get higher priority when sooner", async () => {
|
||||
const source = new GoogleCalendarSource({ client: defaultMockClient() })
|
||||
const items = await source.fetchItems(createContext())
|
||||
|
||||
@@ -100,17 +99,16 @@ describe("GoogleCalendarSource", () => {
|
||||
|
||||
expect(soon).toBeDefined()
|
||||
expect(later).toBeDefined()
|
||||
expect(soon!.signals!.urgency).toBeGreaterThan(later!.signals!.urgency!)
|
||||
expect(soon!.priority).toBeGreaterThan(later!.priority)
|
||||
})
|
||||
|
||||
test("all-day events get flat urgency (0.4)", async () => {
|
||||
test("all-day events get flat priority (0.4)", async () => {
|
||||
const source = new GoogleCalendarSource({ client: defaultMockClient() })
|
||||
const items = await source.fetchItems(createContext())
|
||||
|
||||
const allDay = items.find((i) => i.data.eventId === "evt-allday")
|
||||
expect(allDay).toBeDefined()
|
||||
expect(allDay!.signals!.urgency).toBe(0.4)
|
||||
expect(allDay!.signals!.timeRelevance).toBe(TimeRelevance.Ambient)
|
||||
expect(allDay!.priority).toBe(0.4)
|
||||
})
|
||||
|
||||
test("generates unique IDs for each item", async () => {
|
||||
@@ -282,7 +280,7 @@ describe("GoogleCalendarSource", () => {
|
||||
})
|
||||
})
|
||||
|
||||
describe("urgency ordering", () => {
|
||||
describe("priority ordering", () => {
|
||||
test("ongoing > upcoming > all-day", async () => {
|
||||
const source = new GoogleCalendarSource({ client: defaultMockClient() })
|
||||
const items = await source.fetchItems(createContext())
|
||||
@@ -291,8 +289,8 @@ describe("GoogleCalendarSource", () => {
|
||||
const upcoming = items.find((i) => i.data.eventId === "evt-soon")!
|
||||
const allDay = items.find((i) => i.data.eventId === "evt-allday")!
|
||||
|
||||
expect(ongoing.signals!.urgency).toBeGreaterThan(upcoming.signals!.urgency!)
|
||||
expect(upcoming.signals!.urgency).toBeGreaterThan(allDay.signals!.urgency!)
|
||||
expect(ongoing.priority).toBeGreaterThan(upcoming.priority)
|
||||
expect(upcoming.priority).toBeGreaterThan(allDay.priority)
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import type { ActionDefinition, Context, FeedItemSignals, FeedSource } from "@aris/core"
|
||||
import type { ActionDefinition, Context, FeedSource } from "@aris/core"
|
||||
|
||||
import { TimeRelevance, UnknownActionError } from "@aris/core"
|
||||
import { UnknownActionError } from "@aris/core"
|
||||
|
||||
import type {
|
||||
ApiCalendarEvent,
|
||||
@@ -35,10 +35,10 @@ import { DefaultGoogleCalendarClient } from "./google-calendar-api"
|
||||
|
||||
const DEFAULT_LOOKAHEAD_HOURS = 24
|
||||
|
||||
const URGENCY_ONGOING = 1.0
|
||||
const URGENCY_UPCOMING_MAX = 0.9
|
||||
const URGENCY_UPCOMING_MIN = 0.3
|
||||
const URGENCY_ALL_DAY = 0.4
|
||||
const PRIORITY_ONGOING = 1.0
|
||||
const PRIORITY_UPCOMING_MAX = 0.9
|
||||
const PRIORITY_UPCOMING_MIN = 0.3
|
||||
const PRIORITY_ALL_DAY = 0.4
|
||||
|
||||
/**
|
||||
* A FeedSource that provides Google Calendar events and next-event context.
|
||||
@@ -171,13 +171,9 @@ function parseEvent(event: ApiCalendarEvent, calendarId: string): CalendarEventD
|
||||
}
|
||||
}
|
||||
|
||||
function computeSignals(
|
||||
event: CalendarEventData,
|
||||
nowMs: number,
|
||||
lookaheadMs: number,
|
||||
): FeedItemSignals {
|
||||
function computePriority(event: CalendarEventData, nowMs: number, lookaheadMs: number): number {
|
||||
if (event.isAllDay) {
|
||||
return { urgency: URGENCY_ALL_DAY, timeRelevance: TimeRelevance.Ambient }
|
||||
return PRIORITY_ALL_DAY
|
||||
}
|
||||
|
||||
const startMs = event.startTime.getTime()
|
||||
@@ -185,23 +181,17 @@ function computeSignals(
|
||||
|
||||
// Ongoing: start <= now < end
|
||||
if (startMs <= nowMs && nowMs < endMs) {
|
||||
return { urgency: URGENCY_ONGOING, timeRelevance: TimeRelevance.Imminent }
|
||||
return PRIORITY_ONGOING
|
||||
}
|
||||
|
||||
// Upcoming: linear decay from URGENCY_UPCOMING_MAX to URGENCY_UPCOMING_MIN
|
||||
// Upcoming: linear decay from PRIORITY_UPCOMING_MAX to PRIORITY_UPCOMING_MIN
|
||||
const msUntilStart = startMs - nowMs
|
||||
if (msUntilStart <= 0) {
|
||||
return { urgency: URGENCY_UPCOMING_MIN, timeRelevance: TimeRelevance.Ambient }
|
||||
return PRIORITY_UPCOMING_MIN
|
||||
}
|
||||
|
||||
const ratio = Math.min(msUntilStart / lookaheadMs, 1)
|
||||
const urgency = URGENCY_UPCOMING_MAX - ratio * (URGENCY_UPCOMING_MAX - URGENCY_UPCOMING_MIN)
|
||||
|
||||
// Within 30 minutes = imminent, otherwise upcoming
|
||||
const timeRelevance =
|
||||
msUntilStart <= 30 * 60 * 1000 ? TimeRelevance.Imminent : TimeRelevance.Upcoming
|
||||
|
||||
return { urgency, timeRelevance }
|
||||
return PRIORITY_UPCOMING_MAX - ratio * (PRIORITY_UPCOMING_MAX - PRIORITY_UPCOMING_MIN)
|
||||
}
|
||||
|
||||
function createFeedItem(
|
||||
@@ -209,13 +199,14 @@ function createFeedItem(
|
||||
nowMs: number,
|
||||
lookaheadMs: number,
|
||||
): CalendarFeedItem {
|
||||
const priority = computePriority(event, nowMs, lookaheadMs)
|
||||
const itemType = event.isAllDay ? CalendarFeedItemType.allDay : CalendarFeedItemType.event
|
||||
|
||||
return {
|
||||
id: `calendar-${event.calendarId}-${event.eventId}`,
|
||||
type: itemType,
|
||||
priority,
|
||||
timestamp: new Date(nowMs),
|
||||
data: event,
|
||||
signals: computeSignals(event, nowMs, lookaheadMs),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -184,8 +184,7 @@ describe("TflSource", () => {
|
||||
expect(typeof item.id).toBe("string")
|
||||
expect(item.id).toMatch(/^tfl-alert-/)
|
||||
expect(item.type).toBe("tfl-alert")
|
||||
expect(item.signals).toBeDefined()
|
||||
expect(typeof item.signals!.urgency).toBe("number")
|
||||
expect(typeof item.priority).toBe("number")
|
||||
expect(item.timestamp).toBeInstanceOf(Date)
|
||||
}
|
||||
})
|
||||
@@ -221,29 +220,29 @@ describe("TflSource", () => {
|
||||
expect(uniqueIds.size).toBe(ids.length)
|
||||
})
|
||||
|
||||
test("feed items are sorted by urgency descending", async () => {
|
||||
test("feed items are sorted by priority descending", async () => {
|
||||
const source = new TflSource({ client: api })
|
||||
const items = await source.fetchItems(createContext())
|
||||
|
||||
for (let i = 1; i < items.length; i++) {
|
||||
const prev = items[i - 1]!
|
||||
const curr = items[i]!
|
||||
expect(prev.signals!.urgency).toBeGreaterThanOrEqual(curr.signals!.urgency!)
|
||||
expect(prev.priority).toBeGreaterThanOrEqual(curr.priority)
|
||||
}
|
||||
})
|
||||
|
||||
test("urgency values match severity levels", async () => {
|
||||
test("priority values match severity levels", async () => {
|
||||
const source = new TflSource({ client: api })
|
||||
const items = await source.fetchItems(createContext())
|
||||
|
||||
const severityUrgency: Record<string, number> = {
|
||||
const severityPriority: Record<string, number> = {
|
||||
closure: 1.0,
|
||||
"major-delays": 0.8,
|
||||
"minor-delays": 0.6,
|
||||
}
|
||||
|
||||
for (const item of items) {
|
||||
expect(item.signals!.urgency).toBe(severityUrgency[item.data.severity]!)
|
||||
expect(item.priority).toBe(severityPriority[item.data.severity]!)
|
||||
}
|
||||
})
|
||||
|
||||
@@ -317,7 +316,9 @@ describe("TflSource", () => {
|
||||
test("executeAction throws on invalid input", async () => {
|
||||
const source = new TflSource({ client: api })
|
||||
|
||||
await expect(source.executeAction("set-lines-of-interest", "not-an-array")).rejects.toThrow()
|
||||
await expect(
|
||||
source.executeAction("set-lines-of-interest", "not-an-array"),
|
||||
).rejects.toThrow()
|
||||
})
|
||||
|
||||
test("executeAction throws for unknown action", async () => {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import type { ActionDefinition, Context, FeedItemSignals, FeedSource } from "@aris/core"
|
||||
import type { ActionDefinition, Context, FeedSource } from "@aris/core"
|
||||
|
||||
import { TimeRelevance, UnknownActionError, contextValue } from "@aris/core"
|
||||
import { UnknownActionError, contextValue } from "@aris/core"
|
||||
import { LocationKey } from "@aris/source-location"
|
||||
import { type } from "arktype"
|
||||
|
||||
@@ -18,18 +18,12 @@ import { TflApi, lineId } from "./tfl-api.ts"
|
||||
|
||||
const setLinesInput = lineId.array()
|
||||
|
||||
const SEVERITY_URGENCY: Record<TflAlertSeverity, number> = {
|
||||
const SEVERITY_PRIORITY: Record<TflAlertSeverity, number> = {
|
||||
closure: 1.0,
|
||||
"major-delays": 0.8,
|
||||
"minor-delays": 0.6,
|
||||
}
|
||||
|
||||
const SEVERITY_TIME_RELEVANCE: Record<TflAlertSeverity, TimeRelevance> = {
|
||||
closure: TimeRelevance.Imminent,
|
||||
"major-delays": TimeRelevance.Imminent,
|
||||
"minor-delays": TimeRelevance.Upcoming,
|
||||
}
|
||||
|
||||
/**
|
||||
* A FeedSource that provides TfL (Transport for London) service alerts.
|
||||
*
|
||||
@@ -143,26 +137,19 @@ export class TflSource implements FeedSource<TflAlertFeedItem> {
|
||||
closestStationDistance,
|
||||
}
|
||||
|
||||
const signals: FeedItemSignals = {
|
||||
urgency: SEVERITY_URGENCY[status.severity],
|
||||
timeRelevance: SEVERITY_TIME_RELEVANCE[status.severity],
|
||||
}
|
||||
|
||||
return {
|
||||
id: `tfl-alert-${status.lineId}-${status.severity}`,
|
||||
type: "tfl-alert",
|
||||
priority: SEVERITY_PRIORITY[status.severity],
|
||||
timestamp: context.time,
|
||||
data,
|
||||
signals,
|
||||
}
|
||||
})
|
||||
|
||||
// Sort by urgency (desc), then by proximity (asc) if location available
|
||||
// Sort by severity (desc), then by proximity (asc) if location available
|
||||
items.sort((a, b) => {
|
||||
const aUrgency = a.signals?.urgency ?? 0
|
||||
const bUrgency = b.signals?.urgency ?? 0
|
||||
if (bUrgency !== aUrgency) {
|
||||
return bUrgency - aUrgency
|
||||
if (b.priority !== a.priority) {
|
||||
return b.priority - a.priority
|
||||
}
|
||||
if (a.data.closestStationDistance !== null && b.data.closestStationDistance !== null) {
|
||||
return a.data.closestStationDistance - b.data.closestStationDistance
|
||||
|
||||
@@ -145,22 +145,20 @@ describe("WeatherSource", () => {
|
||||
}
|
||||
})
|
||||
|
||||
test("assigns signals based on weather conditions", async () => {
|
||||
test("assigns priority based on weather conditions", async () => {
|
||||
const source = new WeatherSource({ client: mockClient })
|
||||
const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
|
||||
|
||||
const items = await source.fetchItems(context)
|
||||
|
||||
for (const item of items) {
|
||||
expect(item.signals).toBeDefined()
|
||||
expect(item.signals!.urgency).toBeGreaterThanOrEqual(0)
|
||||
expect(item.signals!.urgency).toBeLessThanOrEqual(1)
|
||||
expect(item.signals!.timeRelevance).toBeDefined()
|
||||
expect(item.priority).toBeGreaterThanOrEqual(0)
|
||||
expect(item.priority).toBeLessThanOrEqual(1)
|
||||
}
|
||||
|
||||
const currentItem = items.find((i) => i.type === WeatherFeedItemType.current)
|
||||
expect(currentItem).toBeDefined()
|
||||
expect(currentItem!.signals!.urgency).toBeGreaterThanOrEqual(0.5)
|
||||
expect(currentItem!.priority).toBeGreaterThanOrEqual(0.5)
|
||||
})
|
||||
|
||||
test("generates unique IDs for each item", async () => {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import type { ActionDefinition, Context, FeedItemSignals, FeedSource } from "@aris/core"
|
||||
import type { ActionDefinition, Context, FeedSource } from "@aris/core"
|
||||
|
||||
import { TimeRelevance, UnknownActionError, contextValue } from "@aris/core"
|
||||
import { UnknownActionError, contextValue } from "@aris/core"
|
||||
import { LocationKey } from "@aris/source-location"
|
||||
|
||||
import { WeatherFeedItemType, type WeatherFeedItem } from "./feed-items"
|
||||
@@ -38,7 +38,7 @@ export interface WeatherSourceOptions {
|
||||
const DEFAULT_HOURLY_LIMIT = 12
|
||||
const DEFAULT_DAILY_LIMIT = 7
|
||||
|
||||
const BASE_URGENCY = {
|
||||
const BASE_PRIORITY = {
|
||||
current: 0.5,
|
||||
hourly: 0.3,
|
||||
daily: 0.2,
|
||||
@@ -199,17 +199,17 @@ export class WeatherSource implements FeedSource<WeatherFeedItem> {
|
||||
}
|
||||
}
|
||||
|
||||
function adjustUrgencyForCondition(baseUrgency: number, conditionCode: ConditionCode): number {
|
||||
function adjustPriorityForCondition(basePriority: number, conditionCode: ConditionCode): number {
|
||||
if (SEVERE_CONDITIONS.has(conditionCode)) {
|
||||
return Math.min(1, baseUrgency + 0.3)
|
||||
return Math.min(1, basePriority + 0.3)
|
||||
}
|
||||
if (MODERATE_CONDITIONS.has(conditionCode)) {
|
||||
return Math.min(1, baseUrgency + 0.15)
|
||||
return Math.min(1, basePriority + 0.15)
|
||||
}
|
||||
return baseUrgency
|
||||
return basePriority
|
||||
}
|
||||
|
||||
function adjustUrgencyForAlertSeverity(severity: Severity): number {
|
||||
function adjustPriorityForAlertSeverity(severity: Severity): number {
|
||||
switch (severity) {
|
||||
case "extreme":
|
||||
return 1
|
||||
@@ -218,29 +218,7 @@ function adjustUrgencyForAlertSeverity(severity: Severity): number {
|
||||
case "moderate":
|
||||
return 0.75
|
||||
case "minor":
|
||||
return BASE_URGENCY.alert
|
||||
}
|
||||
}
|
||||
|
||||
function timeRelevanceForCondition(conditionCode: ConditionCode): TimeRelevance {
|
||||
if (SEVERE_CONDITIONS.has(conditionCode)) {
|
||||
return TimeRelevance.Imminent
|
||||
}
|
||||
if (MODERATE_CONDITIONS.has(conditionCode)) {
|
||||
return TimeRelevance.Upcoming
|
||||
}
|
||||
return TimeRelevance.Ambient
|
||||
}
|
||||
|
||||
function timeRelevanceForAlertSeverity(severity: Severity): TimeRelevance {
|
||||
switch (severity) {
|
||||
case "extreme":
|
||||
case "severe":
|
||||
return TimeRelevance.Imminent
|
||||
case "moderate":
|
||||
return TimeRelevance.Upcoming
|
||||
case "minor":
|
||||
return TimeRelevance.Ambient
|
||||
return BASE_PRIORITY.alert
|
||||
}
|
||||
}
|
||||
|
||||
@@ -284,14 +262,12 @@ function createCurrentWeatherFeedItem(
|
||||
timestamp: Date,
|
||||
units: Units,
|
||||
): WeatherFeedItem {
|
||||
const signals: FeedItemSignals = {
|
||||
urgency: adjustUrgencyForCondition(BASE_URGENCY.current, current.conditionCode),
|
||||
timeRelevance: timeRelevanceForCondition(current.conditionCode),
|
||||
}
|
||||
const priority = adjustPriorityForCondition(BASE_PRIORITY.current, current.conditionCode)
|
||||
|
||||
return {
|
||||
id: `weather-current-${timestamp.getTime()}`,
|
||||
type: WeatherFeedItemType.current,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
conditionCode: current.conditionCode,
|
||||
@@ -308,7 +284,6 @@ function createCurrentWeatherFeedItem(
|
||||
windGust: convertSpeed(current.windGust, units),
|
||||
windSpeed: convertSpeed(current.windSpeed, units),
|
||||
},
|
||||
signals,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -318,14 +293,12 @@ function createHourlyWeatherFeedItem(
|
||||
timestamp: Date,
|
||||
units: Units,
|
||||
): WeatherFeedItem {
|
||||
const signals: FeedItemSignals = {
|
||||
urgency: adjustUrgencyForCondition(BASE_URGENCY.hourly, hourly.conditionCode),
|
||||
timeRelevance: timeRelevanceForCondition(hourly.conditionCode),
|
||||
}
|
||||
const priority = adjustPriorityForCondition(BASE_PRIORITY.hourly, hourly.conditionCode)
|
||||
|
||||
return {
|
||||
id: `weather-hourly-${timestamp.getTime()}-${index}`,
|
||||
type: WeatherFeedItemType.hourly,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
forecastTime: new Date(hourly.forecastStart),
|
||||
@@ -342,7 +315,6 @@ function createHourlyWeatherFeedItem(
|
||||
windGust: convertSpeed(hourly.windGust, units),
|
||||
windSpeed: convertSpeed(hourly.windSpeed, units),
|
||||
},
|
||||
signals,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -352,14 +324,12 @@ function createDailyWeatherFeedItem(
|
||||
timestamp: Date,
|
||||
units: Units,
|
||||
): WeatherFeedItem {
|
||||
const signals: FeedItemSignals = {
|
||||
urgency: adjustUrgencyForCondition(BASE_URGENCY.daily, daily.conditionCode),
|
||||
timeRelevance: timeRelevanceForCondition(daily.conditionCode),
|
||||
}
|
||||
const priority = adjustPriorityForCondition(BASE_PRIORITY.daily, daily.conditionCode)
|
||||
|
||||
return {
|
||||
id: `weather-daily-${timestamp.getTime()}-${index}`,
|
||||
type: WeatherFeedItemType.daily,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
forecastDate: new Date(daily.forecastStart),
|
||||
@@ -374,19 +344,16 @@ function createDailyWeatherFeedItem(
|
||||
temperatureMax: convertTemperature(daily.temperatureMax, units),
|
||||
temperatureMin: convertTemperature(daily.temperatureMin, units),
|
||||
},
|
||||
signals,
|
||||
}
|
||||
}
|
||||
|
||||
function createWeatherAlertFeedItem(alert: WeatherAlert, timestamp: Date): WeatherFeedItem {
|
||||
const signals: FeedItemSignals = {
|
||||
urgency: adjustUrgencyForAlertSeverity(alert.severity),
|
||||
timeRelevance: timeRelevanceForAlertSeverity(alert.severity),
|
||||
}
|
||||
const priority = adjustPriorityForAlertSeverity(alert.severity)
|
||||
|
||||
return {
|
||||
id: `weather-alert-${alert.id}`,
|
||||
type: WeatherFeedItemType.alert,
|
||||
priority,
|
||||
timestamp,
|
||||
data: {
|
||||
alertId: alert.id,
|
||||
@@ -400,6 +367,5 @@ function createWeatherAlertFeedItem(alert: WeatherAlert, timestamp: Date): Weath
|
||||
source: alert.source,
|
||||
urgency: alert.urgency,
|
||||
},
|
||||
signals,
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user