Sovereign IQ
Intelligence Platform
Documentation · Platform reference

Platform Documentation

Complete technical overview of the Sovereign IQ intelligence engine — architecture, AI models, data sources, and blueprint taxonomy across Scout, Strategist, and Sovereign tiers.

What Is Sovereign IQ?

Sovereign IQ is an AI-powered country intelligence and sovereign risk assessment platform. It generates investment-grade country blueprints across 115+ industry sectors, combining real-time World Bank and IMF economic data with institutional-grade AI analysis powered by our AI intelligence engine.

The platform is designed for investment professionals, development finance institutions, multinational corporations, consulting firms, and government agencies evaluating market entry into emerging and frontier economies.

System Architecture v2.0

Full-Stack Intelligence Infrastructure

Frontend

React 18, Tailwind CSS, Shadcn/UI, Recharts, react-simple-maps, i18n (EN/FR/PT)

PRODUCTION
Backend

Python FastAPI, Motor (async MongoDB), httpx, ThreadPoolExecutor for non-blocking LLM calls

PRODUCTION
AI Engine

AI engine (text, chunked), Gemini Nano Banana (images), Sora 2 (cinematic brief video), OpenAI TTS (audio), Gamma (decks)

ACTIVE
Live Data

World Bank API (8 indicators), IMF WEO (5 forecasts for 122 countries), auto-refreshing

REAL-TIME
PDF Engine

ReportLab — investment-grade format with AI Executive Brief, inline charts, Unicode-safe text, custom cover + back page branding

PRODUCTION
Research Database

1,000+ curated sources across 20 categories with 145 API integrations. Dynamic source injection into AI prompts.

1000 SOURCES
Authentication

JWT with bcrypt password hashing + Admin-approval workflow. Public pages accessible without login.

JWT + APPROVAL
Database

MongoDB via Motor async driver. Collections: users, countries (blueprints with 31-section content), research_sources, generation_logs, leads, report_versions, observations (Data Fabric audit trail).

MONGODB

Pages & Features

Interactive World Map

SVG map (react-simple-maps) with risk-coded markers. Click any country to open its blueprint. Markers are grouped and color-coded by risk level (Stable/Caution/Moderate/High Risk).

Intelligence Feed

Real-time World Bank data showing GDP Growth, Inflation, Unemployment, FDI, Trade/GDP, External Debt/GNI, and Current Account for all tracked countries. Auto-refreshes on server startup.

IMF Economic Forecasts

Live IMF World Economic Outlook data for 122 countries showing GDP Growth, Inflation, Unemployment, Current Account, and Government Debt forecasts for 2023-2026.

Historical Trend Charts

Recharts-powered interactive line charts with 5 economic metrics. Country comparison across 6-year spans with World Bank historical data.

Investment-Grade PDF Export

ReportLab generates 30-60 page investment-grade PDFs with custom cover page, table of contents, economic trends (KPI table + matplotlib charts), full-page illustrations, and back page branding.

Research Database

1,000+ curated intelligence sources across 20 categories with 145 API integrations. Searchable, filterable, with Source Health Monitor.

30 Blueprint Sections — Three Tiers

Each section is generated independently by our AI intelligence engine with a senior economist persona, referencing 1,000+ authoritative data sources. Strategist and Sovereign tiers use chunked Part A + Part B generation for 2× richer content (~10-12k chars per section).

01SCOUT

Country Snapshot

Key indicators, rankings, GDP, population, HDI, credit rating

02SCOUT

Executive Summary

Country overview, sector status, strategic recommendation

03SCOUT

PESTLE Analysis

Political, Economic, Social, Technology, Legal, Environmental

04SCOUT

Market Opportunity

Demand analysis, TAM/SAM/SOM, service gaps

05SCOUT

Government Capacity

Payment mechanisms, budget, fiscal risk

06SCOUT

Competitive Landscape

Operators, market structure, entry barriers

07SCOUT

Business Model

Entry model, revenue streams, phased rollout

08SCOUT

Risk Analysis

Political, economic, operational risks & mitigation

09SCOUT

Financial Projections

