| compatibility | Python 3.8+, standard library only. No network. No third-party packages. |
| description | Tracks institutional, foreign, sponsor/director, and fund-manager moves for a DSE stock from public shareholding disclosures and returns an accumulation/distribution score, rating, and reasoning. Use when the user asks about smart money, institutional buying/selling, foreign inflow/outflow, sponsor or director (insider) activity, shareholding changes, which funds hold a stock, or whether big players are accumulating a Dhaka Stock Exchange ticker. Public data only. |
| license | Apache-2.0 |
| metadata | {"author":"stock-buddy","github-path":"skills/smart-money-flow","github-pinned":"main","github-ref":"refs/heads/main","github-repo":"https://github.com/kuntal-r-d/my-skills","github-tree-sha":"5f565c3ee36ff3a3ac8f496e50d78b39611bd383","mode":["momentum","investment"],"prd_refs":["PRD-002:REQ-021","PRD-002:REQ-106","PRD-001:REQ-051"],"version":"0.1.0"} |
| name | smart-money-flow |
Smart Money Flow
When to use
Activate when a user asks who is moving a DSE stock: "is smart money accumulating GP?",
"any foreign inflow into BEXIMCO?", "did sponsors sell?", "which funds hold this?",
"institutional buying or selling?". This is the flow leg of the dual-mode signal — feed
its score into signal-synthesizer, or pair it with sentiment-news.
What it does
Implements the Smart Money Agent and Fund Manager Tracker (PRD-002 REQ-021/106) using
public disclosure data only:
- Shareholding deltas — month-over-month change in sponsor / govt / institution /
foreign / public percentages. Moves >= 2pp (institution, foreign, sponsor) are
significant.
- Directional rules:
- Foreign inflow is positive (confidence/governance signal); outflow negative.
- Institutional accumulation positive; distribution negative.
- Sponsor/director selling is a RED FLAG (strong negative); buying positive.
- Fund manager featuring — from the optional
funds array, funds raising their
weight are positive, scaled by track_record_3y; funds cutting weight are negative.
Output is a Thinking Card (see suite README) with the accumulation/distribution score.
Guardrails (critical, PRD-002 REQ-021)
- Uses only the public disclosure data present in the input.
- Never fabricates or infers a private/non-public "broker book". Missing data is
reported in
reasoning and lowers confidence.
- Monthly cadence is stale by nature -> confidence is capped at 0.7 and the flag
monthly_disclosure_lag is always present.
- No
shareholding -> score 0, low confidence, flag no_disclosure_data, and the
reasoning explains the data is unavailable (nothing is invented).
How to run
python3 scripts/analyze.py --input data.json --pretty
cat data.json | python3 scripts/analyze.py
Reads shareholding (monthly array) and optional funds. Returns score (-1..+1),
confidence (0..1, capped 0.7), rating (accumulation / neutral / distribution),
key_metrics (latest deltas, named funds featuring) and dated reasoning.
Try it now with the shared fixture:
python3 scripts/analyze.py --input ../_fixtures/sample_input.json --pretty
Interpreting output
rating accumulation with foreign + institutional inflow and no sponsor selling is
the strongest constructive read.- A
sponsor_director_selling flag is the single most important warning — it dominates
the score even amid other inflow.
flags carry confidence penalties (monthly_disclosure_lag, single_month_no_trend,
no_disclosure_data) — never silently dropped.
Notes
The rules, the 2pp threshold, the public-data-only guardrail, and DSE monthly
shareholding disclosure context are documented in
references/METHODOLOGY.md. Output is educational analysis
only, never financial advice.
