Intelligent Stock Analysis Assistant

An A-share investment analysis tool built on the HelloAgents multi-agent collaboration framework, integrating market data, financial analysis, news sentiment, intelligent stock screening, simulated trading, and more to provide data-driven investment decision support.

⚠️ Disclaimer: All analysis results from this tool are for reference only and do not constitute investment advice. Investing involves risk; exercise caution when entering the market.

Features

Module	Feature	Status
📊 Market Quotes	Real-time individual stock quotes, index quotes, sector quotes	✅
📈 Financial Analysis	Financial indicators, company profile (description list layout), top 10 shareholders (multi-format table parsing)	✅
📉 Stock Analysis UX	Prioritize loading quotes and charts; finance/profile/shareholders load asynchronously	✅
🗣️ AI Sentiment Analysis	AI auto-searches news and analyzes market sentiment, streaming output	✅
📉 AI Data Analysis	AI auto-queries market/financial data and generates analysis reports, streaming output	✅
💬 AI Chat Assistant	Coordinator Agent parses user intent, auto-dispatches sub-agents, streaming dialogue output	✅
📰 News & Info	Financial news search, hot headlines browsing	✅
🔍 Smart Stock Screener	Multi-criteria combined screening (market + financial dual dimensions)	✅
🏛️ Buffett Evaluation	Value investing framework, ReflectionAgent self-reflection optimized streaming report generation with Markdown download	✅
⭐ Watchlist	MX watchlist add/delete/query; "Add to Watchlist" on stock analysis page & screener results; removal requires confirmation	✅
🏠 Dashboard	Three-thread parallel warmup (indices/watchlist/hotspots), watchlist uses API-returned price data directly	✅
💰 Simulated Trading	Simulated buy/sell/cancel orders, position management, profit curve; order/cancel confirmation dialogs to prevent misoperation	✅
📝 History Records	AI Sentiment / AI Data / Buffett / AI Chat four analysis history types stored by day, with view/delete support	✅
💾 File Cache	Each stock's data saved as an independent JSON file, no refresh within the day, supports grep keyword search	✅
🧠 Memory System	Daily first-start date tracking, daily cutover re-fetches dashboard snapshot; persisted under `data/memory/` (JSON, not HelloAgents MemoryManager); watchlist count changes trigger refresh when prior watchlist records exist (frontend still requests watchlist API in real-time)	✅
⚙️ Preferences	Personalized investment style, risk preference, and sector preference settings	✅
🐳 Docker Deployment	One-click containerized deployment, frontend/backend separation	✅
📦 exe Packaging	PyInstaller packaging as standalone exe, no Python/Node.js installation required	✅

Highlights

Multi-Agent Collaboration: Uses Reflection (Buffett evaluation), ReAct (sentiment/data/general advisor), and coordinator routing; stock analysis tabs run streaming agents independently; the AI chat assistant dispatches sub-agents on demand. Stock screening, watchlist, and simulated trading use backend services directly against skills/, not separate agents
AI Chat Assistant: Single LLM routing decision (data / sentiment / advisor combinations), sub-agents run non-streaming, then coordinator consolidates; single-dimension pushes results directly, multi-dimension uses LLM streaming to generate a comprehensive reply (with length and word count limits, see agents/coordinator_agent.py, agents/text_truncation.py)
Streaming AI Analysis: Sentiment analysis, data analysis, and Buffett evaluation all support NDJSON streaming output with real-time generation display
Buffett Value Investing Framework: Full value investing analysis system integrated (8 reference documents), ReflectionAgent self-reflection optimizes evaluation reports
File Cache System: All data per stock persisted to local files, prioritize cache reads over API calls, supports grep-style keyword search
Personalized Investment Analysis: User preference storage (risk preference, investment style, sector preference), persisted via preference_service and exposed through /api/v1/preferences
Full-Stack Integration: Vue3 frontend + FastAPI backend + HelloAgents agents + East Money MX data, end-to-end self-contained
Operational Safety: Dangerous operations like simulated buy/sell and watchlist removal require confirmation dialogs

Tech Stack

Layer	Technology	Version
Frontend	Vue3 + Element Plus + ECharts	3.x / 2.x / 5.x
Backend	FastAPI + Uvicorn	0.110+
Database	SQLite (SQLAlchemy + aiosqlite)	—
Agents	HelloAgents Optimized	0.2.9
LLM	DeepSeek / OpenAI-compatible API	—
Financial Data	East Money MX API	—

Quick Start

Prerequisites

Python ≥ 3.10
Node.js ≥ 18
Docker ≥ 24 (optional, for production deployment)

Environment Variables

Copy .env.example to .env and fill in your keys. For local dev, keep BACKEND_PORT=8000 (must match frontend/vite.config.js proxy). For exe builds, use 5174 if needed. Commonly used items are as follows (see .env.example comments for full details):