CAPEX, revenue forecast, IRR, NPV, payback

10SCOUT

Sovereign Risk

Credit ratings, debt sustainability, macro stability

11SCOUT

Social Impact

Employment, SDG alignment, ESG scoring

12SCOUT

Governance

Institutional framework, regulatory quality, PPP readiness

13STRATEGIST

Stakeholder Map

Decision-makers, blockers, engagement plan

14STRATEGIST

Regulatory Deep Dive

Licensing pathway, compliance roadmap

15STRATEGIST

Value Chain & Margins

Upstream to downstream, profit pool analysis

16STRATEGIST

Technology Readiness

Infrastructure, connectivity, tech adoption

17STRATEGIST

Entry Strategy

Entry mode decision tree, 90-day plan

18STRATEGIST

Local Partner & JV

Partner identification, JV structuring

19STRATEGIST

Scenario Planning

Bull/Base/Bear with decision gates

20STRATEGIST

Tax & Incentives

Tax regime, SEZs, DTAAs, structuring

21STRATEGIST

Talent & Labor

Skill availability, wage benchmarks, unions

22STRATEGIST

Supply Chain & Logistics

Ports, corridors, localization opportunities

23SOVEREIGN

DFI & Blended Finance

Active DFI pipeline matched to deal

24SOVEREIGN

Deal Structuring & PPP

Concession structures, risk allocation

25SOVEREIGN

M&A Targets

Screened targets with valuations

26SOVEREIGN

Geopolitical Brief

Conflict, elections, elite dynamics

27SOVEREIGN

Diplomatic Relations

BITs, trade agreements, dispute history

28SOVEREIGN

IC Investment Memo

Board-ready go/no-go synthesis

29SOVEREIGN

Portfolio Benchmark

Cross-country heatmap comparison

30SOVEREIGN

100-Day Playbook

Week-by-week post-commitment roadmap

AI Studio Capabilities

Multimodal Intelligence Generation

Section Content Generation

Senior economist persona generates up to 31 sections with chunked Part A + Part B rendering for Strategist/Sovereign tiers. Uses the Pyramid Principle: lead with the answer, MECE logic, quantified assertions. 1,000+ source references.

Intelligence Engine
Illustration Generation

AI-generated infographics and section illustrations embedded in both the web interface and the investment-grade PDF report. Full-page rendering with auto-rotation for landscape images.

Gemini Nano Banana
Cinematic Brief Generation

Multi-scene cinematic video briefings — temporarily disabled, planned for the next release. Will be board-ready for investor days, regional strategy sessions, and executive pitches.

Sora 2 + OpenAI TTS
Audio Narration

2-4 minute professional narration of the executive brief — ideal for executives who prefer listening during commutes or travel.

OpenAI TTS
Presentation Deck

Auto-generated slide decks (5-25 slides) with theme picker, language support, and direct link for presentation to stakeholders.

Gamma AI

TechStuff

Full transparency — every LLM, model ID & prompt used across the platform

LLM Models & Providers

Claude Sonnet 4.5

claude-sonnet-4-5-20250929

Provider: Anthropic (via Emergent Universal Key)

Used for: 31 section generation (Part A + Part B), Executive Investment Brief (PDF), References compilation, Audio narration script, Video scene prompts

Pricing: $5 input / $25 output per 1M tokens · Streaming: Yes — chunked streaming to stay under the 60s proxy ceiling

Claude Sonnet 4.6

claude-sonnet-4-6

Provider: Anthropic (via Emergent Universal Key)

Used for: Illustration fallback: generates self-contained HTML + inline SVG that is rendered to PNG via headless Chromium (Playwright). Used when Gemini image generation is unavailable.

Pricing: $5 input / $25 output per 1M tokens · Streaming: Non-streaming, 200s outer timeout

Gemini Nano Banana

gemini-3.1-flash-image-preview

Provider: Google (via Emergent Universal Key)

Used for: Primary illustration generator: per-section infographics + full-page investment infographic. Multimodal response (text + image).

Pricing: $0.04 per image · Streaming: Non-streaming, 90s outer timeout per attempt

OpenAI TTS

