pi-sparkles

Read-only finance evidence tools for two coding-agent hosts: Pi in the terminal and DeepSeek Harness (DSH) in the browser. Both distributions reuse the same Gleam functional cores while keeping host registration, session ownership, presentation, packaging, and release maturity separate.

The Pi and DSH distributions are independently ProductUseful T1–T6 releases covering the same 135 ledger components through separate host-native entrypoints. No component can place, route, cancel, replace, or otherwise mutate a paper or live order.

Install and start

Pi:

npm install --global @earendil-works/pi-coding-agent@1.4.0
pi install npm:@pi-sparkles/pi-sparkles@0.1.14
export AGENT_CONTACT="ops@example.com"
pi --finance-track cn

DeepSeek Harness:

dsh plugin --profile <name> add @dsh-sparkles/dsh-sparkles@latest
export AGENT_CONTACT="ops@example.com"
dsh --profile <name>

In either host, run /finance-setup and /finance-track before the first provider fetch. A missing adapter is allowed and never triggers fallback.

The seven packages excluded from the aggregate (hello, lifecycle, safety_gate, cn_setup, hk_setup, cn_fundamentals, hk_fundamentals) are development extras, not extra products.

Package-level Experimental labels are inventory. ProductUseful applies only to a whole role tier. Tiers are not a 6×3 track matrix. See PRODUCT_TIERS.md.

The DSH distribution mounts 131 global-safe shells plus per-agent counterparts for track status, swing workbench, portfolio, and watchlist. Its finance track status and vertically stacked OHLCV charts share DSH's browser shell.overlay. Drag the status bar to move the group; hide/show each chart separately. See dsh/README.md.

DSH also provides opt-in, session-owned saved picks and bounded recurring reviews through its native storage runner. See DSH recurring pick reviews.

Remember personal picks with Pi Durable

When you use a watchlist, Sparkles gives the LLM an option to offer: “Shall I remember these picks across chats?” Accept in conversation; no command-line opt-in is needed. Storage and checks stay off until you accept. The default private store is ~/.pi-sparkles-watchlist; accepted stores reopen with Pi.

Saving picks is separate from scheduling. You can ask for one review or choose an interval and bounded count of recurring reviews. CN checks reuse the explicit Eastmoney A-share source and its runtime AGENT_CONTACT requirement. HK/US picks are saved, but their scheduled checks are labelled track_partial. Checks run while Pi is open. Inspect results through conversation; failures and interrupted calls are unknown, with no automatic refetch or external alerts. See watchlist for controls and limits.

Try: “My picks are CN 600519 and CN 600000.” If Pi offers to remember them, reply “Yes, remember these picks across chats.” In another chat, ask to show the saved watchlist or review it once using Eastmoney A-share quotes. Pi Durable 1.0.2 is bundled lazily; DSH retains its per-agent session watchlist.

Docs

Develop

Requirements: Gleam and Bun, plus the host used by the lane being tested: either a hydrated Pi checkout or installed pi, and installed dsh for DSH runtime verification.

bun run tier:audit
bun run aggregate:build
pi --no-extensions -e ./dist/aggregate/t6 --list-models
bun run test:aggregate:pi

test:aggregate:pi loads the cumulative T1–T6 entrypoint once. Per-plugin and earlier-tier Pi-load targets are not part of verification. It uses PI_SOURCE_DIR when that checkout has its dependencies, defaults to /home/kaiwu/Documents/github/pi-mono in this workspace, and falls back to the installed Pi.

Focused diagnostics stay cheap; promotion is always a whole tier:

bun run build -- hello
bun run test:unit -- safety_gate
bun run tier:checkpoint -- T1
bun run test:acceptance -- swing

Opt-in live lanes are excluded from bun run test:

bun run test:live:tutor
AGENT_CONTACT="you@your-real-domain.com" bun run test:live:sec

Packaging: bun run tier:package -- T1, bun run aggregate:build (T6 means T1–T6; pass T5 only to reproduce the prior boundary), bun run npm:pack, bun run npm:release:verify. Details in NPM_RELEASE.md and PRODUCT_TIERS.md.

Hex still distributes Gleam source, not a loadable Pi plugin, and is not the user-facing product. pi_gleam is an unpublished 0.1.0 binding.

Runtime environment

Set variables in the environment that launches Pi or DSH. This repository does not load .env files. Restart the selected host after changes.

AGENT_CONTACT identifies the caller and grants no provider or market authority. A known exact CN code can use Eastmoney history without Tushare. Eastmoney, CNINFO, HKEX, and SEC reuse AGENT_CONTACT only. T6 reviews caller-supplied capability packets and receipts; it does not read broker credentials.

export AGENT_CONTACT="ops@example.com"
export TUSHARE_TOKEN="<secret-manager:tushare>"            # optional
export OPENFIGI_API_KEY="<secret-manager:openfigi>"        # optional
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>"
# Pi
pi --finance-track cn

# DSH (select the track with /cn-track after launch)
dsh --profile <name>

Generated CONFIGURATION.md lists names only. Per-plugin contracts live in each plugin README.

Layout

sparkles/
├── pi_gleam/          Gleam binding for Pi's extension API
├── finance/           77 reusable non-Pi libraries (no Pi imports)
├── plugins/           142 Gleam plugin packages; 135 are the T1–T6 ledger
├── dsh/               DeepSeek Harness adapter + bundle (parallel npm line)
├── scripts/           Bun task drivers
├── test/              binding, architecture, artifact, acceptance, workflow
├── tiers.json         exclusive proposal ownership and promotion state
└── dist/              generated, gitignored Pi and DSH artifacts

The root is not a Gleam package. Every finance/ and plugins/ package owns a gleam.toml, README, source, and tests. Root tasks discover packages by gleam.toml. All 135 ledger proposals are implemented; there is no README-only remainder.

Architecture rules: FUNCTIONAL_DESIGN.md. Plugin index: plugins/README.md. Binding surface: pi_gleam/README.md.

Tasks

PI_SPARKLES_TEST_JOBS=1..16 bounds unit-test workers (default 4). Publishing is never part of build or test.

Still open

The Pi and DSH finance products are shipped through independent release lanes. Remaining work is Hex source publication and further typed pi_gleam coverage — not missing role tiers.

• Hex name, consumer builder, and hex:check / hex:publish are unbuilt.
• pi_gleam typed wrappers still grow only when a plugin needs them; pi/raw covers the rest.
• Later calendars, official CN/HK filing-linked accounting depth, production entitlements, and redistribution stay explicitly unknown.

Unknown facts stay unknown. Providers, SDKs, gateways, credentials, login state, and live certification stay caller-owned.