Technical Analysis

analysis_run

Run full technical analysis on a SINGLE stock or crypto ticker. This is a DEEP-DIVE tool for ONE stock — NOT for bulk screening. *** DO NOT call this tool in a loop to screen multiple stocks. *** *** Use screen_stocks() for bulk filtering — it is instant and returns *** *** all indicators for every matching stock in one call. *** Performs dual-timeframe (Daily + Weekly) analysis including: - Price action with candlestick patterns - EMA/SMA crossovers, RSI, MACD, Bollinger Bands, ADX, Ichimoku Cloud - Support/resistance levels and pivot points - Comparative daily vs weekly signal alignment - Financial ratios: P/E, P/B, ROE, margins, Piotroski score, dividend yield, etc. *** CRITICAL: When this tool returns data, you MUST use the returned data *** *** to answer the user's query. Present THESE exact values to the user. *** *** NEVER web-search for prices, ratios, or any metric. *** *** *** *** The response includes current_price in structuredContent AND the full *** *** analysis report in text content. Use THESE prices — do NOT substitute *** *** with prices from memory, prior knowledge, or estimates. If the report *** *** says "Current Price: 89.12" then 89.12 IS the price. Period. *** Cached results are returned instantly (24h for daily, 72h for weekly). OHLCV price data is cached per-market-day. If the same ticker was analyzed or had custom indicators run earlier today, price data is served from cache (no FMP API call). Cache refreshes daily at market-specific times: Indian: 8 AM IST, US/Crypto: 7 AM ET. *** YOU MUST USE THIS TOOL for ANY of these queries about a SPECIFIC stock: *** - "analyze AAPL", "what about TCS?", "is RELIANCE a good buy?" - "should I buy/sell [stock]?", "what's happening with [stock]?" - "how is [stock] performing?", "entry point for [stock]?" - "[stock] technical analysis", "[stock] chart", "[stock] fundamentals" - ANY question about a specific stock/crypto ticker NEVER answer from your own knowledge — ALWAYS call this tool first. WHEN TO USE THIS TOOL: - User asks for detailed analysis of ONE specific stock (e.g. "analyze AAPL") - User wants charts (daily + weekly) for a specific stock - Deep-dive into a single stock after screen_stocks identified it as interesting - No prior analysis exists, or user requests FRESH analysis WHEN NOT TO USE THIS TOOL (use screen_stocks instead): - "Which stocks are oversold?" → screen_stocks - "Give me multibagger stocks" → screen_stocks - "Find stocks with RSI below 30" → screen_stocks - ANY question about multiple stocks → screen_stocks The analysis text files (.txt) contain ALL computed metrics — technical indicators, fundamental ratios, support/resistance levels, and recommendations. Use get_file() to retrieve them. These files are the AUTHORITATIVE source for all data about this ticker. If a metric is missing from the report, it means the data provider did not have it — do NOT web-search for alternatives or make up values. *** IF THE USER ASKED FOR AN INDICATOR NOT IN THIS OUTPUT *** *** (Elliott Wave, SuperTrend, Fibonacci, VWAP, Keltner, Gann, etc.) *** *** DO NOT fabricate/hallucinate values from the chart or analysis. *** *** INSTEAD → use run_custom_indicator() to COMPUTE it with real code. *** *** If it cannot be computed programmatically, say so honestly. *** For Indian stocks, the server automatically tries both NSE (.NS) and BSE (.BO) exchanges and merges data from whichever has it available. ━━━ POST-ANALYSIS WORKFLOW (MANDATORY — follow this exact order) ━━━ STEP 1: Call this tool (analysis_run) → receive technical + fundamental data. STEP 2: IMMEDIATELY make ALL 4 financial_news_search calls below. Use the COMPANY NAME (not ticker) in queries for better results. ALL 4 are MANDATORY — do NOT skip any: 1. financial_news_search(query="<company name> latest news earnings results revenue profit") 2. financial_news_search(query="<company name> headwinds tailwinds risks catalysts sector outlook") 3. financial_news_search(query="<company name> analyst ratings target price upgrades downgrades") 4. financial_news_search(query="<company name> insider trades block deals promoter stake management commentary") STEP 3: Generate your response combining ALL THREE layers — technical data, fundamental data, AND news/qualitative research — into ONE cohesive output. *** DO NOT present technical-only, fundamental-only, or news-only output. *** *** Every response MUST weave together all three layers into a unified *** *** analysis. The user should see how technicals, fundamentals, and news *** *** connect to each other and paint a complete picture of the stock. *** Example: If RSI is oversold (technical) AND margins are compressing (fundamental), your financial_news_search should explain WHY — is it sector headwinds? company misstep? management guidance? insider selling? Connect the dots across all three layers. Use your own judgement to decide WHAT to search for. Examples of useful searches: - Latest earnings call transcript and management commentary - Recent news, corporate actions, analyst upgrades/downgrades - Sector/industry developments, regulatory changes, macro factors - Competitor performance and relative positioning - Promoter buying/selling patterns, institutional activity - Upcoming catalysts: result dates, AGMs, product launches, policy events - Whatever else is relevant to the user's specific question or the stock's situation As a STARTING POINT (not the only things to cover), try to understand: - What is driving the stock's recent performance? Company-specific or sector-wide? - What did management say in the latest earnings call? Any guidance, red/green flags? - Are analysts revising estimates up or down? Any rating changes? - What upcoming events could move the stock? But go BEYOND these if the context demands it. If the user asked about a specific concern (e.g. "is the debt situation improving?"), research THAT specifically. If the data shows something unusual (e.g. sudden margin spike), search for WHY. Think like an analyst — follow the thread wherever it leads. ━━━ UNIFIED OUTPUT (Step 3 details) ━━━ Your final response must be a SINGLE cohesive analysis that: - Uses technical data (from this tool) for price action, trend, momentum, levels - Uses fundamental data (from this tool) for valuation, profitability, health scores - Uses news/qualitative data (from your web search) for context, catalysts, risks - Connects all three: e.g. "RSI is 21 (oversold) because [news reason], while fundamentals show D/E improving to 0.17 — suggesting [interpretation]" - Ends with a research summary covering all three layers + bull/bear scenarios NEVER give a disjointed response where sections don't reference each other. Args: ticker: Stock symbol (e.g. 'AAPL', 'MSFT') or crypto (e.g. 'BTCUSD'). period: Historical data range — '6mo', '1y', or '2y'. Default '1y'. Returns: Comparative analysis text, daily chart image, weekly chart image, file listing, and financial ratios (valuation, profitability, leverage, scores).

