pi-fluency 0.1.0

package/extensions/pi-fluency/types.ts

@@ -0,0 +1,138 @@
+import type { ErrantCategory, ErrantErrorType } from "./taxonomy.js";
+
+export const SETTINGS_SCHEMA_VERSION = 3 as const;
+export const HISTORY_SCHEMA_VERSION = 4 as const;
+export const SCHEMA_VERSION = SETTINGS_SCHEMA_VERSION;
+export const ANALYSIS_SCHEMA_VERSION = 3 as const;
+
+export interface CollectedPrompt {
+  promptHash: string;
+  prose: string;
+  observedAt: number;
+}
+
+export type ContextScope = "sentence" | "previous-and-current" | "current-and-next";
+
+export interface RawAnalyzerMistake {
+  original: string;
+  correction: string;
+  contextScope: ContextScope;
+  explanation: string;
+  errorType: ErrantErrorType;
+  patternKey: string;
+  confidence: number;
+}
+
+export interface AnalyzerMistake extends RawAnalyzerMistake {
+  sourceExcerpt: string;
+  correctedExcerpt: string;
+}
+
+export interface DemonstratedFix {
+  patternKey: string;
+  evidence: string;
+  confidence: number;
+}
+
+export type AnalysisLanguage = "en" | "other";
+
+export interface RawAnalysisResult {
+  schemaVersion: typeof ANALYSIS_SCHEMA_VERSION;
+  language: AnalysisLanguage;
+  mistakes: RawAnalyzerMistake[];
+  demonstratedFixes: DemonstratedFix[];
+}
+
+export interface AnalysisResult {
+  schemaVersion: typeof ANALYSIS_SCHEMA_VERSION;
+  language: AnalysisLanguage;
+  mistakes: AnalyzerMistake[];
+  demonstratedFixes: DemonstratedFix[];
+}
+
+export type OccurrenceDecision = "pending" | "accepted" | "dismissed";
+
+export interface EnglishObservation {
+  promptHash: string;
+  observedAt: number;
+  localDate: string;
+  wordCount: number;
+  occurrenceIds: string[];
+}
+
+export interface MistakeOccurrence {
+  id: string;
+  promptHash: string;
+  patternId: string;
+  patternKey: string;
+  observedAt: number;
+  localDate: string;
+  decision: OccurrenceDecision;
+}
+
+export interface FluencyAnalyticsSnapshot {
+  observations: EnglishObservation[];
+  occurrences: MistakeOccurrence[];
+  patterns: MistakePattern[];
+  ignoredPatternKeys: string[];
+  ignoredCategories: ErrantCategory[];
+}
+
+export interface MistakePattern {
+  id: string;
+  patternKey: string;
+  original: string;
+  correction: string;
+  sourceExcerpt: string;
+  correctedExcerpt: string;
+  explanation: string;
+  errorType: ErrantErrorType;
+  confidence: number;
+  firstSeenAt: number;
+  lastSeenAt: number;
+  occurrenceCount: number;
+  demonstratedFixCount: number;
+}
+
+export type SnapshotPattern = MistakePattern;
+
+export interface ReviewPattern extends MistakePattern {
+  pendingCount: number;
+  acceptedCount: number;
+  dismissedCount: number;
+}
+
+export interface FluencySettings {
+  schemaVersion: typeof SCHEMA_VERSION;
+  enabled: boolean;
+  consentedAt?: number;
+  provider?: string;
+  modelId?: string;
+  minimumConfidence: number;
+  retentionLimit: number;
+  ignoredPatternKeys: string[];
+  ignoredCategories: ErrantCategory[];
+}
+
+export const DEFAULT_SETTINGS: FluencySettings = {
+  schemaVersion: SCHEMA_VERSION,
+  enabled: false,
+  minimumConfidence: 0.8,
+  retentionLimit: 500,
+  ignoredPatternKeys: [],
+  ignoredCategories: [],
+};
+
+type HistoryEventBase = { schemaVersion: typeof HISTORY_SCHEMA_VERSION; at: number };
+
+export type FluencyEvent =
+  | (HistoryEventBase & { type: "analysis"; prompt: CollectedPrompt; wordCount: number; result: AnalysisResult })
+  | (HistoryEventBase & { type: "review"; occurrenceIds: string[]; decision: Exclude<OccurrenceDecision, "pending"> })
+  | (HistoryEventBase & { type: "snapshot"; patterns: SnapshotPattern[]; observations: EnglishObservation[]; occurrences: MistakeOccurrence[]; processedPromptHashes: string[] });
+
+export interface FluencyState {
+  patterns: Map<string, MistakePattern>;
+  observations: Map<string, EnglishObservation>;
+  occurrences: Map<string, MistakeOccurrence>;
+  processedPromptHashes: Set<string>;
+}

package/extensions/pi-fluency/worker.ts