# LLM (compatible with HelloAgents)
LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=sk-your-deepseek-key
LLM_BASE_URL=https://api.deepseek.com
# Optional: single request timeout (seconds); backend merges with a longer floor value
# to prevent premature disconnection during ReAct/chat multi-turn
# LLM_TIMEOUT=180

# Buffett evaluation: optional reflection rounds (see BUFFETT_MAX_REFLECTIONS in .env.example)

# East Money MX financial data
MX_APIKEY=your-mx-apikey
# Optional: MX_API_URL, MX_CACHE_TTL_SECONDS, local replay MX_REPLAY_FIXTURES, etc.

# Service port: dev mode defaults to 8000 when not set; PyInstaller exe defaults to 5174 when not overridden
# (consistent with run_exe.py prompt)
# If modifying BACKEND_PORT, also update the /api proxy target in frontend/vite.config.js

💡 DeepSeek API: https://platform.deepseek.com
💡 MX API: https://dl.dfcfs.com/m/itc4

Local Development

Backend:

# Install dependencies (equivalent: also run pip install -r requirements.txt from repo root)
pip install -r backend/requirements.txt

# Start service (from project root)
python -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload

API docs: http://localhost:8000/docs

Frontend:

cd frontend
npm install
npm run dev

Frontend UI: http://localhost:5173 (dev mode auto-proxies /api to backend port 8000)

Docker Deployment

docker compose up -d

Frontend: http://localhost:8080
Backend API: http://localhost:8000/docs

For detailed deployment instructions, see DEPLOY.md

Standalone exe Packaging

Package the frontend and backend into a single .exe file, no Python/Node.js installation required to run.

Requirements

Component	Purpose	Packaging Only?
Python 3.10+	PyInstaller build	Yes
Node.js 18+	Frontend build	Yes
PyInstaller	Python → exe	Yes

One-Click Build

# 1. Install packaging dependencies
pip install pyinstaller

# 2. Run the build script (from project root)
python scripts/build_exe.py

Screenshots

Due to the large amount of data loaded, it's best to wait for data warmup before entering the interface. Also, due to East Money restrictions, do not use a VPN/proxy, or it will fail.

UI screenshots are not shipped with the repo. Capture them locally after startup, or place them under outputs/screenshots/ for documentation.

Project Structure

