@semanticintent/semantic-chirp-intelligence-mcp 3.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/.env.example +8 -0
- package/LICENSE +21 -0
- package/README.md +250 -0
- package/authenticate.js +207 -0
- package/build/analyses/BreakoutAnalysis.js +386 -0
- package/build/analyses/GamesInHandAnalysis.js +257 -0
- package/build/analyses/IceAnalysis.js +316 -0
- package/build/analyses/LineupAnalysis.js +284 -0
- package/build/analyses/StreamingAnalysis.js +246 -0
- package/build/analyses/WeekendStreamAnalysis.js +599 -0
- package/build/config/chirp-styles.js +36 -0
- package/build/config/personality-modes.js +36 -0
- package/build/config/tool-metadata.js +113 -0
- package/build/domain/governance.js +322 -0
- package/build/domain/types.js +14 -0
- package/build/experimental/semantic-breakout-tool.js +188 -0
- package/build/experimental/semantic-intent-parser.js +222 -0
- package/build/experimental/semantic-tool-integration.js +146 -0
- package/build/experimental/test-parser.js +61 -0
- package/build/index.js +1549 -0
- package/build/services/ChirpIntelligence.js +213 -0
- package/build/services/YahooApiClient.js +309 -0
- package/build/template/AnalysisTemplate.js +167 -0
- package/build/types.js +2 -0
- package/package.json +50 -0
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tool Metadata Configuration
|
|
3
|
+
*
|
|
4
|
+
* Semantic Anchoring Governance markers for all tools
|
|
5
|
+
*/
|
|
6
|
+
export const TOOL_METADATA = {
|
|
7
|
+
get_team_roster: {
|
|
8
|
+
chirp_style: "analytical_assessment",
|
|
9
|
+
discovery_tags: ["roster", "lineup", "players", "status", "team"],
|
|
10
|
+
intent_category: "team_assessment",
|
|
11
|
+
hockey_context: "roster_analysis",
|
|
12
|
+
chirp_potential: "roster_weaknesses"
|
|
13
|
+
},
|
|
14
|
+
get_league_standings: {
|
|
15
|
+
chirp_style: "competitive_reality",
|
|
16
|
+
discovery_tags: ["standings", "league", "competition", "rankings", "position"],
|
|
17
|
+
intent_category: "league_awareness",
|
|
18
|
+
hockey_context: "competitive_landscape",
|
|
19
|
+
chirp_potential: "standings_truth"
|
|
20
|
+
},
|
|
21
|
+
get_current_matchup: {
|
|
22
|
+
chirp_style: "matchup_assessment",
|
|
23
|
+
discovery_tags: ["matchup", "opponent", "week", "competition", "stats"],
|
|
24
|
+
intent_category: "weekly_strategy",
|
|
25
|
+
hockey_context: "head_to_head_battle",
|
|
26
|
+
chirp_potential: "matchup_reality"
|
|
27
|
+
},
|
|
28
|
+
get_games_in_hand: {
|
|
29
|
+
chirp_style: "strategic_advantage",
|
|
30
|
+
discovery_tags: ["schedule", "advantage", "games", "strategy", "matchup"],
|
|
31
|
+
intent_category: "competitive_intelligence",
|
|
32
|
+
hockey_context: "schedule_warfare",
|
|
33
|
+
chirp_potential: "schedule_domination",
|
|
34
|
+
// 🆕 Template Pattern Metadata
|
|
35
|
+
uses_template_pattern: true,
|
|
36
|
+
analysis_class: "GamesInHandAnalysis",
|
|
37
|
+
template_version: "1.0.0",
|
|
38
|
+
analysis_type: "schedule_advantage"
|
|
39
|
+
},
|
|
40
|
+
get_streaming_recommendations: {
|
|
41
|
+
chirp_style: "opportunity_hunter",
|
|
42
|
+
discovery_tags: ["pickups", "waivers", "streaming", "schedule", "trends"],
|
|
43
|
+
intent_category: "acquisition_strategy",
|
|
44
|
+
hockey_context: "waiver_wire_mastery",
|
|
45
|
+
chirp_potential: "pickup_strategy",
|
|
46
|
+
// 🆕 Template Pattern Metadata
|
|
47
|
+
uses_template_pattern: true,
|
|
48
|
+
analysis_class: "StreamingAnalysis",
|
|
49
|
+
template_version: "1.0.0",
|
|
50
|
+
analysis_type: "streaming_strategy"
|
|
51
|
+
},
|
|
52
|
+
get_roster_transaction_recommendations: {
|
|
53
|
+
chirp_style: "ice_cold_truth",
|
|
54
|
+
discovery_tags: ["optimization", "ICE", "championship", "decisions", "transactions"],
|
|
55
|
+
intent_category: "ultimate_advisor",
|
|
56
|
+
hockey_context: "league_domination",
|
|
57
|
+
chirp_potential: "brutal_optimization",
|
|
58
|
+
is_ice_engine: true,
|
|
59
|
+
tool_semantic_identity: "ICE - Intent Chirp Engine",
|
|
60
|
+
// 🆕 Template Pattern Metadata
|
|
61
|
+
uses_template_pattern: true,
|
|
62
|
+
analysis_class: "IceAnalysis",
|
|
63
|
+
template_version: "1.0.0",
|
|
64
|
+
analysis_type: "ice_roster"
|
|
65
|
+
},
|
|
66
|
+
get_weekly_stats: {
|
|
67
|
+
chirp_style: "performance_review",
|
|
68
|
+
discovery_tags: ["stats", "weekly", "performance", "matchup", "analysis"],
|
|
69
|
+
intent_category: "performance_tracking",
|
|
70
|
+
hockey_context: "stat_battle",
|
|
71
|
+
chirp_potential: "weekly_performance"
|
|
72
|
+
},
|
|
73
|
+
compare_matchup: {
|
|
74
|
+
chirp_style: "head_to_head_analysis",
|
|
75
|
+
discovery_tags: ["comparison", "matchup", "opponent", "strategy", "categories"],
|
|
76
|
+
intent_category: "tactical_analysis",
|
|
77
|
+
hockey_context: "category_warfare",
|
|
78
|
+
chirp_potential: "matchup_insights"
|
|
79
|
+
},
|
|
80
|
+
optimize_lineup: {
|
|
81
|
+
chirp_style: "lineup_optimization",
|
|
82
|
+
discovery_tags: ["lineup", "optimization", "active", "bench", "strategy"],
|
|
83
|
+
intent_category: "daily_management",
|
|
84
|
+
hockey_context: "lineup_strategy",
|
|
85
|
+
chirp_potential: "lineup_fixes",
|
|
86
|
+
// 🆕 Template Pattern Metadata
|
|
87
|
+
uses_template_pattern: true,
|
|
88
|
+
analysis_class: "LineupAnalysis",
|
|
89
|
+
template_version: "1.0.0",
|
|
90
|
+
analysis_type: "lineup_optimization"
|
|
91
|
+
},
|
|
92
|
+
search_players: {
|
|
93
|
+
chirp_style: "player_discovery",
|
|
94
|
+
discovery_tags: ["search", "players", "available", "free_agents", "discovery"],
|
|
95
|
+
intent_category: "player_research",
|
|
96
|
+
hockey_context: "talent_scouting",
|
|
97
|
+
chirp_potential: "player_insights"
|
|
98
|
+
},
|
|
99
|
+
get_player_stats: {
|
|
100
|
+
chirp_style: "player_evaluation",
|
|
101
|
+
discovery_tags: ["stats", "player", "performance", "evaluation", "analysis"],
|
|
102
|
+
intent_category: "player_analysis",
|
|
103
|
+
hockey_context: "individual_assessment",
|
|
104
|
+
chirp_potential: "player_reality"
|
|
105
|
+
},
|
|
106
|
+
get_trending_players: {
|
|
107
|
+
chirp_style: "trend_hunting",
|
|
108
|
+
discovery_tags: ["trends", "hot", "cold", "momentum", "pickups"],
|
|
109
|
+
intent_category: "market_intelligence",
|
|
110
|
+
hockey_context: "waiver_trends",
|
|
111
|
+
chirp_potential: "trend_opportunities"
|
|
112
|
+
}
|
|
113
|
+
};
|
|
@@ -0,0 +1,322 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 🏛️ Semantic Anchoring Governance System
|
|
3
|
+
*
|
|
4
|
+
* This module implements the complete Semantic Anchoring Governance framework
|
|
5
|
+
* across all 5 phases:
|
|
6
|
+
* - Phase 1: Semantic Markers and Tool Identity
|
|
7
|
+
* - Phase 2: Immutability Protection
|
|
8
|
+
* - Phase 3: Semantic Contract Validation
|
|
9
|
+
* - Phase 4: Documentation
|
|
10
|
+
* - Phase 5: Runtime Governance Enforcement
|
|
11
|
+
*
|
|
12
|
+
* Governance Rules:
|
|
13
|
+
* - Rule 1: Semantic Over Structural - Decisions based on semantic properties
|
|
14
|
+
* - Rule 2: Intent Preservation - Semantic intent validated through transformations
|
|
15
|
+
* - Rule 3: Observable Anchoring - Decisions based on observable semantic properties
|
|
16
|
+
* - Rule 4: Immutability Protection - Semantic contracts cannot be mutated
|
|
17
|
+
*/
|
|
18
|
+
// ==========================================
|
|
19
|
+
// 📈 Runtime Governance Monitor
|
|
20
|
+
// ==========================================
|
|
21
|
+
/**
|
|
22
|
+
* 🏛️ GOVERNANCE_MONITOR
|
|
23
|
+
*
|
|
24
|
+
* Central monitoring system for all governance enforcement.
|
|
25
|
+
* Tracks violations, contracts, immutability enforcement, and semantic decisions.
|
|
26
|
+
*
|
|
27
|
+
* Enhanced in Template Pattern Migration:
|
|
28
|
+
* - Added analysis execution tracking
|
|
29
|
+
* - Added performance monitoring
|
|
30
|
+
* - Added analysis-specific metrics
|
|
31
|
+
*/
|
|
32
|
+
export const GOVERNANCE_MONITOR = {
|
|
33
|
+
// Existing governance metrics (Phases 1-5)
|
|
34
|
+
violations: [],
|
|
35
|
+
contracts_validated: 0,
|
|
36
|
+
immutability_enforced: 0,
|
|
37
|
+
semantic_decisions: 0,
|
|
38
|
+
// 🆕 NEW: Analysis tracking (Template Pattern)
|
|
39
|
+
analyses_executed: 0,
|
|
40
|
+
analysis_by_type: new Map(),
|
|
41
|
+
analysis_durations: [],
|
|
42
|
+
/**
|
|
43
|
+
* Track a governance violation
|
|
44
|
+
* Automatically adds timestamp and maintains violation history
|
|
45
|
+
*/
|
|
46
|
+
trackViolation(violation) {
|
|
47
|
+
this.violations.push({
|
|
48
|
+
...violation,
|
|
49
|
+
timestamp: new Date()
|
|
50
|
+
});
|
|
51
|
+
// Keep only last 100 violations to prevent memory growth
|
|
52
|
+
if (this.violations.length > 100) {
|
|
53
|
+
this.violations = this.violations.slice(-100);
|
|
54
|
+
}
|
|
55
|
+
},
|
|
56
|
+
/**
|
|
57
|
+
* 🆕 Track analysis start
|
|
58
|
+
* Called when template method begins execution
|
|
59
|
+
*/
|
|
60
|
+
trackAnalysisStart(type) {
|
|
61
|
+
if (process.env.NODE_ENV === "development") {
|
|
62
|
+
console.log(`[GOVERNANCE] Analysis started: ${type}`);
|
|
63
|
+
}
|
|
64
|
+
},
|
|
65
|
+
/**
|
|
66
|
+
* 🆕 Track analysis completion
|
|
67
|
+
* Records execution time and updates metrics
|
|
68
|
+
*/
|
|
69
|
+
trackAnalysisComplete(type, duration_ms) {
|
|
70
|
+
this.analyses_executed++;
|
|
71
|
+
this.analysis_by_type.set(type, (this.analysis_by_type.get(type) || 0) + 1);
|
|
72
|
+
this.analysis_durations.push({
|
|
73
|
+
type,
|
|
74
|
+
duration_ms,
|
|
75
|
+
timestamp: new Date()
|
|
76
|
+
});
|
|
77
|
+
// Keep only last 100 duration records
|
|
78
|
+
if (this.analysis_durations.length > 100) {
|
|
79
|
+
this.analysis_durations = this.analysis_durations.slice(-100);
|
|
80
|
+
}
|
|
81
|
+
if (process.env.NODE_ENV === "development") {
|
|
82
|
+
console.log(`[GOVERNANCE] Analysis completed: ${type} (${duration_ms}ms)`);
|
|
83
|
+
}
|
|
84
|
+
},
|
|
85
|
+
/**
|
|
86
|
+
* Get governance health report
|
|
87
|
+
* Returns comprehensive metrics about system health
|
|
88
|
+
*/
|
|
89
|
+
getHealthReport() {
|
|
90
|
+
const warnings = this.violations.filter(v => v.severity === "warning").length;
|
|
91
|
+
const errors = this.violations.filter(v => v.severity === "error").length;
|
|
92
|
+
return {
|
|
93
|
+
total_violations: this.violations.length,
|
|
94
|
+
warnings,
|
|
95
|
+
errors,
|
|
96
|
+
contracts_validated: this.contracts_validated,
|
|
97
|
+
immutability_enforced: this.immutability_enforced,
|
|
98
|
+
semantic_decisions: this.semantic_decisions,
|
|
99
|
+
recent_violations: this.violations.slice(-10), // Last 10 violations
|
|
100
|
+
// 🆕 Analysis metrics
|
|
101
|
+
analyses_executed: this.analyses_executed,
|
|
102
|
+
analysis_by_type: Object.fromEntries(this.analysis_by_type),
|
|
103
|
+
avg_duration_ms: this.calculateAverageDuration(),
|
|
104
|
+
slowest_analysis: this.getSlowestAnalysis()
|
|
105
|
+
};
|
|
106
|
+
},
|
|
107
|
+
/**
|
|
108
|
+
* 🆕 Calculate average analysis duration
|
|
109
|
+
*/
|
|
110
|
+
calculateAverageDuration() {
|
|
111
|
+
if (this.analysis_durations.length === 0)
|
|
112
|
+
return 0;
|
|
113
|
+
const total = this.analysis_durations.reduce((sum, d) => sum + d.duration_ms, 0);
|
|
114
|
+
return Math.round(total / this.analysis_durations.length);
|
|
115
|
+
},
|
|
116
|
+
/**
|
|
117
|
+
* 🆕 Get slowest analysis from recent executions
|
|
118
|
+
*/
|
|
119
|
+
getSlowestAnalysis() {
|
|
120
|
+
if (this.analysis_durations.length === 0)
|
|
121
|
+
return null;
|
|
122
|
+
return this.analysis_durations.reduce((slowest, current) => current.duration_ms > slowest.duration_ms ? current : slowest);
|
|
123
|
+
},
|
|
124
|
+
/**
|
|
125
|
+
* Reset monitoring counters (for testing)
|
|
126
|
+
*/
|
|
127
|
+
reset() {
|
|
128
|
+
this.violations = [];
|
|
129
|
+
this.contracts_validated = 0;
|
|
130
|
+
this.immutability_enforced = 0;
|
|
131
|
+
this.semantic_decisions = 0;
|
|
132
|
+
this.analyses_executed = 0;
|
|
133
|
+
this.analysis_by_type.clear();
|
|
134
|
+
this.analysis_durations = [];
|
|
135
|
+
}
|
|
136
|
+
};
|
|
137
|
+
// ==========================================
|
|
138
|
+
// 🔍 Semantic Contract Audit Logger
|
|
139
|
+
// ==========================================
|
|
140
|
+
/**
|
|
141
|
+
* Audit semantic contract operations
|
|
142
|
+
* Logs contract state during validation, enforcement, and decisions
|
|
143
|
+
*
|
|
144
|
+
* @param contract - The semantic contract being audited
|
|
145
|
+
* @param toolName - Name of the tool processing the contract
|
|
146
|
+
* @param phase - Which phase of processing (validation, enforcement, decision)
|
|
147
|
+
*/
|
|
148
|
+
export function auditSemanticContract(contract, toolName, phase) {
|
|
149
|
+
const audit = {
|
|
150
|
+
phase,
|
|
151
|
+
tool_name: toolName,
|
|
152
|
+
semantic_intent: contract.semantic_intent,
|
|
153
|
+
enable_chirp: contract.enable_chirp,
|
|
154
|
+
chirp_intensity: contract.chirp_intensity,
|
|
155
|
+
personality_mode: contract.personality_mode,
|
|
156
|
+
tool_context: contract.tool_context,
|
|
157
|
+
timestamp: new Date().toISOString()
|
|
158
|
+
};
|
|
159
|
+
// Log to console in development mode
|
|
160
|
+
if (process.env.NODE_ENV === "development") {
|
|
161
|
+
console.log(`🔍 Semantic Audit [${phase}]:`, JSON.stringify(audit, null, 2));
|
|
162
|
+
}
|
|
163
|
+
// Update monitoring counters
|
|
164
|
+
if (phase === "validation") {
|
|
165
|
+
GOVERNANCE_MONITOR.contracts_validated++;
|
|
166
|
+
}
|
|
167
|
+
else if (phase === "enforcement") {
|
|
168
|
+
GOVERNANCE_MONITOR.immutability_enforced++;
|
|
169
|
+
}
|
|
170
|
+
else if (phase === "decision") {
|
|
171
|
+
GOVERNANCE_MONITOR.semantic_decisions++;
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
// ==========================================
|
|
175
|
+
// 🏥 Governance Health Check
|
|
176
|
+
// ==========================================
|
|
177
|
+
/**
|
|
178
|
+
* Check governance system health
|
|
179
|
+
* Returns status and actionable recommendations
|
|
180
|
+
*/
|
|
181
|
+
export function checkGovernanceHealth() {
|
|
182
|
+
const report = GOVERNANCE_MONITOR.getHealthReport();
|
|
183
|
+
const recommendations = [];
|
|
184
|
+
let status = "healthy";
|
|
185
|
+
// Check error rate
|
|
186
|
+
if (report.errors > 10) {
|
|
187
|
+
status = "critical";
|
|
188
|
+
recommendations.push("Critical: High error rate detected. Review recent violations immediately.");
|
|
189
|
+
}
|
|
190
|
+
else if (report.errors > 0) {
|
|
191
|
+
status = "degraded";
|
|
192
|
+
recommendations.push("Warning: Governance errors detected. Review violation logs.");
|
|
193
|
+
}
|
|
194
|
+
// Check warning rate
|
|
195
|
+
if (report.warnings > 20) {
|
|
196
|
+
if (status !== "critical")
|
|
197
|
+
status = "degraded";
|
|
198
|
+
recommendations.push("Warning: High warning rate. Review semantic contract usage patterns.");
|
|
199
|
+
}
|
|
200
|
+
// Check validation rate
|
|
201
|
+
if (report.contracts_validated === 0) {
|
|
202
|
+
recommendations.push("Info: No contracts validated yet. System may not be processing requests.");
|
|
203
|
+
}
|
|
204
|
+
// 🆕 Check analysis performance
|
|
205
|
+
if (report.avg_duration_ms > 5000) {
|
|
206
|
+
if (status !== "critical")
|
|
207
|
+
status = "degraded";
|
|
208
|
+
recommendations.push(`Performance: Average analysis duration is ${report.avg_duration_ms}ms (threshold: 5000ms)`);
|
|
209
|
+
}
|
|
210
|
+
if (recommendations.length === 0) {
|
|
211
|
+
recommendations.push("System is operating within governance parameters.");
|
|
212
|
+
}
|
|
213
|
+
return { status, report, recommendations };
|
|
214
|
+
}
|
|
215
|
+
// ==========================================
|
|
216
|
+
// 📚 Semantic Contract Validation
|
|
217
|
+
// ==========================================
|
|
218
|
+
/**
|
|
219
|
+
* 🏛️ validateSemanticChirpContract Function:
|
|
220
|
+
* Enforces Semantic Anchoring Governance Rule 2 (Intent Preservation) by validating
|
|
221
|
+
* that semantic intent is preserved through chirp parameter transformations.
|
|
222
|
+
*
|
|
223
|
+
* Purpose:
|
|
224
|
+
* Ensures that chirp parameters maintain semantic coherence and prevents accidental
|
|
225
|
+
* or malicious violations of user intent.
|
|
226
|
+
*
|
|
227
|
+
* Governance Principles:
|
|
228
|
+
* - User intent has highest priority and must never be overridden
|
|
229
|
+
* - System defaults should be semantically consistent
|
|
230
|
+
* - Tool-specific overrides must be confined to their tool context
|
|
231
|
+
* - Conflicting intentions should be detected and reported
|
|
232
|
+
*
|
|
233
|
+
* Validation Cases:
|
|
234
|
+
*
|
|
235
|
+
* Case 1: User-Requested Disable
|
|
236
|
+
* Scenario: User explicitly sets enable_chirp=false with semantic_intent="user_requested"
|
|
237
|
+
* Action: Allow and preserve user intent (highest priority)
|
|
238
|
+
* Governance: Protects user autonomy and semantic control
|
|
239
|
+
*
|
|
240
|
+
* Case 2: Default Behavior
|
|
241
|
+
* Scenario: enable_chirp is undefined or true (system default)
|
|
242
|
+
* Action: Allow as valid default semantic behavior
|
|
243
|
+
* Governance: System defaults are semantically consistent
|
|
244
|
+
*
|
|
245
|
+
* Case 3: Ice Cold Intensity Validation
|
|
246
|
+
* Scenario: chirp_intensity="ice_cold" without explicit semantic intent
|
|
247
|
+
* Action: Warn if used on non-ICE tools (may be accidental)
|
|
248
|
+
* Governance: Prevents unintentional semantic shifts in tool behavior
|
|
249
|
+
* Rationale: ice_cold is semantically strong and should be intentional
|
|
250
|
+
*
|
|
251
|
+
* Case 4: Conflicting Intent Detection
|
|
252
|
+
* Scenario: enable_chirp=false but chirp_intensity is specified
|
|
253
|
+
* Action: Log warning about semantic contradiction
|
|
254
|
+
* Governance: Detects semantic incoherence in parameters
|
|
255
|
+
* Rationale: Disabled chirp with intensity setting is semantically inconsistent
|
|
256
|
+
*
|
|
257
|
+
* Case 5: Tool Override Protection
|
|
258
|
+
* Scenario: semantic_intent="tool_override" with mismatched tool_context
|
|
259
|
+
* Action: Throw error (strict enforcement)
|
|
260
|
+
* Governance: Prevents semantic contract violations across tool boundaries
|
|
261
|
+
* Rationale: Tool overrides must stay within their semantic domain
|
|
262
|
+
*
|
|
263
|
+
* @param contract - The semantic contract to validate
|
|
264
|
+
* @param toolName - Name of the tool requesting validation
|
|
265
|
+
* @param toolMetadata - Optional tool metadata for semantic property checks
|
|
266
|
+
*/
|
|
267
|
+
export function validateSemanticChirpContract(contract, toolName, toolMetadata) {
|
|
268
|
+
// 🔍 Phase 5: Audit contract validation
|
|
269
|
+
auditSemanticContract(contract, toolName, "validation");
|
|
270
|
+
// Rule 2: Intent Preservation - validate semantic coherence
|
|
271
|
+
// Case 1: User explicitly disabled chirp - valid semantic intent
|
|
272
|
+
if (contract.enable_chirp === false && contract.semantic_intent === "user_requested") {
|
|
273
|
+
return; // Valid: User intent to disable is preserved
|
|
274
|
+
}
|
|
275
|
+
// Case 2: Default behavior - chirp enabled unless explicitly disabled
|
|
276
|
+
if (contract.enable_chirp === undefined || contract.enable_chirp === true) {
|
|
277
|
+
// This is valid default behavior
|
|
278
|
+
return;
|
|
279
|
+
}
|
|
280
|
+
// Case 3: ice_cold intensity should be intentional, not accidental
|
|
281
|
+
if (contract.chirp_intensity === "ice_cold" && !contract.semantic_intent) {
|
|
282
|
+
// Log warning but allow (ICE tool deliberately uses ice_cold as default)
|
|
283
|
+
if (toolMetadata && !toolMetadata.is_ice_engine) {
|
|
284
|
+
const warning = `ice_cold intensity without explicit intent on non-ICE tool '${toolName}'`;
|
|
285
|
+
console.error(`⚠️ Semantic Warning: ${warning}`);
|
|
286
|
+
// 📊 Phase 5: Track governance violation
|
|
287
|
+
GOVERNANCE_MONITOR.trackViolation({
|
|
288
|
+
rule: "Rule 2 - Intent Preservation",
|
|
289
|
+
severity: "warning",
|
|
290
|
+
tool_name: toolName,
|
|
291
|
+
violation_type: "unintentional_intensity",
|
|
292
|
+
details: warning
|
|
293
|
+
});
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
// Case 4: Detect conflicting semantic intentions
|
|
297
|
+
if (contract.enable_chirp === false && contract.chirp_intensity) {
|
|
298
|
+
const warning = `Conflicting intent - chirp disabled but intensity specified for '${toolName}'`;
|
|
299
|
+
console.error(`⚠️ Semantic Warning: ${warning}`);
|
|
300
|
+
// 📊 Phase 5: Track governance violation
|
|
301
|
+
GOVERNANCE_MONITOR.trackViolation({
|
|
302
|
+
rule: "Rule 2 - Intent Preservation",
|
|
303
|
+
severity: "warning",
|
|
304
|
+
tool_name: toolName,
|
|
305
|
+
violation_type: "conflicting_intent",
|
|
306
|
+
details: warning
|
|
307
|
+
});
|
|
308
|
+
}
|
|
309
|
+
// Case 5: Tool override should only be used by system, not user input
|
|
310
|
+
if (contract.semantic_intent === "tool_override" && contract.tool_context !== toolName) {
|
|
311
|
+
const error = `tool_override intent mismatch for '${toolName}' - expected context '${toolName}', got '${contract.tool_context}'`;
|
|
312
|
+
// 📊 Phase 5: Track governance violation
|
|
313
|
+
GOVERNANCE_MONITOR.trackViolation({
|
|
314
|
+
rule: "Rule 2 - Intent Preservation",
|
|
315
|
+
severity: "error",
|
|
316
|
+
tool_name: toolName,
|
|
317
|
+
violation_type: "tool_override_mismatch",
|
|
318
|
+
details: error
|
|
319
|
+
});
|
|
320
|
+
throw new Error(`🚨 Semantic contract violation: ${error}`);
|
|
321
|
+
}
|
|
322
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 🏛️ Domain Types - Semantic Chirp Intelligence MCP
|
|
3
|
+
*
|
|
4
|
+
* This file contains all core type definitions and interfaces for the
|
|
5
|
+
* Yahoo Fantasy MCP with Template Method Pattern implementation.
|
|
6
|
+
*
|
|
7
|
+
* Organized by domain:
|
|
8
|
+
* - Analysis Types
|
|
9
|
+
* - Chirp Intelligence
|
|
10
|
+
* - Yahoo API Data
|
|
11
|
+
* - Recommendations
|
|
12
|
+
* - Responses
|
|
13
|
+
*/
|
|
14
|
+
export {};
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Semantic Breakout Tool Integration
|
|
3
|
+
*
|
|
4
|
+
* Implements breakout player analysis using semantic intent pattern.
|
|
5
|
+
* This tool uses natural language intent to auto-configure the MCP tool.
|
|
6
|
+
*/
|
|
7
|
+
import { SemanticIntentParser } from './semantic-intent-parser.js';
|
|
8
|
+
/**
|
|
9
|
+
* Semantic tool definition for breakout player analysis
|
|
10
|
+
*
|
|
11
|
+
* This comprehensive prompt integrates:
|
|
12
|
+
* - Data-driven predictability (40% recent, 30% projections, 20% opportunity, 10% risk)
|
|
13
|
+
* - External source references (Rotowire, NHL EDGE, DobberHockey)
|
|
14
|
+
* - Position-specific filtering
|
|
15
|
+
* - League context awareness
|
|
16
|
+
*/
|
|
17
|
+
export const SEMANTIC_BREAKOUT_ANALYSIS = {
|
|
18
|
+
name: "analyze_breakout_players",
|
|
19
|
+
description: "Analyze free agents to identify top pickups and breakout candidates using comprehensive data-driven scoring",
|
|
20
|
+
semanticIntent: `
|
|
21
|
+
I analyze free agents in Yahoo Fantasy Hockey to recommend top 5-10 pickups and 3-5 breakout candidates.
|
|
22
|
+
I use a predictable scoring formula: 40% recent performance + 30% projections + 20% opportunity - 10% risk.
|
|
23
|
+
I focus on players under 50% owned and provide position-specific analysis.
|
|
24
|
+
|
|
25
|
+
I need: position filter (optional array of strings like ["C", "RW"]),
|
|
26
|
+
ownership threshold (optional number, default 50),
|
|
27
|
+
breakout age max (optional number, default 26),
|
|
28
|
+
minimum score (optional number, default 0),
|
|
29
|
+
max results (optional number, default 10),
|
|
30
|
+
chirp intensity (optional string),
|
|
31
|
+
personality mode (optional string),
|
|
32
|
+
enable chirp (optional boolean)
|
|
33
|
+
|
|
34
|
+
I will: Yahoo API calls, statistical analysis, trend detection, opportunity scoring, risk assessment
|
|
35
|
+
|
|
36
|
+
I return: Top pickups with scores, breakout candidates, position breakdown, market intelligence
|
|
37
|
+
|
|
38
|
+
I estimate: moderate complexity, 3000 tokens
|
|
39
|
+
`
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* Parse semantic intent for breakout analysis
|
|
43
|
+
*/
|
|
44
|
+
export function parseBreakoutAnalysisIntent() {
|
|
45
|
+
const parser = new SemanticIntentParser();
|
|
46
|
+
return parser.parseIntent(SEMANTIC_BREAKOUT_ANALYSIS.semanticIntent);
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Get MCP input schema from semantic intent
|
|
50
|
+
*/
|
|
51
|
+
export function getBreakoutAnalysisInputSchema() {
|
|
52
|
+
const parsed = parseBreakoutAnalysisIntent();
|
|
53
|
+
// Build schema from parsed parameters
|
|
54
|
+
const properties = {};
|
|
55
|
+
const required = [];
|
|
56
|
+
for (const param of parsed.parameters) {
|
|
57
|
+
properties[param.name] = {
|
|
58
|
+
type: param.type,
|
|
59
|
+
description: param.description
|
|
60
|
+
};
|
|
61
|
+
if (param.required) {
|
|
62
|
+
required.push(param.name);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
// Add enum constraints for specific parameters
|
|
66
|
+
if (properties.chirp_intensity) {
|
|
67
|
+
properties.chirp_intensity.enum = ['gentle', 'standard', 'savage', 'ice_cold'];
|
|
68
|
+
}
|
|
69
|
+
if (properties.personality_mode) {
|
|
70
|
+
properties.personality_mode.enum = ['analytical', 'motivational', 'roast_master', 'championship_coach'];
|
|
71
|
+
}
|
|
72
|
+
if (properties.position_filter) {
|
|
73
|
+
properties.position_filter.items = { type: 'string' };
|
|
74
|
+
}
|
|
75
|
+
return {
|
|
76
|
+
type: "object",
|
|
77
|
+
properties,
|
|
78
|
+
required: required.length > 0 ? required : undefined
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Execute breakout analysis with semantic configuration
|
|
83
|
+
*/
|
|
84
|
+
export async function executeBreakoutAnalysis(args, breakoutAnalysis) {
|
|
85
|
+
const parsed = parseBreakoutAnalysisIntent();
|
|
86
|
+
// Build semantic contract
|
|
87
|
+
const semanticContract = {
|
|
88
|
+
chirp_intensity: args.chirp_intensity || 'standard',
|
|
89
|
+
personality_mode: args.personality_mode || 'analytical',
|
|
90
|
+
enable_chirp: args.enable_chirp !== false,
|
|
91
|
+
semantic_intent: 'user_requested',
|
|
92
|
+
tool_context: 'analyze_breakout_players'
|
|
93
|
+
};
|
|
94
|
+
// Build analysis args
|
|
95
|
+
const analysisArgs = {
|
|
96
|
+
position_filter: args.position_filter,
|
|
97
|
+
ownership_threshold: args.ownership_threshold,
|
|
98
|
+
breakout_age_max: args.breakout_age_max,
|
|
99
|
+
min_score: args.min_score,
|
|
100
|
+
max_results: args.max_results
|
|
101
|
+
};
|
|
102
|
+
try {
|
|
103
|
+
// Execute analysis using template pattern
|
|
104
|
+
const result = await breakoutAnalysis.executeAnalysis(analysisArgs, semanticContract);
|
|
105
|
+
// Enhance with semantic metadata
|
|
106
|
+
return {
|
|
107
|
+
...result,
|
|
108
|
+
_semantic_metadata: {
|
|
109
|
+
tool_name: SEMANTIC_BREAKOUT_ANALYSIS.name,
|
|
110
|
+
parsed_capabilities: parsed.capabilities,
|
|
111
|
+
parse_confidence: `${(parsed.confidence * 100).toFixed(0)}%`,
|
|
112
|
+
message: '✅ Tool auto-configured from semantic intent!',
|
|
113
|
+
prompt_integration: {
|
|
114
|
+
scoring_formula: '40% recent + 30% projections + 20% opportunity - 10% risk',
|
|
115
|
+
external_sources: 'Ready for: Rotowire, NHL EDGE, DobberHockey integration',
|
|
116
|
+
data_driven: 'Predictable rankings with confidence scores'
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
catch (error) {
|
|
122
|
+
throw new Error(`Breakout analysis failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Improved prompt recommendations for Claude Desktop integration
|
|
127
|
+
*/
|
|
128
|
+
export const BREAKOUT_PROMPT_IMPROVEMENTS = {
|
|
129
|
+
semantic_clarity: {
|
|
130
|
+
original: "Complex multi-paragraph template with embedded formulas",
|
|
131
|
+
improved: "Structured semantic intent with clear I need/I will/I return sections",
|
|
132
|
+
benefit: "Claude Desktop can better understand tool purpose and auto-suggest when user asks about breakouts"
|
|
133
|
+
},
|
|
134
|
+
parameter_discovery: {
|
|
135
|
+
original: "Parameters embedded in prose",
|
|
136
|
+
improved: "Explicit parameter definitions with types and optionality",
|
|
137
|
+
benefit: "MCP can auto-generate input schema, reducing manual configuration"
|
|
138
|
+
},
|
|
139
|
+
capability_mapping: {
|
|
140
|
+
original: "References to external sources without integration plan",
|
|
141
|
+
improved: "Capability tags (yahoo_api, data_analysis) that map to available functions",
|
|
142
|
+
benefit: "Tool knows what it can and cannot do, preventing hallucination"
|
|
143
|
+
},
|
|
144
|
+
predictability_enhancement: {
|
|
145
|
+
original: "Scoring formula mentioned in prose",
|
|
146
|
+
improved: "Formula implemented in code with observable weights",
|
|
147
|
+
benefit: "Consistent, repeatable results that users can trust"
|
|
148
|
+
},
|
|
149
|
+
integration_points: {
|
|
150
|
+
yahoo_api: "Direct integration via YahooApiClient",
|
|
151
|
+
rotowire: "Placeholder for future web scraping capability",
|
|
152
|
+
nhl_edge: "Placeholder for NHL API integration",
|
|
153
|
+
dobber_hockey: "Placeholder for prospect data integration"
|
|
154
|
+
},
|
|
155
|
+
usage_with_claude_desktop: `
|
|
156
|
+
When user asks: "tell me about breakout players" or "who should I pick up?"
|
|
157
|
+
|
|
158
|
+
Claude Desktop will:
|
|
159
|
+
1. Recognize semantic intent matches analyze_breakout_players tool
|
|
160
|
+
2. Auto-extract parameters from conversation context (league format, roster needs)
|
|
161
|
+
3. Call tool with appropriate chirp settings (analytical by default)
|
|
162
|
+
4. Present results in conversational format with player tables and reasoning
|
|
163
|
+
|
|
164
|
+
Example interaction:
|
|
165
|
+
User: "I need a right wing, who are the best breakout candidates?"
|
|
166
|
+
|
|
167
|
+
Claude: *uses analyze_breakout_players with position_filter=["RW"]*
|
|
168
|
+
|
|
169
|
+
"Based on data-driven analysis, here are the top RW breakout candidates:
|
|
170
|
+
|
|
171
|
+
🏒 Must-Adds (Score 80+):
|
|
172
|
+
1. [Player Name] (Team) - 85 score
|
|
173
|
+
- Catalyst: Top-6 center opportunity
|
|
174
|
+
- Recent: 0.9 PPG | Projected: 0.7 FPG
|
|
175
|
+
- Risk: Low (15%)
|
|
176
|
+
- Confidence: High
|
|
177
|
+
|
|
178
|
+
2. [Player Name] (Team) - 82 score
|
|
179
|
+
...
|
|
180
|
+
|
|
181
|
+
📊 Position Analysis:
|
|
182
|
+
- RW pool strength: 15 candidates with 65+ scores
|
|
183
|
+
- Market trend: RW pickups trending up 23%
|
|
184
|
+
- Recommendation: Act fast on must-adds
|
|
185
|
+
|
|
186
|
+
💡 Next steps: Should I analyze your roster to see who you could drop?"
|
|
187
|
+
`
|
|
188
|
+
};
|