hyntx 2.5.4 → 2.7.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.
Files changed (4) hide show
  1. package/README.md +26 -8
  2. package/dist/cli.d.ts +105 -2
  3. package/dist/cli.js +1296 -173
  4. package/package.json +6 -1
package/README.md CHANGED
@@ -119,6 +119,15 @@ hyntx --from 2025-01-15 --to 2025-01-22 --project backend-api
119
119
 
120
120
  # Generate markdown report for yesterday
121
121
  hyntx --date yesterday --output yesterday-analysis.md
122
+
123
+ # Deep analysis with individual mode for critical project
124
+ hyntx -m individual --project production-api --date today
125
+
126
+ # Fast batch analysis across date range
127
+ hyntx --from 2025-01-15 --to 2025-01-20 --analysis-mode batch -o report.md
128
+
129
+ # Watch mode with individual analysis (slower but detailed)
130
+ hyntx --watch -m individual --project critical-app
122
131
  ```
123
132
 
124
133
  ## Configuration
@@ -151,16 +160,25 @@ hyntx --analysis-mode individual # Use individual mode
151
160
  hyntx -m individual # Short form
152
161
  ```
153
162
 
154
- #### Mode Comparison
163
+ #### Quick Mode Comparison
164
+
165
+ | Mode | Speed/Prompt | Use Case | Accuracy | When to Use |
166
+ | ---------- | ------------ | -------------------------- | -------- | ----------------------------------------- |
167
+ | Batch | ~300-400ms | Daily analysis, monitoring | Good | Quick feedback, large datasets |
168
+ | Individual | ~1-1.5s | Deep analysis, learning | Better | Quality-focused reviews, critical prompts |
169
+
170
+ **Speedup**: Batch mode is 3-4x faster than individual mode.
171
+
172
+ **Recommendation**: Use batch mode (default) for daily analysis to get fast feedback. Switch to individual mode when:
155
173
 
156
- | Mode | Speed/Prompt | Use Case | Accuracy |
157
- | ---------- | ------------ | -------------- | -------- |
158
- | Batch | ~300-400ms | Daily analysis | Good |
159
- | Individual | ~1-1.5s | Deep analysis | Better |
174
+ - You need detailed, nuanced feedback on each prompt
175
+ - You're learning prompt engineering patterns
176
+ - Analyzing high-stakes or complex prompts
177
+ - Conducting quality audits or teaching sessions
160
178
 
161
- **Recommendation**: Use batch mode for daily analysis (faster feedback), switch to individual mode when you need maximum quality or are learning prompt engineering techniques.
179
+ **Performance Note**: Numbers based on `llama3.2` on CPU. Actual speed varies by hardware, model size, and prompt complexity.
162
180
 
163
- **Note**: Performance numbers are based on `llama3.2` running on CPU. Actual speed depends on your hardware and model choice.
181
+ **Detailed Guide**: See [Analysis Modes Documentation](./docs/ANALYSIS_MODES.md) for comprehensive comparison, examples, and decision guidelines.
164
182
 
165
183
  ### Rules Configuration
166
184
 
@@ -972,7 +990,7 @@ Contributions are welcome! Please:
972
990
 
973
991
  ## Roadmap
974
992
 
