DOCSEARCHbyAlgolia
Submit Docs

AlphaSift Stock Discovery and Ranking Engine

repository·main·Indexed 43 days ago

https://github.com/zhulinsen/alphasift

An agent-friendly stock discovery engine (v0.2.0) that uses deterministic screening (L1) and optional LLM reasoning (L2) to identify market opportunities. It allows users to define stock selection strategies via YAML, provides a CLI for screening and hotspot discovery, and includes a local JSON API for integration with dashboards and AI agents. Features include multi-channel LLM configuration via LiteLLM, automated data source fallback for A-share markets, and built-in strategies across Value, Income, Trend, Quality, Momentum, and Reversal categories.

Tokens
63.6K
Snippets
162
Records
261
Agent score
55%

What's inside AlphaSift

  1. Understand the AlphaSift Project Structure

    main

    AlphaSift is organized into a core Python package and a strategy directory.

    • strategies/: Contains YAML files defining stock selection strategies. This is where you add custom strategies.
    • alphasift/: The core Python package containing the logic for:
      • cli.py: The command-line interface entry point.
      • pipeline.py: Orchestrates the main execution flow.
      • filter.py: Performs L1 hard filtering.
      • scorer.py: Calculates scores.
      • ranker.py: Performs L2 LLM-based ranking.
      • risk.py: Handles the independent risk layer.
      • post_analysis.py: Provides pluggable L3 post-analysis.
      • snapshot.py: Manages full-market snapshots with automatic data source fallback.
      • store.py: Persists run results.
      • evaluate.py: Handles T+N posterior evaluation and batch aggregation.
    alphasift/
