Initial commit of FinSightX

.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+
+
+# Virtual environment
+venv/
+.env
+
+
+# VSCode
+.vscode/
+
+
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Model files
+*.pth
+*.pt
+*.bin
+*.gguf
+*.ckpt
+*.safetensors
+
+# Hugging Face transformers
+tokenizer_config.json
+config.json
+special_tokens_map.json
+pytorch_model.bin
+sentence_bert_config.json
+model.safetensors
+
+# ChromaDB local data
+chroma/
+chroma.db/
+chroma_data/
+*.sqlite
+
+# Streamlit cache
+.streamlit/
+.cache/
+__pycache__/
+
+# Misc
+*.csv
+*.parquet
+*.zip
+*.tar
+*.h5
+*.pdf
+
+# Ignore test or temp files
+*.bak
+*.tmp

README.md

@@ -0,0 +1,118 @@
+# 📊 FinSightX – AI-Powered Financial Analyst Suite
+
+**FinSightX** is an intelligent, agent-powered financial assistant built using Groq's ultra-fast LLaMA 3.1 models, AutoRAG, and open-source tools. It allows users to query equities, summarize news, run macroeconomic forecasts, test quant strategies, track regulatory changes, and receive client-style advisory responses — all in one lightweight app.
+
+> 💡 Built with Groq API, Hugging Face Transformers, ChromaDB, and Streamlit.
+
+---
+
+## 🚀 Features
+
+| Agent | Role |
+|-------|------|
+| **EquityAnalystAgent** | Answers stock-specific financial questions using live data and sentiment |
+| **NewsSummarizerAgent** | Summarizes market headlines via LLM and retrieval |
+| **MacroStrategistAgent** | Forecasts macroeconomic trends using NeuralProphet |
+| **QuantBacktesterAgent** | Runs quant strategies using historical price data |
+| **ReguRadarAgent** | Scans for key regulatory disclosures |
+| **ClientAdvisorAgent** | Provides personalized financial advice based on user tone and goals |
+
+---
+
+## 🛠️ Tech Stack
+
+- **LLM**: `llama-3.1-8b-instant` via Groq API (OpenAI-compatible)
+- **Embedding**: `all-MiniLM-L6-v2` (SentenceTransformers)
+- **Sentiment Analysis**: `ProsusAI/finbert`
+- **Vector DB**: ChromaDB (local)
+- **Forecasting**: NeuralProphet
+- **Backtesting**: `bt` package
+- **UI**: Streamlit
+
+---
+
+## ⚙️ Setup Instructions
+
+1. Clone the repo  
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+3. Create a .env file:
+    ```bash
+    GROQ_API_KEY=your_groq_key
+    GROQ_API_URL=https://api.groq.com/openai/v1/chat/completions
+    ```
+4. Run the app:
+    ```bash
+    streamlit run ui/streamlit_app.py
+    ```
+
+## 📉 Current Limitations
+
+- ChromaDB does not yet include 10-K/10-Q or earnings data
+- Macro indicators (CPI, interest rates) not integrated
+- No real-time alerts or portfolio memory
+- No backtest visualization (plotly optional)
+- LLaMA 3.1 license is research-only (not commercial)
+
+---
+
+## 📂 Future Improvements
+
+### 📄 Financial Documents to Integrate
+
+| Document                     | Use                                          |
+|------------------------------|-----------------------------------------------|
+| 10-K / 10-Q                  | Full financial analysis and risk sections     |
+| 8-K                          | Instant updates on events, deals, or risks    |
+| Earnings Transcripts         | Management commentary and guidance            |
+| Investor Presentations       | Visual and forward-looking insights           |
+| Proxy Statements (DEF 14A)   | Governance and voting info                    |
+
+### 📊 Financial Metrics to Add
+
+- Free cash flow  
+- ROE / ROIC  
+- Altman Z-Score  
+- Piotroski F-Score  
+- Debt/equity & profitability ratios  
+
+### 🌐 Macroeconomic Indicators
+
+| Indicator                | Source                            |
+|--------------------------|------------------------------------|
+| CPI, GDP, Unemployment   | FRED API / IMF / World Bank        |
+| Fed rates, Inflation     | TradingEconomics / OpenBB          |
+| Currency / Commodities   | Yahoo Finance / forex-python       |
+
+### 🔌 Tools & Libraries to Integrate
+
+- `sec-api.io` or `sec-edgar-downloader` (for 10-Ks)  
+- `openbb` (for macro + financial aggregation)  
+- `plotly` (for backtesting visualization)  
+- `redis` or `duckdb` (for memory/session tracking)  
+
+---
+
+## 🔮 Future Agent Extensions
+
+| Agent Name             | Description                                                            |
+|------------------------|------------------------------------------------------------------------|
+| `PortfolioBuilderAgent`| Recommends custom portfolio allocations based on user goals            |
+| `RiskMonitorAgent`     | Tracks volatility, drawdowns, exposure and market risk                 |
+| `AlertAgent`           | Notifies users of macro shifts, earnings releases, or regulatory events|
+
+---
+
+## 📘 License
+
+Currently for **research and educational purposes only**.  
+If using Groq-hosted LLaMA 3.1, ensure compliance with Meta’s licensing.
+
+---
+
+## 👨‍💻 Author
+
+Developed by **Rahul Thakur**  
+Want to collaborate or contribute? Fork, star, and connect!

