How to Set Up the ZhuLinsen/daily_stock_analysis Repository Locally: Complete Installation Guide

To set up the ZhuLinsen/daily_stock_analysis repository locally, clone the repository, install Python 3.10+ dependencies from requirements.txt, copy .env.example to .env and configure your API keys, then run python main.py --dry-run to verify the installation before executing full analysis.

The ZhuLinsen/daily_stock_analysis repository is an open-source Python application that automates daily stock market analysis using multiple data providers, LLM-powered insights, and multi-channel notifications. Setting up this repository locally requires configuring environment variables for data sources and notification channels, then running the pipeline through main.py or the optional Web UI.

Prerequisites and System Requirements

The project requires Python 3.10 or higher. All dependencies are specified in requirements.txt at the repository root. You will need API keys for at least one LLM provider (Gemini, OpenAI, DeepSeek, or others supported via LiteLLM) and at least one notification channel to receive analysis reports.

Step-by-Step Local Setup

Clone the Repository

Start by cloning the source code from GitHub and navigating into the project directory:

git clone https://github.com/ZhuLinsen/daily_stock_analysis.git
cd daily_stock_analysis

Install Python Dependencies

Create an isolated virtual environment to avoid conflicts with system packages, then install the required dependencies:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install -r requirements.txt

Validation: Run the CI gate script to verify the installation and run static checks:

./scripts/ci_gate.sh

This executes flake8 linting and pytest -m "not network" to ensure the codebase passes quality gates before you configure runtime settings.

Configure Environment Variables

Copy the example environment file and edit it with your specific configuration:

cp .env.example .env

Edit .env to configure these critical components:

• STOCK_LIST: Comma-separated tickers to analyze (e.g., 600519,HK00700,AAPL for A-shares, Hong Kong, and US stocks)
• LLM API Keys: Set at least one of GEMINI_API_KEY, OPENAI_API_KEY, or AIHUBMIX_KEY
• Notification Channels: Configure WECHAT_WEBHOOK_URL, TELEGRAM_BOT_TOKEN, or other supported channels (Feishu, Discord, Slack, Email, etc.)
• Scheduling: Set SCHEDULE_ENABLED=true and SCHEDULE_TIME=18:00 for automatic daily runs
• Proxy Settings: If required, set USE_PROXY=true with PROXY_HOST and PROXY_PORT

When the application starts, src/config.py loads these variables through the setup_env() function, which also configures the NO_PROXY list with domestic finance domains (see lines 10000-10030 in src/config.py).

Run a Quick Local Test

Verify your setup without consuming LLM API credits by running a dry test:

python main.py --dry-run

The --dry-run flag fetches market data through the data_provider/ adapters but skips LLM generation, allowing you to confirm that data providers and the src/core/pipeline.py orchestration are functioning correctly.

To execute a full analysis with LLM insights:

python main.py

Optional Features and Advanced Configuration

Enable the Web UI

The repository includes a FastAPI-based Web UI with a Vue/React frontend. To launch it:

python main.py --webui

The first run automatically builds frontend assets via src/webui_frontend.py and stores them under apps/dsa-web/. Access the interface at http://127.0.0.1:8000 (or your configured host/port). The UI enables interactive stock management, manual analysis triggering via /api/v1/analysis/analyze, and browsing of historical reports stored in ./data/stock_analysis.db.

Schedule Automatic Analysis

To run the analysis automatically at a specific time each trading day:

1. Set SCHEDULE_ENABLED=true and SCHEDULE_TIME (default 18:00) in .env
2. Set TRADING_DAY_CHECK_ENABLED=true to skip non-trading days
3. Launch the scheduler:

python main.py --schedule

The src/scheduler.py module handles the cron-like scheduling and can launch background event monitors. Use --force-run to execute immediately regardless of the schedule.

Project Architecture Overview

Understanding the key files helps troubleshoot setup issues:

• main.py: CLI entry point that parses arguments and bootstraps all modes (analysis, Web UI, scheduler)
• src/config.py: Validates environment variables and exposes a singleton Config object used throughout the application
• src/core/pipeline.py: Contains StockAnalysisPipeline which orchestrates data fetching, LLM analysis via src/agent/llm_adapter.py, and report generation
• src/services/stock_service.py: Wraps data providers (TickFlow, Tushare, YFinance, Longbridge) with priority-based fallback logic
• src/search_service.py: Aggregates news and sentiment from Anspire, SerpAPI, Tavily, and other sources
• src/notification.py: Dispatches reports to configured channels through individual sender modules in src/notification_sender/

Programmatic Usage Examples

Using the Pipeline Directly

You can invoke the analysis pipeline programmatically without the CLI:

from src.core.pipeline import StockAnalysisPipeline
from src.config import get_config

cfg = get_config()  # Loads .env and returns singleton Config

pipeline = StockAnalysisPipeline(
    config=cfg,
    max_workers=2,
    query_id="demo123",
    query_source="script"
)

results = pipeline.run(
    stock_codes=["600519", "AAPL"],
    dry_run=False,
    send_notification=False
)

for r in results:
    print(f"{r.code}: {r.operation_advice} (score={r.sentiment_score})")

Integrating the Scheduler

Embed the scheduler in another Python process:

import threading
from src.scheduler import run_with_schedule
from src.core.pipeline import StockAnalysisPipeline
from src.config import get_config

def scheduled_task():
    cfg = get_config()
    pipeline = StockAnalysisPipeline(cfg, query_source="schedule")
    pipeline.run(stock_codes=None)  # None uses cfg.stock_list

run_with_schedule(
    task=scheduled_task,
    schedule_time="18:00",
    run_immediately=True,
    background_tasks=[]
)

Sending Test Notifications

Verify notification channels without running analysis:

from src.notification import NotificationService
from src.config import get_config

cfg = get_config()
notifier = NotificationService()
notifier.send("Daily Stock Analysis test message", email_send_to_all=True)

Summary

• Clone the repository from https://github.com/ZhuLinsen/daily_stock_analysis.git
• Install Python 3.10+ dependencies using pip install -r requirements.txt
• Configure the .env file with at least one LLM API key, STOCK_LIST, and a notification webhook
• Test with python main.py --dry-run before running full analysis
• Extend functionality via the Web UI (--webui) or automatic scheduling (--schedule)
• Customize behavior through src/config.py which manages the global Config singleton and environment validation

Frequently Asked Questions

What Python version is required for daily_stock_analysis?

The repository requires Python 3.10 or higher. This is enforced because the code uses modern typing features and async patterns that depend on recent Python versions.

Which API keys are mandatory to run the analysis?

You must configure at least one LLM provider key (such as GEMINI_API_KEY, OPENAI_API_KEY, or AIHUBMIX_KEY) and at least one notification channel (WeChat webhook, Telegram bot token, or similar). The application uses LiteLLM through src/agent/llm_adapter.py to normalize calls across providers, and src/notification.py will raise validation errors if no channels are configured.

How do I verify the installation without consuming LLM credits?

Run python main.py --dry-run to test the data pipeline and configuration loading. This mode fetches stock data through the data_provider/ adapters and validates your .env configuration, but skips the LLM generation phase in src/core/pipeline.py, preventing API usage charges.

Can I run this on Windows?

Yes. While the virtual environment activation command differs (use .venv\Scripts\activate instead of source .venv/bin/activate), all Python dependencies and path handling in main.py and src/config.py are cross-platform compatible. The NO_PROXY domain handling in src/config.py and the scheduler in src/scheduler.py work identically on Windows, Linux, and macOS.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}