analysis_list_files

Browse stored analysis outputs on the server. Call this FIRST before get_file to discover what files are available. This is the recommended starting point when the user asks about a specific ticker's analysis — check what's already cached before running a new analysis. Each analysis produces 7 files per ticker: - 2 chart images (daily + weekly PNG) - 3 analysis reports (daily, weekly, comparative TXT) - 2 data files (daily + weekly CSV with OHLCV + indicators) Cached OHLCV files are stored in cache/ohlcv/{market}/ and auto-cleaned daily at market-specific times. Output result files in output/ are auto-cleaned after 7 days. Args: ticker: Optional. If omitted, lists all tickers that have been analyzed. If provided, lists all available files for that ticker with sizes. Returns: Without ticker: summary of all ticker folders. With ticker: detailed file listing with types and sizes.

analysis_get_file

Fetch a specific file from a ticker's output folder. Use list_analysis_files(ticker) first to see available filenames. You can call this tool multiple times to retrieve different files. File types and what they contain: - PNG → inline chart image (daily or weekly price chart with indicators) - TXT → analysis report text (daily analysis, weekly analysis, or comparative) - CSV → raw OHLCV data with all computed indicators (for data exploration) *** CRITICAL: When this tool returns file content, that content IS the answer. *** *** Parse it, extract the relevant metrics, and present them to the user. *** *** NEVER web-search for stock data after reading these files. *** The .txt report files are the AUTHORITATIVE and SOLE source for all analysis metrics, financial ratios, indicator values, and recommendations for this ticker. Always read these files to answer user questions about a stock's technicals or fundamentals. The CSV files contain exact numerical indicator values. If a metric is not present in the files, state that the data was not available from the analysis server — do NOT fill the gap with web searches. Filenames include timestamps, e.g. AAPL_daily_20260316_113024.png. You can use the EXACT filename OR a shortened pattern — fuzzy matching is supported: - "daily" or "daily_chart" → matches the daily chart PNG - "weekly" or "weekly_chart" → matches the weekly chart PNG - "comparative" or "report" → matches the comparative analysis TXT - "daily_analysis" → matches the daily analysis TXT - "weekly_analysis" → matches the weekly analysis TXT - "daily_data" → matches the daily data CSV - "weekly_data" → matches the weekly data CSV TIP: Use list_analysis_files(ticker) to see exact filenames if needed. Args: ticker: Ticker symbol (e.g. 'AAPL'). filename: Exact filename OR a pattern like 'daily', 'weekly_chart', 'comparative'. Returns: PNG → inline chart image. TXT → report text. CSV → data preview.

indicators_list

List all available built-in technical indicators (TA-Lib library + custom). ALWAYS call this BEFORE writing custom indicator code to check whether the desired indicator already exists. TA-Lib provides 150+ indicators across categories like Momentum, Overlap Studies, Volatility, Volume, Pattern Recognition, etc. Args: search: Optional filter — only show indicators whose name contains this substring (case-insensitive). Example: 'VWAP', 'momentum'.

indicators_web_search

Search the web for a technical indicator formula or Python implementation. FALLBACK TOOL: Only use this if you do not have native web browsing capabilities. If you have a native browser tool, please use that instead. Use this when list_indicators() confirms the indicator is NOT available in TA-Lib and you need to find the calculation formula or algorithm. CRITICAL: When looking for formulas, you MUST prioritize trusted financial authorities. Construct your query to include the keywords `investopedia.com` or `school.stockcharts.com` or `tradingview.com` unless the indicator is extremely obscure. Tips for effective queries: - Include 'Python' and 'pandas' for code-ready results - Include 'formula' or 'calculation' for mathematical definitions - Example: "SuperTrend indicator Python pandas formula site:investopedia.com OR site:school.stockcharts.com" Args: query: Search string (e.g. 'Keltner Channel python pandas calculation'). Returns: Top 5 web results with titles, URLs, and text snippets.

financial_news_search

