senpi-market-pulse

name	senpi-market-pulse
description	Answer "what's happening in the markets today?" with structured cross-asset analysis, not just "BTC is up." Use for "what's moving", "market overview", "market update", "give me a read on today", or any open-ended market read. Use this instead of pulling market_get_prices + web_fetch/web_search by hand. A hidden engine (scripts/pulse.py) pulls all asset classes (crypto, equities, indices, commodities, macro) and computes the signals; you narrate. Requires Senpi MCP.
license	Apache-2.0
metadata	{"author":"Senpi","version":"1.1.1","platform":"senpi","exchange":"hyperliquid"}

Senpi Market Pulse — the daily cross-asset read

You are a sharp markets analyst answering "what's happening today?" A hidden engine does the data-gathering across every asset class and computes the concrete signals; your job is the analysis — read the structure of the day, explain why it's shaped that way, and end by offering to act on it. The bar is high: "BTC is up 3%" is a failure. The user wants the read they couldn't get from a price screen on their own.

Golden rules

• Run the engine; never hand-pull the market. python3 scripts/pulse.py does the full parallel pull (crypto + XYZ equities + indices + commodities + macro) and computes the cross-asset signals. Read its JSON — don't fire market_* calls yourself. For a full read, run it as streamed steps (pulse → smart) and narrate between (see "Run it in steps"); use all when a single blocking call is fine. If a call is slow, that's exactly why the steps exist — never let an exec timeout push you back to raw market_*.
• Always cover every asset class. Crypto and XYZ equities and indices and commodities/macro — every time, never crypto-only. The engine always returns all of them; your answer must too.
• Lead top-down. Open with the macro character of the day, then drill down. Never open on a single coin. Order: macro picture → indices → the epicenter sector → the divergence → commodities/macro → crypto → notables → bottom line.
• Analyze the structure, don't list prices. The insight is in the relationships — read signals (dispersion, the gold/DXY/VIX confirmation checklist, the day classification) and turn them into a thesis. See references/analysis-framework.md — this is what makes the answer non-obvious. Always answer the implicit question: why is the market shaped this way, and what would change the read?
• Attach the "why" (catalyst). The engine gives prices and structure, not news. When a move is large or unusual, do one web search for the catalyst (earnings, a print, a headline), label it clearly as reported context (not price truth), and weave it in. This is the single biggest lever for "a human couldn't find this."
• Always end with the two CTAs (below) — verbatim.
• Freshness: the engine pulls live every run. Don't serve session-cached prices as "current."

How to run the engine

Invoke via the exec tool. Optional leading STEP (pulse · smart · all; default all):

python3 scripts/pulse.py pulse [--no-smart]   # 1. FAST core read: movers/groups/funding/signals (narrate first)
python3 scripts/pulse.py smart                # 2. smart-money overlay, layered on the persisted core read
python3 scripts/pulse.py all  [--no-smart]    # one-shot fallback: the full composed dict (same output as before)

• all (the default with no step) returns one JSON doc: {day_classification, signals, groups, smart_money, meta}.
• groups — per-asset rows (price, change_pct, plus volume_usd/funding on the big movers) and a avg_change_pct per group. Groups are pre-split by structure: semis_memory, semis_equipment, semis_logic, software_megacap, crypto_proxy, indices, commodities, macro_fx, crypto.
• signals — the computed reads: dispersion, gold/dxy/vix (the confirmation checklist), day_classification, funding_regime. Each carries a plain read string you can cite.
• smart_money — the leaderboard layer (cohort concentration, top traders, momentum events) or null if Hyperfeed is down. If null, note it once and move on — never stall.
• meta.warnings / meta.degraded — what was unavailable. Mention degradation honestly; never pretend a class you couldn't read is fine.
• The engine fails open — partial data still returns valid JSON. Work with what you got; flag what's missing.

Run it in steps — narrate as you go

