pi-model-fallback 0.3.2 → 0.3.3

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.
Files changed (3) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +131 -164
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,12 @@
4
4
 
5
5
  - Add Buy Me a Coffee sponsor button to README and native GitHub funding link via `.github/FUNDING.yml`.
6
6
 
7
+ ## [0.3.3] - 2026-07-04
8
+
9
+ ### Changed
10
+
11
+ - Rewrite the README with real `pi-model-fallback` install, command, configuration, and state-path documentation instead of template placeholders.
12
+
7
13
  ## [0.3.2] - 2026-07-04
8
14
 
9
15
  ### Fixed
package/README.md CHANGED
@@ -1,164 +1,131 @@
1
- # PACKAGE_DISPLAY_NAME
2
-
3
- [![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/ci.yml)
4
- [![Publish](https://github.com/OWNER/REPO/actions/workflows/publish.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/publish.yml)
5
- [![npm version](https://img.shields.io/npm/v/PACKAGE_NAME.svg)](https://www.npmjs.com/package/PACKAGE_NAME)
6
- [![npm downloads](https://img.shields.io/npm/dm/PACKAGE_NAME.svg)](https://www.npmjs.com/package/PACKAGE_NAME)
7
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
- [![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
9
- [![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)
10
- <a href="https://buymeacoffee.com/ekawano114m"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="217" height="60"></a>
11
-
12
- > One-line pitch for this TypeScript-first Pi package.
13
-
14
- ## What this is
15
-
16
- Briefly explain what this TypeScript-first package adds to Pi and who should use it.
17
-
18
- ## Features
19
-
20
- - Feature 1
21
- - Feature 2
22
- - Feature 3
23
-
24
- ## Install
25
-
26
- Install the published npm package with Pi:
27
-
28
- ```bash
29
- pi install npm:PACKAGE_NAME
30
- ```
31
-
32
- Replace `PACKAGE_NAME` with the exact `name` from `package.json`.
33
- For a scoped npm package, keep the `npm:` prefix:
34
-
35
- ```bash
36
- pi install npm:@your-scope/your-pi-package
37
- ```
38
-
39
- Pin a specific version when you want reproducible installs:
40
-
41
- ```bash
42
- pi install npm:PACKAGE_NAME@0.1.0
43
- ```
44
-
45
- Install into the current project instead of your user Pi settings:
46
-
47
- ```bash
48
- pi install npm:PACKAGE_NAME -l
49
- ```
50
-
51
- Or install from GitHub:
52
-
53
- ```bash
54
- pi install git:github.com/OWNER/REPO
55
- ```
56
-
57
- Try it without permanently installing:
58
-
59
- ```bash
60
- pi -e npm:PACKAGE_NAME
61
- ```
62
-
63
- ## Quick start
64
-
65
- Try this package locally:
66
-
67
- ```bash
68
- pi -e .
69
- ```
70
-
71
- Then run:
72
-
73
- ```txt
74
- /your-command
75
- ```
76
-
77
- ## Package contents
78
-
79
- | Path | Purpose |
80
- |---|---|
81
- | `extensions/` | Pi TypeScript extension entrypoints (`*.ts` and `index.ts`) |
82
- | `lib/` | Shared TypeScript helpers |
83
- | `skills/` | Agent Skills |
84
- | `prompts/` | Prompt templates |
85
- | `themes/` | Pi themes |
86
- | `docs/` | Optional supporting docs (usage, examples, release, ADRs) |
87
-
88
- ## Development
89
-
90
- ```bash
91
- npm install
92
- npm run ci
93
- ```
94
-
95
- ## Development flow
96
-
97
- Use this default flow when building a new Pi extension OSS project from this template:
98
-
99
- 1. Create the Vault project notes under `4_Project/<ProjectName>/`.
100
- 2. Add `CONTEXT.md`, `README.md`, `ROADMAP.md`, `Docs/`, `Issues/`, and `Progress/`.
101
- 3. Write the PRD in `4_Project/<ProjectName>/Docs/`.
102
- 4. Split approved tracer-bullet issues into `4_Project/<ProjectName>/Issues/`.
103
- 5. Implement in the OSS repo.
104
- 6. Run `npm run ci`, `npm test`, and `npm pack --dry-run`.
105
- 7. Release with Trusted Publishing.
106
- 8. Save release notes and follow-up decisions back to the Vault project.
107
-
108
- Short version:
109
-
110
- ```txt
111
- Vault notes -> PRD -> Issues -> implement -> ci/check -> release -> save learnings
112
- ```
113
-
114
- ## Release
115
-
116
- This package is set up for npm Trusted Publishing, so no `NPM_TOKEN` is required.
117
-
118
- ```bash
119
- npm version patch
120
- git push
121
- ```
122
-
123
- See [`docs/release.md`](docs/release.md) for setup details.
124
-
125
- ## Docs
126
-
127
- `docs/` is optional supporting documentation, not a fixed six-file set. README stays the GitHub/npm entrypoint; add `docs/*.md` only when they help users or maintainers.
128
-
129
- After creating a repository from this template:
130
-
131
- 1. Follow [`docs/template-checklist.md`](docs/template-checklist.md) for setup.
132
- 2. Run the **post-generation docs cleanup** in that checklist: delete or merge template bootstrap docs that no longer add project value.
133
-
134
- Useful docs to keep when they add value:
135
-
136
- - [`docs/examples.md`](docs/examples.md) — examples for extensions, skills, prompts, and themes
137
- - [`docs/release.md`](docs/release.md) — Trusted Publishing details (README Release summarizes the flow)
138
- - `docs/usage.md` — create when usage does not fit in README
139
-
140
- Optional maintainer guidance (not a public-user navigation target in mature repos):
141
-
142
- - [`docs/template-checklist.md`](docs/template-checklist.md)
143
-
144
- Template bootstrap docs to delete or merge after setup unless they still teach something project-specific:
145
-
146
- - `docs/github-template.md`
147
- - `docs/repository-settings.md`
148
- - `docs/typescript.md`
149
-
150
- ## Security
151
-
152
- Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.
153
-
154
- For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
155
-
156
- ## Links
157
-
158
- - npm: https://www.npmjs.com/package/PACKAGE_NAME
159
- - GitHub: https://github.com/OWNER/REPO
160
- - Issues: https://github.com/OWNER/REPO/issues
161
-
162
- ## License
163
-
164
- MIT
1
+ # pi-model-fallback
2
+
3
+ [![CI](https://github.com/eiei114/pi-model-fallback/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-model-fallback/actions/workflows/ci.yml)
4
+ [![Publish](https://github.com/eiei114/pi-model-fallback/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-model-fallback/actions/workflows/publish.yml)
5
+ [![npm version](https://img.shields.io/npm/v/pi-model-fallback.svg)](https://www.npmjs.com/package/pi-model-fallback)
6
+ [![npm downloads](https://img.shields.io/npm/dm/pi-model-fallback.svg)](https://www.npmjs.com/package/pi-model-fallback)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
+ [![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
9
+ <a href="https://buymeacoffee.com/ekawano114m"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="217" height="60"></a>
10
+
11
+ > Pi extension that switches to a fallback model after provider failures such as 429 rate limits.
12
+
13
+ ## What this does
14
+
15
+ `pi-model-fallback` watches provider failures and automatically moves Pi to a safer fallback model when a matching rule fires.
16
+
17
+ Current default:
18
+
19
+ - source provider: `zai`
20
+ - matching statuses: `429`, `500`, `502`, `503`, `504`
21
+ - fallback model: `deepseek/deepseek-v4-flash`
22
+
23
+ When a failure matches, the extension also stores persistent fallback state so future sessions can preselect the fallback model until the cooldown expires.
24
+
25
+ ## Install
26
+
27
+ Install from npm:
28
+
29
+ ```bash
30
+ pi install npm:pi-model-fallback
31
+ ```
32
+
33
+ Install into the current project only:
34
+
35
+ ```bash
36
+ pi install npm:pi-model-fallback -l
37
+ ```
38
+
39
+ Or install from GitHub:
40
+
41
+ ```bash
42
+ pi install git:github.com/eiei114/pi-model-fallback
43
+ ```
44
+
45
+ Try it without permanently installing:
46
+
47
+ ```bash
48
+ pi -e npm:pi-model-fallback
49
+ ```
50
+
51
+ ## Commands
52
+
53
+ ```text
54
+ /model-fallback:status
55
+ /model-fallback:reset
56
+ ```
57
+
58
+ - `status`: shows whether fallback is enabled, active persistent entries, and current paths
59
+ - `reset`: clears persistent fallback state and switches back to the remembered original model when possible
60
+
61
+ ## Configuration
62
+
63
+ The extension exposes the `model_fallback_config` tool for reading, validating, and saving config JSON.
64
+
65
+ Default config shape:
66
+
67
+ ```json
68
+ {
69
+ "version": 1,
70
+ "enabled": true,
71
+ "rules": [
72
+ {
73
+ "name": "zai-to-deepseek-flash",
74
+ "matchProviders": ["zai"],
75
+ "statuses": [429, 500, 502, 503, 504],
76
+ "fallback": {
77
+ "provider": "deepseek",
78
+ "model": "deepseek-v4-flash"
79
+ }
80
+ }
81
+ ]
82
+ }
83
+ ```
84
+
85
+ Rule fields:
86
+
87
+ - `matchProviders`: match all models from a provider
88
+ - `matchModels`: match specific `provider` + `model` pairs
89
+ - `statuses`: optional; defaults to `429, 500, 502, 503, 504`
90
+ - `cooldownMs`: optional persistent fallback window
91
+ - `fallback`: target model Pi should switch to
92
+
93
+ ## State and paths
94
+
95
+ The extension stores:
96
+
97
+ - config: `model-fallback/config.json`
98
+ - state: `model-fallback/state.json`
99
+
100
+ If the package is installed project-locally and the current project references it from `.pi/settings.json`, those files live under the project `.pi/` directory. Otherwise they live under the user agent directory.
101
+
102
+ ## Behavior notes
103
+
104
+ - Successful responses do nothing.
105
+ - Matching failures from `after_provider_response` can trigger fallback immediately.
106
+ - Assistant error messages parsed at `turn_end` can also persist fallback state for SDK/provider failures that do not emit the normal response hook.
107
+ - The failed request is not automatically replayed.
108
+
109
+ ## Development
110
+
111
+ ```bash
112
+ npm install
113
+ npm run ci
114
+ ```
115
+
116
+ Run locally in Pi:
117
+
118
+ ```bash
119
+ pi -e .
120
+ ```
121
+
122
+ ## Links
123
+
124
+ - npm: https://www.npmjs.com/package/pi-model-fallback
125
+ - GitHub: https://github.com/eiei114/pi-model-fallback
126
+ - Issues: https://github.com/eiei114/pi-model-fallback/issues
127
+ - Usage notes: [`docs/usage.md`](docs/usage.md)
128
+
129
+ ## License
130
+
131
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-model-fallback",
3
- "version": "0.3.2",
3
+ "version": "0.3.3",
4
4
  "description": "Pi extension that switches to a fallback model after provider failures such as 429 rate limits.",
5
5
  "type": "module",
6
6
  "license": "MIT",