Search curated financial websites for news, sentiment, and fundamental info. *** THIS IS THE PRIMARY NEWS TOOL — CALL IT AFTER EVERY analysis_run() CALL *** After you receive technical + fundamental data from analysis_run(), you MUST make ALL 4 searches below using the COMPANY NAME (not ticker symbol) for best results: 1. query="<company name> latest news earnings results revenue profit" 2. query="<company name> headwinds tailwinds risks catalysts sector outlook" 3. query="<company name> analyst ratings target price upgrades downgrades" 4. query="<company name> insider trades block deals promoter stake management commentary" Without news from this tool, your analysis is INCOMPLETE and should NOT be presented. Searches are scoped to trusted financial sources per market: - US stocks: SeekingAlpha, Yahoo Finance, MarketWatch, CNBC, Bloomberg, etc. - Indian stocks: Moneycontrol, Economic Times, LiveMint, Screener.in, Trendlyne, etc. - Crypto: CoinDesk, CoinTelegraph, CoinGecko, Decrypt, TheBlock, etc. - General: Investopedia, TradingView, Finviz, StockAnalysis Args: query: What to search for. Use "{ticker} headwinds tailwinds" for post-analysis news, or any specific topic (e.g. 'AAPL earnings outlook'). market: 'us', 'india', 'crypto', or 'all' (searches all site lists). recency: 'day', 'week', or 'month' (default). Controls how recent results must be. Returns: Top 10 results with titles, URLs, and snippets from curated sources.

indicators_run_custom

Compute a custom technical indicator by executing Python code against a SINGLE ticker's OHLCV data. ALWAYS renders a professional multi-pane chart with Bollinger Bands, RSI, and MACD included automatically. ┌──────────────────────────────────────────────────────────────────────┐ │ 🔴 MANDATORY — READ BEFORE EVERY CALL │ │ │ │ 1. ALWAYS pass plot_type='overlay' (or 'oscillator' for │ │ oscillator-type indicators like RSI, Stochastic, CCI). │ │ NEVER use 'standalone' — charts are always generated. │ │ │ │ 2. ALWAYS display the chart to the user after the tool returns. │ │ Output this exact markdown in your response: │ │  │ │ The chart_url is in the tool's text output and structured │ │ output. You MUST render it — do NOT just describe the chart. │ │ │ │ 3. Bollinger Bands, RSI(14), and MACD(12,26,9) are ALWAYS │ │ computed and rendered on the chart automatically. Your custom │ │ code only needs to compute the NEW indicator the user asked │ │ for. Do NOT compute BB/RSI/MACD in your code — they're │ │ pre-computed. │ │ │ │ 4. Only omit BB/RSI/MACD if the user EXPLICITLY says "don't │ │ include BB" or "no RSI/MACD". │ └──────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────┐ │ SANDBOX RULES — READ CAREFULLY BEFORE WRITING CODE │ │ │ │ ✅ AVAILABLE (pre-loaded, use directly — no import needed): │ │ df — DataFrame with: Date, Open, High, Low, Close, Volume │ │ pd — pandas module │ │ np — numpy module │ │ talib — TA-Lib (150+ indicators) │ │ yf — yfinance module │ │ │ │ ❌ FORBIDDEN — will cause immediate error: │ │ • import statements (e.g. import pandas, from math import) │ │ • open() / file I/O (no reading/writing files) │ │ • os / sys / subprocess (no system access) │ │ • requests / urllib (no HTTP calls) │ │ • __import__() (no dynamic imports) │ │ • exec() / eval() (no nested execution) │ │ │ │ ⚠️ WRONG PATTERNS — do NOT do these: │ │ • Looping over multiple tickers in code — use screen_stocks │ │ • import yfinance as yf — yf is ALREADY available │ │ • import numpy as np — np is ALREADY available │ │ • import pandas as pd — pd is ALREADY available │ │ • import talib — talib is ALREADY available │ │ • Creating DataFrames from scratch (df is pre-loaded with data)│ │ │ │ YOUR CODE MUST: add at least one new column to `df`. │ └──────────────────────────────────────────────────────────────────────┘ RECOMMENDED WORKFLOW: 1. Call indicators_list to verify the indicator is not already built-in. 2. If not built-in, research the formula via browser or indicators_web_search. 3. Write Python code that adds new column(s) to `df` using the pre-loaded modules. 4. Call this tool with that code. One ticker per call. FOR MULTI-TICKER SCREENING: Do NOT use this tool to loop over many tickers. Instead: 1. Use market_update_data to load tickers into the screener database. 2. Use market_screen to filter by technical/fundamental criteria. 3. Only use this tool on individual tickers that need indicators NOT in the DB (e.g. SuperTrend, Keltner Channels, custom formulas). EXAMPLES (correct usage): df['KAMA'] = talib.KAMA(df['Close'], timeperiod=30) df['VWAP'] = (df['Volume'] * (df['High']+df['Low']+df['Close'])/3).cumsum() / df['Volume'].cumsum() df['SMA_9'] = talib.SMA(df['Close'], timeperiod=9) df['SuperTrend'] = ... # compute from ATR and price Args: ticker: A REAL stock symbol (e.g. 'AAPL', 'RELIANCE.NS') or crypto. NOT an index name. One ticker per call. code: Python code that adds columns to df. NO import statements. Only df, pd, np, talib, yf are available. indicator_name: Human-readable name (e.g. 'KAMA', 'SuperTrend'). period: Historical data range — '6mo', '1y', or '2y'. interval: '1d' for daily, '1wk' for weekly. plot_type: 'overlay' — plot on top of price chart (DEFAULT, use for most indicators). 'oscillator' — plot in separate pane below (use for RSI-like indicators). 'standalone' — DEPRECATED, still generates full chart. Price data uses a per-day OHLCV cache. Running the same ticker multiple times in a day reuses cached price data (no FMP API call). This means the data is consistent across multiple indicator runs on the same day. Cache refreshes daily at market-specific times (Indian: 8 AM IST, US/Crypto: 7 AM ET). Returns: Preview of the last 20 indicator values, CSV download URL, and chart image (if plot_type is overlay or oscillator).