intelligent-stock-analyzer/
├── README.md
├── README_EN.md
├── requirements.txt                # Root aggregated deps (points to backend/requirements.txt)
├── run_exe.py                      # exe runtime entry
├── scripts/
│   └── build_exe.py                # PyInstaller build script
├── data/                           # Data directory (created at runtime)
│   ├── stock_cache/                #   File cache (independent JSON per stock)
│   └── memory/                     #   Memory system state (dashboard_state.json)
├── outputs/                        # Optional: local reports/screenshots
├── backend/                        # 🖥️ Backend FastAPI
│   ├── app/
│   │   ├── main.py                 #   App entry + lifecycle
│   │   ├── config.py               #   Configuration management
│   │   ├── api/                    #   API route modules
│   │   │   ├── chat.py             #     AI chat assistant streaming endpoint
│   │   │   ├── sentiment.py        #     AI sentiment streaming (agreed path)
│   │   │   ├── data_analysis.py    #     AI data analysis streaming (agreed path)
│   │   │   ├── agent_api.py        #     Sentiment/data streaming impl + /agent compat path
│   │   │   ├── history.py          #     Analysis history CRUD
│   │   │   ├── system_browser.py   #     exe/desktop: backend opens system browser for external links
│   │   │   ├── cache_api.py        #     File cache management / grep search
│   │   │   └── ...                 #     market / financial / news / screener etc.
│   │   ├── services/               #   Business logic layer
│   │   │   ├── chat_service.py     #     Chat assistant dispatch (coordinator streaming)
│   │   │   ├── memory_service.py   #     Memory system (daily cutover + dashboard warmup etc.)
│   │   │   ├── stock_file_cache.py #     File cache (grep search support)
│   │   │   ├── history_service.py  #     History CRUD
│   │   │   ├── screener_service.py #     Stock screening (direct skills/mx-xuangu)
│   │   │   ├── watchlist_service.py#     Watchlist (direct skills/mx-zixuan)
│   │   │   ├── simulation_service.py#    Simulated trading (direct skills/mx-moni)
│   │   │   ├── preference_service.py#    User preferences CRUD / context
│   │   │   └── ...                 #     market / news / buffett etc.
│   │   ├── models/                 #   Data models
│   │   │   ├── report.py           #     AnalysisReport
│   │   │   ├── history_models.py   #     Analysis history ORM (SQLite)
│   │   │   ├── history.py          #     Compat re-export AnalysisHistory
│   │   │   ├── memory_models.py    #     MemorySnapshot and other memory data structures
│   │   │   └── preference.py       #     UserPreference
│   │   ├── middleware/             #   Middleware placeholder (skeleton, not registered in main)
│   │   └── utils/                  #   Utilities
│   ├── Dockerfile
│   └── requirements.txt
│
├── frontend/                       # 🎨 Frontend Vue3
│   ├── src/
│   │   ├── views/                  #   Page views
│   │   │   ├── Dashboard.vue       #     Dashboard (watchlist direct price display)
│   │   │   ├── StockAnalysis.vue   #     Stock analysis (6 tabs)
│   │   │   ├── StockScreener.vue   #     Smart stock screener
│   │   │   ├── NewsCenter.vue      #     News center
│   │   │   └── Simulation.vue      #     Simulated trading (confirmation dialogs)
│   │   ├── components/             #   Shared components
│   │   │   ├── StreamOutput.vue    #     Streaming output generic component
│   │   │   ├── AIAnalysisPanel.vue #     AI analysis panel
│   │   │   ├── ChatAssistant.vue   #     AI chat assistant
│   │   │   ├── HistoryDrawer.vue   #     History drawer
│   │   │   └── NewsDetailDrawer.vue#     News detail
│   │   ├── api/                    #   Axios wrapper
│   │   ├── router/                 #   Vue Router
│   │   └── store/                  #   Pinia state management
│   ├── Dockerfile
│   ├── nginx.conf
│   └── package.json
│
├── agents/                         # 🤖 Agent layer (AI analysis & chat only)
│   ├── agent_system.py             #   Unified agent management & streaming dispatch
│   ├── coordinator_agent.py        #   AI chat assistant (routing LLM + sequential sub-agent calls + integrated streaming)
│   ├── text_truncation.py          #   Coordinator output natural boundary truncation
│   ├── advisor_agent.py            #   Buffett evaluation agent (Reflection + streaming)
│   ├── general_advisor_agent.py    #   General investment advisor agent (ReAct)
│   ├── sentiment_agent.py          #   Sentiment analysis agent (ReAct + streaming)
│   ├── data_analysis_agent.py      #   Data analysis agent (ReAct + streaming)
│   ├── tests/                      #   Agent-layer unit tests
│   └── tools/                      #   ReAct tool wrappers (for agents above)
│       ├── mx_data_tool.py         #     Market data → skills/金融数据
│       └── mx_search_tool.py       #     News search → skills/资讯搜索
│
├── HelloAgents Optimized/          # 🧩 Multi-agent framework (StockSage slim build)
│   └── hello_agents/
│       ├── core/                   #   LLM, Config, Agent base, ConversationManager, etc.
│       └── agents/                 #   ReActAgent, ReflectionAgent (used by this app)
│
├── skills/                         # 🔧 East Money MX skills (business API layer)
│   ├── 金融数据/mx-data
│   ├── 资讯搜索/mx-search
│   ├── 智能选股/mx-xuangu
│   ├── 自选股管理/mx-zixuan
│   ├── 模拟组合管理/mx-moni
│   └── 巴菲特投资思维/             #   Value investing reference docs
│
├── docker-compose.yml
├── DEPLOY.md
└── .env.example

API Route Overview

Route Group	Prefix	Description
System	`/api/v1/system`	`GET /health`, `GET /config` (registered in `main.py`); `POST /open-external-url` registered by `system_browser.py` under the same prefix, for exe scenarios to open http(s) links in the native browser
Market	`/api/v1/market`	Individual stock quotes, indices, sectors
Financial	`/api/v1/financial`	Financial indicators, company profile, shareholders
Analysis	`/api/v1/analysis`	In-depth stock report `POST /report/{code}`, `GET /report/{report_id}`, list `GET /reports`
News	`/api/v1/news`	News search, sentiment analysis, hot topics
Screener	`/api/v1/screener`	Conditional screening, filter criteria
Watchlist	`/api/v1/watchlist`	Watchlist add/delete/query
Simulation	`/api/v1/simulation`	Simulated trading (buy/sell/cancel/positions)
Buffett	`/api/v1/buffett`	Buffett evaluation (Reflection / advisor streaming, history type `buffett`)
Preferences	`/api/v1/preferences`	User investment preferences CRUD
Chat	`/api/v1/chat`	AI chat assistant NDJSON streaming `POST /stream`
Sentiment	`/api/v1/sentiment`	AI sentiment `POST /analyze/stream` (agreed path)
Data analysis	`/api/v1/data-analysis`	AI data analysis `POST /analyze/stream` (agreed path)
Agent (compat)	`/api/v1/agent`	Semantically same as above: `POST /sentiment/stream`, `POST /data-analysis/stream`
History	`/api/v1/history`	Analysis history list/detail/delete/clear; `type` includes `sentiment` / `data_analysis` / `buffett` / `chat`
Cache	`/api/v1/cache`	File cache grep / stats / clear