tts-1-hd (voice: onyx, speed: 0.95)

Provider: OpenAI (via Emergent Universal Key)

Used for: Audio Overview — 2-4 min MP3 narration of the executive brief. Also used for Sora 2 cinematic brief voiceover (UI currently disabled).

Pricing: $15 per 1M characters · Streaming: Non-streaming

Sora 2

sora-2

Provider: OpenAI (via Emergent Universal Key)

Used for: Cinematic Brief — multi-scene 8s documentary clips stitched by FFmpeg with TTS voiceover overlay. Currently UI-disabled (planned for next release).

Pricing: ~$0.50 per second of rendered video · Streaming: Asynchronous job

Master System Prompt (applied to every section)

You are a senior tier-one strategy economist and country-sector strategist with 20+ years of advisory experience to Fortune 500 corporations, sovereign governments, development finance institutions (IFC, AfDB, World Bank, FMO, DEG, USDFC, BII), and institutional investors across emerging and frontier markets. You write with the analytical rigor, intellectual honesty, and decision-oriented clarity that characterizes top-tier management consulting.

CONTEXT VARIABLES:
- {COUNTRY}: The target country for analysis
- {SECTOR}: The target sector for analysis

MANDATORY STANDARDS FOR EVERY SECTION:
1. DATA RECENCY: Prioritize data from the last 24 months. Flag any data older than 3 years as "legacy benchmark." Always state the reference year alongside every figure.
2. SOURCE RIGOR: Cite only authoritative sources — multilateral institutions (World Bank, IMF, UN, OECD, WTO, UNCTAD), rating agencies (S&P, Moody's, Fitch), national central banks and statistics offices, peer-reviewed journals, top-tier consultancies, and regulated financial disclosures.
3. QUANTIFICATION: Every qualitative assertion must be accompanied by a quantitative anchor (a figure, a ratio, a percentile, a ranking). Avoid vague qualifiers like "significant," "substantial," or "considerable" without numbers.
4. TRIANGULATION: When data sources conflict, present the range and name the sources. Do not average; disclose the divergence.
5. IMPLICATIONS-FIRST WRITING: Every analytical block ends with a "So what?" line that converts the finding into a decision-relevant implication.
6. NO HALLUCINATION: If data is unavailable or unreliable, say so explicitly and offer the nearest reliable proxy. Never fabricate figures.
7. STRUCTURED OUTPUT: Use the exact subsection headers specified in the section prompt. Include the data tables, matrices, and frameworks requested.
8. TONE: Tier-one consulting senior partner — analytical, confident, occasionally contrarian where evidence supports, never promotional. Assume the reader is a CEO, IC member, or sovereign minister with 10 minutes to make a decision.

OUTPUT FORMAT:
- Markdown-ready with H2/H3 headers
- Tables in pipe-separated markdown format
- Bullet points only where they add scanability; otherwise prose
- Every figure cited inline with source and year
- End every section with a standalone "KEY TAKEAWAYS FOR DECISION-MAKERS" box containing 3-5 bullets

Chunked Generation · Part A + Part B

Every section runs through two streaming LLM calls (plus a self-heal pass). Combined output ~3,000-3,500 words. Each chunk is clamped to ~800 words to finish under the 60s proxy ceiling.

PART A PROMPT (first half, max 800w)

{SECTION_PROMPT}

CRITICAL: You are writing PART 1 OF 2 of this section. Produce the FIRST HALF only — cover the opening subsections in depth (context, landscape, quantitative baseline, first frameworks/tables). Keep the response under 800 words. DO NOT write a KEY TAKEAWAYS box yet. Stop cleanly at a natural subsection boundary so Part 2 can continue.

IMPORTANT: Do NOT include any 'Part 1 of 2' header, 'Part 2 continues' footer, or other chunk-marker text in your output — write as if this is one continuous document.

PART B PROMPT (second half + KEY TAKEAWAYS + sentinel)

{SECTION_PROMPT}

CRITICAL: You are writing PART 2 OF 2 of this section, CONTINUING from Part 1. Do NOT repeat anything already covered.

STRICT OUTPUT STRUCTURE — you MUST produce in this exact order:
1) The SECOND HALF continuation covering remaining subsections (deeper frameworks, strategic implications, recommendations) — at most 500 words.
2) Then IMMEDIATELY a '## KEY TAKEAWAYS FOR DECISION-MAKERS' section containing 3-5 bullet points (decision-ready, quantified where possible) — at most 200 words.
3) Finally, on a new line at the very end, print this exact sentinel marker verbatim: `--- END OF SECTION ---`. This marker is REQUIRED — do not summarise, omit, or paraphrase it. Nothing may come after it.

