pi-fluency 0.1.0 → 0.1.2
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/README.md +64 -125
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,171 +1,110 @@
|
|
|
1
1
|
# Pi Fluency
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**English writing analytics for [Pi](https://github.com/earendil-works/pi).**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Pi Fluency analyzes human-authored prompts, lets you review possible English mistakes, and tracks recurring patterns over time. It is an analytical tool—not an English teacher—and every finding stays provisional until you review it.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- Reviews only interactive prompts you write
|
|
8
|
+
- Groups repeated findings into concrete recurring patterns
|
|
9
|
+
- Tracks accepted mistakes per 1,000 English words
|
|
10
|
+
- Keeps one-off mistakes out of recurring-pattern counts
|
|
11
|
+
- Works across Pi projects and sessions
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
## See the inbox
|
|
10
14
|
|
|
11
|
-
-
|
|
12
|
-
- removes code;
|
|
13
|
-
- redacts common API keys, tokens, secrets, passwords, private keys, JWTs, cloud credentials, and URL user-info credentials;
|
|
14
|
-
- hashes the sanitized prose for replay protection.
|
|
15
|
+
Pi Fluency opens as a keyboard-first TUI inside Pi. Each card groups currently pending occurrences of one possible mistake:
|
|
15
16
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
17
|
+
```text
|
|
18
|
+
╭──────────────────────────────────────────────────────────────────────╮
|
|
19
|
+
│ Pi Fluency · Inbox Pending 3 · accepted 0 · ← 1 / 1 →│
|
|
20
|
+
│ ──────────────────────────────────────────────────────────────────── │
|
|
21
|
+
│ › I want to have an parallel agent with a deliberately long │
|
|
22
|
+
│ └─ a │
|
|
23
|
+
│ context. │
|
|
24
|
+
│ │
|
|
25
|
+
│ Use “a” before a consonant sound. │
|
|
26
|
+
│ ──────────────────────────────────────────────────────────────────── │
|
|
27
|
+
│ ←→ card ↑↓/jk scroll a accept d dismiss │
|
|
28
|
+
│ i ignore tab view esc close │
|
|
29
|
+
╰──────────────────────────────────────────────────────────────────────╯
|
|
30
|
+
```
|
|
25
31
|
|
|
26
|
-
|
|
32
|
+
- **Accept** confirms current pending occurrences and includes them in analytics.
|
|
33
|
+
- **Dismiss** rejects current batch without suppressing future recurrence.
|
|
34
|
+
- **Ignore** hides exact pattern or mistake category until restored.
|
|
35
|
+
- **Tab** cycles through Inbox, Accepted, Ignored, and Stats views.
|
|
27
36
|
|
|
28
|
-
## Install
|
|
37
|
+
## Install and start
|
|
29
38
|
|
|
30
|
-
|
|
39
|
+
Requires Pi 0.80.10 or newer.
|
|
31
40
|
|
|
32
41
|
```sh
|
|
33
42
|
pi install npm:pi-fluency
|
|
34
43
|
```
|
|
35
44
|
|
|
36
|
-
Run `/reload
|
|
45
|
+
Run `/reload`, then `/fluency`. Choose an available analysis model and confirm provider disclosure. Analysis remains off until setup completes.
|
|
37
46
|
|
|
38
|
-
|
|
47
|
+
Useful commands:
|
|
39
48
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
Run `/fluency`. Select an available low-cost analyzer model, review the provider disclosure, and accept consent. Analysis remains disabled unless setup completes. Provider credentials come from Pi's model registry.
|
|
50
|
-
|
|
51
|
-
## Review model
|
|
52
|
-
|
|
53
|
-
Each Inbox card represents every currently pending occurrence of one concrete rule.
|
|
54
|
-
|
|
55
|
-
- **Accept** confirms only the current pending batch. Accepted occurrences enter analytics. A later recurrence opens the rule in Inbox again.
|
|
56
|
-
- **Dismiss** rejects only the current pending batch. It does not suppress future recurrence and does not enter the mistake-rate numerator.
|
|
57
|
-
- **Ignore** persistently hides an exact rule or ERRANT category. Hidden pending occurrences remain stored and return when restored. Already accepted history remains accepted.
|
|
58
|
-
- **Clear** removes coaching and analytics history while preserving settings, model choice, and consent.
|
|
49
|
+
| Command | Action |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| `/fluency` | Set up Pi Fluency or open Inbox |
|
|
52
|
+
| `/fluency stats` | Open 30-day analytics |
|
|
53
|
+
| `/fluency pause` | Pause analysis and hide toolbar status |
|
|
54
|
+
| `/fluency resume` | Resume analysis |
|
|
55
|
+
| `/fluency model` | Change analysis model |
|
|
56
|
+
| `/fluency status` | Show model, queue, and storage status |
|
|
57
|
+
| `/fluency clear` | Confirm, then clear coaching and analytics history |
|
|
59
58
|
|
|
60
|
-
|
|
59
|
+
`Ctrl+Shift+L` opens Inbox after setup.
|
|
61
60
|
|
|
62
|
-
##
|
|
61
|
+
## What it measures
|
|
63
62
|
|
|
64
|
-
|
|
63
|
+
Pi Fluency counts only findings you accept. Every analyzer-classified English prompt contributes to word totals, including prompts with no findings.
|
|
65
64
|
|
|
66
65
|
```text
|
|
67
|
-
|
|
66
|
+
accepted mistake rate = accepted occurrences / English words × 1000
|
|
68
67
|
```
|
|
69
68
|
|
|
70
|
-
|
|
71
|
-
| --- | --- |
|
|
72
|
-
| ` 12` | 12 visible pending occurrences; `` means zero |
|
|
73
|
-
| ` 6` | 6 recurring rule-explanation groups with accepted occurrences in the trailing seven days |
|
|
74
|
-
| `▆▄▃▂▁▂▂` | Seven rolling seven-day accepted-mistake rates |
|
|
75
|
-
| `8.4/k` | Latest accepted mistakes per 1,000 English words |
|
|
69
|
+
Stats covers trailing 30 local calendar days. It shows accepted rate, review coverage, one-off total, recurring patterns, and trends. Pattern list is sorted by accepted occurrence count. Pattern becomes recurring after at least two accepted occurrences across retained history; one-offs remain in overall accepted totals and rate but stay out of recurring-pattern list and toolbar count.
|
|
76
70
|
|
|
77
|
-
|
|
71
|
+
Toolbar summarizes current activity and accepted-mistake trends:
|
|
78
72
|
|
|
79
73
|
```text
|
|
80
|
-
|
|
81
|
-
ERR model
|
|
82
|
-
ERR analyze
|
|
83
|
-
ERR store
|
|
84
|
-
ERR migrate
|
|
74
|
+
📥 12 💡 6 ▆▄▃▂▁▂▂ 8.4/k
|
|
85
75
|
```
|
|
86
76
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
## Commands and keyboard controls
|
|
90
|
-
|
|
91
|
-
`Ctrl+Shift+L` opens Inbox when configured.
|
|
92
|
-
|
|
93
|
-
| Command | Action |
|
|
77
|
+
| Part | Meaning |
|
|
94
78
|
| --- | --- |
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
| `/fluency status` | Show state, model, queue, drops, and storage warnings |
|
|
100
|
-
| `/fluency model` | Select another analyzer model and review provider disclosure |
|
|
101
|
-
| `/fluency clear` | Confirm, then remove coaching and analytics history |
|
|
102
|
-
|
|
103
|
-
Inside the overlay:
|
|
104
|
-
|
|
105
|
-
- Left/Right changes cards.
|
|
106
|
-
- Up/Down, `j`/`k`, and Page Up/Down scroll.
|
|
107
|
-
- `a` accepts the current Inbox batch; `l` remains a compatibility alias.
|
|
108
|
-
- `d` dismisses the current Inbox batch.
|
|
109
|
-
- `i` ignores an exact rule or ERRANT category.
|
|
110
|
-
- `u` restores every ignore affecting an item in Ignored.
|
|
111
|
-
- Tab cycles Inbox, Accepted, Ignored, and Stats.
|
|
112
|
-
- Esc closes.
|
|
113
|
-
|
|
114
|
-
Actions auto-advance to the next card. Stats is read-only. Compact diffs use `└─` for replacements, strikethrough for deletions, and underline for insertions.
|
|
115
|
-
|
|
116
|
-
## Analytics and Stats
|
|
117
|
-
|
|
118
|
-
For a period `P`:
|
|
119
|
-
|
|
120
|
-
```text
|
|
121
|
-
accepted mistake rate(P) = accepted occurrences in P / English words in P × 1000
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
Every analyzer-classified English prompt contributes words, including prompts with zero findings. Pending, dismissed, hidden-unaccepted, and non-English occurrences do not enter the numerator.
|
|
125
|
-
|
|
126
|
-
Stats covers 30 local calendar days and shows:
|
|
127
|
-
|
|
128
|
-
- 30-day accepted rate, English words, accepted, dismissed, and visible pending totals;
|
|
129
|
-
- a single aggregate count for one-off accepted mistakes in the period;
|
|
130
|
-
- review coverage: `(accepted + dismissed) / (accepted + dismissed + visible pending)`;
|
|
131
|
-
- active trailing-seven-day recurring rules;
|
|
132
|
-
- rolling seven-day toolbar trend;
|
|
133
|
-
- recurring-rule rates, sparklines, and `improving`, `worsening`, `stable`, or `new` trends.
|
|
134
|
-
|
|
135
|
-
A rule becomes recurring after at least two accepted occurrences across retained history. One-offs remain part of accepted totals and rates, but do not clutter the toolbar count, Concrete rules list, or trend totals. Rule trends compare adjacent 30-day windows. Improving/worsening requires both at least 20% relative change and at least 0.5 mistakes per 1,000 words absolute change. Rules are grouped and displayed by human explanation, never by internal key or broad category.
|
|
136
|
-
|
|
137
|
-
## Storage and migration
|
|
79
|
+
| `📥 12` | 12 visible pending occurrences |
|
|
80
|
+
| `💡 6` | 6 recurring patterns active during trailing 7 days |
|
|
81
|
+
| `▆▄▃▂▁▂▂` | Seven rolling accepted-mistake rates |
|
|
82
|
+
| `8.4/k` | Latest accepted mistakes per 1,000 English words |
|
|
138
83
|
|
|
139
|
-
|
|
84
|
+
## Data and limitations
|
|
140
85
|
|
|
141
|
-
|
|
142
|
-
- retains 365 local calendar days of reviewed observations and occurrences;
|
|
143
|
-
- preserves hashes referenced by retained observations;
|
|
144
|
-
- writes state-free schema-v4 snapshots under an atomic cross-process lock.
|
|
86
|
+
Pi already sends your prompts to selected main model. When enabled, Pi Fluency additionally sends eligible, filtered prompt prose to analysis model you choose during setup. It excludes assistant messages, tool output, slash commands, injected extension input, and code; it also redacts common credentials before analysis.
|
|
145
87
|
|
|
146
|
-
|
|
88
|
+
Local analytics live under `~/.pi/agent/pi-fluency/`. History contains hashes, dates, word counts, review decisions, and bounded finding excerpts—not complete prompts. Storage is shared across Pi projects and sessions.
|
|
147
89
|
|
|
148
|
-
|
|
90
|
+
Model findings can be incomplete or wrong. Accept only findings you agree with. Pi Fluency measures reviewed writing patterns; it does not assess fluency, guarantee improvement, or replace human instruction.
|
|
149
91
|
|
|
150
|
-
|
|
92
|
+
## Project
|
|
151
93
|
|
|
152
|
-
|
|
153
|
-
2. Run `/fluency clear`.
|
|
154
|
-
3. Confirm the prompt.
|
|
155
|
-
4. Verify `/fluency stats` is empty and settings/model/consent remain configured.
|
|
94
|
+
Product idea and product decisions are by Ihar Trafimovich. All code, tests, and documentation were written by AI.
|
|
156
95
|
|
|
157
|
-
Pi Fluency
|
|
96
|
+
Pi Fluency uses the English error taxonomy from the MIT-licensed [ERRANT toolkit](https://github.com/chrisjbryant/errant) and its [ACL 2017 paper](https://aclanthology.org/P17-1074/). It does not bundle ERRANT, Python, spaCy, language models, or learner corpora.
|
|
158
97
|
|
|
159
|
-
|
|
98
|
+
For local development:
|
|
160
99
|
|
|
161
100
|
```sh
|
|
101
|
+
git clone https://github.com/unutranyholas/pi-fluency.git
|
|
102
|
+
cd pi-fluency
|
|
162
103
|
npm install
|
|
163
104
|
npm run check
|
|
164
105
|
pi -e ./extensions/pi-fluency/index.ts
|
|
165
106
|
```
|
|
166
107
|
|
|
167
|
-
Automated tests
|
|
168
|
-
|
|
169
|
-
## Known limitations
|
|
108
|
+
Automated tests use temporary storage and never touch `~/.pi/agent/pi-fluency/`.
|
|
170
109
|
|
|
171
|
-
|
|
110
|
+
[Report an issue](https://github.com/unutranyholas/pi-fluency/issues) · [MIT License](LICENSE)
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-fluency",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.2",
|
|
4
|
+
"description": "English writing analytics for human-authored Pi prompts",
|
|
5
5
|
"author": "Ihar Trafimovich",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"keywords": [
|