Pulse — Intelligence Engine

Status: Preview · Spec: openapi/pulse.yaml · Base URL: https://pulse.dev.apex.reisiger.org

Pulse is in Preview: authentication and entitlement enforcement are still hardening. Call Pulse only from trusted server-side environments, and expect surface changes before general availability.

Pulse answers "what would happen if…" and "what is moving right now": multi-agent shadow simulations of stakeholder populations reacting to a scenario, plus signal collection, trend and anomaly detection, and investigation sweeps over live sources.

Auth & tenancy: platform Bearer credential; tenant as ?tenant_id=…. Rate limit 120 requests/min.

Shadow simulations

The flagship. POST /v1/simulations takes a scenario prompt (or a pre-designed blueprint) plus configuration — rounds, agent count, interaction style, platforms to emulate, voting mechanics — and runs a population of AI personas through it round by round.

• Watch it live: GET /v1/simulations/{id}/stream is Server-Sent Events (text/event-stream) — rounds, posts, and assembly outcomes as they happen.
• Intervene mid-run: POST /v1/simulations/{id}/inject drops a catalyst into a running simulation (news_break, leaked_document, scandal, policy_reversal, external_shock); 409 if the simulation is not running.
• Inspect afterwards: rounds, personas, the interaction graph, assembly outcomes, results, a synthesised report and summary — then POST …/chat for conversational analysis over the finished run ("which persona group flipped, and after what?").

Blueprints separate design from execution: POST /v1/blueprints/design (or its SSE variant) turns documents and guidance into a reviewable simulation design; run it when ready.

Signals, trends, anomalies

• GET /v1/signals (+ /summary, SSE /stream) — collected external signals, filterable by source type.
• GET /v1/trends/entity | volume | topics — bucketed trend series over the signal store.
• GET /v1/anomalies (+ /baselines) — deviations against learned baselines.

Opportunities

Normalised procurement opportunities collected from a per-tenant portal registry, built for downstream platforms that poll and process them.

• GET /v1/opportunities — list/filter by portal, category (rfp / eoi / tender / pre_qualification / rfi), country, and published/closing date windows. Responses use the APEX envelope (ok / data / meta); opportunity fields are camelCase.
• Poll with the cursor. Pass the returned nextCursor back as since to receive everything new or amended since your last poll. Identifiers are deterministic per source notice — upserting by id gives you zero duplicates across re-collection, and amendments update the existing record rather than creating a new one.
• Cross-portal duplicates are clustered. The same tender published on two portals gets two records (different ids) but a shared nullable clusterId — treat records with the same clusterId as aliases of one canonical opportunity.
• POST /v1/opportunities/collect — trigger an on-demand collection sweep across the tenant's portal registry; blocks until done and returns per-portal outcomes. One portal's failure never aborts the batch. 409 if collection is not enabled for the tenant or a sweep is already in flight.
• GET /v1/opportunities/runs — per-portal run history with status, timing, dedup counts, and errors; use it to monitor collection health. A run may carry a nullable yieldAlert: the run completed but fetched far below the portal's usual volume — a silent failure signal (changed page layout, narrowed feed) worth investigating even though nothing errored.

Portal registries are tenant configuration — which portals are watched, and how often, is agreed per tenant, not hard-coded.

Investigation sweeps

POST /v1/sweeps/investigate and /v1/sweeps/run execute collection sweeps for a target; GET /v1/sweeps/status and /list track them; POST /v1/sweeps/query runs read-only SQL SELECT over accumulated sweep results for your own analysis.

Integration notes

• Abstraction layer, always. Preview status means schema evolution — isolate Pulse behind your own interface so surface changes are a one-file fix.
• Simulations are minutes, not milliseconds. Design UX around the SSE stream or background completion, never a blocking request.
• Simulation output is decision support — synthetic stakeholder reaction, valuable for stress-testing announcements and strategies; do not present it as a prediction with certainty.