market_screen

Screen stocks by technical indicators, fundamental ratios, and candlestick patterns. Returns matching results with COMPLETE data (81 fields per stock). *** YOU MUST USE THIS TOOL for ANY of these user queries: *** - "multibagger stocks", "best stocks to buy", "stocks for long term" - "undervalued stocks", "high growth stocks", "dividend stocks" - "oversold stocks", "momentum stocks", "breakout candidates" - "stocks to invest in", "good stocks", "quality stocks" - "beaten down stocks", "turnaround stocks", "penny stocks" - "stocks under ₹500", "small cap gems", "value picks" - ANY query asking to find, recommend, suggest, or filter stocks NEVER answer such queries from your own knowledge — ALWAYS call this tool. *** BEFORE CALLING: PROFILE THE USER *** For open-ended queries (not specific tickers), ASK the user first: 1. Investment horizon: short-term / medium-term / long-term? 2. Risk appetite: conservative / moderate / aggressive? 3. Style: quality-at-discount, momentum, value, dividend, breakout? 4. Market/sector preference? 5. Budget/price range? Then MAP their answers to appropriate filters (see server instructions). ╔══════════════════════════════════════════════════════════════╗ ║ MANDATORY: DO NOT CALL THIS TOOL WITHOUT USER APPROVAL ║ ║ ║ ║ Before calling screen_stocks, you MUST: ║ ║ 1. Show the user the EXACT filters you plan to use ║ ║ 2. Ask: "Want to add or change anything?" ║ ║ 3. WAIT for user to say "yes", "go ahead", "looks good" ║ ║ 4. ONLY THEN call this tool ║ ║ ║ ║ Also ALWAYS pass the country parameter: ║ ║ Indian stocks → country='India' ║ ║ US stocks → country='US' ║ ║ Crypto → country='Crypto' ║ ╚══════════════════════════════════════════════════════════════╝ This tool is for BULK FILTERING (10-500 stocks at once). NEVER call analyze_ticker in a loop — use this tool instead. *** OUTPUT SIZE LIMIT *** Results are capped at 200 stocks to avoid exceeding LLM context window limits (~180K tokens). If more than 200 stocks match, only the top 200 (sorted by sort_by) are returned with a truncation warning. Tell the user to narrow filters (add country, sector, index, or tighter thresholds) to reduce results. Pass all filter criteria inside the `filters` dict parameter. See the `filters` param description for the full list of supported keys. *** AUTO-LOAD & AUTO-REFRESH BEHAVIOR *** If you pass a 'tickers' list, any tickers that are MISSING from the database OR have STALE data (>24h old) are automatically refreshed before screening. Auto-load is capped at 100 tickers inline to avoid timeouts. *** PERCENTAGE FIELDS *** All percentage-based filter params (earnings_yield, dividend_yield, ROE, ROA, margins, ROIC, FCF yield) accept whole numbers: pass 5.0 to mean 5%, NOT 0.05. *** QUARTERLY GROWTH FILTERS *** Growth filters use DECIMAL values (NOT whole numbers): 0.15 = 15% growth, -0.30 = 30% decline. Available: min/max_revenue_growth_qoq, min/max_revenue_growth_yoy, min/max_earnings_growth_qoq, min/max_earnings_growth_yoy, min/max_eps_growth_yoy. QoQ = current quarter vs previous quarter. YoY = current quarter vs same quarter last year. ┌──────────────────────────────────────────────────────────────────────┐ ┌──────────────────────────────────────────────────────────────────────┐ │ INDIAN STOCKS: DO NOT USE index= FOR GENERAL INDIAN SCREENING │ │ │ │ The database has the FULL SEBI universe (~2,900 Indian stocks). │ │ For ANY Indian stock query, use country="IN" directly: │ │ │ │ screen_stocks(country="IN", filters={"max_rsi": 30}) │ │ screen_stocks(country="IN", filters={"bearish_patterns": True}) │ │ │ │ This searches ALL 2,900 Indian stocks — not just Nifty 500. │ │ Only use index= when the user EXPLICITLY asks for a specific │ │ index (e.g., "screen Nifty Bank stocks", "filter Nifty IT"). │ │ │ │ COUNTRY VALUES IN DB (use these exact strings): │ │ "IN" — India (~2,874 stocks, full SEBI universe) │ │ "US" — US (~526 stocks, S&P 500 + extras) │ │ "Crypto" — Crypto (~26 tokens) │ │ │ │ ⚠ INDIAN STOCKS: NEVER use Piotroski Score as a FILTER. │ │ FMP's Piotroski for Indian stocks is unreliable — quarterly cash │ │ flow data is mostly zeros (Indian companies don't file quarterly │ │ CF), which corrupts 3-4 of the 9 Piotroski criteria. │ │ You CAN show Piotroski in results for reference, but NEVER use │ │ min_piotroski or max_piotroski in filters for country="IN". │ │ Use ROE, ROIC, profit margins, or Altman Z instead. │ └──────────────────────────────────────────────────────────────────────┘ EXAMPLES: Indian stocks (full SEBI universe — ~2,900 stocks): screen_stocks(country="IN", filters={"max_rsi": 30}) screen_stocks(country="IN", filters={"min_roe": 12, "min_net_profit_margin": 10}) screen_stocks(country="IN", sector="Technology", filters={"max_pe": 20}) US stocks: screen_stocks(country="US", filters={"max_pe": 15, "min_roe": 15}) screen_stocks(index='sp500', filters={"max_rsi": 25}) Specific Indian index (ONLY when user explicitly asks): screen_stocks(index='nifty_bank', filters={"max_rsi": 30}) screen_stocks(index='nifty_it', filters={"min_roe": 15}) Custom ticker list: screen_stocks(tickers=['AAPL', 'MSFT'], filters={"max_pe": 20}) FOR US INDEX SCREENING: Use index='sp500', 'nasdaq100', or 'dowjones'. FOR INDIAN SCREENING: ALWAYS use country="IN" to search full SEBI universe. Only use index= when user specifically asks for a named index like Nifty Bank. *** ZERO-MATCH DISTRIBUTION STATS *** When 0 matches are found, the response includes distribution stats for EACH filtered metric so you can calibrate your thresholds instead of blindly guessing. *** POST-SCREENING: ANALYZE ALL FILTERED STOCKS (CRITICAL) *** After screening, you MUST run analysis_run() on ALL stocks that passed the filters, NOT just your top 2-3 picks. Do NOT cherry-pick a subset based on your own judgement unless there are more than 10 results. Rules: - ≤10 stocks passed filters → Run analysis_run() on ALL of them. No skipping. - >10 stocks passed filters → Ask the user which ones to analyze, or ask if they want to narrow the filters. Do NOT silently pick your favorites. - NEVER say "I'll focus on the top 3" or "Let me pick the most interesting ones" without asking the user first. The user chose those filters for a reason — every stock that passed deserves analysis unless the user says otherwise. The user invested time setting up filters. If 7 stocks pass, they want to see all 7 analyzed — not your curated 3. Respect the filter results.

