docs: finalize FinSight documentation and report package

Author: beautifulrem

.env.example

@@ -1,5 +1,5 @@
 # ============================================================================
-# ARIN Query Intelligence 环境变量配置示例
+# FinSight 环境变量配置示例
 # ============================================================================
 # 使用方法：
 # 1. 复制本文件为 .env: cp .env.example .env

.gitattributes

@@ -0,0 +1,5 @@
+*.pdf binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.zip binary

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Mission & Boundaries
 
-ARIN Query Intelligence turns a user’s financial question into evidence artifacts that downstream systems can analyze and answer from. The owned core is NLU plus Retrieval: `nlu_result` captures normalized query, product type, intents, topics, entities, missing slots, risk flags, and source plan; `retrieval_result` captures executed sources, documents, structured data, coverage, warnings, ranking debug traces, and `analysis_summary`.
+FinSight turns a user’s financial question into evidence artifacts that downstream systems can analyze and answer from. The owned core is Query Intelligence: `nlu_result` captures normalized query, product type, intents, topics, entities, missing slots, risk flags, and source plan; `retrieval_result` captures executed sources, documents, structured data, coverage, warnings, ranking debug traces, and `analysis_summary`.
 
 Query Intelligence does not write final natural-language investment answers, does not produce deterministic buy/sell decisions, and does not own frontend, account, or scheduling systems. Downstream consumers such as `sentiment/` and `scripts/llm_response.py` must consume upstream artifacts instead of re-inferring intent, target entities, or source plan.
 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Group 4.2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -2,16 +2,18 @@
 
 Languages: English | [中文](zh/index.md)
 
-These pages document FinSight, the ARIN7012 Group 4.2 evidence-first financial analysis chatbot project. The technical backend remains ARIN Query Intelligence.
+These pages document FinSight, the ARIN7012 Group 4.2 evidence-first financial analysis chatbot project. The technical backend module is Query Intelligence.
 
 The root README is intentionally short; use these pages when you need contracts, configuration details, training steps, or downstream handoff notes.
 
 ## Contents
 
 | Document | Purpose |
 |---|---|
+| [Modules](modules.md) | Five-module map: frontend, NLU/Retrieval, numerical analysis, text analysis, and LLM summary/prediction. |
 | [Query Intelligence](query-intelligence.md) | Scope, architecture, API, NLU and retrieval output contracts, live providers, environment variables, troubleshooting. |
 | [Local Frontend Chatbot](frontend-chatbot.md) | Browser UI, `/chat` contract, DeepSeek v4 settings, real local screenshots, and troubleshooting. |
+| [Numerical Analysis](numerical-analysis.md) | `analysis_summary`, technical indicators, fundamentals, macro signals, and data readiness. |
 | [Presentation Materials](presentation/README.md) | Clean slide outline and links to current demo screenshots. |
 | [Training](training.md) | Public dataset sync, manifest-based training, runtime asset materialization, evaluation, and release checks. |
 | [LLM Response](llm-response.md) | Legacy local-transformers answer-generation JSON handoff, output contract, configuration, and safeguards. |

README_CN.md

@@ -0,0 +1,49 @@
+# FinSight Modules
+
+Languages: English | [中文](zh/modules.md)
+
+FinSight is organized into five modules. Each module has a clear responsibility and exchanges structured artifacts with the next stage.
+
+## Module Overview
+
+| Module | Responsibility | Main outputs | Detailed docs |
+|---|---|---|---|
+| Frontend | Browser interaction, `/chat` request flow, rendered answer cards, evidence display, and bilingual user experience. | Chat UI state, user request, rendered answer, source cards. | [Local Frontend Chatbot](frontend-chatbot.md) |
+| NLU and Retrieval | Normalize the query, resolve entities, classify intent/topic/style, plan sources, retrieve documents and structured rows, rank evidence, and package traceable outputs. | `nlu_result`, `retrieval_result`, coverage, warnings, debug trace. | [Query Intelligence](query-intelligence.md) |
+| Numerical Analysis | Convert structured market, fundamental, valuation, macro, and price-history rows into compact analytical signals. | `analysis_summary.market_signal`, `fundamental_signal`, `macro_signal`, `data_readiness`. | [Numerical Analysis](numerical-analysis.md) |
+| Text Analysis | Clean retrieved documents, detect language, filter entity-relevant sentences, and classify financial sentiment. | `SentimentResult`, document-level `SentimentItem`, entity aggregates. | [Document Sentiment Analysis](sentiment.md) |
+| LLM Summary and Prediction | Generate frontend-ready answer JSON and follow-up question suggestions from compact evidence. | `answer_generation`, `next_question_prediction`, citations, disclaimer. | [LLM Response Handoff](llm-response.md) |
+
+## Data Flow
+
+```mermaid
+flowchart TD
+  A["User query"] --> B["Frontend"]
+  B --> C["NLU"]
+  C --> D["Retrieval"]
+  D --> E["Numerical Analysis"]
+  D --> F["Text Analysis"]
+  D --> G["LLM Summary and Prediction"]
+  E --> G
+  F --> G
+  G --> H["Frontend answer"]
+```
+
+## Boundaries
+
+- The frontend should not infer financial intent or source plans. It sends user input and renders returned evidence.
+- NLU and Retrieval should stay explainable and evidence-producing. They do not write final investment answers.
+- Numerical analysis summarizes structured evidence. It does not claim causal forecasts.
+- Text analysis classifies retrieved documents. It does not retrieve new sources independently.
+- LLM summary uses only compact evidence and cited evidence IDs. It must not invent missing facts.
+
+## Where to Change Things
+
+| Task | Start here |
+|---|---|
+| Add a new endpoint or contract field | `query_intelligence/contracts.py`, then update [Query Intelligence](query-intelligence.md). |
+| Add a new source provider | `query_intelligence/integrations/`, retrieval source planning, and provider config. |
+| Add a new numerical indicator | `query_intelligence/retrieval/market_analyzer.py`, then update [Numerical Analysis](numerical-analysis.md). |
+| Change frontend display | `query_intelligence/chatbot.py`, then update [Local Frontend Chatbot](frontend-chatbot.md). |
+| Change sentiment preprocessing or labels | `sentiment/`, then update [Document Sentiment Analysis](sentiment.md). |
+| Change LLM JSON output | `scripts/llm_response.py` and `/chat` response mapping, then update [LLM Response Handoff](llm-response.md). |