agents/client_advisor.py

@@ -0,0 +1,11 @@
+from tools.sentiment_tool import analyze_sentiment
+from llm.groq_llm import call_groq_mistral
+
+def advise_client(user_input: str) -> str:
+    sentiment = analyze_sentiment(user_input)
+    prompt = (
+        f"A client asked a financial question: '{user_input}'\n"
+        f"Their emotional tone is: {sentiment}.\n"
+        f"As a financial advisor, provide a thoughtful and empathetic response."
+    )
+    return call_groq_mistral(prompt)

agents/equity_analyst.py

@@ -0,0 +1,14 @@
+from tools.sentiment_tool import analyze_sentiment
+from tools.autorag_tool import query_equity_kb
+from llm.groq_llm import call_groq_mistral
+
+def answer_equity_question(query: str) -> str:
+    context = query_equity_kb(query)
+    sentiment = analyze_sentiment(context)
+
+    prompt = (
+        f"Analyze this equity context:\n{context}\n\n"
+        f"Sentiment of the data: {sentiment}.\n"
+        f"Provide a concise financial analysis and any risks or opportunities."
+    )
+    return call_groq_mistral(prompt)

agents/macro_strategist.py

@@ -0,0 +1,7 @@
+from tools.forecast_tool import forecast
+import pandas as pd
+
+def analyze_macro_trends(df: pd.DataFrame) -> dict:
+    forecast_df = forecast(df)
+    latest = forecast_df.tail(1)
+    return latest.to_dict(orient="records")[0]

agents/news_summarizer.py

@@ -0,0 +1,7 @@
+from llm.summarizer import summarize
+from tools.autorag_tool import query_equity_kb
+
+def summarize_market_news(news_text: str) -> str:
+    # You can use summarizer directly or summarize context if preloaded into KB
+    context = query_equity_kb(news_text)
+    return summarize(context or news_text)

agents/quant_backtester.py

@@ -0,0 +1,23 @@
+import bt
+
+def run_simple_backtest(
+    strategy_name="SMA Cross", tickers=["AAPL"], sma_short=20, sma_long=50
+):
+    def strategy_logic():
+        prices = bt.get(tickers, start="2020-01-01")
+        sma_s = prices.rolling(sma_short).mean()
+        sma_l = prices.rolling(sma_long).mean()
+        # Note: Signal is not used in bt directly
+        return bt.Strategy(
+            strategy_name,
+            [
+                bt.algos.SelectAll(),
+                bt.algos.WeighEqually(),
+                bt.algos.Rebalance(),
+            ]
+        )
+
+    s = strategy_logic()
+    data = bt.get(tickers)
+    test = bt.Backtest(s, data)
+    return bt.run(test)

agents/regu_radar.py

@@ -0,0 +1,10 @@
+from tools.autorag_tool import query_equity_kb
+from llm.groq_llm import call_groq_mistral
+
+def monitor_regulatory_changes(text: str) -> str:
+    context = query_equity_kb(text)
+    prompt = (
+        f"The following text contains a regulatory update:\n{context}\n\n"
+        f"Summarize the key implications for investors and compliance."
+    )
+    return call_groq_mistral(prompt)

config/env.py

