sparklesfinance kit

Manual · install

One toolkit. Two host-native bundles.

Choose Pi or DeepSeek Harness, install that host's current all-in-one package, configure only the adapters you will select, then ask the agent to inventory the safe path before any fetch.

Pi package@pi-sparkles/pi-sparkles@latest
DSH package@dsh-sparkles/dsh-sparkles@latest
Tested Pi hostPi 1.0.2
Required DSH hostExactly 0.2.0-rc.2
Product inventory135 · T1–T6
Release lanesPi published · DSH published
Current releasesPi 0.1.13 · DSH 0.1.15
Secrets in the tarballNone

Operator sequence

Install, identify yourself, then inventory.

01

Install the all-in-one package

The npm latest channel is the published T1-through-T6 Pi aggregate. It loads one Pi entrypoint and registers all 135 ProductUseful plugins. Use the release channel rather than an unpacked directory whose inventory may differ from the release lock.

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

Set the operator identity

AGENT_CONTACT is the one non-secret identity reused by every CN, HK, and US adapter. 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.

The Pi package does 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 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 with Sparkles
›

Show the 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.

/finance-setup and /finance-track are registered in both host lanes. See the command reference for host-specific launch flags and status UI.

What the package contains

Names, checksums, and notices — not gateways.

  • One host entrypoint per distribution, 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. Host libraries remain required peers and are not bundled into either distribution.
  • 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 the selected host.

Source checkout

Contributors build each host lane explicitly.

A later tier includes its ProductUseful dependencies. The release aggregate 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
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. The shared ledger marks T1 through T6 ProductUseful; publishing remains host-specific.

Trust the artifact

Treat the extension as local application code.

  • A Pi extension or DSH server plugin runs as trusted local application code with host-process permissions. It is not the agent's command sandbox.
  • Only supported, content-locked npm releases should be used. Verify registry integrity and the included SHA256SUMS against release-lock.json.
  • Each host package declares its own exact runtime files and host peers. The shared finance core does not make Pi and DSH host APIs interchangeable.
  • 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.