pi sparklesfinance kit

Manual · install

One package. One Pi entrypoint.

Version 0.1.5 is the cumulative T1-through-T6 ProductUseful release. Install the pinned npm identity, export only the adapters you will select, then ask Pi to inventory the safe path before any fetch.

Package@pi-sparkles/pi-sparkles@0.1.5
Plugins135 · one entrypoint
HostPi 0.83.0 or later
Secrets in the tarballNone

Operator sequence

Install, identify yourself, then inventory.

01

Install the all-in-one package

Version 0.1.5 is the published T1-through-T6 aggregate. It loads one Pi entrypoint and registers all 135 ProductUseful plugins. Pin the version; do not install an unpacked directory whose inventory differs from the release lock.

pi install npm:@pi-sparkles/pi-sparkles@0.1.5
02

Set the operator identity

AGENT_CONTACT is the one non-secret identity reused by every CN, HK, and US adapter and by the statusline. Export it in the environment that launches Pi. It grants no provider or market authority.

export AGENT_CONTACT="ops@example.com"
03

Add only the adapters you will select

Optional credentials stay in the same process environment. A missing provider is allowed. Never put values in a prompt, repository, receipt, or this website.

export TUSHARE_TOKEN="<secret-manager:tushare>"
export ALPACA_API_KEY_ID="<secret-manager:alpaca-key-id>"
export ALPACA_API_SECRET_KEY="<secret-manager:alpaca-secret>"
export OPENFIGI_API_KEY="<secret-manager:openfigi>"
export TWELVE_DATA_API_KEY="<secret-manager:twelve-data>"
export FRED_API_KEY="<secret-manager:fred>"
04

Launch Pi and inventory the path

Reload or restart Pi after changing configuration because plugins capture environment values when their factory initializes. Ask for the capability inventory before any fetch.

pi

Same-process environment

Configuration is captured at plugin init.

This repository and the published package do not load .env files. Use your shell, service manager, or a private loader, then start Pi from that environment. Restart Pi after changing values.

# Illustrative names only — supply your own private values
export AGENT_CONTACT="ops@example.com"

# Optional read-only adapters. Omit any you will not select.
export OPENFIGI_API_KEY="<secret-manager:openfigi>"
export TUSHARE_TOKEN="<secret-manager:tushare>"
export ALPACA_API_KEY_ID="<secret-manager:alpaca-key-id>"
export ALPACA_API_SECRET_KEY="<secret-manager:alpaca-secret>"
export TWELVE_DATA_API_KEY="<secret-manager:twelve-data>"
export FRED_API_KEY="<secret-manager:fred>"

# Launch Pi from the same private environment
pi --finance-track=cn
Do not paste secrets into Pi chat. Ask whether a variable name is configured. Never ask a tool to display the value. Eastmoney, CNINFO, HKEX, and SEC need no provider-specific secret; they reuse AGENT_CONTACT.

First request after install

Refuse implicit provider choice.

Try this in Pi
›

Show the Pi Sparkles finance capability inventory. Do not reveal environment values. Ask me to choose CN, US, or HK, then list only the configured read-only sources for that track. Do not fetch data or infer a provider.

Inside Pi, /finance-setup and /finance-track are the matching operator commands. See the command reference for the rest of the slash surface.

What the package contains

Names, checksums, and notices — not gateways.

  • One Pi entrypoint, an exact file allowlist, Apache-2.0 and third-party notices, and inner plus outer checksums.
  • CONFIGURATION.md lists environment-variable names and declared provider access. It never contains values.
  • pdfjs-dist is pinned so CN PDF CMap assets resolve at runtime. Pi host libraries remain required peers and are not bundled.
  • Futu OpenD, Alpaca, IBKR, their SDKs or gateways, credentials, login state, entitlements, and live certification stay outside the tarball.
  • There are no npm lifecycle scripts. Duplicate named registrations fail before they reach Pi.

Source checkout

Contributors build the same aggregate.

A later tier includes its ProductUseful dependencies. The published all-in-one selection is always T6, meaning T1 through T6 in ledger order. T5 remains available only to reproduce the prior release boundary.

bun run aggregate:build
pi --no-extensions -e ./dist/aggregate/t6 --list-models
# inspect names only
less dist/aggregate/t6/CONFIGURATION.md

Package maturity and tier maturity are different scales:

Package inventory

Draft → Designing → Implementing → Experimental

Experimental describes existing package behavior. It is not a delivery target or a permission to hide unknowns.

Role product

Queued → BlockerResolution → Building → Verifying → ProductUseful

Experimental describes existing package behavior. ProductUseful applies only to a whole role tier with a supported repeatable input path and a complete professional journey. Version 0.1.5 publishes T1 through T6 as ProductUseful.

Trust the artifact

Treat the extension as local application code.

  • A Pi extension runs with the user's full permissions. Treat the installed package as trusted local application code, not a sandbox.
  • Only supported, content-locked npm releases should be used. Verify registry integrity and the included SHA256SUMS against release-lock.json.
  • The package pins pdfjs-dist so the CN PDF path can resolve CMap assets at runtime. Pi host libraries stay as required peer ranges and are not bundled.
  • There are no npm lifecycle scripts. Packaging never reads credential values.
  • Report suspected vulnerabilities privately to the repository owner. Revoke any exposed credential before sending a redacted report.