@@ -0,0 +1,11 @@
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+GROQ_API_KEY = os.getenv("GROQ_API_KEY")
+GROQ_API_URL = os.getenv("GROQ_API_URL", "https://api.groq.com/openai/v1/chat/completions")
+HF_TOKEN = os.getenv("HF_TOKEN")
+CHROMA_DB_PATH = os.getenv("CHROMA_DB_PATH", "./chroma")
+
+print("GROQ_API_KEY Loaded:", bool(GROQ_API_KEY))

config/model_config.py

@@ -0,0 +1,18 @@
+MODEL_CONFIG = {
+    "llm": {
+        "provider": "groq",
+        "model": "mistral-7b-instruct",
+    },
+    "embedding_model": {
+        "name": "all-MiniLM-L6-v2",
+        "provider": "sentence-transformers"
+    },
+    "summarizer": {
+        "use_groq": True,
+        "fallback_model": "TinyLlama"
+    },
+    "sentiment_model": {
+        "name": "ProsusAI/finbert",
+        "provider": "huggingface"
+    }
+}

embeddings/embedder.py

@@ -0,0 +1,6 @@
+from sentence_transformers import SentenceTransformer
+
+model = SentenceTransformer("all-MiniLM-L6-v2")
+
+def get_embedding(text: str):
+    return model.encode([text])[0]

embeddings/vector_store.py

@@ -0,0 +1,11 @@
+import chromadb
+
+client = chromadb.Client()
+collection = client.get_or_create_collection("finsightx_kb")
+
+def add_to_db(doc_id: str, text: str, embedding):
+    collection.add(ids=[doc_id], documents=[text], embeddings=[embedding])
+
+def query(text: str, embed_fn) -> dict:
+    query_embedding = embed_fn(text)
+    return collection.query(query_embeddings=[query_embedding], n_results=3)

llm/groq_llm.py

@@ -0,0 +1,16 @@
+from config.env import GROQ_API_KEY, GROQ_API_URL
+import httpx
+
+def call_groq_mistral(prompt: str) -> str:
+    headers = {"Authorization": f"Bearer {GROQ_API_KEY}"}
+    body = {
+        "model": "llama-3.1-8b-instant",
+        "messages": [{"role": "user", "content": prompt}],
+        "temperature": 0.7
+    }
+    try:
+        response = httpx.post(GROQ_API_URL, json=body, headers=headers, timeout=10)
+        response.raise_for_status()
+        return response.json()["choices"][0]["message"]["content"]
+    except Exception as e:
+        return f"❌ Error calling Groq: {str(e)}"

llm/summarizer.py

@@ -0,0 +1,11 @@
+from config.model_config import MODEL_CONFIG
+from llm.groq_llm import call_groq_mistral
+# from llm.tinyllama_runner import tinyllama_chat  # fallback if needed
+
+def summarize(text: str) -> str:
+    prompt = f"Summarize the following article:\n{text}"
+
+    if MODEL_CONFIG["summarizer"]["use_groq"]:
+        return call_groq_mistral(prompt)
+    else:
+        return "🪫 Fallback LLM not enabled"  # or: tinyllama_chat(prompt)

llm/tinyllama_runner.py

@@ -0,0 +1,14 @@
+from llama_cpp import Llama
+
+# Load quantized TinyLlama
+llm = Llama(model_path="models/tinyllama-1.1b-chat.gguf", n_ctx=2048)
+
+def tinyllama_chat(prompt: str) -> str:
+    try:
+        response = llm.create_chat_completion(
+            messages=[{"role": "user", "content": prompt}],
+            temperature=0.7
+        )
+        return response["choices"][0]["message"]["content"]
+    except Exception as e:
+        return f"⚠️ TinyLlama failed: {str(e)}"

requirements.txt

@@ -0,0 +1,10 @@
+streamlit
+pandas
+neuralprophet
+sentence-transformers
+chromadb
+httpx
+python-dotenv
+transformers
+torch
+llama-cpp-python

space.yaml

@@ -0,0 +1,9 @@
+sdk: streamlit
+app_file: ui/streamlit_app.py
+python_version: 3.10
+pinned: false
+license: apache-2.0
+title: FinSightX - Financial Agent Suite
+emoji: 📊
+colorFrom: blue
+colorTo: green

tools/autorag_tool.py

