Skip to content

About

๐ŸŽฏ AI-Powered Financial Causal Inference Engine - Visualize the Butterfly Effect in Macroeconomics

Topics

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

ย 

History

12 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐ŸŽฏ Domino-Agent: AI-Powered Financial Causal Inference Engine

CI Python FastAPI Next.js langchain License

Visualize the "Butterfly Effect" in Macroeconomics with AI

Demo โ€ข Features โ€ข Quick Start โ€ข Architecture โ€ข Contributing


Note

Project status: working prototype. The causal-inference engine (backend/) runs end-to-end; the frontend/ directory is a placeholder โ€” the demo screenshots show the exploratory UI from the prototyping phase, not a shipped web app. Treat the FastAPI/Next.js badges below as the target architecture.

๐ŸŒŸ What is Domino-Agent?

Domino-Agent is an AI-powered financial analysis system that automatically discovers and visualizes causal chains in macroeconomic events. Using Large Language Models (LLMs) and graph theory, it helps analysts understand how a single event can trigger a cascade of impacts across global markets.

Why Domino-Agent?

  • ๐Ÿง  AI-Driven Analysis: Leverages GPT-4/DeepSeek to identify hidden causal relationships
  • ๐Ÿ“Š Interactive Visualization: Beautiful force-directed graphs with real-time animations
  • ๐Ÿ”— Multi-Layer Impact Discovery: Recursively explores direct and downstream effects
  • ๐Ÿ’ผ Professional Reports: Auto-generates executive summaries in financial language
  • โšก Real-Time Processing: Fast API backend with modern React frontend

๐ŸŽฌ Demo

Try it yourself: Enter any macro event like "Fed raises interest rates by 50bps" and watch the causal chain unfold.

Example 1: Trump Election Victory

Demo 1 - Trump Election

Analysis: "็‰นๆœ—ๆ™ฎ่ตขๅพ—ๅคง้€‰" (Trump wins election)

  • ๐Ÿ”ด Root Event: Political shift
  • ๐Ÿ”ต Direct Impacts: US Dollar strength, Treasury yields, Defense stocks
  • ๐Ÿ”ต Downstream Effects: Emerging market currencies, Renewable energy sector

Example 2: Fed Rate Hike

Demo 2 - Fed Rate Hike

Analysis: "็พŽ่”ๅ‚จๅŠ ๆฏ 50 ไธชๅŸบ็‚น" (Fed raises rates by 50bps)

  • ๐Ÿ”ด Root Event: Monetary policy tightening
  • ๐Ÿ”ต Multi-Agent Analysis: Detective proposes creative impacts, Reviewer validates
  • ๐Ÿ”ต Console Logs: See the AI agents' debate in real-time

  • Sidebar Controls: Dedicated control panel for clean UX
  • Responsive Layout: Works on desktop and tablet

๐Ÿš€ Quick Start

Prerequisites

  • Python 3.9+
  • Node.js 18+
  • OpenAI API Key (or compatible endpoint like DeepSeek)

1๏ธโƒฃ Backend Setup

cd backend

# Install dependencies
pip install -r requirements.txt

# Configure API Key
echo "OPENAI_API_KEY=your_key_here" > .env

# Start server
python -m uvicorn main:app --reload

The API will run on http://localhost:8000

2๏ธโƒฃ Frontend Setup

cd frontend

# Install dependencies
npm install

# Start dev server
npm run dev

Open http://localhost:3000 in your browser.

3๏ธโƒฃ Usage

  1. Enter a macro event in the sidebar (e.g., "Oil prices surge by 20%")
  2. Click "ๅผ€ๅง‹ๆŽจๆผ”" (Simulate)
  3. Watch the causal graph build in real-time
  4. Hover over connections to see explanations
  5. Read the AI-generated report at the bottom

๐Ÿ—๏ธ Architecture

graph LR
    A[User Input] --> B[FastAPI Backend]
    B --> C[LangChain + LLM]
    C --> D[NetworkX Graph]
    D --> E[JSON Response]
    E --> F[Next.js Frontend]
    F --> G[ForceGraph2D]
    G --> H[Interactive Visualization]
Loading

Tech Stack

Backend

  • FastAPI (API framework)
  • LangChain (LLM orchestration)
  • NetworkX (Graph construction)
  • Pydantic (Data validation)

Frontend

  • Next.js 14 (App Router)
  • TypeScript
  • TailwindCSS
  • react-force-graph-2d
  • Framer Motion

AI

  • OpenAI GPT-4 / DeepSeek
  • Structured output parsing
  • Recursive impact analysis

๐Ÿ“– How It Works

Step 1: Event Analysis

# User inputs: "Fed raises rates"
direct_impacts = llm.analyze(event, count=3)
# Returns: [
#   {target: "Bond Prices", sentiment: "negative"},
#   {target: "USD Strength", sentiment: "positive"},
#   {target: "Tech Stocks", sentiment: "negative"}
# ]

Step 2: Recursive Expansion

for impact in direct_impacts:
    downstream = llm.analyze(f"Change in {impact.target}", count=2)
    graph.add_edge(event, impact.target)
    for sub_impact in downstream:
        graph.add_edge(impact.target, sub_impact.target)

Step 3: Visualization

  • Nodes colored by layer (Red = root, Blue = impacts)
  • Arrows show directionality
  • Particles animate along edges
  • Tooltips display explanations

๐ŸŽฏ Use Cases

  • Risk Assessment: Identify hidden risks in policy changes
  • Investment Strategy: Discover sector rotation opportunities
  • Economic Research: Visualize complex macro relationships
  • Education: Teach economics through interactive simulations
  • Scenario Planning: Explore "what-if" analyses

๐Ÿค Contributing

We welcome contributions! Here's how you can help:

  1. ๐Ÿ› Report Bugs: Open an issue with reproduction steps
  2. ๐Ÿ’ก Suggest Features: Share your ideas in Discussions
  3. ๐Ÿ”ง Submit PRs: Fork, create a branch, and submit a pull request
  4. ๐Ÿ“š Improve Docs: Help us make the documentation better

See CONTRIBUTING.md for detailed guidelines.


๐Ÿ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.


๐ŸŒŸ Star History

If you find this project useful, please consider giving it a โญ on GitHub!


๐Ÿ™ Acknowledgments

  • LangChain for LLM orchestration
  • react-force-graph for graph visualization
  • FastAPI for the amazing backend framework
  • Vercel for Next.js and deployment tools

๐Ÿ“ฌ Contact


Built with โค๏ธ by the Domino-Agent Team

โฌ† Back to Top

About

๐ŸŽฏ AI-Powered Financial Causal Inference Engine - Visualize the Butterfly Effect in Macroeconomics

Topics

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages