aiagents-stock: a Streamlit desk where several model agents argue about an A-share

A panel of analysts instead of one prompt

The project description sets out the premise plainly: a multi-agent stock team analysis and monitoring system for mainland A-shares that simulates a securities research desk. A stock goes in, and several agents with different mandates analyse it and report back. The file listing shows how that is built, and the naming is the architecture.

There is a `longhubang_` family for the Dragon-Tiger List, the daily disclosure of which institutions and individuals traded a stock in unusual volume, split across agents, data access, scoring, engine, PDF export and UI files. A `macro_analysis_` family and a `macro_cycle_` family cover two different macro lenses. A `low_price_bull_` family implements the valuation screen, split into selector, service, strategy and UI. Then there are the singletons: `main_force_` modules for institutional capital tracking, `market_sentiment_data.py`, `fund_flow_akshare.py`, and the AI plumbing in `ai_agents.py`, `llm_client.py` and `deepseek_client.py`.

The naming pattern is the useful signal. Splitting a feature into an agents file, a data file, an engine file and a UI file, four times over, is a consistent convention rather than an accident, and it tells you the author treats each analysis as a pipeline with a scoring step rather than as a single prompt.

Two SQLite databases are committed to the repository, `longhubang.db` and `low_price_bull_monitor.db`, along with `main_force_batch.db`. That is worth pausing on: binary state files in version control mean the schema is not fully expressed in migration files, and it suggests the databases were committed as samples rather than as an empty starting point.

Three data source migrations in one README

The most valuable section of this README documents what stopped working. In June 2026, the author reports that Eastmoney's API server was restricting access from their IP, so the Akshare calls returned `RemoteDisconnected` and the application could not fetch A-share data at all. Historical K-line data moved from Eastmoney's endpoint to a Tencent source at `proxy.finance.qq.com`. Per-stock company information moved from Eastmoney to Sina at `hq.sinajs.cn`. Full-market real-time quotes moved to a Sina single-stock API.

That last swap is the interesting engineering decision, and the README explains it: iterating over more than 5,000 individual stocks was taking about 15 seconds, while a single-stock Sina API returns in under a second. The file list confirms the supporting modules, with `data_source_manager.py` at the root and helpers under `utils/`.

A second migration followed in late June, this time for stock screening rather than quotes. `iwencai.com` was performing TLS fingerprint detection against the Python `requests` library and serving captchas or 403s, which broke every `pywencai.get()` call across eight files. The fix was to add `utils/iwencai_browser.py`, which launches headless Chromium with Playwright to obtain real browser cookies, caches the session for five minutes, and feeds those cookies to a new `safe_get` wrapper in `utils/pywencai_helper.py` that falls back to a direct call.

The pattern across both migrations is consistent: an upstream endpoint begins fingerprinting or blocking, a browser-shaped request path is added as a fallback, and the README records which of the data paths currently work. As of the last entry, fund flow from Eastmoney is marked as limited and skipped, Tushare is marked as a fallback awaiting a token, and stock screening needs a logged-in browser session.

What the screening and valuation screens actually filter on

The value-investing module is the most precisely specified part of the project, and its filters are numeric rather than aspirational. The README states the criteria as a low price-to-earnings ratio of 20 or below, a price-to-book ratio of 1.5 or below, a dividend yield of 1% or above, and a debt ratio of 30% or below, with results sorted by float market capitalisation ascending so that small caps surface first.

It also specifies the timing rules, which is unusual for a project at this level. Buys happen on a daily scan at the open, limited to 30% of capital per stock and four holdings maximum. Sells trigger when a holding reaches 30 days, or earlier when the 14-period RSI crosses above 70. The module offers a one-click simulated buy, live indicator monitoring, and export to PDF or Markdown.

The macro module is built on two well-known frameworks rather than invented ones: the 50 to 60 year Kondratieff cycle, the 3 to 5 year Merrill Lynch investment clock quadrants, and Chinese monetary, fiscal, industrial and property policy as an explicit third dimension. The macro data pulls GDP, industrial output, CPI, PPI, PMI, M2, retail sales, fixed asset investment, property investment and the surveyed urban unemployment rate from the National Bureau of Statistics at `data.stats.gov.cn`, then maps the result onto industry sectors and named candidate stocks.

It is worth being clear about what this produces. It is a structured research summary assembled by a language model from public statistics, with an explicit list of sectors it judges will benefit or suffer over the next one to two quarters. The repository description itself carries the warning that markets are risky, and nothing in the code turns a model opinion into a verified claim about a company.

Model routing without touching the code

One design decision deserves more attention than it gets: every model name in this project is read from the environment. A February 2026 note records the change, saying all hardcoded model names were moved to `.env`, that per-page model dropdowns were removed from the Dragon-Tiger List, institutional screening and research pages, and that the configuration screen gained a model input field.

