ArthaNETRA

AI swarm-based financial sentiment simulation platform.

ArthaNETRA fetches market news, extracts financial entities, builds a knowledge graph, runs investor-agent simulations, scores sentiment, and generates a final scenario report. It is designed for research, demos, and experimentation around market narrative analysis.

Core Features

• Market news intake with GDELT primary and Google News RSS fallback
• Local fallback/demo mode when external providers are unavailable
• Financial entity and event extraction
• Knowledge graph generation and React Flow visualization
• Multi-agent financial sentiment swarm simulation
• Sentiment scoring with bull, bear, confidence, agreement, and risk metrics
• Final report dashboard with Recharts visualizations
• JSON and Markdown report download
• Safety layer for PII masking, financial-advice language rewriting, and disclaimers
• Supabase/PostgreSQL schema and storage abstraction with in-memory fallback

Tech Stack

Frontend

• Next.js App Router
• TypeScript
• Tailwind CSS
• shadcn-style reusable components
• React Flow
• Recharts

Backend

• FastAPI
• Python 3.11+
• Pydantic / pydantic-settings
• HTTPX

Planned infrastructure

• Supabase / PostgreSQL
• Qdrant
• Gemini, NVIDIA NIM, and Hugging Face provider fallbacks

Architecture Overview

apps/
  web/          Next.js frontend
  api/          FastAPI backend

packages/
  shared/       Shared package placeholder

docs/           Architecture, agents, prompts, routing, and deployment notes

High-level pipeline:

Input topic/company
  -> news fetch
  -> market analysis
  -> knowledge graph builder
  -> agent swarm simulation
  -> sentiment scoring
  -> final report generation

The frontend stores local workflow state in localStorage for demo and MVP flows. The backend can persist data through Supabase REST when configured, otherwise it uses in-memory mock storage.

Financial Agents

The simulation includes these personas:

1. Retail Investor Agent
2. Institutional Investor Agent
3. Short Seller Agent
4. Financial Analyst Agent
5. News Media Agent
6. Regulator Agent
7. Long-Term Investor Agent
8. Quant Momentum Agent
9. Competitor Watch Agent
10. Risk Manager Agent
11. Chief Market Synthesizer

Each agent produces sentiment, confidence, reasoning, main risk, main opportunity, evidence used, and questions for other agents.

Local Setup

Install dependencies from the repo root:

npm install

Create environment files from the examples:

copy .env.example .env
copy apps\web\.env.example apps\web\.env.local
copy apps\api\.env.example apps\api\.env

For PowerShell on Windows, the commands above work as written. On macOS/Linux, use cp and forward slashes.

Environment Variables

The MVP runs without AI, Supabase, or Qdrant keys. Leave provider secrets blank to use mock/demo mode.

Frontend:

NEXT_PUBLIC_API_URL=http://localhost:8000

Backend:

GEMINI_API_KEY=
GEMINI_REASONING_MODEL=gemini-2.5-flash
NVIDIA_API_KEY=
NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
NVIDIA_REASONING_MODEL=
NVIDIA_EMBEDDING_MODEL=
NVIDIA_PII_MODEL=
HUGGINGFACE_API_KEY=
HUGGINGFACE_REASONING_MODEL=Qwen/Qwen2.5-7B-Instruct
SUPABASE_URL=
SUPABASE_SERVICE_KEY=
DATABASE_URL=
QDRANT_URL=
QDRANT_API_KEY=
CORS_ORIGINS=http://localhost:3000

Required for MVP:

• NEXT_PUBLIC_API_URL
• CORS_ORIGINS

Optional:

• Gemini, NVIDIA, and Hugging Face keys for real model calls
• Supabase/PostgreSQL values for persistence
• Qdrant values for future vector search

Running Frontend

From the repo root:

npm run dev:web

Or from apps/web:

npm run dev

Open:

http://localhost:3000

Running Backend

From apps/api:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python -m uvicorn main:app --reload --port 8000

Open:

http://localhost:8000/health
http://localhost:8000/docs

Demo Mode

The app includes a stable demo simulation for:

NVIDIA AI chip demand

Demo mode includes curated mock:

• articles
• market summary
• graph nodes and edges
• swarm rounds
• agent outputs
• scores
• final report

Use it from the landing page:

Open landing page -> Demo Simulation

Demo mode works without NVIDIA, Hugging Face, Supabase, Qdrant, or live news access.

UI Theme

ArthaNETRA uses a professional token-based light/dark theme driven by CSS variables. The landing page uses a lightweight WebGL shader background for brand impact, while dashboard pages use static themed surfaces with subtle grid and radial glow layers for performance. Knowledge graph colors are domain-specific and intentionally preserved for node types, sentiment edges, and legend readability.

Main Local Flow

With both frontend and backend running:

1. Open http://localhost:3000
2. Go to New Simulation
3. Enter a topic or company
4. Click Fetch candidate news
5. Select articles
6. Open the knowledge graph
7. Run the swarm simulation
8. Review the final report

If external news providers are unavailable, the backend returns local fallback articles so the MVP flow still works.

API Routes

• GET /health
• POST /api/news/fetch
• POST /api/simulation/run
• GET /api/simulation/{simulation_id}

Database

Initial PostgreSQL/Supabase schema:

apps/api/migrations/001_initial_schema.sql

Tables:

• simulations
• articles
• market_summaries
• graph_nodes
• graph_edges
• agent_outputs
• simulation_rounds
• final_reports

When Supabase env vars are missing, the backend uses in-memory mock storage.

Deployment Plan

Recommended deployment path:

1. Deploy apps/api as a FastAPI service.
2. Deploy apps/web as a Next.js app.
3. Configure NEXT_PUBLIC_API_URL to point to the deployed API.
4. Apply apps/api/migrations/001_initial_schema.sql to Supabase/PostgreSQL.
5. Add provider secrets through the deployment platform secret manager.
6. Enable Qdrant once vector retrieval is implemented.
7. Add monitoring, request logging, and rate limits before production use.

Safety Disclaimer

ArthaNETRA generates AI-assisted scenario analysis. It is not financial advice and does not recommend buying, selling, or holding any security.

Reports must include:

This is AI-generated scenario analysis, not financial advice.

The backend safety layer masks common PII patterns, rewrites direct financial-advice commands into safer scenario language, and adds input quality warnings when evidence is weak, sparse, stale, or conflicting.

Future Scope

• Real Supabase persistence in the deployed environment
• Qdrant vector retrieval for article and entity context
• Expanded Gemini, NVIDIA NIM, and Hugging Face model routing
• Better entity resolution and duplicate merging
• Historical simulation comparison
• Portfolio/watchlist support
• Authentication and saved workspaces
• Export to PDF
• CI tests for frontend, backend, and API contracts
• Observability, rate limiting, and production hardening