Developments and Events

Developments are structured narrative units (name, description, scores, stakeholders with signed impact, sources with quotes) versioned over time. Events are longer-lived story containers that group related developments into a lifecycle (earnings cycle, M&A process, regulatory campaign, geopolitical conflict).

When to use

Use this surface when you need to:

• Explain a market move with who wins/loses (signed impact_score per ticker) and cited sources
• Track a storyline lifecycle via an event_id
• Scan for surprising / important developments
• Filter by public-company ticker involvement
• Backtest “what was known as of T” with end_timestamp

Do not use when you need:

• Realtime novelty-clustered headlines → Wire
• Quoteable document passages → semantic_search
• A single-entity dossier → retrieve_entity
• Exact entity-registry monitoring by canonical_name → Wire (developments use tickers, not Ultralayer entity ids)

Use cases

Ticker blast radius — Find developments that hit a ticker hard in either direction, with signed impacts and quotes.

Code
{
  "stakeholder_symbol": "TSLA",
  "min_impact_score": 0.5,
  "max_impact_score": -0.5,
  "limit": 8
}

Negative for one ticker — Isolate clearly negative impact on a single name.

Code
{
  "stakeholder_symbol": "GOOGL",
  "max_impact_score": -0.5,
  "limit": 8
}

Surprising geopolitics — Scan for high-surprise security developments, not every geopolitics mention.

Code
{
  "development_type": "geopolitical_security",
  "min_surprise_score": 0.6,
  "start_timestamp": "2026-07-20T00:00:00Z",
  "limit": 10
}

Theme → development evidence — Ask in natural language and get structured impact packages back.

Code
{
  "query": "Strait of Hormuz shipping disruption oil",
  "start_timestamp": "2026-07-01T00:00:00Z",
  "limit": 5
}

Theme → event clusters — See how a theme groups into longer-lived stories, not just one-off updates.

Code
{
  "query": "Middle East oil",
  "limit": 5,
  "developments_per_event": 2
}

M&A scan — List active deal storylines without inventing your own type labels.

Code
{
  "event_type": "merger_acquisition",
  "limit": 5,
  "developments_per_event": 1
}

Important prints — Desk scan for high-importance developments without a theme query.

Code
{
  "min_importance_score": 0.8,
  "limit": 10
}

Lifecycle expand — Once you have an event id, pull the full timeline (scheduled → print → follow-ons).

Code
{
  "event_id": 125,
  "limit": 20,
  "include_future_developments": true
}

As-of / backtest search — Ask what developments were known as of a past timestamp.

Code
{
  "query": "Tesla Q2 earnings margins",
  "end_timestamp": "2026-07-22T21:00:00Z",
  "limit": 10
}

As-of single development — Reconstruct one development’s package as it stood at a prior time.

Code
{
  "development_id": 1793,
  "end_timestamp": "2026-07-22T21:00:00Z"
}

Mental model

Code
Event (long-lived story)
  └── Development (versioned fact/update in that story)
        ├── scores: importance / surprise / confidence
        ├── occurrence_*: real-world time + status
        ├── stakeholders[]: PUBLIC_COMPANY + symbol + impact ∈ [-1,1]
        └── sources[]: citations with quotes

A development can belong to multiple events. Always read events / event_ids.

Three clocks (do not conflate):

search_developments

Optional query: semantic over development descriptions, ranked by cosine (cosine not returned in the response). No query: latest version per development_id matching filters, ordered by timestamp DESC.

Packages are large (rationale + per-stakeholder quotes). Prefer tight limit (3–10), then retrieve_development for ids you brief.

occurrence_status values seen: occurred, scheduled, announced, ongoing, rumored — no status filter param.

retrieve_development

Required: development_id. Optional: end_timestamp for as-of (latest version with timestamp <= end).

Missing id → 404. As-of before the development existed → 404. Future end_timestamp → realtime.

search_events

Optional query: semantic over event descriptions. No query: ordered by most recent development activity.

Timestamp filters gate on development activity: an older event still appears if it had a development recorded in-window. No activity → [].

Embedded recent_developments are summaries (no rationale/stakeholders/sources). Escalate with retrieve_* for depth.

retrieve_event_developments

Required: event_id. Returns event metadata + full developments ordered by occurrence_timestamp DESC.

start_timestamp / end_timestamp filter on development recording time (useful for polling new packages). Missing event → 404.

Workflow

1. Decide grain: atomic impact update (developments) vs storyline cluster (events).
2. Prefer ticker + score filters for desk questions; prefer semantic query for themes.
3. Keep limit small; set developments_per_event low (or 0) when scanning events.
4. From a strong hit, expand with retrieve_*.
5. Collapse near-duplicate developments under the same event before briefing.
6. Hand off to Wire for live novelty, semantic search for raw evidence, retrieve_entity for identity packages.

Limitations

• Near-duplicate developments can exist as separate ids for the same real-world fact — dedupe by event + occurrence window + name similarity.
• Stakeholders are PUBLIC_COMPANY + ticker only — no countries/commodities/people as stakeholders.
• Ticker strings are exact and case-sensitive (TSLA ≠ tsla).
• development_type / event_type are not closed enums — inventing labels yields empty results.
• Cosine not exposed for thresholding.
• Packages are heavy — bad default for large scans without tight limits or developments_per_event: 0.
• scheduled status can linger after occurrence time.
• Not filterable by Ultralayer entity ids; use tickers or semantic query text.

FAQ

Q: Wire already has Tesla headlines — why developments?
A: Developments add multi-ticker impact scores, rationales, and event clustering. Wire tells you it printed; developments tell you who is in the blast radius and why.

Q: Why did development_type: "earnings" return nothing?
A: Earnings prints are often typed financial_update; earnings appears more as an event_type. Discover types from hits.

Q: include_future_developments: false still showed “scheduled” items.
A: Filter is on occurrence_timestamp vs now, not on status label. Past-dated schedules remain.

Q: Can I filter by Ultralayer entity name Tesla, Inc.?
A: No. Use stakeholder_symbol: "TSLA" or semantic query text.

Q: search_events with a July window returned an older long-running event — bug?
A: Timestamps gate development activity. Old events with new developments in-window correctly appear.

Q: retrieve_development as-of before the print 404s.
A: Expected — no version existed yet.

Q: search_events vs search_developments?
A: Events for clusters/lifecycles; developments for atomic updates + stakeholder math. Typical flow: search either → grab ids → retrieve_*.