Product · Oil MVP
From curated events to explainable oil signals.
Velocy ingests structured events (countries, chokepoints, commodities), runs a transparent V1 causal rule engine, and persists signals with rationale, evidence, watchlists, and source provenance. The Oil cockpit surfaces what the system actually produces today.
Markets move on physical reality — your stack should show the chain.
Headlines are noisy. What desks need is a repeatable link from a fact pattern (where, what, who in the graph) to a directional read with explicit assumptions, invalidation, and instruments to watch. Velocy is built around that chain—not around black-box price calls.
Why now
How Velocy works today
Three layers you can inspect in code and in the product: operational events, deterministic rules, and persisted signals.
Events & graph
Events carry type, time, confidence, and links to countries, chokepoints, and commodities. Structured sources (or legacy source fields) attach for traceability before anything becomes a signal.
Causal rule engine (V1)
Ordered, readable rules evaluate the event graph (e.g. chokepoint closure vs threat, OPEC text heuristics, major producers). Outputs include direction, intensity, horizon, evidence, and suggested futures/ETF tickers—no external ML in this loop.
Signals & Oil cockpit
Signals are stored with rationale, invalidation notes, scoring factors, and guidance watchlists. The /oil page reads the same Prisma rows: timeline, detail, and benchmarks when your database is seeded.
Oil intelligence you can open in the browser.
The Oil cockpit is wired to the knowledge base: producers and chokepoints from seed data, recent signals from the pipeline, and narrative drivers from the commodity page. Ingestion catalogues RSS and institutional sources for future automation—V1 does not auto-create events from feeds.
Operational geography
Chokepoints (e.g. Hormuz, Suez, Bab el-Mandeb) and producer roles inform both rules and UI context.
Same signals as internal tools
What you see on /oil is the same Signal objects staff review on internal routes—no separate marketing dataset.
What a signal contains
Illustrative numbers below; live values depend on your seeded events and rule paths. The shape—direction, intensity, horizon, confidence, evidence, watch tickers—is what the engine persists.
Example layout only. Connect data and run the pipeline to populate real signals.
Linked event (example)
Chokepoint threat — Strait of Hormuz (fixture-style)
Direction
Intensity
Watch tickers (from guidance)
Evidence, scoring, and watchlists
Every signal is designed to be argued with: what strengthened the read, what weakens it, what to watch, and how to invalidate it.
Source provenance
Events accept structured source rows (official, wire, media, analyst). Signals carry a compact provenance snapshot for audit and UI.
Explainable scoring
Short strengthen / weaken bullets capture graph richness, confidence, and rule context—without a hidden composite score.
Guidance & invalidation
Checklists and watch zones (benchmarks, tickers, routes, producer ISOs) serialize with the signal so alerts and reports can reuse the same JSON.
Agent-first outputs
Velocy is not only a web UI. Stable JSON projections support scripts, workers, and future channels—without duplicating business logic in the front end.
Machine API (optional bearer)
Versioned REST for events and oil signals when VELOCY_MACHINE_API_KEY is set.
Alert & digest payloads
AlertPayloadV1 for short pushes; SyntheticReportV1 for bundled summaries—see Documentation.
Automation-ready pipeline
runSignalPipeline is synchronous and idempotent—ready for cron or queue workers when you add them.
Premium, delayed public, or internal
Audience tiers (internal, premium, public delayed, public) and optional release timestamps live on signals and knowledge surfaces. Billing is not wired yet—the schema separates who should see what from how signals are computed.
- INTERNAL by default for pipeline-generated signals.
- PUBLIC_DELAYED + release time supports a responsible public feed later.
- Policy helpers stay out of React—see Documentation.
Use the product as it exists today.
Sign in to access the dashboard and internal tools if your workspace is provisioned. Open the Oil cockpit to see live signals when the database is seeded—or join the waitlist if you are exploring Velocy for your desk.