975
- For detailed development roadmap, planned features, and implementation status, see [docs/ROADMAP.md](docs/ROADMAP.md).
993
+ For detailed development roadmap, planned features, and implementation status, see [GitHub Issues](https://github.com/jmlweb/hyntx/issues) and [GitHub Projects](https://github.com/jmlweb/hyntx/projects).
976
994
 
977
995
  ## License
978
996
 
package/dist/cli.d.ts CHANGED
@@ -109,6 +109,104 @@ type AnalysisProvider = {
109
109
  analyze(prompts: readonly string[], date: string, context?: ProjectContext): Promise<AnalysisResult>;
110
110
  getBatchLimits?(): ProviderLimits;
111
111
  };
112
+ /**
113
+ * Descriptive statistics for a dataset.
114
+ * Provides comprehensive statistical measures beyond simple averages.
115
+ */
116
+ type DescriptiveStats = {
117
+ readonly count: number;
118
+ readonly mean: number;
119
+ readonly median: number;
120
+ readonly stdDev: number;
121
+ readonly variance: number;
122
+ readonly min: number;
123
+ readonly max: number;
124
+ readonly range: number;
125
+ readonly percentiles: {
126
+ readonly p25: number;
127
+ readonly p50: number;
128
+ readonly p75: number;
129
+ readonly p90: number;
130
+ readonly p95: number;
131
+ };
132
+ readonly skewness: number;
133
+ readonly kurtosis: number;
134
+ };
135
+ /**
136
+ * A single cluster from clustering analysis.
137
+ */
138
+ type Cluster = {
139
+ readonly id: number;
140
+ readonly indices: readonly number[];
141
+ readonly size: number;
142
+ };
143
+ /**
144
+ * A labeled cluster with interpretation.
145
+ */
146
+ type LabeledCluster = Cluster & {
147
+ readonly label: string;
148
+ readonly keywords: readonly string[];
149
+ readonly representativePrompt: string;
150
+ readonly dominantIssue?: string;
151
+ };
152
+ /**
153
+ * Complete cluster analysis with labeled clusters.
154
+ */
155
+ type ClusterAnalysis = {
156
+ readonly clusters: readonly LabeledCluster[];
157
+ readonly metrics: {
158
+ readonly silhouetteScore: number;
159
+ readonly inertia: number;
160
+ readonly optimalK: number;
161
+ };
162
+ readonly summary: {
163
+ readonly totalPrompts: number;
164
+ readonly avgClusterSize: number;
165
+ readonly largestCluster: number;
166
+ readonly smallestCluster: number;
167
+ };
168
+ };
169
+ /**
170
+ * Result of trend analysis using linear regression.
171
+ */
172
+ type TrendAnalysis = {
173
+ readonly slope: number;
174
+ readonly intercept: number;
175
+ readonly rSquared: number;
176
+ readonly direction: 'improving' | 'stable' | 'declining';
177
+ readonly confidence: 'high' | 'medium' | 'low';
178
+ readonly projectedScore: (days: number) => number;
179
+ };
180
+ /**
181
+ * Enhanced statistics extending the basic AnalysisStats.
182
+ * Backward compatible - all enhanced fields are optional.
183
+ */
184
+ type EnhancedAnalysisStats = AnalysisStats & {
185
+ readonly descriptive?: DescriptiveStats;
186
+ readonly specificity?: {
187
+ readonly mean: number;
188
+ readonly distribution: readonly number[];
189
+ };
190
+ readonly lexical?: {
191
+ readonly avgComplexity: number;
192
+ readonly avgWordCount: number;
193
+ };
194
+ readonly timing?: {
195
+ readonly analysisStarted: number;
196
+ readonly analysisCompleted: number;
197
+ readonly durationMs: number;
198
+ readonly tokensProcessed: number;
199
+ };
200
+ };
201
+ /**
202
+ * Enhanced analysis result with optional data science features.
203
+ * Backward compatible - all enhanced fields are optional.
204
+ */
205
+ type EnhancedAnalysisResult = AnalysisResult & {
206
+ readonly enhancedStats?: EnhancedAnalysisStats;
207
+ readonly clusters?: ClusterAnalysis;
208
+ readonly trend?: TrendAnalysis;
209
+ };
112
210
 
113
211
  /**
114
212
  * Terminal reporter for analysis results.
@@ -168,6 +266,10 @@ type ParsedArgs = {
168
266
  readonly mcpServer: boolean;
169
267
  readonly listRules: boolean;
170
268
  readonly analysisMode: 'batch' | 'individual';
269
+ readonly detailedStats: boolean;
270
+ readonly showClusters: boolean;
271
+ readonly trendAnalysis: boolean;
272
+ readonly noEmbeddings: boolean;
171
273
  };
172
274
  /**
173
275
  * Parses command-line arguments.
@@ -307,11 +409,12 @@ declare function runWatchMode(provider: AnalysisProvider, args: ParsedArgs, cont
307
409
  /**
308
410
  * Displays analysis results.
309
411
  *
310
- * @param result - Analysis result
412
+ * @param result - Analysis result (can be enhanced)
311
413
  * @param format - Output format
312
414
  * @param compact - Whether to use compact JSON (only relevant for JSON format)
415
+ * @param args - Parsed arguments to determine if enhanced features are enabled
313
416
  */
314
- declare function displayResults(result: AnalysisResult, format: 'terminal' | 'json', compact: boolean): void;
417
+ declare function displayResults(result: AnalysisResult | EnhancedAnalysisResult, format: 'terminal' | 'json', compact: boolean, args?: ParsedArgs): void;
315
418
  /**
316
419
  * Handles errors and exits with appropriate code.
317
420
  *