Total Part 2 length MUST be under 700 words. Reserve room to complete the KEY TAKEAWAYS box AND the END OF SECTION marker — both are non-negotiable. Be concise; density over breadth.

IMPORTANT: Do NOT include any 'Part 2 of 2', 'PART 2:', 'continuing from Part 1' header or similar chunk-marker text. Write as a seamless continuation.

=== TAIL OF PART 1 FOR CONTINUITY ===
{part_a_tail}
=== END ===

Now write PART 2:

SELF-HEAL COMPLETION CALL (triggered if sentinel missing)

You previously wrote PART 2 of a section but the output was cut off before the mandatory '--- END OF SECTION ---' marker.

=== TAIL OF YOUR PREVIOUS OUTPUT ===
{tail_b}
=== END ===

Continue from exactly where you stopped. Complete the current sentence/bullet, then finish the KEY TAKEAWAYS FOR DECISION-MAKERS box (add any missing bullets to reach 3-5 total), and finally print the sentinel marker verbatim on its own line: `--- END OF SECTION ---`. Keep your continuation under 250 words. Nothing may come after the marker.

Pipeline Guardrails & Architecture

Chunked generation

Every section is generated in 2 streaming calls — Part A (~800w) and Part B (~500w body + 200w KEY TAKEAWAYS box + "--- END OF SECTION ---" sentinel). Self-healing completion call triggers if the sentinel is missing. Keeps each call under the 60s Emergent proxy ceiling.

Per-country lock

asyncio.Lock registry prevents parallel section generations on the same country. Concurrent requests return "queued" with a live queue-ahead count.

Illustration fallback chain

Gemini is tried with 3 prompt variants (detailed → intent-preserving → generic safe). If the admin has toggled to Claude HTML, the Playwright renderer is used instead. PNG bytes are base64-encoded and stored in countries.section_illustrations.<key>.

PDF rendering

ReportLab composes a 30-60 page PDF: cover, ToC, Executive Brief page, inline charts (PESTLE radar, governance scorecard, revenue forecast, risk matrix, sovereign radar), per-section illustrations (image-compressed to JPEG q70 to stay under the 60s ingress ceiling), references, back page branding. Clickable www.sovereigniq.org footer on all 122+ pages.

Budget guard

_classify_llm_error() is a central helper that detects "Budget has been exceeded" and returns a clean 503 with a "Top up Universal Key" message. Automation aborts immediately on budget breach (no wasted retries).

Source injection

Each section prompt is appended with dynamic data_sources drawn from 1,000+ curated entries across 20 categories (192 APIs). Keeps citations grounded in the admin-managed research database.

30 Section Prompts

AI Studio · Inline Prompts

Illustration Prompts (Gemini + Claude HTML fallback)

Admin can toggle between Gemini Nano Banana (direct image gen) and Claude Sonnet 4.6 HTML→PNG (headless Chromium render) from the User Management page. Both paths store identical countries.section_illustrations.<key> shape.

Talk to our team

Ready to see Sovereign IQ in action?

Schedule a live walkthrough or get a sample 31-section blueprint tailored to your target country & sector.

  • 31-section investment-grade country blueprints on demand
  • Live World Bank + IMF data, 1,000+ sources
  • PDF, Gamma deck, audio brief, and Sora 2 cinematic video

We'll reply within 1 business day. No spam.

Analytics cookies

We use a single cookie to measure how Sovereign IQ is being used (page views, scroll depth, where you came from). No third-party trackers, no personal data sold. You can decline and the site works exactly the same.