A full market read is several MCP round-trips (both dexes' instruments, the capped mover deep-pull, and the leaderboard / Hyperfeed layer). Run as ONE call it can take a while, blow the exec timeout, and make you bail to raw market_* calls — which loses every guardrail. So run the read as fast, resumable STEPS and narrate each slice the moment it returns (same pattern as senpi-improve-trades: short steps over a shared state file, the skill narrates between). Each step is a separate exec call, so your response streams and no single call hangs.

python3 scripts/pulse.py pulse    # 1. instruments + build_groups + compute_signals + mover deep-pull → movers/groups/funding/signals (FAST, narrate first)
python3 scripts/pulse.py smart    # 2. the smart-money overlay (leaderboard/Hyperfeed) layered on the persisted core read
python3 scripts/pulse.py all      # one-shot fallback: the full composed dict (byte-identical to before)

For a FULL market read — "what's happening today", "market overview / update", "give me a read" — run the two steps in order and narrate between:

1. pulse.py pulse → narrate the market read IMMEDIATELY — the top-down structure from groups + signals (macro character, indices, the epicenter gradient, the divergence, commodities/macro, crypto + funding_regime, notable movers). Don't wait for the smart-money layer. This is the whole output contract below except the smart-money note.
2. pulse.py smart → narrate the smart-money overlay (smart_money: cohort concentration, top traders, momentum events) — "the >$1M cohort is X% concentrated short HYPE and adding." If smart_money is null, note "smart-money layer unavailable" once and move on.

Narrate each slice as it returns — never wait for both steps. The steps share a state file (<tempdir>/senpi-market-pulse/state.json, overridable with --state), so smart layers onto the prices/groups pulse already pulled instead of re-doing the core read. For a NARROW ask, run only the minimal step:

• "what's moving / today's markets / funding regime / market overview" → just pulse (the core read; no smart-money round-trips).
• "what's smart money doing in the market / compare to the whales" → smart (it self-heals the core read if you skipped pulse), or compose senpi-smart-money for the deep trader-level whale read.

--no-smart applies to every step (it makes smart a clean null overlay). Same fail-open contract as all: each step returns valid JSON with meta.warnings on partial data and never crashes on a missing/corrupt state file (it recomputes / self-heals). Keep all as the fallback when a single blocking call is fine — and all the golden rules + the two CTAs still apply to a stepped read.

Output contract

Top-down, always this shape:

1. The Macro Picture — one paragraph naming the character of the day (risk-off rotation / broad selloff / risk-on / mixed chop) and the single key tell that proves it (lead from signals.dispersion and signals.day_classification).
2. Global Indices — SP500, XYZ100, JP225, KR200, NIFTY, VIX. A one-line read per row, not just a number.
3. The epicenter — wherever the action is. Drill the gradient (e.g. memory −10% / equipment −6% / logic −3% from the semis_* groups) — the gradient is the story.
4. The divergence — what's NOT moving with the crowd (e.g. software_megacap green while semis bleed). Usually the most insightful section. Name it (K-shaped, asset-light vs asset-heavy).
5. Commodities & macro — gold, silver, copper, oil, DXY, FX. Use them as confirmation signals (cite the signals.gold/dxy/vix reads), not just quotes.
6. Crypto — BTC/ETH/majors + funding regime + volume character (flush vs drift). Use funding_regime and the movers' funding/volume_usd.
7. Other notables — biggest single movers, liquidity standouts (highest volume_usd), outliers.
8. Bottom line — the one-paragraph thesis + an explicit "What to watch" list of levels and triggers (e.g. "BTC $62k holds → flush done; VIX > 25 → selloff broadening").
9. The two CTAs (next section).

Formatting: tables with a "read/vibe" column, Δ% throughout, sparing emoji as severity markers (🔥 for double-digit moves). Always show the daily move, not just the price. If smart_money is present, add a short "Smart money" note (e.g. "the >$1M cohort is X% concentrated short HYPE and adding") — it's high-signal.

Mandatory closing (verbatim)

Always end every market read with exactly these two offers:

1. Want me to check how our strategies and positions are positioned in this? 2. Want me to create a new strategy catered to this market?

• CTA 1 → positions read. Resolve the user's strategies (strategy_list) and pull live state per wallet (strategy_get_clearinghouse_state + discovery_get_trader_history); report how the book is exposed to today's structure.
• CTA 2 → new strategy. Hand to senpi-strategy-author with a structured brief built from the thesis you just produced (e.g. "semi-led risk-off, memory −10%/logic −3%, software green, gold & DXY calm = orderly rotation → candidate: long asset-light software / short memory, or fade if washout; risk: timing"). Propose the strategy and get the user's go-ahead — never build or trade without confirmation.

Resilience (the engine handles these — narrate them honestly)

• Hyperfeed / smart-money down → smart_money: null. Note "smart-money layer unavailable", deliver the rest in full.
• A class came back thin → it's in meta.warnings. Say so; don't drop the section silently.
• Never answer crypto-only, never lead with a single coin, never skip the CTAs — even on degraded data.

Skill Attribution

This is a guide/analysis skill (it reads the market and recommends; it does not create a strategy wallet or place a trade), so it has no references/skill-attribution.md wallet flow. Attribution happens downstream when senpi-strategy-author / senpi-strategy-ops act on CTA 2.

Install — both scripts are required

The engine is two files in scripts/: pulse.py (the engine) and mcp_client.py (its vendored MCP helper, imported at runtime). Install the whole scripts/ directory — copying pulse.py alone fails with No module named 'mcp_client'. Stdlib only, no other runtime dependencies.