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)
Backend
Python FastAPI, Motor (async MongoDB), httpx, ThreadPoolExecutor for non-blocking LLM calls
AI Engine
AI engine (text, chunked), Gemini Nano Banana (images), Sora 2 (cinematic brief video), OpenAI TTS (audio), Gamma (decks)
Live Data
World Bank API (8 indicators), IMF WEO (5 forecasts for 122 countries), auto-refreshing
PDF Engine
ReportLab — investment-grade format with AI Executive Brief, inline charts, Unicode-safe text, custom cover + back page branding
Research Database
1,000+ curated sources across 20 categories with 145 API integrations. Dynamic source injection into AI prompts.
Authentication
JWT with bcrypt password hashing + Admin-approval workflow. Public pages accessible without login.
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).
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).
Country Snapshot
Key indicators, rankings, GDP, population, HDI, credit rating
Executive Summary
Country overview, sector status, strategic recommendation
PESTLE Analysis
Political, Economic, Social, Technology, Legal, Environmental
Market Opportunity
Demand analysis, TAM/SAM/SOM, service gaps
Government Capacity
Payment mechanisms, budget, fiscal risk
Competitive Landscape
Operators, market structure, entry barriers
Business Model
Entry model, revenue streams, phased rollout
Risk Analysis
Political, economic, operational risks & mitigation
Financial Projections
CAPEX, revenue forecast, IRR, NPV, payback
Sovereign Risk
Credit ratings, debt sustainability, macro stability
Social Impact
Employment, SDG alignment, ESG scoring
Governance
Institutional framework, regulatory quality, PPP readiness
Stakeholder Map
Decision-makers, blockers, engagement plan
Regulatory Deep Dive
Licensing pathway, compliance roadmap
Value Chain & Margins
Upstream to downstream, profit pool analysis
Technology Readiness
Infrastructure, connectivity, tech adoption
Entry Strategy
Entry mode decision tree, 90-day plan
Local Partner & JV
Partner identification, JV structuring
Scenario Planning
Bull/Base/Bear with decision gates
Tax & Incentives
Tax regime, SEZs, DTAAs, structuring
Talent & Labor
Skill availability, wage benchmarks, unions
Supply Chain & Logistics
Ports, corridors, localization opportunities
DFI & Blended Finance
Active DFI pipeline matched to deal
Deal Structuring & PPP
Concession structures, risk allocation
M&A Targets
Screened targets with valuations
Geopolitical Brief
Conflict, elections, elite dynamics
Diplomatic Relations
BITs, trade agreements, dispute history
IC Investment Memo
Board-ready go/no-go synthesis
Portfolio Benchmark
Cross-country heatmap comparison
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.
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.
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.
Audio Narration
2-4 minute professional narration of the executive brief — ideal for executives who prefer listening during commutes or travel.
Presentation Deck
Auto-generated slide decks (5-25 slides) with theme picker, language support, and direct link for presentation to stakeholders.
TechStuff
Full transparency — every LLM, model ID & prompt used across the platform
LLM Models & Providers
Claude Sonnet 4.5
claude-sonnet-4-5-20250929Provider: 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-6Provider: 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-previewProvider: 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-2Provider: 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 bulletsChunked 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.
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