Full Swagger docs: dev default http://localhost:8000/docs (port per BACKEND_PORT in .env)

Agent Collaboration Flow

AI Chat Assistant Flow

User chat message
    │
    ▼
Coordinator (routing LLM, single-line keyword)
    │ none → general conversation (coordinator LLM streaming reply, or stock context guidance)
    │ data / sentiment / advisor or combinations
    ▼
Sub-Agents run sequentially (non-streaming, with word limit)
    ├── data → run_data_analysis
    ├── sentiment → run_sentiment
    └── advisor → inject existing data/sentiment summaries into advisor prompt → run_advisor
    │
    ▼
User-facing streaming output
    ├── single sub-agent only → directly push that result (truncated to limit)
    └── multiple agents → coordinator LLM stream_invoke to integrate into structured response

Buffett Evaluation Flow

User clicks "Generate Buffett Evaluation Report"
    │
    ▼
advisor_agent (ReflectionAgent)
    │ collects market/financial/sentiment data
    ├── initial analysis → moat / management / margin of safety
    ├── self-reflection → data accuracy / logical consistency
    └── iterative optimization → refine report
    │
    ▼
Streaming final evaluation report + auto-save history

Business API vs. Agents

Capability	Implementation
AI sentiment / data analysis / chat / Buffett evaluation	`agents/*` + HelloAgents (ReAct / Reflection / coordinator)
Stock screening / watchlist / simulated trading / market & news queries	`backend/app/services/` → `skills/` (MX API)
User preferences	`preference_service` + `/api/v1/preferences`

Stock Analysis Page Structure

When entering individual stock analysis (/analysis or /analysis/:code, :code optional), there are 6 tabs:

Tab	Content	Notes
📊 Market Charts	ECharts candlestick + market details	Priority loading
📈 Financial Data	Financial indicator cards + company profile + top 10 shareholders	Async loading
🗣️ AI Sentiment	AI auto-searches news for market sentiment analysis	Streaming output
📉 AI Data Analysis	AI queries market/financial data to generate reports	Streaming output
🧠 Buffett Evaluation	ReflectionAgent self-reflection optimized evaluation	Streaming output
💬 AI Chat Assistant	Free-form conversation, auto-dispatches sub-agents	Streaming output

Each analysis tab supports viewing history records and downloading reports.

File Cache System

All stock data is automatically persisted to the data/stock_cache/{stock_code}/ directory:

data/stock_cache/
  _index.json           # Master index
  600519/
    quote.json          # Market data
    financial.json      # Financial indicators
    profile.json        # Company profile
    holders.json        # Top 10 shareholders
    sentiment.json      # Sentiment analysis
    news.json           # Related news (when cached)

Same-day cache returns directly with no hourly limit; cross-day data expires after 24h
API is called only on cache miss, and results are automatically written back
Supports GET /api/v1/cache/search?keyword=Kweichow Moutai grep-style keyword search
Cache persists across service restarts

Reserved Config (Not Wired Yet)

Redis and JWT variables in .env.example are read by config.py but not used in the current release (caching uses in-process MX TTL + file cache; APIs have no login). See Roadmap below.

Roadmap

Add technical indicator analysis (MACD, KDJ, RSI, etc.)
Implement user authentication system (JWT Token; env vars reserved)
Add portfolio optimization algorithms (Markowitz model)
Add A-share trading calendar and holiday detection
Add strategy backtesting engine
Add full-text search for history records

Contributing

Issues and Pull Requests are welcome!

Development Workflow

Fork this repository
Create a feature branch: git checkout -b feature/your-feature
Commit changes: git commit -m "feat: feature description"
Push to branch: git push origin feature/your-feature
Create a Pull Request

Commit Conventions

Type	Description
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation update
`style`	Code formatting (no logic change)
`refactor`	Code refactoring
`test`	Test-related
`chore`	Miscellaneous (e.g., dependency updates)

PR Checklist

Code runs normally without errors
Related documentation updated
Clear usage examples (if applicable)
Code has appropriate comments
Common exceptions are handled

License

MIT License

Author

- GitHub: [@lcyting](https://github.com/lcyting)
- Email: lcy154745@163.com

Acknowledgments

Thanks to Hello-Agents for the multi-agent framework
Thanks to Datawhale open-source learning community
Thanks to agi-queen for the open-source bft-skills
Thanks to East Money MX API for financial data services
Thanks to all GitHub open-source contributors

README_EN.md 21 KB 히스토리 Raw