A-Share Analyst

An LLM-powered automated quarterly earnings review tool for Chinese A-share companies. Enter a company name or stock code with a reporting period, and it collects financial data and generates a professional research report.

Features

• Automated data collection - Calls 28 AKShare financial data interfaces, covering income statements, balance sheets, cash flow statements, financial indicators, peer comparisons, earnings forecasts, and more.
• ReAct data completion - A Phase 2 ReAct loop lets the LLM decide which extra data to collect, with up to 30 tool calls.
• Professional report generation - Produces a 5-section report: performance and operations, outlook and investment thesis, earnings forecast and valuation, risk factors, and executive summary.
• Traceable data citations - Each analysis paragraph includes DATA_REFS references that trace back to specific data sources.
• File-based caching - Uses three TTL tiers (7 days / 1 day / 1 hour) to avoid repeated API calls.
• Flexible LLM configuration - Supports OpenAI-compatible APIs and configurable models.

Quick Start

1. Install dependencies

git clone https://github.com/DreamWalkerXZ/a-share-analyst.git
cd a-share-analyst
uv sync

2. Configure environment variables

cp .env.example .env

Edit .env and set the required API keys:

Variable	Description
OPENAI_API_KEY	LLM API key (required)
SERPER_API_KEY	Serper search API key (required)
OPENAI_BASE_URL	API endpoint, defaults to https://api.openai.com/v1
OPENAI_MODEL	Model name, defaults to gpt-4o

Optional LangSmith tracing variables are documented in .env.example.

3. Generate a report

# Use a company name
uv run main.py "贵州茅台 2025 Q4"

# Use a stock code
uv run main.py "600519 2025 Q4"

Reports are written to the output/ directory. Example:

output/贵州茅台_2025Q4_20260426_231909.md

Sample report screenshot

Usage

Input format

uv run main.py "<company name or stock code> <year> <quarter>"

Supported quarters: Q1, Q2, Q3, Q4.

Disable cache

Force fresh data collection and skip the local cache:

DISABLE_DATA_CACHE=1 uv run main.py "贵州茅台 2025 Q4"

Architecture

graph LR;
    data_collection[data_collection<br>Phase 1: 12 AKShare pre-fetch<br>Phase 2: ReAct loop]
    report_generation[report_generation<br>Sections 1-4 then Section 0<br>LLM validate + retry]
    output[output<br>Assemble Markdown + refs]

    data_collection --> report_generation --> output

Loading

Data collection is orchestrated with LangGraph. In Phase 2, the LLM schedules calls across three tools:

Tool	Purpose
StructuredDataTool	Calls AKShare financial data interfaces
RealTimeSearchTool	Searches industry news and analyst views through Serper
FinancialCalculatorTool	Runs sandboxed financial calculations with simpleeval

Development

Run tests

uv run pytest

Project structure

src/
├── agent/          # LangGraph workflow: graph, nodes, subgraph, state
├── prompts/        # LLM prompts for data collection and report sections
├── tools/          # Tool wrappers for AKShare, Serper search, and calculator
└── utils/          # Utilities for LLM factory, cache, and data formatting

Tech Stack

• Python 3.11+
• LangGraph - Workflow orchestration
• LangChain + langchain-openai - LLM calls
• AKShare - Chinese A-share financial data
• simpleeval - Safe expression evaluation