io.github.Anarkitty1/semantic-frame

Analyze numerical data and return a semantic description. Use this tool when you have a list of numbers (prices, metrics, sensor readings) and need to understand the trends, anomalies, and patterns without doing math yourself. This tool provides 95%+ token compression - sending 10,000 data points returns a ~50 word semantic summary instead of consuming context with raw numbers. Args: data: A string containing the numbers. Can be a JSON array "[1, 2, 3]", CSV "1, 2, 3", or newline-separated values. context: A label for the data (e.g., "Server CPU Load", "Daily Sales"). This helps the tool generate a more relevant description. Returns: A natural language paragraph describing the data's behavior including: - Trend direction (rising, falling, flat) - Volatility level (stable, moderate, extreme) - Anomalies detected with positions - Baseline statistics Examples: Input: data="[100, 102, 99, 500, 101]", context="Latency (ms)" Output: "The Latency (ms) data shows a flat/stationary pattern with stable variability. 1 anomaly detected at index 3 (value: 500.00)." Input: data="10, 20, 30, 40, 50", context="Daily Sales" Output: "The Daily Sales data shows a rapidly rising pattern..."

Analyze multiple data series in a single call. Efficient for analyzing DataFrames or multiple metrics at once. Each dataset is analyzed independently and results are combined. Args: datasets: JSON object mapping names to data arrays. Example: '{"cpu": [45, 47, 95, 44], "memory": [60, 61, 60]}' output_format: "text" for narratives (default), "json" for structured output. Returns: Combined analysis for all datasets. Example: Input: datasets='{"cpu": [45, 47, 95], "mem": [60, 61, 60]}' Output: "cpu: The cpu data shows a flat/stationary pattern... mem: The mem data shows a flat/stationary pattern..."

Analyze numerical data and return structured JSON output. Same as describe_data but returns JSON for programmatic use. Args: data: Numbers as JSON array, CSV, or newline-separated. context: Label for the data. Returns: JSON string with trend, volatility, anomalies, and narrative.

Analyze drawdowns in an equity curve. Use this tool when you have equity/balance data and need to understand drawdown risk, recovery patterns, and current drawdown status. Args: equity: Cumulative equity values as JSON array, CSV, or newline-separated. Example: "[10000, 10500, 10200, 9800, 9500, 10000, 10800]" context: Label for the strategy (e.g., "BTC strategy", "CLAUDE agent"). Returns: Semantic description of drawdown characteristics including: - Maximum drawdown percentage and duration - Current drawdown status (at high, recovering, in drawdown) - Severity classification (minimal/moderate/significant/severe/catastrophic) - Number of drawdown periods and recovery stats Example: Input: equity="[10000, 10500, 10200, 9800, 9500, 10000, 10800]", context="BTC strategy" Output: "The BTC strategy has moderate drawdown risk (max 9.5% over 3 periods). Currently at equity high."

Analyze trading performance from a series of trade PnLs. Use this tool when you have trade results and need to understand win rate, profit factor, risk-adjusted returns, and consistency. Args: trades: PnL per trade as JSON array, CSV, or newline-separated. Positive = profit, negative = loss. Example: "[100, -50, 75, -25, 150, -30, 80]" context: Label for the strategy (e.g., "CLAUDE agent", "Momentum strategy"). Returns: Semantic description of trading performance including: - Win rate and profit factor - Risk-adjusted metrics (Sharpe, Sortino if calculable) - Performance rating (excellent/good/average/below_average/poor) - Risk profile classification - Streak analysis and consistency rating Example: Input: trades="[100, -50, 75, -25, 150, -30, 80]", context="CLAUDE" Output: "CLAUDE shows good performance with 57% win rate and 2.86x profit factor. Risk profile: moderate."

Compare multiple agents/strategies and produce rankings. Use this tool when you have equity curves from multiple trading agents and need to compare their performance across multiple dimensions. Args: equity_curves: JSON object mapping names to equity arrays. Example: '{"CLAUDE": [10000, 11000, 12000], "GROK": [10000, 12000, 11000]}' context: Label for what's being compared (e.g., "AI agents", "strategies"). Returns: Comparative ranking analysis including: - Overall leader (composite score) - Best by return, risk-adjusted, volatility, and drawdown - Per-agent rankings across all dimensions Example: Input: equity_curves='{"CLAUDE": [10000, 10500, 11000], "GROK": [10000, 12000, 9000]}' Output: "Comparing 2 AI agents: CLAUDE leads overall with 10.0% return. GROK has highest raw return (20.0%). CLAUDE is most stable..."