@@ -0,0 +1,144 @@
+import { AnalyzerConfigurationError, type Analyzer } from "./analyzer.js";
+import type { AnalysisResult, CollectedPrompt, MistakePattern } from "./types.js";
+
+export interface WorkerSnapshot {
+  queued: number;
+  dropped: number;
+  running: boolean;
+  shuttingDown: boolean;
+}
+
+export interface WorkerOptions {
+  analyzer: Analyzer;
+  isIdle: () => boolean;
+  getPatterns: () => MistakePattern[];
+  onResult: (prompt: CollectedPrompt, result: AnalysisResult) => Promise<void>;
+  onError: (error: Error) => void;
+  onOverflow: (dropped: number) => void;
+  maxQueue?: number;
+}
+
+const DEFAULT_MAX_QUEUE = 10;
+const ANALYSIS_TIMEOUT_MS = 30_000;
+const RETRY_DELAY_MS = 500;
+
+function normalizeError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function abortableDelay(delayMs: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(resolve, delayMs);
+    signal.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    }, { once: true });
+  });
+}
+
+export class FluencyWorker {
+  private readonly queue: CollectedPrompt[] = [];
+  private readonly maxQueue: number;
+  private controller: AbortController | undefined;
+  private active: Promise<void> | undefined;
+  private dropped = 0;
+  private shuttingDown = false;
+
+  constructor(private readonly options: WorkerOptions) {
+    this.maxQueue = Number.isSafeInteger(options.maxQueue) && (options.maxQueue ?? -1) >= 0
+      ? options.maxQueue as number
+      : DEFAULT_MAX_QUEUE;
+  }
+
+  enqueue(prompt: CollectedPrompt): void {
+    if (this.shuttingDown) return;
+    this.queue.push(prompt);
+    while (this.queue.length > this.maxQueue) {
+      this.queue.shift();
+      this.dropped += 1;
+      this.options.onOverflow(this.dropped);
+    }
+  }
+
+  async drain(): Promise<void> {
+    if (this.active || this.shuttingDown || !this.options.isIdle()) return this.active;
+    this.active = this.run().finally(() => {
+      this.active = undefined;
+    });
+    return this.active;
+  }
+
+  async shutdown(): Promise<void> {
+    this.shuttingDown = true;
+    this.queue.length = 0;
+    this.controller?.abort();
+    await this.active?.catch(() => undefined);
+  }
+
+  getSnapshot(): WorkerSnapshot {
+    return {
+      queued: this.queue.length,
+      dropped: this.dropped,
+      running: this.active !== undefined,
+      shuttingDown: this.shuttingDown,
+    };
+  }
+
+  private async run(): Promise<void> {
+    while (!this.shuttingDown && this.options.isIdle()) {
+      const prompt = this.queue.shift();
+      if (!prompt) return;
+      try {
+        const result = await this.analyzeWithRetry(prompt);
+        await this.options.onResult(prompt, result);
+      } catch (error) {
+        if (!this.shuttingDown) {
+          const normalized = normalizeError(error);
+          if (normalized instanceof AnalyzerConfigurationError) {
+            this.queue.unshift(prompt);
+            this.options.onError(normalized);
+            return;
+          }
+          this.options.onError(normalized);
+        }
+      } finally {
+        this.controller = undefined;
+      }
+    }
+  }
+
+  private async analyzeWithRetry(prompt: CollectedPrompt): Promise<AnalysisResult> {
+    let lastError: Error | undefined;
+    for (const delayMs of [0, RETRY_DELAY_MS]) {
+      if (this.shuttingDown) throw new DOMException("Aborted", "AbortError");
+      if (delayMs > 0) {
+        const signal = this.controller?.signal;
+        if (!signal) throw new Error("Analysis retry lost abort controller");
+        await abortableDelay(delayMs, signal);
+      }
+      if (this.shuttingDown) throw new DOMException("Aborted", "AbortError");
+
+      this.controller = new AbortController();
+      const signal = AbortSignal.any([
+        this.controller.signal,
+        AbortSignal.timeout(ANALYSIS_TIMEOUT_MS),
+      ]);
+      try {
+        return await this.options.analyzer.analyze(prompt, this.options.getPatterns(), signal);
+      } catch (error) {
+        const normalized = normalizeError(error);
+        if (
+          normalized.name === "AbortError"
+          || this.shuttingDown
+          || normalized instanceof AnalyzerConfigurationError
+        ) throw normalized;
+        lastError = normalized;
+      }
+    }
+    throw lastError ?? new Error("Analysis failed");
+  }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "pi-fluency",
+  "version": "0.1.0",
+  "description": "Learn from language mistakes in your Pi prompts",
+  "author": "Ihar Trafimovich",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "language-learning",
+    "grammar",
+    "writing"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unutranyholas/pi-fluency.git"
+  },
+  "homepage": "https://github.com/unutranyholas/pi-fluency#readme",
+  "bugs": {
+    "url": "https://github.com/unutranyholas/pi-fluency/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "extensions/pi-fluency/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run check"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/pi-fluency/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.80.10",
+    "@earendil-works/pi-coding-agent": ">=0.80.10",
+    "@earendil-works/pi-tui": ">=0.80.10"
+  },
+  "dependencies": {
+    "proper-lockfile": "^4.1.2"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.83.0",
+    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-tui": "^0.83.0",
+    "@types/node": "^22.0.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}