Knowledge Base
Granular Q&A spanning 15+ documentation files. Technical details, operational flags, and institutional financial logic.
General & Vision
What problem does FIntrepidQ solve?
Equity analysts waste hours reading scattered data sources. FIntrepidQ automates the entire research loop — from raw API data to a professional investment thesis — in under 30 seconds, with guaranteed quantitative accuracy.
What is the "ReAct" pattern used in the agents?
Reasoning + Acting: It forces the AI to explain its logic ("Thought") before calling a tool. It then makes the call, observes the result, and repeats. This eliminates hallucination by grounding every claim in real API data.
How does "Hybrid Data Flow" work?
The system intercepts the raw JSON from tool message history and passes it directly to the Synthesis agent. This ensures that even if an agent's narrative summary misses a detail, the final report has 100% quantitative accuracy.
What technologies power the system?
LangGraph for agent orchestration, Google Gemini for AI, yfinance + Alpha Vantage for financial APIs, Rust (PyO3) for high-performance calculations, Rich for CLI, and tenacity for retry logic.
What is the compact report format?
Every report follows a strict 5-section structure: Verdict → Key Metrics Table → Green
Flags → Red Flags → Investment Thesis. All flags are tagged with one of the 7 hedge
fund categories (e.g., [FUNDAMENTAL], [MOMENTUM]).
Deep Architecture
What are the responsibilities of the 4 Agents?
1. Data Agent — Collects financials, news, and strategic triggers with retry
logic.
2. Validation Agent — Checks completeness (0-100%) and fixes gaps via Alpha
Vantage.
3. Analysis Agent — "Senior Analyst." Generates the investment thesis using
SKILL.md rules.
4. Synthesis Agent — "Lead Strategist." Polishes the report, attributes
sources, adds timeline metadata.
What is the role of Pydantic models?
The utils/models.py file defines a "Pydantic Shield." Models like
Technicals, RiskMetrics, FinancialTrends, and
ICRAnalysis enforce strict types and
ranges (e.g., RSI must be 0-100). If the Data Agent returns corrupted data, the system catches
it before the Analyst sees it.
How does the Validation Agent assign confidence?
It uses a two-axis system: ≥ 80% completeness + ≥ 90% critical metrics = High. ≥ 60% + ≥ 70% = Medium. Below that = Low. Critical metrics include price, market cap, revenue growth, margins, P/E, debt/equity, FCF, and ROE.
What is the difference between the Analysis Agent and Synthesis Agent?
The Analysis Agent is the "builder" — it generates the full structured report using SKILL.md rules on raw JSON. The Synthesis Agent is the "editor" — it integrates validation metadata, cross-references sources, polishes tone, and adds timeline context. Both receive identical raw data.
What is the Rust Acceleration library?
The rust_finance library is a Python extension written in Rust (PyO3).
technicals.rs handles RSI, SMA, MACD. risk.rs handles Volatility,
Sharpe, VaR, Max Drawdown. utils.rs handles Trend detection. Rust is orders of
magnitude faster than pure Python for numerical loops.
What is the JSON_SEND protocol?
It's a high-fidelity delivery protocol for the WhatsApp bot. It wraps multiline investment reports into a single JSON object for transmission, ensuring no truncation or formatting loss between Python and Node.js.
What is the load_skill tool?
It is the Analysis Agent's primary tool. It loads a specialized "skill framework" (like
equity_trigger_analysis/SKILL.md) containing preset rules, thresholds, and report
templates that guide the agent's analysis logic.
Operations & CLI
What are the key automation flags?
Use --auto-save to skip the confirmation prompt. Use --no-save-file to
only save reports to the database without cluttering your local reports/ folder.
Can I use company names instead of tickers?
Yes. Running python chat.py analyze "Tesla" uses smart resolution to map the name
to TSLA, prioritizing symbols in parentheses if found.
What is the Human-in-the-Loop save flow?
After analysis, the system pauses and asks: yes = save to file AND database,
no = save to file only, cancel = discard. Use
--auto-save to bypass the prompt entirely.
How does the /compare command
work?
/compare TSLA triggers automated competitor discovery, fetches institutional
metrics for all peers, computes industry averages, and pulls strategic news. Output includes a
12-column benchmark table, a signal dashboard, and a data-driven Sector Verdict.
How do I clean up old reports by date?
Use cleanup-by-date --before 2025-12-08 or --older-than 7 (days). Add
--ticker TSLA to filter, and always use --dry-run first to preview
what will be deleted.
How does file cleanup sync with database cleanup?
When save_analysis_to_memory() runs auto-cleanup, it also deletes old
.md files from reports/. For manual sync, run
cleanup-files which keeps the latest N files per ticker aligned with the database.
Signal Engine
What are the "Big 7" categories?
Every report is structured by: 1. FUNDAMENTAL, 2. VALUATION, 3. QUALITY, 4. MOMENTUM, 5. RISK, 6. SENTIMENT, and 7. DIVIDEND. This ensures no professional blind spots.
What is the "Self-funded growth" detection logic?
The system checks: If CapEx trend is Increasing and Debt trend is Decreasing, it flags it as institutional-grade self-funded growth. This is one of our highest-conviction green flags.
How is a "Volume Spike" defined?
A volume spike is defined as trading volume exceeding 1.5 times the 50-day moving average. This signifies high institutional interest and is a key indicator for momentum signals.
What is the 200-Week SMA and why is it important?
The 200-Week SMA serves as the Macro Cycle Baseline. When a stock's price drops below this level, it historically represents a significant long-term buying opportunity. It filters out short-term noise and identifies deep-value entry points.
How does Golden Cross / Death Cross detection work?
Golden Cross: SMA 50 crosses above SMA 200 → Strong bullish
signal.
Death Cross: SMA 50 crosses below SMA 200 → Strong bearish signal.
Auto-detected from 2-year price history, tagged under [MOMENTUM].
What are the ICR (Interest Coverage Ratio) risk levels?
> 3.0 = Strong (comfortably covers debt). 1.5 – 3.0 = Fair
(adequate but monitor). < 1.5 = Risk (high default risk). The system also
tracks ICR trend YoY under [QUALITY].
How does Strategic Correlation Analysis work?
Cross-references CapEx and Debt trends: CapEx↑ + Debt↓ = 🟢 Self-funded growth. CapEx↑ + Debt↑ = 🟡 Leveraged expansion. CapEx↓ + Debt↓ = ⚪ Conservative. CapEx↓ + Debt↑ = 🚩 Deteriorating.
Quality & Troubleshooting
What constitutes "High Confidence" data?
High Confidence requires 80% overall completeness and at least 90% of critical metrics (Price, Revenue, Net Income, etc.) to be present. The agent will refuse a strong verdict if confidence is low.
What are the Critical, Optional, and Advanced metric tiers?
Critical (8): price, market cap, revenue growth, margins, P/E, debt/equity, FCF, ROE. Optional (6): forward P/E, PEG, dividend yield, payout ratio, ROA, operating cashflow. Advanced (5): technicals, risk metrics, financial trends, volume, dividends.
What happens if data completeness is below 70%?
The report automatically includes a ⚠️ Data Quality Warning section listing missing critical metrics, analysis confidence level, and specific limitations. The agent will not issue a strong Buy/Sell verdict.
Why do I see "gzip response" warnings in the logs?
This is a yfinance artifact when an API endpoint returns no data for a specific
field. FIntrepidQ catches this automatically and substitutes the missing value with N/A or data
from Alpha Vantage.
What is the structured logging system?
Dual logging: 1) Rich CLI Output — live progress table with phase spinners and
timing. 2) JSON File Logging — rotating files (10MB max, 5 backups) with specialized loggers:
analysis_logger, api_logger, error_logger.
Database & Persistence
What is the database schema?
SQLite (equity_ai.db) with an analysis_reports table: id,
session_id (unique), user_id, ticker, report
(full markdown), and created_at. Performance indexes on ticker and
(ticker, created_at DESC).
What is the retention policy?
By default, the system keeps the latest 3 reports per ticker and auto-deletes
older ones. Configurable via REPORTS_TO_KEEP in memory.py or
DB_RETENTION.ACTIVE_REPORTS_PER_TICKER in config.py.
How do I backup and reset the database?
Backup: copy equity_ai.db equity_ai_backup.db.
Reset: Delete the file and run
python -c "from context_engineering.memory import init_db; init_db()" to create a
fresh one.
What deployment options exist for 24/7 operation?
Local: Free via PM2 or Windows Startup folder. Cloud: ~$5/month via Railway, Render, or a Linux VPS. Cloud provides 99.9% uptime. Start local, then migrate to cloud when comfortable.
WhatsApp Bot Integration
How do I connect the WhatsApp Bot?
1. Run python chat.py whatsapp login and scan the QR code.
2. Run python chat.py whatsapp run-bot to start the listener.
Once connected, the bot acts as a mobile terminal for the entire multi-agent system.
Are reports formatted for mobile?
Yes. The Synthesis Agent generates an "Executive Summary" specifically for mobile consumption.
It uses the JSON_SEND protocol to ensure multiline reports are delivered in one
stable block without truncation.
What is the Heartbeat telemetry system?
The bot prints a heartbeat signal every 5 seconds to the CLI console, confirming the Python ↔ Node.js communication pipe is healthy. If heartbeats stop, the pipe has broken and needs restarting.
What are common WhatsApp bot troubleshooting steps?
"Bot stopped." — Ensure Node.js is installed. No Response —
Check for ✅ WhatsApp Bot CONNECTED in console. 429 error — Gemini
API rate limit, wait 60s. Invalid Ticker — Try the explicit symbol (e.g.,
"TSLA").
Portfolio & Roadmap
How does the Zerodha Kite integration work?
It uses the Personal Tier API (which is free). It fetches your holdings once a day, calculates your cost-basis, and runs the analysis pipeline to detect "Thesis Drift" (when a stock you bought for growth is no longer growing).
What is "Thesis Drift"?
When the current report's verdict flips compared to the previous one (e.g., BUY → SELL) or red flags increase significantly, the system triggers a Thesis Drift Alert via WhatsApp.
Does it monitor earnings results automatically?
Yes. It tracks the stock.calendar from yfinance. It schedules a check 7
days before earnings to set a baseline and 3 days after to capture
the new financial statements.
What is the planned Portfolio Analysis Mode?
A /portfolio AAPL, TSLA, NVDA command that calculates portfolio-level metrics:
weighted volatility, Sharpe Ratio, sector allocation, and a correlation matrix to identify
concentration risk.
What are Real-time Monitoring Alerts?
A planned /alert AAPL price_above 200 command that stores custom conditions in the
database and periodically checks them against live data, notifying the user when triggers fire.
What data visualizations are planned?
Three chart types using Altair: Annual Trends (Revenue, Net Income, Debt, CapEx bar chart), Quarterly Trends (same metrics, 4 quarters), and Price + SMA (line chart with SMA 50, 200, and 200W).