docs/index.md

@@ -0,0 +1,86 @@
+# Numerical Analysis
+
+Languages: English | [中文](zh/numerical-analysis.md)
+
+The numerical analysis module summarizes structured evidence retrieved by FinSight. It is implemented mainly in `query_intelligence/retrieval/market_analyzer.py` and exposed through `retrieval_result.analysis_summary`.
+
+This module supports explanation and evidence readiness. It does not produce deterministic buy/sell decisions.
+
+## Inputs
+
+Numerical analysis consumes structured rows already selected by retrieval:
+
+| Input | Typical source | Use |
+|---|---|---|
+| Price and quote history | `market_api`, Tushare, AKShare, efinance, seed data | Returns, moving averages, volatility, RSI, MACD, Bollinger bands. |
+| Fundamentals | `fundamental_sql`, Tushare, local structured rows | Profitability, valuation, ROE, PE/PB, data completeness. |
+| Industry context | `industry_sql` | Sector identity and sector-level context. |
+| Macro indicators | `macro_sql`, `macro_indicator`, `policy_event` | CPI, PMI, M2, treasury yields, policy-event direction. |
+| Fund/index rows | `fund_nav`, `fund_fee`, `index_daily`, `index_valuation` | NAV, fee, redemption, index trend and valuation evidence. |
+
+The module uses the resolved entity, source plan, retrieved structured rows, and NLU intent/topic hints. It does not re-run NLU.
+
+## Output
+
+`analysis_summary` is a compact object designed for downstream modules:
+
+```text
+analysis_summary
+├── market_signal
+│   ├── trend_signal
+│   ├── pct_change_nd
+│   ├── ma5 / ma20
+│   ├── rsi_14
+│   ├── macd
+│   ├── bollinger
+│   └── volatility_20d
+├── fundamental_signal
+│   ├── pe_ttm / pb / roe
+│   ├── valuation_assessment
+│   └── available_fields
+├── macro_signal
+│   ├── indicators[]
+│   └── overall
+└── data_readiness
+    ├── has_price_data
+    ├── has_fundamentals
+    ├── has_macro
+    ├── has_news
+    ├── has_technical_indicators
+    ├── relevant_intents
+    └── relevant_topics
+```
+
+## Indicator Meaning
+
+| Signal | Meaning |
+|---|---|
+| `trend_signal` | Directional description inferred from recent price and moving-average context. |
+| `pct_change_nd` | Recent percentage return over available windows. |
+| `ma5`, `ma20` | Short and medium moving averages when enough price history exists. |
+| `rsi_14` | Momentum indicator. Extreme values should be treated as context, not a standalone trading rule. |
+| `macd` | Trend and momentum signal derived from exponential moving averages. |
+| `bollinger` | Price position relative to recent volatility bands. |
+| `volatility_20d` | Recent realized volatility. |
+| `valuation_assessment` | Lightweight valuation interpretation based on available PE/PB/fundamental rows. |
+| `data_readiness` | Flags that tell downstream modules whether enough evidence exists for a reliable explanation. |
+
+## Design Rules
+
+- Use only structured evidence already retrieved by FinSight.
+- Keep calculations explainable and inspectable.
+- Preserve missing-data warnings instead of filling unsupported facts.
+- Treat indicators as descriptive signals, not trading instructions.
+- Keep downstream LLM prompts compact by passing summarized fields, not raw provider dumps.
+
+## Related Tests
+
+```bash
+python -m pytest tests/test_analysis_summary.py tests/test_market_analyzer.py -q
+```
+
+## Related Documentation
+
+- [Query Intelligence](query-intelligence.md)
+- [LLM Response Handoff](llm-response.md)
+- [Training and Runtime Assets](training.md)

docs/modules.md

@@ -1,6 +1,6 @@
 # Presentation Materials
 
-This folder is the cleaned presentation entry point for the FinSight / ARIN Query Intelligence project.
+This folder is the cleaned presentation entry point for the FinSight project.
 
 The original `PPT_Overleaf` backup contained older browser screenshots, LaTeX build byproducts, unrelated image assets, and raw planning notes. The reusable content has been consolidated here as a clean slide outline and linked to the current documented frontend screenshots.