├── SKILL.md                # Skill description for AI Agents
├── strategies/             # Stock selection strategy YAMLs
├── docs/                   # Documentation
└── alphasift/              # Python package
    ├── cli.py              # CLI entrypoint
    ├── pipeline.py         # Main flow orchestration
    └── ... (core logic modules)

  2. Integrate with daily_stock_analysis (DSA)

    main

    AlphaSift can be integrated with an external service called daily_stock_analysis (DSA) to provide deep analysis for individual stocks.

    • Role Separation: AlphaSift handles market-wide discovery, hard filtering, cross-sectional scoring, and LLM ranking. DSA handles deep analysis of single stocks.
    • Integration Mechanism: DSA is treated as an L3 post-analysis plugin. AlphaSift calls the DSA service via a synchronous REST request (POST /api/v1/analysis/analyze) only for the final shortlisted candidates to control costs.
    • Configuration: Use the DSA_API_URL environment variable to decouple the deployment of the two services.
    • Impact: The structured results returned by DSA influence the final_score, risk assessments, and final ranking in the AlphaSift pipeline.

  3. Understand the AlphaSift Three-Layer Funnel architecture

    main

    AlphaSift operates using a three-layer filtering and ranking pipeline to select stocks:

    1. L1: Hard Filtering (Code-based): Uses predefined logic in YAML strategies to perform initial hard screening of the market.
    2. L2: LLM Ranking (Soft Judgment): Performs cross-stock comparisons using an LLM. The LLM evaluates candidates based on market context, news, and technical factors, outputting a global market judgment, selection logic, and confidence scores.
    3. L3: Post-Analysis (Optional/Pluggable): An optional layer for deep analysis.
      • Scorecard: A built-in lightweight consistency check (enabled by default via POST_ANALYZERS=scorecard).
      • DSA (Deep Stock Analysis): An optional external service for deep analysis that can be added as a pluggable L3 analyzer.

    All logic is driven by Strategy-as-YAML, meaning selection rules are defined in YAML files rather than hardcoded in Python.

  4. Use parallel candidate context fetching

    main

    AlphaSift implements parallelized fetching for LLM candidate enrichment (e.g., for news, fund_flow, and announcement providers). This reduces wall-time costs by fetching data for multiple candidates concurrently.

    Key behaviors:

    • Order Preservation: Rows preserve their original candidate order even when workers finish out of order.
    • Error Isolation: A failure for a specific candidate/provider records a row error but does not abort the entire process.
    • Stability: Cache behavior remains stable during parallel execution.
    python -m pytest tests/test_candidate_context.py -q

  5. Optimize LLM context via budget allocation

    main

    To manage LLM latency and costs, AlphaSift bounds the context sent to the model by allocating a specific token/character budget across different sections.

    When building LLM context, the budget is distributed among:

    • Market context
    • Snapshot summary
    • Candidate context
    • DSA context

    Prioritization:

    • The system preserves required candidate identity fields and top-ranked candidates first.
    • If low-priority context is trimmed to fit the budget, the system emits a degradation notice.

  6. Understand AlphaSift's position in the financial analysis workflow

    main

    AlphaSift is designed for full-market candidate discovery and LLM-based cross-sectional ranking. It is not a single-stock deep analysis tool or a notification assistant, but rather a top-of-funnel discovery engine.

    Relationship with other tools

    • Upstream: AlphaSift identifies candidates.
    • Downstream: Tools like daily_stock_analysis (DSA) can be used for L3 deep analysis of the candidates discovered by AlphaSift.
    • Integration: AlphaSift can reuse LLM configurations from daily_ai_assistant but remains decoupled from notification responsibilities.
    • Comparison: Unlike OpenBB or Microsoft Qlib, AlphaSift is not a general-purpose financial data platform or a full quantitative research framework; it focuses on structured LLM re-ranking and portfolio risk auditing.

  7. Define stock selection strategies using YAML

    main

    AlphaSift uses .yaml files to define stock selection strategies. Each file must contain two primary sections:

    1. style:: Describes the stylistic attributes used by the UI or agents to categorize the strategy.
    2. screening:: Defines the actual screening rules.

    Built-in strategies utilize advanced profiling beyond simple hard_filters and factor_weights. These profiles include:

    • scoring_profile: Factor scoring curves (e.g., penalties for chasing highs, ideal volume/turnover ratios).
    • risk_profile: Risk thresholds (e.g., abnormal volume, high turnover, low confidence).
    • portfolio_profile: LLM-based industry/theme risk buckets for portfolio diversification.
    • scorecard_profile: Default L3 scorecard scoring/deduction rules.

    For more detailed implementation instructions, refer to the Strategy Writing Guide.

  8. Understand Hotspot Stage classification and Stock Roles

    main

    AlphaSift uses deterministic scoring to classify the lifecycle of a hotspot and the roles of individual stocks within it.

    Hotspot Stages: Stages are classified based on trend, cooling, and persistence scores:

    • 初次异动 (Initial Anomaly)
    • 确认扩散 (Confirmed Diffusion)
    • 加速主升 (Accelerating Main Rise)
    • 分歧放量 (Divergence with High Volume)
    • 降温退潮 (Cooling Down/Ebbing Tide)

    Stock Roles: Individual stocks within a hotspot are assigned roles based on their scoring (price change, turnover, volume ratio, net inflow, etc.):

    • 核心龙头 (Core Leader)
    • 助攻 (Assist/Support)
    • 补涨 (Catch-up)
    • 后排 (Back-row/Laggard)
    • 掉队 (Falling Behind)

  9. Use LLMs for soft judgment and semantic grouping

    main

    In AlphaSift, LLMs are restricted to "soft judgment" tasks and are not responsible for numerical thresholding or full-market screening.

    LLM Responsibilities:

    • News semantic understanding.
    • Relative ranking between candidates.
    • Identifying industry/theme tags and potential catalysts.
    • Generating risk summaries and ranking justifications.

    Portfolio Risk via LLM: LLMs identify industry/theme commonalities to output portfolio concentration risks. These semantic labels (or structured fields like industry, concepts, etc.) are mapped by the code to industry risk buckets (e.g., grouping 'Bank', 'Brokerage', and 'Insurance' into a 'Financial' risk bucket) to generate an auditable portfolio_penalty.

  10. How to configure factor_weights

    main

    Use factor_weights to adjust the importance of different scoring dimensions. This configuration takes precedence over tech_weight.

    Recommended configurations by strategy type:

    • Value strategies: Increase value and stability; keep liquidity moderate.
    • Momentum strategies: Increase momentum, activity, and liquidity.
    • Theme/Capital flow strategies: Include theme_heat to allow sector heat/cooling trends to influence soft scoring.
    • Reversal strategies: Increase reversal and stability; avoid pure chasing of falling prices.

  11. Understand AlphaSift data source fallback logic

    main

    AlphaSift uses multiple A-share market snapshot and K-line sources with automatic priority-based fallback. If a source is unavailable, times out, or lacks required fields, the system skips to the next one in the chain.

    Full-market Snapshot Sources

    • With TUSHARE_TOKEN / TUSHARE_API_TOKEN: tushare $\rightarrow$ sina $\rightarrow$ efinance $\rightarrow$ akshare_em $\rightarrow$ em_datacenter
    • Without Tushare: sina $\rightarrow$ efinance $\rightarrow$ akshare_em $\rightarrow$ em_datacenter

    Daily K-line Enrichment (OHLCV)

    • With Tushare token: tushare $\rightarrow$ tencent $\rightarrow$ sina $\rightarrow$ akshare $\rightarrow$ baostock
    • Without Tushare token: tencent $\rightarrow$ sina $\rightarrow$ akshare $\rightarrow$ baostock

    Configuration & Reliability

    • Throttling: To prevent bans, Eastmoney-only HTTP fallbacks use a shared retrying session with serial throttling. Tune ALPHASIFT_EASTMONEY_MIN_INTERVAL_SEC upward for sensitive networks.
    • Stale Data: If all live sources fail, the system uses the last-good snapshot/cache, marked with stale/fallback attributes. Use SNAPSHOT_FALLBACK_MAX_AGE_HOURS to reject overly old data.

  12. How to write ranking_hints for LLMs

    main

    The ranking_hints field provides natural language instructions to the LLM to guide relative ranking of candidates.

    Best Practices:

    • List priority dimensions clearly (e.g., 1, 2, 3).
    • Use specific descriptive preferences (e.g., "significant volume contraction" instead of "good volume").
    • Mention risk exclusion criteria.
    • Remind the LLM to identify industry/theme commonalities to avoid over-concentration.

    Avoid:

    • Letting the LLM decide the stock selection criteria.
    • Including exact numerical thresholds (use hard_filters for this).
    • Asking the LLM to provide target prices.