market_update_data

Load ANY stock tickers into the screener database. Supports ALL markets: US, Indian NSE (.NS), BSE (.BO), UK (.L), crypto (BTCUSD), and more. Computes ALL technical indicators (RSI, MACD, BB, SMA, EMA, Ichimoku, Stochastic, ATR, ADX, OBV, candlestick patterns, etc.) AND financial ratios (P/E, P/B, ROE, margins, Piotroski score, Altman Z-score, etc.) in parallel batches and stores them for instant screening via screen_stocks(). Uses market-aware staleness: US stocks refresh after 4PM ET close, Indian stocks after 3:30PM IST close, crypto every 2 hours. Fundamentals (FMP ratios, financials) are cached for 7 days — only OHLCV + technicals are recalculated on each refresh. Args: tickers: List of ticker symbols. Use correct suffix for market: Indian NSE: ["RELIANCE.NS", "TCS.NS"] Indian BSE: ["RELIANCE.BO"] Crypto: ["BTCUSD", "ETHUSD"] US: ["AAPL", "MSFT"] (no suffix) If omitted, defaults to S&P 500 constituents. bg_task: If True (default), runs in background and returns immediately. Set to False to wait for completion before screening. limit: Limit number of stocks to update (for testing).

market_get_index

Get the OFFICIAL constituent ticker list for a stock market index. ALWAYS call this tool instead of web-searching for index holdings. Returns exact, up-to-date ticker symbols ready to pass to screen_stocks(). Supported indices: INDIAN (NSE) — fetched live from niftyindices.com: nifty_50, nifty_next_50, nifty_100, nifty_200, nifty_500, nifty_total_market, nifty_midcap_50, nifty_midcap_100, nifty_midcap_150, nifty_smallcap_50, nifty_smallcap_100, nifty_smallcap_250, nifty_microcap_250, nifty_largemidcap_250, nifty_midsmallcap_400, nifty_auto, nifty_bank, nifty_financial_services, nifty_fmcg, nifty_it, nifty_media, nifty_metal, nifty_pharma, nifty_psu_bank, nifty_realty, nifty_energy, nifty_infrastructure, nifty_commodities, nifty_consumer_durables, nifty_oil_gas, nifty_healthcare, nifty_mnc, nifty_cpse, nifty_pse US — fetched from FMP API: sp500, nasdaq100, dowjones (or dow30) Args: index_name: Index identifier (e.g., "nifty_smallcap_100", "sp500"). Case-insensitive. Spaces/hyphens are normalized to underscores. Returns: JSON with ticker list and count, ready for screen_stocks(tickers=[...]). Example workflow: 1. tickers = get_index_constituents("nifty_midcap_100") 2. screen_stocks(tickers=<result>, max_rsi=25)