@@ -0,0 +1,6 @@
+from embeddings.embedder import get_embedding
+from embeddings.vector_store import query
+
+def query_equity_kb(text: str) -> str:
+    results = query(text, get_embedding)
+    return "\n".join(results["documents"][0]) if results and results["documents"] else "No relevant documents found."

tools/forecast_tool.py

@@ -0,0 +1,16 @@
+from neuralprophet import NeuralProphet
+import pandas as pd
+
+model = NeuralProphet()
+
+def forecast(
+    df: pd.DataFrame, 
+    time_col: str = "ds", 
+    value_col: str = "y", 
+    periods: int = 30
+) -> pd.DataFrame:
+    df = df.rename(columns={time_col: "ds", value_col: "y"})
+    model.fit(df, freq="D")
+    future = model.make_future_dataframe(df, periods=periods)
+    forecast_df = model.predict(future)
+    return forecast_df[["ds", "yhat1"]]

tools/sentiment_tool.py

@@ -0,0 +1,7 @@
+from transformers import pipeline
+
+sentiment_pipe = pipeline("sentiment-analysis", model="ProsusAI/finbert")
+
+def analyze_sentiment(text: str) -> str:
+    result = sentiment_pipe(text)
+    return result[0]["label"] if result else "NEUTRAL"

ui/streamlit_app.py