Enhanced anomaly detection with severity and type classification. Use this tool when you need detailed analysis of outliers in data, including severity levels, anomaly types, and contextual descriptions. Args: data: Numerical values as JSON array, CSV, or newline-separated. Example: "[100, 102, 99, 500, 101, 98, -200]" context: Label for the data (e.g., "Trade PnL", "Server Latency"). is_pnl_data: If True, uses gain/loss terminology instead of spike/drop. Returns: Enhanced anomaly analysis including: - Each anomaly with severity (mild/moderate/severe/extreme) - Anomaly type (spike/drop/gain/loss) - Contextual descriptions - Frequency classification (rare/occasional/frequent/pervasive) Example: Input: data="[100, 102, 99, 500, 101, -200]", context="Trade PnL", is_pnl_data=True Output: "The Trade PnL has occasional anomalies (2 detected in 6 points). Most significant: index 3 (value: 500.00, z-score: 2.3, exceptional profit)."

Multi-timeframe analysis across different time windows. Use this tool when you need to analyze data across multiple timeframes to compare short-term vs long-term trends and filter noise from signal. Args: data: Price/value data as JSON array, CSV, or newline-separated. Most recent data at the end. windows: Comma-separated window sizes (e.g., "10,50,200" or "1h,4h,1d"). context: Label for the data (e.g., "BTC/USD", "CPU metrics"). Returns: Multi-timeframe analysis including: - Per-window trend and volatility - Timeframe alignment (all bullish, all bearish, mixed, diverging) - Noise level assessment - Suggested positioning Example: Input: data="[100,102,105,103,108,110,112,109,115,118,120]", windows="5,10" Output: "Multi-timeframe analysis: all timeframes bullish. Windows: 5 rising (+4.3%), 10 rising (+20.0%). Noise level: low."

Detect and classify market regimes from return data. Use this tool when you need to understand the current market regime (bull, bear, sideways, recovery, correction) and regime stability. Args: returns: Period returns as JSON array, CSV, or newline-separated. Values should be decimals (e.g., 0.01 = 1% return). Example: "[0.01, 0.02, -0.05, -0.08, 0.03, 0.04]" context: Label for the data (e.g., "BTC/USD", "S&P 500"). lookback: Lookback window for regime classification (default 20). Returns: Regime analysis including: - Current regime (bull/bear/sideways/recovery/correction/high_volatility) - Regime strength (strong/moderate/weak) - Regime stability (very_stable to highly_unstable) - Number of regime changes and average duration - Actionable insights Example: Input: returns="[0.01, 0.02, 0.01, -0.05, -0.08, -0.03, 0.02, 0.03, 0.04]" Output: "BTC is in a moderate recovery regime (duration: 3 periods). 2 regime change(s) detected - conditions are unstable. Early signs of recovery - consider gradual re-entry."

Analyze multi-asset portfolio and suggest allocation weights. DISCLAIMER: This provides educational analysis only, NOT financial advice. Use this tool when you need position sizing or portfolio allocation suggestions based on risk analysis and diversification. Args: assets: JSON object mapping asset names to price arrays. Example: '{"BTC": [100, 105, 102], "ETH": [50, 52, 48]}' context: Label for the portfolio (e.g., "Crypto Portfolio"). method: Allocation method - "equal_weight", "risk_parity", "min_variance", "target_vol". target_volatility: Target portfolio volatility (%) for target_vol method. Returns: Allocation analysis including: - Suggested weights for each asset - Portfolio expected return and volatility - Risk level classification - Diversification score and correlation insights - Educational disclaimer Example: Input: assets='{"BTC": [100,105,102,108], "ETH": [50,52,48,55]}' Output: "Portfolio analysis for Crypto: Suggested allocation: BTC (45%), ETH (55%). Expected return: 85.2%, volatility: 42.1% (high risk)."