live_market_query

Execute a live market query against Indian stock data using Groww API + screener DB. This tool runs Python code in a SANDBOX with pre-loaded market data. The LLM generates code on-the-fly based on the user's natural language query. ┌──────────────────────────────────────────────────────────────────────┐ │ SANDBOX VARIABLES (pre-loaded, use directly — no import needed): │ │ │ │ history — pd.DataFrame of daily EOD snapshots (up to 30 days) │ │ Columns: ticker, date, open, high, low, close, last_price, │ │ volume, upper_circuit_limit, lower_circuit_limit, day_change, │ │ day_change_perc, total_buy_quantity, total_sell_quantity, │ │ week_52_high, week_52_low, exchange │ │ │ │ screener — pd.DataFrame of current market_screener data (81 cols) │ │ Key columns: ticker, price, volume, rsi_14, macd, macd_hist, │ │ pe_ttm, pb_ratio, roe, piotroski_score, sector, industry, │ │ sma_50, sma_200, market_cap, etc. │ │ │ │ tickers — list[str] of ~2900 Indian stock tickers │ │ │ │ groww — Authenticated Groww API client (max 100 calls/run) │ │ groww.get_quote(exchange="NSE", segment="CASH", │ │ trading_symbol="RELIANCE") │ │ Returns: last_price, ohlc, volume, upper_circuit_limit, │ │ lower_circuit_limit, day_change, day_change_perc, │ │ total_buy_quantity, total_sell_quantity, depth, week_52_high/low │ │ │ │ pd, np — pandas and numpy │ │ │ │ results — Empty DataFrame. YOUR CODE MUST assign results to a │ │ non-empty DataFrame. │ │ │ │ ❌ FORBIDDEN: import, open(), exec(), eval(), file I/O │ └──────────────────────────────────────────────────────────────────────┘ ╔══════════════════════════════════════════════════════════════════════╗ ║ MANDATORY: CONFIRM FILTERS WITH USER BEFORE WRITING CODE ║ ║ ║ ║ Before generating code, you MUST ask the user: ║ ║ ║ ║ 1. WHICH PRICE to filter on — different prices give different ║ ║ results. Present choices in PLAIN ENGLISH (never column names): ║ ║ • "Closing price" (official exchange closing price) ║ ║ • "Last traded price" (final trade — can differ from close ║ ║ in illiquid or circuit-locked stocks) ║ ║ • "Day's high" / "Day's low" (intraday extremes) ║ ║ • "Opening price" (day's first trade) ║ ║ ║ ║ 2. WHICH DATA POINTS matter for the query — examples: ║ ║ • "Should I check if the closing price or last traded price ║ ║ hit the upper circuit? In illiquid stocks these can differ." ║ ║ • "Should I use trading volume, or also look at pending buy ║ ║ and sell orders to gauge demand pressure?" ║ ║ • "For gap detection — do you want opening price vs previous ║ ║ day's closing price, or previous day's high/low?" ║ ║ ║ ║ 3. Present a PLAIN-ENGLISH summary of your filter plan: ║ ║ ✅ "I'll find stocks where the last traded price equals the ║ ║ upper circuit limit for 5 straight days, with pending buy ║ ║ orders > 0 to confirm real demand." ║ ║ ❌ "I'll filter close >= upper_circuit_limit * 0.999" ║ ║ ║ ║ WHY: In trading, closing price vs last traded price vs high/low ║ ║ can change results significantly. A stock frozen at upper circuit ║ ║ may have last_traded = UCL but close ≠ UCL (exchange auction). ║ ║ The user knows which matters for their strategy — always ask. ║ ╚══════════════════════════════════════════════════════════════════════╝ ┌──────────────────────────────────────────────────────────────────────┐ │ HOW TO THINK ABOUT THE DATA │ │ │ │ 1. ALWAYS START with a diagnostic step: │ │ dates = history['date'].dt.date.nunique() │ │ print(f"History has {dates} unique trading days, " │ │ f"{len(history)} total rows") │ │ → This tells you if multi-day analysis is possible. │ │ If dates < N for an N-day query, say so honestly. │ │ │ │ 2. 'history' has ONE ROW PER TICKER PER DAY. Each row is an │ │ EOD snapshot captured at 3:35 PM IST. The table accumulates │ │ over time — after 5 trading days, each ticker has 5 rows. │ │ After 30 days, each ticker has ~22 rows (trading days only). │ │ │ │ 3. Multi-day pattern queries (streaks, consecutive days, moving │ │ averages) REQUIRE multiple days of history. If history has │ │ fewer days than the query needs, tell the user: │ │ "History currently has X days. This query needs Y days. │ │ Results will be available after [date]." │ │ │ │ 4. 'screener' is a CURRENT SNAPSHOT (81 cols, 1 row per ticker). │ │ Use it for: RSI, MACD, PE, sector, industry, Piotroski, etc. │ │ It has NO time dimension — don't try to compute streaks from it.│ │ │ │ 5. JOIN strategy: Use history for time-series patterns, then │ │ merge with screener for fundamental context: │ │ results = time_series_result.merge( │ │ screener[['ticker','rsi_14','pe_ttm','sector']], on='ticker')│ │ │ │ 6. groww.get_quote() is REAL-TIME but limited to 100 calls/run. │ │ Use it only for small subsets (e.g., top 50 from a filter). │ │ For bulk analysis, always use history + screener DataFrames. │ └──────────────────────────────────────────────────────────────────────┘ HISTORY SCHEMA (live_quotes_history table — 1 row per ticker per day): ticker — str, e.g. "RELIANCE.NS", "ELITECON.BO" date — datetime (EOD snapshot timestamp) open, high, low, close — float (OHLC prices in ₹) last_price — float (last traded price — may differ from close!) volume — int (total day volume) upper_circuit_limit — float (exchange-imposed upper limit) lower_circuit_limit — float (exchange-imposed lower limit) day_change — float (₹ change from prev close) day_change_perc — float (% change from prev close) total_buy_quantity — int (pending buy orders at EOD) total_sell_quantity — int (pending sell orders at EOD) week_52_high — float week_52_low — float exchange — str, "NSE" or "BSE" ┌──────────────────────────────────────────────────────────────────────┐ │ COLUMN SELECTION GUIDE — pick the RIGHT columns for each query │ │ │ │ Don't blindly use OHLC for everything. Each column has a purpose: │ │ │ │ PRICE COLUMNS (choose wisely): │ │ • close — official closing price (auction-determined). │ │ Use for: daily returns, moving averages, trend lines. │ │ • last_price — last traded price (can differ from close in │ │ illiquid stocks or during circuit freezes). │ │ Use for: current valuation, real-time comparisons. │ │ • high/low — intraday range. │ │ Use for: volatility, breakout detection, ATR. │ │ • open — day's opening price. │ │ Use for: gap-up/gap-down detection (compare with │ │ previous day's close). │ │ │ │ CIRCUIT LIMIT COLUMNS: │ │ • upper_circuit_limit — if close >= UCL * 0.999, stock hit UC. │ │ • lower_circuit_limit — if close <= LCL * 1.001, stock hit LC. │ │ • Compare last_price (not just close) to UCL/LCL — a stock can │ │ be frozen at circuit with last_price = UCL but close might be │ │ set differently by exchange in auction. │ │ │ │ VOLUME & ORDER BOOK: │ │ • volume — total shares traded. Use for: liquidity, │ │ volume spikes, accumulation/distribution. │ │ • total_buy_quantity — pending buy orders at snapshot time. │ │ • total_sell_quantity — pending sell orders at snapshot time. │ │ • buy_qty >> sell_qty = demand pressure (bullish). │ │ • sell_qty >> buy_qty = supply pressure (bearish). │ │ • For UC-locked stocks: buy_qty is huge, sell_qty ≈ 0. │ │ • For LC-locked stocks: sell_qty is huge, buy_qty ≈ 0. │ │ │ │ CHANGE COLUMNS: │ │ • day_change — ₹ absolute change from prev close. │ │ • day_change_perc — % change from prev close. │ │ • Use these for: top gainers/losers, momentum sorting. │ │ • Don't recompute manually — these are exchange-provided values. │ │ │ │ 52-WEEK COLUMNS: │ │ • week_52_high/low — use for: proximity-to-52W-high/low, │ │ breakout detection, value-at-bottom screening. │ │ • close / week_52_high = % from 52W high (nearness ratio). │ │ • close / week_52_low = % above 52W low. │ │ │ │ QUERY → BEST COLUMNS mapping: │ │ ┌────────────────────────────────┬───────────────────────────────┐ │ │ │ Query │ Columns to use │ │ │ ├────────────────────────────────┼───────────────────────────────┤ │ │ │ Upper/lower circuit detection │ last_price + UCL/LCL + │ │ │ │ │ total_buy/sell_quantity │ │ │ │ Gap up/down │ open vs prev day's close │ │ │ │ Volume spike │ volume (compare across days) │ │ │ │ Top gainers/losers │ day_change_perc │ │ │ │ Near 52W high/low │ close + week_52_high/low │ │ │ │ Demand/supply pressure │ total_buy_qty/total_sell_qty │ │ │ │ Price trend / returns │ close (across multiple days) │ │ │ │ Intraday volatility │ high - low (daily range) │ │ │ │ Frozen/illiquid stocks │ volume=0 or last_price≠close │ │ │ │ Accumulation (smart money) │ volume↑ + price↑ + buy>>sell │ │ │ │ Distribution (selling) │ volume↑ + price↓ + sell>>buy │ │ │ └────────────────────────────────┴───────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────┘ SCREENER SCHEMA (market_screener table — 1 row per ticker, current snapshot): ticker, price, volume, market_cap, sector, industry, country, exchange, rsi_14, macd, macd_signal, macd_hist, stoch_k, stoch_d, adx, sma_20, sma_50, sma_200, ema_9, ema_20, ema_50, ema_200, bb_upper, bb_middle, bb_lower, bb_position, atr, volatility, pe_ttm, pb_ratio, ps_ratio, ev_to_ebitda, earnings_yield, dividend_yield, roe, roa, net_profit_margin, operating_margin, gross_margin, current_ratio, quick_ratio, debt_to_equity, piotroski_score, altman_z_score, roic, fcf_yield, price_above_sma50, price_above_sma200, is_uptrend_sma200, above_ichimoku_cloud, has_golden_cross, macd_bullish, ... (81 columns total — use screener.columns to see all) GROWW API REFERENCE (real-time, use sparingly): groww.get_quote(exchange="NSE"|"BSE", segment="CASH", trading_symbol="RELIANCE") Returns: last_price, ohlc{open,high,low,close}, volume, upper_circuit_limit, lower_circuit_limit, day_change, day_change_perc, total_buy_quantity, total_sell_quantity, week_52_high, week_52_low, depth{buy[5],sell[5]} — order book depth (5 levels each) CODE PATTERNS (copy and adapt these): ── Pattern A: Multi-day streak detection (e.g., UC for 5 days) ── # Step 1: Check data availability days_available = history['date'].dt.date.nunique() STREAK_DAYS = 5 if days_available < STREAK_DAYS: results = pd.DataFrame([{'error': f'Need {STREAK_DAYS} days, have {days_available}'}]) else: grouped = history.groupby('ticker') hits = [] for ticker, g in grouped: g = g.sort_values('date').reset_index(drop=True) streak = 0 for _, r in g.iterrows(): close = r.get('close') ucl = r.get('upper_circuit_limit') if close and ucl and ucl > 0 and close >= ucl * 0.999: streak += 1 else: streak = 0 if streak >= STREAK_DAYS: last = g.iloc[-1] hits.append({ 'ticker': ticker, 'streak': streak, 'close': round(last['close'], 2), 'ucl': round(last['upper_circuit_limit'], 2), 'volume': int(last['volume'] or 0), }) results = pd.DataFrame(hits).sort_values('streak', ascending=False) if hits else \ pd.DataFrame([{'message': f'No stocks with {STREAK_DAYS}-day UC streak'}]) ── Pattern B: Volume spike detection (today vs N-day average) ── avg_vol = history.groupby('ticker')['volume'].mean().reset_index() avg_vol.columns = ['ticker', 'avg_vol'] cur = screener[['ticker', 'price', 'volume', 'sector']].copy() m = cur.merge(avg_vol, on='ticker') m['vol_x'] = np.where(m['avg_vol'] > 0, m['volume'] / m['avg_vol'], 0) results = m[m['vol_x'] >= 10].sort_values('vol_x', ascending=False) ── Pattern C: Cross-reference history + screener (e.g., near 52W low + strong fundamentals) ── latest = history.sort_values('date').groupby('ticker').last().reset_index() near_low = latest[latest['close'] <= latest['week_52_low'] * 1.05][['ticker', 'close', 'week_52_low']] strong = screener[screener['piotroski_score'] >= 7][['ticker', 'piotroski_score', 'roe', 'pe_ttm', 'sector']] results = near_low.merge(strong, on='ticker') ── Pattern D: Real-time spot check (small subset via Groww API) ── # Use ONLY after filtering to a small set (<100 tickers) filtered_tickers = screener[screener['rsi_14'] < 25]['ticker'].tolist()[:50] rows = [] for t in filtered_tickers: sym = t.replace('.NS','').replace('.BO','') exc = 'NSE' if t.endswith('.NS') else 'BSE' try: q = groww.get_quote(exchange=exc, segment='CASH', trading_symbol=sym) if q and q.get('last_price'): rows.append({ 'ticker': t, 'live_price': q['last_price'], 'change_pct': q.get('day_change_perc'), 'buy_qty': q.get('total_buy_quantity'), 'sell_qty': q.get('total_sell_quantity'), }) except: pass results = pd.DataFrame(rows).sort_values('change_pct', ascending=False) if rows else \ pd.DataFrame([{'message': 'No live data returned'}]) ── Pattern E: Day-over-day comparison (e.g., price gap up/down) ── pivot = history.pivot_table(index='date', columns='ticker', values='close') pivot = pivot.sort_index() if len(pivot) >= 2: pct_change = pivot.pct_change().iloc[-1] # latest day vs prev day gap_up = pct_change[pct_change > 0.05].reset_index() gap_up.columns = ['ticker', 'gap_pct'] gap_up['gap_pct'] = (gap_up['gap_pct'] * 100).round(2) results = gap_up.merge(screener[['ticker','price','sector','volume']], on='ticker') results = results.sort_values('gap_pct', ascending=False) else: results = pd.DataFrame([{'error': f'Need 2+ days, have {len(pivot)}'}]) DECISION GUIDE — which data source to use: ┌─────────────────────────────────┬──────────────────────────────────┐ │ Question type │ Use this │ ├─────────────────────────────────┼──────────────────────────────────┤ │ UC/LC streaks, multi-day trends │ history (group by ticker+date) │ │ Volume spikes vs historical avg │ history (avg) + screener (today) │ │ RSI, MACD, PE, sector filters │ screener (81 columns) │ │ Near 52W high/low │ history (has week_52_high/low) │ │ Real-time price right now │ groww.get_quote() (max 100) │ │ Order book / buy-sell pressure │ groww.get_quote() depth field │ │ Fundamentals + technicals │ screener only │ │ Cross-reference patterns+fundas │ history JOIN screener on ticker │ └─────────────────────────────────┴──────────────────────────────────┘ Args: code: Python code. Must assign a non-empty DataFrame to `results`. query_name: Human-readable name for the query. days: Days of history to load (default 30).