@@ -0,0 +1,192 @@
+import sys
+import os
+import streamlit as st
+import pandas as pd
+
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from agents.equity_analyst import answer_equity_question
+from agents.news_summarizer import summarize_market_news
+from agents.macro_strategist import analyze_macro_trends
+from agents.quant_backtester import run_simple_backtest
+from agents.regu_radar import monitor_regulatory_changes
+from agents.client_advisor import advise_client
+
+# --- UI Setup ---
+st.set_page_config(page_title="FinSightX", layout="wide")
+
+st.title("📊 FinSightX: AI-Powered Financial Agent Suite")
+
+# Sidebar
+agent = st.sidebar.selectbox(
+    "Choose Agent",
+    [
+        "🏠 Home",
+        "Equity Analyst",
+        "News Summarizer",
+        "Macro Strategist",
+        "Quant Backtester",
+        "ReguRadar",
+        "Client Advisor"
+    ]
+)
+
+# --- Agent Routing ---
+
+if agent == "🏠 Home":
+    st.header("A Multi-Agent Financial Intelligence Assistant")
+    st.markdown("""
+    A **modular industry-grade application** where agents collaborate to handle:
+
+    - **Equity Research**
+    - **News Summarization**
+    - **Macroeconomic Analysis**
+    - **Quantitative Backtesting**
+    - **Regulatory Updates**
+    - **Client Portfolio Q&A**
+    """)
+
+elif agent == "Equity Analyst":
+    st.subheader("🔍 Equity Analyst")
+    st.markdown("""
+    ### Role:
+    Analyzes individual stocks or companies using:
+    - Financial filings (e.g., 10-K, 10-Q)
+    - Earnings call summaries
+    - Market sentiment
+
+    ### Capabilities:
+    - Retrieve documents from a knowledge base using **AutoRAG**
+    - Run sentiment analysis (FinBERT)
+    - Generate insight using LLM (Groq Mistral)
+    - Summarize risks, opportunities, and outlook
+
+    ### Example Use Cases:
+    - "What’s the market sentiment around Tesla this quarter?"
+    - "Give me an analysis of Apple’s earnings call."
+    """)
+    query = st.text_input("Enter your financial query about a stock or company:")
+    if st.button("Analyze"):
+        with st.spinner("Analyzing equity..."):
+            response = answer_equity_question(query)
+        st.markdown(response)
+
+elif agent == "News Summarizer":
+    st.subheader("📰 News Summarizer")
+    st.markdown("""
+    ### Role:
+    Digest and summarize **real-time or bulk market news** to extract insights and relevance.
+
+    ### Capabilities:
+    - Accept raw headlines or long-form articles
+    - Retrieve context (e.g., related documents or sectors)
+    - Summarize using LLM (via Groq or fallback)
+
+    ### Use Cases:
+    - "Summarize today’s financial news relevant to energy stocks."
+    - "Give me a brief on Nvidia's latest product announcement."
+    """)
+    news = st.text_area("Paste financial news or headlines:")
+    if st.button("Summarize News"):
+        with st.spinner("Summarizing..."):
+            summary = summarize_market_news(news)
+        st.markdown(summary)
+
+elif agent == "Macro Strategist":
+    st.subheader("📉 Macro Trend Forecaster")
+    st.markdown("""
+    ### Role:
+    Analyzes **macroeconomic indicators** and helps in trend forecasting.
+
+    ### Capabilities:
+    - Forecasts economic time series (CPI, GDP, unemployment) using `neuralprophet`
+    - Returns structured future outlooks
+    - Used in multi-agent reasoning for “market climate”
+
+    ### Use Cases:
+    - "Forecast US inflation for the next 3 months."
+    - "What does the GDP trend look like post-2023?"
+    """)
+    st.markdown("Upload a time series CSV with columns `ds` (date) and `y` (value).")
+    uploaded_file = st.file_uploader("Upload CSV", type=["csv"])
+    if uploaded_file:
+        df = pd.read_csv(uploaded_file)
+        if st.button("Forecast"):
+            with st.spinner("Forecasting..."):
+                forecast_result = analyze_macro_trends(df)
+            st.write("📈 Forecasted Value:")
+            st.json(forecast_result)
+
+elif agent == "Quant Backtester":
+    st.subheader("💹 Quant Strategy Backtester")
+    st.markdown("""
+    ### Role:
+    Tests trading strategies on historical price data.
+
+    ### Capabilities:
+    - Define and run strategies using `bt` or `vectorbt`
+    - Simple moving average crossovers, rebalancing, etc.
+    - Return backtest performance metrics
+
+    ### Use Cases:
+    - "Backtest an SMA crossover on AAPL from 2020 to 2023."
+    - "Run a balanced ETF strategy on SPY, QQQ, and VTI."
+
+    > This agent focuses on backtesting, not execution or portfolio construction (those can be added later).
+    """)
+    tickers = st.text_input("Enter tickers (comma-separated)", value="AAPL,MSFT")
+    sma_short = st.number_input("Short SMA", value=20)
+    sma_long = st.number_input("Long SMA", value=50)
+    if st.button("Run Backtest"):
+        with st.spinner("Backtesting strategy..."):
+            result = run_simple_backtest(
+                tickers=[t.strip() for t in tickers.split(",")],
+                sma_short=sma_short,
+                sma_long=sma_long
+            )
+        st.write("✅ Backtest completed. Check your terminal/logs for output.")
+        st.markdown("Note: Visual performance plots not yet integrated in Streamlit.")
+
+elif agent == "ReguRadar":
+    st.subheader("📜 ReguRadar – Regulatory Monitor")
+    st.markdown("""
+    ### Role:
+    Monitors and interprets **regulatory updates** that may affect sectors, firms, or compliance requirements.
+
+    ### Capabilities:
+    - AutoRAG over legal and regulatory filings (e.g., RBI circulars, SEC rules)
+    - LLM summarization to extract impact
+    - Optional: track historical regulatory shifts
+
+    ### Use Cases:
+    - "Has the RBI changed anything that affects crypto investors?"
+    - "Summarize the SEC’s latest ESG compliance memo."
+    """)
+    reg_query = st.text_area("Paste a regulatory update or query:")
+    if st.button("Analyze Regulation"):
+        with st.spinner("Scanning for relevance..."):
+            reg_response = monitor_regulatory_changes(reg_query)
+        st.markdown(reg_response)
+
+elif agent == "Client Advisor":
+    st.subheader("🧑‍💼 Client Advisor")
+    st.markdown("""
+    ### Role:
+    Acts as a **virtual financial advisor**, helping individual users based on their queries and emotional tone.
+
+    ### Capabilities:
+    - Understand user intent + emotion using FinBERT
+    - Generate personalized advice using Groq LLM
+    - Can be expanded into user profile tracking (e.g., risk appetite, goals)
+
+    ### Use Cases:
+    - "Should I invest in tech during a recession? I’m scared of losing money."
+    - "I’ve retired and need a low-risk investment plan."
+
+    > In the future, this can evolve into a memory-based portfolio coach.
+    """)
+    user_msg = st.text_area("What does your client say?")
+    if st.button("Advise"):
+        with st.spinner("Analyzing sentiment and crafting advice..."):
+            advice = advise_client(user_msg)
+        st.markdown(advice)