The effect is that any OpenAI-compatible endpoint can be used without a code change. The `.env.example` template ships with `DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL` pointing at `https://api.deepseek.com/v1`, and `DEFAULT_MODEL_NAME` set to `deepseek-chat`, with comments listing `deepseek-reasoner`, `qwen-plus` and `gpt-4o` as other common choices.

There is a second route in, and the two coexist by design. Setting `ORCAROUTER_API_KEY` makes OrcaRouter the engine for every analysis module without configuring DeepSeek, with `ORCAROUTER_BASE_URL` and `ORCAROUTER_MODEL=orcarouter/auto` selecting automatic routing across DeepSeek, Qwen and Kimi. The README states that leaving the OrcaRouter key unset has no effect on the DeepSeek path.

The third integration is different in kind. `YDC_API_KEY` and `YDC_RESEARCH_EFFORT` configure You.com Research for the sector research feature, with effort levels from lite through standard and deep to exhaustive. That is a hosted search-and-reason service inside an otherwise local tool, which is worth noticing when you decide what leaves your machine.

A broker API, an email sender and a documented port mismatch

The project has a path from analysis to execution. `miniqmt_interface.py` implements a MiniQMT hook, the client interface used by Chinese brokers for programmatic trading, and `.env.example` gates it behind `MINIQMT_ENABLED=false` with an account ID, host and port. The README's notification block also covers SMTP for email alerts, with `SMTP_SERVER`, `SMTP_PORT`, credentials and a recipient, plus a DingTalk webhook URL and `WEBHOOK_TYPE=dingtalk` for chat alerts.

The scheduler side lives in `monitor_scheduler.py`, `monitor_manager.py`, `monitor_db.py` and `monitor_schedule_config.json`, which together implement scheduled price monitoring with database-backed state rather than a shell cron job.

Here is a contradiction worth knowing about. The README's environment block gives the MiniQMT port as 58080:

MINIQMT_ENABLED=false
MINIQMT_ACCOUNT_ID=
MINIQMT_HOST=127.0.0.1
MINIQMT_PORT=58080

The `.env.example` template gives 58610 for the same key. Both cannot be the broker's port. Whichever you copy will be wrong somewhere, so find out what your broker's MiniQMT client actually listens on before enabling this, and note that `MINIQMT_ENABLED` ships false, which is the safe default.

A second point about the release: the single tagged release is named `aiagents-stock1.0.1` and its tag string is a comma-separated list of Chinese keywords rather than a version. The release body links to a zip on GitHub's user attachments and tells you to download the latest version from the project homepage instead.

Two Dockerfiles, one aimed at users inside China

The repository ships two Dockerfiles, and the difference between them is the most useful signal about who this is for. The default `Dockerfile` pulls its base image from a Huawei Cloud registry mirror, rewrites `apt-get` to Aliyun Debian mirrors, downloads Node.js 18.20.4 as a tarball from the Taobao npm mirror, and points pip at the Tsinghua PyPI mirror.

The second file, named for the international source variant, is the same recipe pointed at upstream sources instead.

Between them they install more than you would expect in a Streamlit app: curl, tar, xz-utils, ca-certificates, two CJK font families, fontconfig and tzdata, with the timezone linked and the cache rebuilt. The fonts matter, because Chinese labels rendered without them become boxes. Node.js is installed and verified in the same layer, which tells you some dependency needs a JS runtime.

The compose file maps port 8503, mounts `./data` and a `.env` file into the container, sets the timezone to Asia/Shanghai, and defines a healthcheck that curls the Streamlit health endpoint every 30 seconds with a 60 second start period and three retries. That is a more careful compose file than most sample projects ship.

Setup on a bare machine is simpler than any of this suggests:

pip install -r requirements.txt
playwright install chromium

Playwright's Chromium is only needed for the stock screening path that logs into iwencai, and the README is explicit that you must sign in to the site in a browser first so the session can be reused. The twenty-line requirements file leans on akshare, pywencai, tushare, yfinance, openai, plotly, ta, peewee and jieba, which is the dependency footprint of a project that does market data, charting, technical indicators, persistence and Chinese word segmentation in one process.

Editorial conclusion

This is an unusual repository to read, because the README is a running incident log rather than a manual, and the data source section is more informative than any design document would be. The app covers an unusual amount of ground for a single Streamlit process: fund flow, a Dragon-Tiger List tracker, macro cycles, valuation screening, price alerts, report export and a MiniQMT execution hook, with every model name read from `.env`. Two things to settle before relying on it. There is no license file at the root and GitHub reports no license, so the default copyright rules apply and you have no grant to redistribute it. And the README's own advice is to run it locally rather than use the hosted demo, because the demo keys leak and the data sources reject heavy traffic. Start with `data_source_manager.py`, then the `.env.example` template, and check whether the Tencent and Sina endpoints it depends on still answer from your network before designing anything on top.

Frequently asked questions

Official sources

1. Issues
2. oficcejo/aiagents-stock on GitHub
3. README
4. Releases