Sparkles for Pi

Turn Pi into a finance research assistant for mainland China, Hong Kong, and US markets.

This is the Pi distribution of Sparkles. DeepSeek Harness users should install the sibling @dsh-sparkles/dsh-sparkles package, which reuses the same finance cores but owns separate DSH tools, agent/session lifecycle, browser presentation, and release maturity.

Ask about a stock or ETF in everyday language. Pi Sparkles brings current market data, price history, company filings, fundamentals, and financial calculations into the conversation, so you can spend less time moving between websites, spreadsheets, and one-off scripts.

What it gives you

• Current quotes and recent price history for supported CN, HK, and US sources.
• Trend, momentum, and volatility analysis with SMA, RSI, and ATR.
• SEC, CNINFO, and HKEXnews filing and disclosure research.
• Fundamental, valuation, portfolio-risk, scenario, event-study, and backtest calculations when the required data is available.
• Bounded CN/HK/US transaction-tape packet review, local possible-fill simulation, read-only broker evidence review, compound compliance checks, non-executable handoffs, and receipt reconciliation.
• Clear source, timestamp, currency, freshness, and data-limit context in answers.

Pi automatically looks up current evidence for questions about price, trend, buying now, or when to sell. You do not need to ask it to "use tools" first.

Quick start

pi install npm:@pi-sparkles/[email protected]

For most mainland China and Hong Kong quote/history research, and for SEC filing research, the only setup is a contact address used to identify requests to public data services:

AGENT_CONTACT="[email protected]" pi --finance-track cn

Choose cn, hk, or us. You can switch later with /cn-track, /hk-track, or /us-track inside Pi.

Then ask naturally:

• 分析一下科创50ETF的走势
• 588000 如果现在买，什么时候卖比较好？
• 分析腾讯 00700.HK 最近半年的趋势、动量和波动
• Summarize AAPL's latest SEC fundamentals and cite the evidence.
• Compare this portfolio with its benchmark and explain the largest risks.

Data sources

| Research area | Available sources | | --- | --- | | Mainland China | Eastmoney quotes and daily history; CNINFO disclosures; optional Tushare symbol, name, corporate-action, earnings, quote, and history data; SSE, SZSE, and BSE calendars and rules | | Hong Kong | Eastmoney quotes and daily history; HKEXnews disclosures; HKEX calendar and rules | | United States | SEC EDGAR and XBRL filings; optional Alpaca quotes, bars, news, corporate actions, and asset data; optional OpenFIGI identity mapping and Twelve Data company profiles; NYSE and Nasdaq calendars and rules | | Macroeconomics | Optional Federal Reserve Bank of St. Louis FRED series | | Day-trader and execution review | Exact bounded packets supplied by a caller-selected external market-data or broker capability; the package validates declared identity, rights, clocks, sequence, conditions, corrections, limits, and receipts without authenticating the provider | | Your own data | Portfolio files and supported structured imports for research and calculation |

Availability and history depth depend on the selected provider and your account's permissions. Public-web sources do not promise uptime, completeness, or real-time delivery.

Optional data-service setup

The package loads without provider credentials. Add only the services you want; you do not need every variable below.

| Variable | What it enables | | --- | --- | | AGENT_CONTACT | Identified access to supported public services, including Eastmoney, CNINFO, SEC, and HKEXnews. Use one email address everywhere. | | TUSHARE_TOKEN | Optional Tushare data for mainland China. Tushare permissions and points apply. | | ALPACA_API_KEY_ID, ALPACA_API_SECRET_KEY | Optional Alpaca US prices, bars, news, corporate actions, and assets. Feed permissions apply. | | OPENFIGI_API_KEY | Optional OpenFIGI identity mapping. | | TWELVE_DATA_API_KEY | Optional Twelve Data company profiles. | | FRED_API_KEY | Optional FRED macroeconomic series. |

Example:

AGENT_CONTACT="[email protected]" \
ALPACA_API_KEY_ID="..." \
ALPACA_API_SECRET_KEY="..." \
pi --finance-track us

Your credentials stay in your runtime environment. Sparkles for Pi does not add them to the package or save them in Pi settings. For a project-local installation, add --local to pi install.

Remember personal picks with Pi Durable

Sparkles can offer to remember watchlist picks across chats. Accept through conversation; no command-line opt-in is needed. Storage and polling are off until you accept. The default private ~/.pi-sparkles-watchlist reopens in later Pi chats. Saving picks does not start polling.

For example, tell Pi: "My picks are CN 600519 and CN 600000." Pi can offer to remember them; reply "Yes, remember these picks across chats" to opt in. Later, ask "Show my saved picks" or "Review my core watchlist once using Eastmoney A-share quotes." The model owns the conversation and interpretation.

Ask for a one-off review, or explicitly choose an interval and bounded count. CN reviews reuse the selected Eastmoney A-share quote tool and runtime AGENT_CONTACT. HK/US picks are saved; their review acquisition is track_partial. Checks run while Pi is open. Interrupted reads remain unknown without automatic refetch. Ask to inspect receipts, cancel a review, or disable persistence through conversation. Saved data is retained on disable.

Pi Durable 1.0.2 and its SDK dependencies are included and initialize only after opt-in. This feature is specific to the Pi package. DSH keeps its per-agent session watchlist and does not run these Durable tasks.

External day-trader and broker dependencies

Transaction-tape and broker-review tools require exact caller-supplied packets or receipts from an explicitly selected provider, gateway, export, or adapter. Futu OpenD, Alpaca, IBKR, their SDKs, credentials, login state, and equivalent provider components are external dependencies and are not included in this npm package. Results preserve the declared provider, entitlement, track, venue, clocks, limits, and unsupported claims; Sparkles never silently selects or falls back to another provider.

Sparkles for Pi is read-only research software: it cannot place, change, or cancel broker orders. It is not investment, legal, accounting, or tax advice. See CONFIGURATION.md for the complete source and configuration reference.

Version 0.1.13 · Pi package @pi-sparkles/pi-sparkles · tested with Pi 1.0.2