nepse-trading-skill 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +50 -0
- package/README.md +229 -2
- package/install.sh +70 -0
- package/nepse_common/__init__.py +1 -0
- package/nepse_common/costs.py +107 -0
- package/nepse_common/data.py +277 -0
- package/nepse_common/indicators.py +80 -0
- package/nepse_common/report.py +37 -0
- package/package.json +40 -4
- package/skills/nepse-corporate-actions-calculator/SKILL.md +94 -0
- package/skills/nepse-corporate-actions-calculator/references/corporate_actions.md +81 -0
- package/skills/nepse-corporate-actions-calculator/scripts/corporate_actions.py +79 -0
- package/skills/nepse-cost-tax-calculator/SKILL.md +89 -0
- package/skills/nepse-cost-tax-calculator/references/costs_and_tax.md +102 -0
- package/skills/nepse-cost-tax-calculator/scripts/cost_calculator.py +59 -0
- package/skills/nepse-daily-analyst/SKILL.md +137 -0
- package/skills/nepse-daily-analyst/scripts/daily_analysis.py +244 -0
- package/skills/nepse-dividend-screener/SKILL.md +93 -0
- package/skills/nepse-dividend-screener/references/dividend_guide.md +83 -0
- package/skills/nepse-dividend-screener/scripts/dividend_screener.py +86 -0
- package/skills/nepse-fundamental-analyst/SKILL.md +105 -0
- package/skills/nepse-fundamental-analyst/references/sector_frameworks.md +102 -0
- package/skills/nepse-fundamental-analyst/references/valuation_guide.md +76 -0
- package/skills/nepse-fundamental-analyst/scripts/valuation.py +121 -0
- package/skills/nepse-ipo-analyzer/SKILL.md +96 -0
- package/skills/nepse-ipo-analyzer/references/ipo_guide.md +95 -0
- package/skills/nepse-ipo-analyzer/scripts/ipo_calendar.py +74 -0
- package/skills/nepse-liquidity-macro-monitor/SKILL.md +91 -0
- package/skills/nepse-liquidity-macro-monitor/references/liquidity_framework.md +91 -0
- package/skills/nepse-liquidity-macro-monitor/references/policy_calendar.md +70 -0
- package/skills/nepse-market-breadth-analyzer/SKILL.md +91 -0
- package/skills/nepse-market-breadth-analyzer/references/breadth_methodology.md +52 -0
- package/skills/nepse-market-breadth-analyzer/scripts/breadth.py +151 -0
- package/skills/nepse-market-regime-detector/SKILL.md +103 -0
- package/skills/nepse-market-regime-detector/references/nepse_cycle_history.md +52 -0
- package/skills/nepse-market-regime-detector/references/regime_methodology.md +65 -0
- package/skills/nepse-market-regime-detector/scripts/market_regime.py +130 -0
- package/skills/nepse-market-rules/SKILL.md +82 -0
- package/skills/nepse-market-rules/references/glossary.md +40 -0
- package/skills/nepse-market-rules/references/trading_rules.md +98 -0
- package/skills/nepse-market-rules/scripts/price_bands.py +101 -0
- package/skills/nepse-momentum-screener/SKILL.md +110 -0
- package/skills/nepse-momentum-screener/references/screen_methodology.md +78 -0
- package/skills/nepse-momentum-screener/scripts/screen_momentum.py +130 -0
- package/skills/nepse-news-sentiment-analyst/SKILL.md +97 -0
- package/skills/nepse-news-sentiment-analyst/references/news_framework.md +100 -0
- package/skills/nepse-news-sentiment-analyst/scripts/news_sentiment.py +157 -0
- package/skills/nepse-portfolio-manager/SKILL.md +98 -0
- package/skills/nepse-portfolio-manager/references/portfolio_framework.md +87 -0
- package/skills/nepse-portfolio-manager/scripts/portfolio_review.py +124 -0
- package/skills/nepse-position-sizer/SKILL.md +107 -0
- package/skills/nepse-position-sizer/references/sizing_for_nepse.md +90 -0
- package/skills/nepse-position-sizer/scripts/position_sizer.py +138 -0
- package/skills/nepse-pre-trade-gate/SKILL.md +105 -0
- package/skills/nepse-pre-trade-gate/references/gate_checks.md +80 -0
- package/skills/nepse-pre-trade-gate/scripts/pre_trade_gate.py +127 -0
- package/skills/nepse-sector-analyst/SKILL.md +87 -0
- package/skills/nepse-sector-analyst/references/nepse_sectors.md +78 -0
- package/skills/nepse-sector-analyst/scripts/sector_rotation.py +85 -0
- package/skills/nepse-technical-analyst/SKILL.md +96 -0
- package/skills/nepse-technical-analyst/assets/analysis_template.md +39 -0
- package/skills/nepse-technical-analyst/references/technical_framework.md +75 -0
- package/skills/nepse-technical-analyst/scripts/technical_snapshot.py +95 -0
- package/skills/nepse-trade-journal/SKILL.md +103 -0
- package/skills/nepse-trade-journal/references/review_guide.md +80 -0
- package/skills/nepse-trade-journal/scripts/journal.py +135 -0
- package/workflows/README.md +89 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Agent skills for the Nepal Stock Exchange (NEPSE), for Claude Code, Codex, Gemini CLI and other Agent Skills clients. `CLAUDE.md` and `GEMINI.md` point here. See `README.md` for the catalogue and `workflows/README.md` for multi-skill workflows.
|
|
4
|
+
|
|
5
|
+
## Rules for working in this repository
|
|
6
|
+
|
|
7
|
+
Scripts run from `~/.nepse-skills` (the link `./install.sh` creates). Run `./install.sh` once before using the skills, even inside this repository.
|
|
8
|
+
|
|
9
|
+
0. **Every analysis starts with `nepse-daily-analyst`** (`~/.nepse-skills/skills/nepse-daily-analyst/scripts/daily_analysis.py --account-size <capital>`). An analysis must always include: market regime and breadth, news and sentiment, sector, the candidate's trigger status, pending events, size for the user's capital, and both timing sections (when to buy, when to sell). Ask for the capital if it is not known.
|
|
10
|
+
|
|
11
|
+
1. **Never answer NEPSE rules, tax or commission from memory.** They changed several times in 2026. Read `~/.nepse-skills/skills/nepse-market-rules/references/trading_rules.md` and `~/.nepse-skills/skills/nepse-cost-tax-calculator/references/costs_and_tax.md`, and search the web for anything newer than their "verified" date when a decision depends on it.
|
|
12
|
+
2. **Run the script, then interpret.** Numbers come from scripts; judgment comes from the references. Do not estimate what a script can compute.
|
|
13
|
+
3. **Every analysis ends with what was not checked** and the disclaimer: unofficial data, educational, not investment advice.
|
|
14
|
+
4. **Never place, simulate or promise an order.** The human trades in TMS.
|
|
15
|
+
5. **Holdings and the journal are private.** They live in `state/` (git-ignored). Do not commit them or send them to any outside service.
|
|
16
|
+
6. **Net numbers only.** Any profit, target or reward-to-risk shown to the user includes charges and capital gains tax.
|
|
17
|
+
|
|
18
|
+
## Structure
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
nepse_common/ data.py (all URLs and parsing), indicators.py, costs.py (all rates), report.py
|
|
22
|
+
skills/<name>/ SKILL.md (frontmatter name = folder name), references/, scripts/, assets/
|
|
23
|
+
tests/ offline pytest suite
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Scripts add the repository root to `sys.path` and import `nepse_common`. They use the standard library only.
|
|
27
|
+
|
|
28
|
+
## Conventions for a new or changed skill
|
|
29
|
+
|
|
30
|
+
- `SKILL.md`: YAML frontmatter with `name` and a `description` that says when to trigger; then Overview, When to Use, Prerequisites, Workflow (numbered steps with commands), Output, Key Principles, Resources.
|
|
31
|
+
- Scripts: `argparse`, a pure function for the calculation (testable without network), `write_reports()` for output, `--output-dir` optional.
|
|
32
|
+
- Any calculation that touches money or a buy/sell decision gets a test in `tests/test_skills.py`.
|
|
33
|
+
- A rate or rule lives in one place: `nepse_common/costs.py` or `~/.nepse-skills/skills/nepse-market-rules/scripts/price_bands.py`. References cite the source and the date checked.
|
|
34
|
+
- Data access goes through `nepse_common/data.py` only.
|
|
35
|
+
|
|
36
|
+
## Commands
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
python3 -m pytest tests -q
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
python3 ~/.nepse-skills/skills/nepse-market-regime-detector/scripts/market_regime.py
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Known limits
|
|
47
|
+
|
|
48
|
+
- Data feeds are unofficial (Merolagani, ShareHub) and may break. Fix in `nepse_common/data.py`.
|
|
49
|
+
- No fundamentals feed, no floorsheet, no holiday calendar.
|
|
50
|
+
- The last daily bar is partial during market hours (11:00 to 15:00 Nepal time, Monday to Friday).
|
package/README.md
CHANGED
|
@@ -1,3 +1,230 @@
|
|
|
1
|
-
#
|
|
1
|
+
# nepse-trading-skill: NEPSE trading skills for AI agents
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Eighteen ready-made skills that teach Claude Code, Codex, Gemini CLI and other AI coding agents how to analyse and trade the **Nepal Stock Exchange (NEPSE)**. Ask in plain words ("which share should I watch today?", "analyse NABIL", "how many kitta can I buy with Rs 30,000?") and the agent runs the right calculation on live NEPSE data, then explains the result.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npx nepse-trading-skill
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
One command installs all eighteen skills for every supported agent. Restart the agent and start asking.
|
|
10
|
+
|
|
11
|
+
## What you get
|
|
12
|
+
|
|
13
|
+
- **A full daily analysis in one command**: market regime and exposure ceiling, market breadth, news and sentiment, sector rotation, a momentum screen, and for each candidate its trigger price, stop, target and size for your own capital, plus when to buy and when to sell.
|
|
14
|
+
- **NEPSE's real rules built in**: 15% daily price limit, index circuit breakers at 5% and 8%, T+2 settlement, lots of 10 kitta, no short selling, Monday to Friday trading since April 2026.
|
|
15
|
+
- **Real costs in every number**: broker commission slabs, SEBON fee, DP charge and capital gains tax (5% up to 365 days, 3.75% after), so every profit, target and break-even is net.
|
|
16
|
+
- **Risk control**: a position sizer that respects liquidity and concentration, and a pre-trade gate that returns PASS, WARN or BLOCK before you place an order in TMS.
|
|
17
|
+
- **Research helpers**: technical snapshot, valuation from quarterly reports (banks, hydropower, insurance), dividend and book-closure screen, bonus and right share calculator, IPO calendar, liquidity and NRB policy checklist, portfolio review with a tax clock, and a trade journal that scores your results in R.
|
|
18
|
+
- **No API key, no paid data.** Python 3.9+ standard library only, using public NEPSE data feeds (Merolagani, ShareHub) and news from ShareSansar, Kathmandu Post and OnlineKhabar.
|
|
19
|
+
|
|
20
|
+
## Supported agents
|
|
21
|
+
|
|
22
|
+
| Agent | Where the skills are linked |
|
|
23
|
+
|---|---|
|
|
24
|
+
| Claude Code | `~/.claude/skills` |
|
|
25
|
+
| OpenAI Codex CLI | `~/.agents/skills` |
|
|
26
|
+
| Google Gemini CLI | `~/.agents/skills` |
|
|
27
|
+
| Other Agent Skills clients (Cursor, GitHub Copilot, OpenCode and others) | `~/.agents/skills` or `~/.claude/skills`, depending on the client |
|
|
28
|
+
|
|
29
|
+
Requires macOS or Linux and Python 3.9 or newer. `npx nepse-trading-skill` copies the package to `~/.nepse-skills` and links each skill into the folders above. Run it again to update. `npx nepse-trading-skill --uninstall` removes the links and keeps `~/.nepse-skills/state` (your journal and holdings).
|
|
30
|
+
|
|
31
|
+
## Example questions
|
|
32
|
+
|
|
33
|
+
- "Run today's NEPSE analysis for Rs 30,000"
|
|
34
|
+
- "Is NEPSE in an uptrend? How much should I be invested?"
|
|
35
|
+
- "Which sectors are leading?"
|
|
36
|
+
- "Find breakout candidates in hydropower"
|
|
37
|
+
- "Analyse NTC. I bought 30 kitta at 943.90: when should I sell?"
|
|
38
|
+
- "I bought 1,000 at 450 and want to sell at 560 after 200 days. Net profit after tax?"
|
|
39
|
+
- "What will the price be after a 15% bonus?"
|
|
40
|
+
- "Which IPOs are open?"
|
|
41
|
+
- "Review my portfolio" (paste your MeroShare holdings)
|
|
42
|
+
|
|
43
|
+
> Educational analysis, not investment advice. Data is unofficial and can be delayed or wrong. Rules and tax rates were verified on 13 November 2026 and change often: confirm with your broker, NEPSE or SEBON before trading. The agent never places orders; you trade in TMS.
|
|
44
|
+
|
|
45
|
+
Modelled on [tradermonty/claude-trading-skills](https://github.com/tradermonty/claude-trading-skills) (same layout: `SKILL.md`, `references/`, `scripts/`, JSON and Markdown reports), rebuilt for NEPSE.
|
|
46
|
+
|
|
47
|
+
## Skills
|
|
48
|
+
|
|
49
|
+
### Start here
|
|
50
|
+
|
|
51
|
+
| Skill | What it does | Script |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| `nepse-daily-analyst` | One command: market, news sentiment, sectors, candidates sized for your capital, trigger status, when to buy and when to sell | `daily_analysis.py` |
|
|
54
|
+
|
|
55
|
+
### Market rules and money
|
|
56
|
+
|
|
57
|
+
| Skill | What it does | Script |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| `nepse-market-rules` | Trading days and sessions, 15% limit, index breakers, order bands, settlement, lots, new-listing ranges; today's price bands | `price_bands.py` |
|
|
60
|
+
| `nepse-cost-tax-calculator` | Commission slabs, SEBON fee, DP charge, capital gains tax; buy cost, sell proceeds, round trip, break-even | `cost_calculator.py` |
|
|
61
|
+
| `nepse-corporate-actions-calculator` | Adjusted price, new quantity, tax and cost after bonus, right or cash dividend | `corporate_actions.py` |
|
|
62
|
+
|
|
63
|
+
### Market direction
|
|
64
|
+
|
|
65
|
+
| Skill | What it does | Script |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| `nepse-market-regime-detector` | Index regime from trend, distribution days and follow-through days; exposure ceiling | `market_regime.py` |
|
|
68
|
+
| `nepse-market-breadth-analyzer` | 0-100 participation score from the live tape; share of stocks above their averages | `breadth.py` |
|
|
69
|
+
| `nepse-sector-analyst` | Ranks the 13 sub-indices by strength against NEPSE; rotation phase | `sector_rotation.py` |
|
|
70
|
+
| `nepse-news-sentiment-analyst` | Headlines and NEPSE notices scored, plus tape mood; market and per-stock news verdict | `news_sentiment.py` |
|
|
71
|
+
| `nepse-liquidity-macro-monitor` | Interest rates, system liquidity, NRB policy, share-loan rules; tailwind or headwind scorecard | research workflow, no script |
|
|
72
|
+
|
|
73
|
+
### Stock selection
|
|
74
|
+
|
|
75
|
+
| Skill | What it does | Script |
|
|
76
|
+
|---|---|---|
|
|
77
|
+
| `nepse-momentum-screener` | Stage 2 leaders in tight bases: trend template, RS rank, tightness, volume dry-up, pivot | `screen_momentum.py` |
|
|
78
|
+
| `nepse-technical-analyst` | Trend stage, averages, RSI, MACD, ATR, levels; scenario-based analysis | `technical_snapshot.py` |
|
|
79
|
+
| `nepse-fundamental-analyst` | PE, PBV, ROE, earnings yield, Graham number; bank, hydropower, insurance checklists | `valuation.py` |
|
|
80
|
+
| `nepse-dividend-screener` | Cash yield on price, bonus habit, consistency, next book closure | `dividend_screener.py` |
|
|
81
|
+
| `nepse-ipo-analyzer` | Open and upcoming offerings; application, allotment, listing range, listing-day plan | `ipo_calendar.py` |
|
|
82
|
+
|
|
83
|
+
### Risk and review
|
|
84
|
+
|
|
85
|
+
| Skill | What it does | Script |
|
|
86
|
+
|---|---|---|
|
|
87
|
+
| `nepse-position-sizer` | Kitta to buy from risk, stop, charges, liquidity and concentration limits; ATR and half-Kelly modes | `position_sizer.py` |
|
|
88
|
+
| `nepse-pre-trade-gate` | PASS / WARN / BLOCK on a planned buy: risk, size, reward, liquidity, chasing, regime, book closure | `pre_trade_gate.py` |
|
|
89
|
+
| `nepse-portfolio-manager` | Holdings CSV to net value, concentration, losers, tax clock | `portfolio_review.py` |
|
|
90
|
+
| `nepse-trade-journal` | Plan at entry, result at exit in R after charges and tax, statistics by setup | `journal.py` |
|
|
91
|
+
|
|
92
|
+
## Quick start
|
|
93
|
+
|
|
94
|
+
Requirements: Python 3.9 or newer and the install step below. Nothing else to install for the scripts; `pytest` for the tests.
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
python3 ~/.nepse-skills/skills/nepse-daily-analyst/scripts/daily_analysis.py --account-size 1000000 --output-dir reports/
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
python3 ~/.nepse-skills/skills/nepse-market-regime-detector/scripts/market_regime.py
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
python3 ~/.nepse-skills/skills/nepse-market-breadth-analyzer/scripts/breadth.py
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
python3 ~/.nepse-skills/skills/nepse-sector-analyst/scripts/sector_rotation.py
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
python3 ~/.nepse-skills/skills/nepse-momentum-screener/scripts/screen_momentum.py --top 100
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
python3 ~/.nepse-skills/skills/nepse-position-sizer/scripts/position_sizer.py --account-size 1000000 --symbol NABIL --atr-multiplier 2.5
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
python3 ~/.nepse-skills/skills/nepse-cost-tax-calculator/scripts/cost_calculator.py roundtrip --price 450 --sell-price 560 --qty 1000 --holding-days 200
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Every script prints Markdown and, with `--output-dir reports/`, saves `<name>_<timestamp>.json` and `.md`.
|
|
125
|
+
|
|
126
|
+
## Install for Claude Code, Codex, Gemini CLI and others
|
|
127
|
+
|
|
128
|
+
The skills follow the open Agent Skills format (a folder with a `SKILL.md`). One script links them where each agent looks:
|
|
129
|
+
|
|
130
|
+
| Agent | Reads skills from |
|
|
131
|
+
|---|---|
|
|
132
|
+
| Claude Code | `~/.claude/skills` |
|
|
133
|
+
| Codex CLI | `~/.agents/skills` |
|
|
134
|
+
| Gemini CLI | `~/.agents/skills` |
|
|
135
|
+
| Other Agent Skills clients (Cursor, GitHub Copilot, OpenCode and others) | `~/.agents/skills` or `~/.claude/skills`, depending on the client |
|
|
136
|
+
|
|
137
|
+
From npm (no clone needed):
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
npx nepse-trading-skill
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
This copies the skills to `~/.nepse-skills` and links each one into `~/.claude/skills` and `~/.agents/skills`. Run it again to update; `npx nepse-trading-skill --uninstall` removes the links and keeps `~/.nepse-skills/state` (your journal and holdings).
|
|
144
|
+
|
|
145
|
+
From git:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
git clone https://gitlab.com/xetu/nepse.git ~/nepse-skills
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
~/nepse-skills/install.sh
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
The script links `~/.nepse-skills` to the clone and links each `nepse-*` skill folder into `~/.claude/skills` and `~/.agents/skills`. Restart the agent. Update with `git pull` in the clone; remove with `~/nepse-skills/install.sh --uninstall`.
|
|
156
|
+
|
|
157
|
+
Do not install single skills with an agent's own installer (for example `gemini skills install --path skills/nepse-...`): the scripts import `nepse_common/` from the repository root and every `SKILL.md` runs them from `~/.nepse-skills`, so a lone copied folder cannot run.
|
|
158
|
+
|
|
159
|
+
Inside this repository the skills also load as project skills (`.claude/skills` and `.agents/skills` link to `skills/`), and `AGENTS.md` (read by Codex; `CLAUDE.md` and `GEMINI.md` point to it) holds the working rules. Run `./install.sh` once here too: the commands use `~/.nepse-skills`.
|
|
160
|
+
|
|
161
|
+
## Workflows
|
|
162
|
+
|
|
163
|
+
Defined in `workflows/README.md`:
|
|
164
|
+
|
|
165
|
+
| Workflow | When | Skills in order |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| Market regime daily | Each trading day, 10 minutes | regime → breadth → sector → news sentiment |
|
|
168
|
+
| Swing opportunity | When the regime allows buying | regime → sector → momentum screen → technical → fundamental check → stock news → position sizer → pre-trade gate → journal |
|
|
169
|
+
| Dividend income | Dividend season, monthly | liquidity → dividend screen → fundamental → corporate actions → cost and tax |
|
|
170
|
+
| IPO | When an offering opens or lists | IPO calendar → fundamental → rules (opening range) → cost and tax → journal |
|
|
171
|
+
| Portfolio review | Monthly | liquidity → regime → portfolio → technical on each holding → journal statistics |
|
|
172
|
+
|
|
173
|
+
## Data sources
|
|
174
|
+
|
|
175
|
+
| Data | Source | Notes |
|
|
176
|
+
|---|---|---|
|
|
177
|
+
| Adjusted daily OHLCV for stocks, NEPSE and sub-indices | Merolagani chart handler | Since November 2010; adjusted for bonus and right |
|
|
178
|
+
| Live prices with sector, market summary, sub-indices | ShareHub live API | Updates through the session |
|
|
179
|
+
| Dividend history, public offerings, NEPSE company notices | ShareHub data API | |
|
|
180
|
+
| News headlines | ShareSansar latest, Kathmandu Post RSS, OnlineKhabar RSS | Latest 10 to 40 items each |
|
|
181
|
+
| Fundamentals | None free | Read from quarterly reports and pass to `valuation.py` |
|
|
182
|
+
| Floorsheet / broker-wise trades | None keyless found | Not covered |
|
|
183
|
+
|
|
184
|
+
Both feeds are unofficial and can change or stop without notice; `nepse_common/data.py` is the only file that knows their URLs. Responses are cached in `.cache/` (15 minutes for prices). The official `nepalstock.com.np` API needs a reverse-engineered token and is not used. For commercial use of NEPSE data, get a licence from NEPSE.
|
|
185
|
+
|
|
186
|
+
## What was verified, and what was not
|
|
187
|
+
|
|
188
|
+
Verified against 2026 press reports on 13 November 2026:
|
|
189
|
+
|
|
190
|
+
- Trading Monday to Friday since 6 April 2026; 11:00 to 15:00; pre-open 10:30 to 10:45
|
|
191
|
+
- 15% daily stock limit, 5% pre-open band, 3% order band, index breakers at 5% (15-minute halt, first two hours) and 8% (closed for the day), since 20 April 2026
|
|
192
|
+
- Capital gains tax for individuals: 3.75% over 365 days, 5% otherwise, since 22 September 2026
|
|
193
|
+
- Commission slabs 0.36% to 0.24%, SEBON fee 0.015%, DP charge Rs 25
|
|
194
|
+
- New-listing opening range moved to a face-value basis in February 2026 (disputed)
|
|
195
|
+
|
|
196
|
+
Not confirmed from a primary source, marked in the references: the institutional capital gains tax rate (10% used), whether the 10-kitta lot floor still applies at every broker, the exact reference price of the 15% limit, bonus-share cost basis for 2026, current NRB share-loan limits after the 2083/84 monetary policy, and whether intraday trading or T+1 has started. Sector descriptions, valuation bands and regulatory thresholds in the fundamental references are general knowledge and are flagged as such.
|
|
197
|
+
|
|
198
|
+
When a rule changes, update `~/.nepse-skills/skills/nepse-market-rules/references/trading_rules.md`, the constants in `nepse_common/costs.py` and `~/.nepse-skills/skills/nepse-market-rules/scripts/price_bands.py`, then run the tests.
|
|
199
|
+
|
|
200
|
+
## Layout
|
|
201
|
+
|
|
202
|
+
```
|
|
203
|
+
nepse_common/ shared code: data.py, indicators.py, costs.py, report.py
|
|
204
|
+
skills/<name>/ SKILL.md, references/, scripts/ (and assets/ where used)
|
|
205
|
+
workflows/ multi-skill workflows
|
|
206
|
+
tests/ offline tests for every money and decision calculation
|
|
207
|
+
.claude/skills link to skills/ (Claude Code project skills)
|
|
208
|
+
.agents/skills link to skills/ (Codex, Gemini CLI project skills)
|
|
209
|
+
install.sh links the skills into ~/.claude/skills and ~/.agents/skills
|
|
210
|
+
AGENTS.md working rules; CLAUDE.md and GEMINI.md point to it
|
|
211
|
+
reports/ state/ .cache/ created at run time, git-ignored
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
## Tests
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
python3 -m pytest tests -q
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
34 offline tests cover commission slabs, tax, break-even, indicators, position sizing, price bands, corporate actions, regime classification, the trend template, breadth scoring, dividend summaries, offering grouping, valuation flags, portfolio review, the journal, the gate, news scoring and parsing, and the daily analyst's trigger status and trade plan.
|
|
221
|
+
|
|
222
|
+
## Differences from the upstream US repository
|
|
223
|
+
|
|
224
|
+
| Upstream | Here | Why |
|
|
225
|
+
|---|---|---|
|
|
226
|
+
| 74 skills | 18 | Options, futures, COT, short-selling, earnings-gap, 13F and US macro skills have no NEPSE counterpart; several upstream skills are merged (three market-direction skills into one regime detector; journal, post-mortem and coach into one journal) |
|
|
227
|
+
| FMP / FINVIZ / Alpaca APIs | Keyless public feeds | No NEPSE data vendor or broker API for retail |
|
|
228
|
+
| Fractional shares, bracket orders | Whole kitta, limit orders, manual stops | TMS has no stop or bracket orders |
|
|
229
|
+
| Earnings calendar | Dividend and book-closure dates | Quarterly results have no reliable free calendar feed |
|
|
230
|
+
| US tax lots | NEPSE charges and capital gains tax in every result | Costs are about 0.7% a round trip plus tax on the gain |
|
package/install.sh
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
# Install the NEPSE skills for Claude Code, Codex, Gemini CLI and any agent that reads
|
|
3
|
+
# the Agent Skills folders (~/.claude/skills or ~/.agents/skills).
|
|
4
|
+
#
|
|
5
|
+
# ./install.sh install (links ~/.nepse-skills to this folder, links each skill)
|
|
6
|
+
# ./install.sh --uninstall remove the links
|
|
7
|
+
# npx nepse-trading-skill same, from npm: copies the package to ~/.nepse-skills first,
|
|
8
|
+
# because npm's own folder can be cleaned away
|
|
9
|
+
#
|
|
10
|
+
# The skills' scripts import nepse_common from the repository root, so each skill is linked,
|
|
11
|
+
# never copied on its own; every SKILL.md runs its scripts from ~/.nepse-skills.
|
|
12
|
+
set -eu
|
|
13
|
+
|
|
14
|
+
HOME_LINK="$HOME/.nepse-skills"
|
|
15
|
+
SELF=$0
|
|
16
|
+
while [ -L "$SELF" ]; do # npm runs this through a link in its bin folder
|
|
17
|
+
LINK=$(readlink "$SELF")
|
|
18
|
+
case $LINK in /*) SELF=$LINK ;; *) SELF=$(dirname "$SELF")/$LINK ;; esac
|
|
19
|
+
done
|
|
20
|
+
SRC=$(cd "$(dirname "$SELF")" && pwd -P)
|
|
21
|
+
case $SRC in */node_modules/*) FROM_NPM=1 ;; *) FROM_NPM=0 ;; esac
|
|
22
|
+
TARGETS="$HOME/.claude/skills $HOME/.agents/skills" # Claude Code; Codex, Gemini CLI and other Agent Skills clients
|
|
23
|
+
|
|
24
|
+
if [ "${1:-}" = "--uninstall" ]; then
|
|
25
|
+
for t in $TARGETS; do
|
|
26
|
+
for s in "$SRC"/skills/nepse-*/; do
|
|
27
|
+
dest="$t/$(basename "$s")"
|
|
28
|
+
[ -L "$dest" ] && rm "$dest" && echo "removed $dest"
|
|
29
|
+
done
|
|
30
|
+
done
|
|
31
|
+
if [ -L "$HOME_LINK" ]; then
|
|
32
|
+
rm "$HOME_LINK" && echo "removed $HOME_LINK"
|
|
33
|
+
elif [ -d "$HOME_LINK" ]; then
|
|
34
|
+
echo "kept $HOME_LINK: it holds your journal and holdings in state/; delete it yourself if you want"
|
|
35
|
+
fi
|
|
36
|
+
exit 0
|
|
37
|
+
fi
|
|
38
|
+
|
|
39
|
+
command -v python3 >/dev/null 2>&1 || { echo "python3 (3.9 or newer) is required" >&2; exit 1; }
|
|
40
|
+
python3 -c 'import sys; sys.exit(sys.version_info < (3, 9))' || { echo "python3 3.9 or newer is required" >&2; exit 1; }
|
|
41
|
+
|
|
42
|
+
if [ "$FROM_NPM" = 1 ]; then
|
|
43
|
+
[ -L "$HOME_LINK" ] && rm "$HOME_LINK" # an earlier git install: replace the link with a copy
|
|
44
|
+
mkdir -p "$HOME_LINK"
|
|
45
|
+
rm -rf "$HOME_LINK/skills" "$HOME_LINK/nepse_common" "$HOME_LINK/workflows" # state/ and .cache/ stay
|
|
46
|
+
cp -R "$SRC/." "$HOME_LINK/"
|
|
47
|
+
elif [ "$SRC" != "$HOME_LINK" ]; then
|
|
48
|
+
if [ -e "$HOME_LINK" ] && [ ! -L "$HOME_LINK" ]; then
|
|
49
|
+
echo "$HOME_LINK exists and is not a link; move it away first" >&2
|
|
50
|
+
exit 1
|
|
51
|
+
fi
|
|
52
|
+
ln -sfn "$SRC" "$HOME_LINK"
|
|
53
|
+
fi
|
|
54
|
+
|
|
55
|
+
count=0
|
|
56
|
+
for t in $TARGETS; do
|
|
57
|
+
mkdir -p "$t"
|
|
58
|
+
for s in "$HOME_LINK"/skills/nepse-*/; do
|
|
59
|
+
name=$(basename "$s")
|
|
60
|
+
dest="$t/$name"
|
|
61
|
+
if [ -e "$dest" ] && [ ! -L "$dest" ]; then
|
|
62
|
+
echo "skipped $dest: a folder with that name already exists" >&2
|
|
63
|
+
continue
|
|
64
|
+
fi
|
|
65
|
+
ln -sfn "$HOME_LINK/skills/$name" "$dest"
|
|
66
|
+
count=$((count + 1))
|
|
67
|
+
done
|
|
68
|
+
done
|
|
69
|
+
echo "Linked $count skill folders into: $TARGETS"
|
|
70
|
+
echo "Scripts run from $HOME_LINK. Restart your agent to load the skills."
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Shared code for the NEPSE trading skills: data, indicators, costs, reports."""
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
"""NEPSE transaction costs and capital gains tax.
|
|
2
|
+
|
|
3
|
+
Rates as researched on 2026-11-13 (see skills/nepse-cost-tax-calculator/references).
|
|
4
|
+
They change by SEBON / Finance Ministry decision: check before relying on them.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
# (upper bound of trade value in Rs, commission rate). The slab rate applies to the whole amount.
|
|
10
|
+
COMMISSION_SLABS = [
|
|
11
|
+
(50_000, 0.0036),
|
|
12
|
+
(500_000, 0.0033),
|
|
13
|
+
(2_000_000, 0.0031),
|
|
14
|
+
(10_000_000, 0.0027),
|
|
15
|
+
(float("inf"), 0.0024),
|
|
16
|
+
]
|
|
17
|
+
MIN_COMMISSION = 10.0
|
|
18
|
+
SEBON_FEE_RATE = 0.00015 # 0.015% of trade value, both sides
|
|
19
|
+
DP_CHARGE = 25.0 # per scrip per transaction day, both sides
|
|
20
|
+
# Resident individual, listed shares, gazetted 2026-09-22.
|
|
21
|
+
CGT_LONG = 0.0375 # held more than 365 days
|
|
22
|
+
CGT_SHORT = 0.05 # held 365 days or less
|
|
23
|
+
CGT_INSTITUTION = 0.10 # not confirmed from a primary source
|
|
24
|
+
LONG_TERM_DAYS = 365
|
|
25
|
+
TICK = 0.1
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def commission(amount: float) -> float:
|
|
29
|
+
for limit, rate in COMMISSION_SLABS:
|
|
30
|
+
if amount <= limit:
|
|
31
|
+
return max(round(amount * rate, 2), MIN_COMMISSION)
|
|
32
|
+
raise ValueError("unreachable")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def cgt_rate(holding_days: int, investor: str = "individual") -> float:
|
|
36
|
+
if investor == "institution":
|
|
37
|
+
return CGT_INSTITUTION
|
|
38
|
+
return CGT_LONG if holding_days > LONG_TERM_DAYS else CGT_SHORT
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def buy_cost(price: float, qty: int) -> dict:
|
|
42
|
+
"""Total payable for a buy, with the per-share cost (WACC of this lot)."""
|
|
43
|
+
if price <= 0 or qty <= 0:
|
|
44
|
+
raise ValueError("price and qty must be positive")
|
|
45
|
+
amount = price * qty
|
|
46
|
+
comm, sebon = commission(amount), round(amount * SEBON_FEE_RATE, 2)
|
|
47
|
+
total = amount + comm + sebon + DP_CHARGE
|
|
48
|
+
return {
|
|
49
|
+
"amount": round(amount, 2),
|
|
50
|
+
"commission": comm,
|
|
51
|
+
"sebon_fee": sebon,
|
|
52
|
+
"dp_charge": DP_CHARGE,
|
|
53
|
+
"total_payable": round(total, 2),
|
|
54
|
+
"cost_per_share": round(total / qty, 4),
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def sell_proceeds(
|
|
59
|
+
price: float,
|
|
60
|
+
qty: int,
|
|
61
|
+
cost_per_share: float,
|
|
62
|
+
holding_days: int = 0,
|
|
63
|
+
investor: str = "individual",
|
|
64
|
+
cgt_override: float | None = None,
|
|
65
|
+
) -> dict:
|
|
66
|
+
"""Net receivable for a sell. cost_per_share is the all-in buy cost (WACC)."""
|
|
67
|
+
if price <= 0 or qty <= 0 or cost_per_share < 0:
|
|
68
|
+
raise ValueError("price and qty must be positive, cost_per_share not negative")
|
|
69
|
+
amount = price * qty
|
|
70
|
+
comm, sebon = commission(amount), round(amount * SEBON_FEE_RATE, 2)
|
|
71
|
+
charges = comm + sebon + DP_CHARGE
|
|
72
|
+
gain = amount - charges - cost_per_share * qty
|
|
73
|
+
rate = cgt_override if cgt_override is not None else cgt_rate(holding_days, investor)
|
|
74
|
+
tax = round(max(gain, 0) * rate, 2) # no tax on a loss; losses are not netted across scrips
|
|
75
|
+
net = amount - charges - tax
|
|
76
|
+
return {
|
|
77
|
+
"amount": round(amount, 2),
|
|
78
|
+
"commission": comm,
|
|
79
|
+
"sebon_fee": sebon,
|
|
80
|
+
"dp_charge": DP_CHARGE,
|
|
81
|
+
"taxable_gain": round(gain, 2),
|
|
82
|
+
"cgt_rate_pct": round(rate * 100, 3),
|
|
83
|
+
"cgt": tax,
|
|
84
|
+
"net_receivable": round(net, 2),
|
|
85
|
+
"net_profit": round(net - cost_per_share * qty, 2),
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def round_trip(buy_price: float, sell_price: float, qty: int, holding_days: int = 0, investor: str = "individual") -> dict:
|
|
90
|
+
buy = buy_cost(buy_price, qty)
|
|
91
|
+
sell = sell_proceeds(sell_price, qty, buy["cost_per_share"], holding_days, investor)
|
|
92
|
+
return {
|
|
93
|
+
"buy": buy,
|
|
94
|
+
"sell": sell,
|
|
95
|
+
"net_profit": sell["net_profit"],
|
|
96
|
+
"net_return_pct": round(sell["net_profit"] / buy["total_payable"] * 100, 3),
|
|
97
|
+
"gross_return_pct": round((sell_price / buy_price - 1) * 100, 3),
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def breakeven_price(buy_price: float, qty: int) -> float:
|
|
102
|
+
"""Lowest sell price (to the Rs 0.10 tick) at which net profit is not negative."""
|
|
103
|
+
cost = buy_cost(buy_price, qty)["cost_per_share"]
|
|
104
|
+
price = round(buy_price, 1)
|
|
105
|
+
while sell_proceeds(price, qty, cost)["net_profit"] < 0:
|
|
106
|
+
price = round(price + TICK, 1)
|
|
107
|
+
return price
|