What is Futuros?
Futuros is the intelligence layer for frontier technology in Latin America. It gathers comparable data from 25 countries and 10 sector axes (education, health, security, environment, labor, democratic governance, infrastructure, innovation, justice, social cohesion), links each datum one-to-one with its primary source, and turns it into actionable intelligence for governments, financial institutions, companies, and civil society.
The platform lives at futuros.xyz. This documentation explains how it works on the inside: where the figures come from, how they are verified, and why provenance is the central asset.
The traceability contract
Every figure on screen traces back to a specific primary-source record in two clicks. No number without a source. No projection without its base rate and its declared assumption. Every claim carries its citation or its [SUPUESTO] (assumption) tag.
This is not a slogan: it is a build rule. The build fails if a citation link points to a generic source instead of the specific country + indicator record. Traceability is the platform's competitive moat — and the constraint that keeps it honest.
How a figure reaches the screen
Every hop in the diagram is verifiable in the repository:
- Ingestion — the adapters (
scripts/sources/adapters.ts, viascripts/ingest-multisource.ts) are additive (existing indicators are never touched), idempotent (re-running replaces by stable id, never duplicates), and honest (a gap is discarded, never fabricated). - Cell — one per axis × geography:
public/data/parameter-cache/<axis>__<ISO>.json, 260 files (10 axes × 26 geographies: 25 countries plus the regional aggregate). The filename uses the axis slug (trabajo-economia), which is the schema key and does not change. Each indicator carriesvalue,series,vintage_year,source_url, and acitation_id. - Citation — one record per figure in
public/data/citations.json(15,098 records as of Aug 2026, across 336 distinct primary sources), fixed shape{id, source, title, url, retrieved_at, year}. Theidprefix (wb-…,oecd-…) resolves the source-registry entry (src/lib/source-registry.ts), whoseurl_templatebuilds the deep-link. - SPA and rendering — the frontend (
src/lib/api.ts) does a same-originfetchof those static JSON files (zero backend, zero LLM in the path), and every number goes through<Traced value cite>, which attaches a<CiteRef>: the figure itself is underlined, hover = a card with title and year, click = the specific source. Instrictmode, an id that does not resolve renders as a marker without a link — a synthetic record that fakes evidence is never fabricated.
The contract as build invariants
The contract does not depend on editorial discipline: it is encoded as a chain of gates in the prebuild hook of package.json. The chain runs two typechecks (scripts and server) and the full 2,076-test suite, then twenty-one check-* gates, then the four data bakes (bake-data-health, bake-source-ledger, bake-api, bake-feeds), and closes by verifying the bake. Any violation is exit 1: red build, not a warning — vite build never runs on data that breaks an invariant.
Gate (scripts/) | Invariant that breaks the build |
|---|---|
check-traced.ts | No number on block surfaces or country cover surfaces renders outside <Traced/> (a grep of the fmtNumber / formatVal / toFixed formatters; exceptions only with an explicit marker, e.g. simulator output). |
check-signals.ts | Every extracted signal has a real source_url present in its source document, and its figure (figure) appears verbatim in the document fragment — no invented numbers. |
check-source-links.ts | Every citation deep-links to a specific record. Fail-closed: a new source without a url_template falls back to the generic landing page and the build fails; the exceptions are a short, justified allowlist. |
check-citations.ts | Every citation referenced by a pilot or archetype resolves to a real record (in citations.json, in the archetype, or to a known key in the source registry) — zero dead citations in front of a stakeholder. |
check-scores.ts | The composite index (scores.json) covers every geography in the parameter-cache (minus quarantines), with composite ∈ [0, 100] and no NaN. |
check-provenance.ts | Every value under hash / digest / signature keys is a full 64-hex SHA-256 or an explicit "no digest" marker — never a truncated hash that fakes a nonexistent cryptographic guarantee. |
check-catalog.ts | Every dataset registered for the assistant points to an existing, populated file or directory; it also re-emits catalog.json, the machine inventory of the corpus. |
check-api.ts | The re-baked static API exactly mirrors public/data: same citation count, one observation per cache cell, parseable bulk CSV/XLSX, and ES/EN/PT labels in sync with the metric registry. |
The operating principle
If it cannot be traced back to a primary source, it is not published as a value. A datum with a cite-only license may appear as a reference, never as a republished figure. Honesty when something is not configured or cannot be verified is part of the contract, not an exception.
The four-pillar flywheel
The platform's strategy is a self-reinforcing cycle:
Data contributed with consent and verifiable provenance feeds a regional sovereign model, whose results strengthen democratic governance and accelerate the private sector's technological frontier — and that value attracts more data.
No audience is privileged over another: the cycle is the story. Each pillar is at once the result of the previous one and the input of the next. The order is causal, not arbitrary. Read the full cycle in The four-pillar cycle; on the platform itself, the flywheel has its own live surface at futuros.xyz/pilares.
The four strategic pillars
| # | Pillar | What it is | Live surfaces |
|---|---|---|---|
| 1 | Data Trust | Contribution infrastructure: institutions, companies, and individuals contribute data under granular consent and receive a verifiable provenance receipt. Rights, not ownership. | /contribuir · /datos-abiertos · /linaje |
| 2 | Sovereign Model | Regional inference on open weights, with the data and the query inside the jurisdiction. Facts live in RAG with deterministic citations — never baked into the weights. | Global assistant — the chat panel lives across the whole platform, available on every route; /sala integrates it deeply ("Go deeper in chat") · a "sovereign mode" badge when inference runs on an endpoint inside the region (requires explicit configuration; without it the badge does not appear) |
| 3 | Governance & Democracy | The model's results in the service of regulators and institutions: cited observatories, election monitoring, auditable situational intelligence. | /gobernanza/observatorio · /gobernanza/regulacion · /sala |
| 4 | Frontier Intelligence | The private sector's decision layer: markets terminal, BI analysis with deterministic provenance, post-AGI economy and compute-sovereignty lenses. | /mercados · /explorar · /economia-agi |
The surfaces listed are a sample, not the full inventory: pillar 3 also includes /gobernanza/elecciones, /gobernanza/transparencia, /consenso, and /prioridades; pillar 4, /soberania-computo, /dependencia, /movimientos, and /alertas, plus the embeddable boards, the MCP server, and the public API. The per-pillar inventory lives in each pillar's chapter.
In grant materials, pillar 3 also carries the name Governance Engine (Motor de Gobernanza); the full three-pillar mapping lives in the grant frame inside the cycle.
The "four strategic pillars" are a lens on the platform's why. They are distinct from the 10 sector axes (education, health, security…), which are the content taxonomy underneath. "Axis" is the canonical noun for each of the ten (state/TAXONOMY_GLOSSARY.md): it replaces "dimension", "pillar" and "parameter" in copy, even though the schema key stays parameter. "Pillar" is reserved for the four strategic ones, which are always named in full.
Who it serves
- Governments and regulators — indicators comparable across countries, observatories of democratic resilience and of regulation, situational intelligence with every alert auditable. The region regulates from its own legal traditions, not with US or EU templates.
- Financial institutions (IDB, CAF, ECLAC) — bankable figures: a cited figure is an investable figure. Pilot → financing → decision-maker chain.
- Private sector — markets terminal, in-browser BI exploration, dependency and post-AGI economy lenses to decide investment and deployment.
- Civil society and research — an open public API, open data with a declared license, anonymous consensus voting, and the lineage of every figure in plain view.
How to navigate this documentation
- Getting started — this page, the four-pillar cycle, and a tour of the platform.
- The four pillars — one chapter per pillar, with the thesis, the verifiable mechanics, and the live surfaces: Data Trust, Sovereign Model, Governance & Democracy, Frontier Intelligence.
- How it works — the data pipeline, public sources, provenance and citations, the provenance roadmap, The Futuros Index, the assistant, and methodology and honesty.
- Developers (EN) — the public API v1, the MCP server, embeds and white-label, and sovereign self-hosting.
Documentation in Spanish for the region's audience; the technical integration reference is in English, following the repository's conventions.