Semantic Frame

🚀 語義框架（Semantic Frame）

語義框架（Semantic Frame）可對數值數據進行高效的語義壓縮。 它能將原始數值數據（如NumPy、Pandas、Polars格式）轉換為適合大語言模型（LLM）處理的自然語言描述。你無需向AI代理發送數千個數據點，只需發送一個50字左右的語義摘要即可。

🚀 快速開始

分析單個序列

from semantic_frame import describe_series
import numpy as np

# 適用於NumPy數組
data = np.array([10, 20, 30, 40, 50, 60, 70, 80, 90, 100])
result = describe_series(data, context="Daily Sales")
print(result)
# "The Daily Sales data shows a rapidly rising pattern with moderate variability..."

分析數據框

from semantic_frame import describe_dataframe
import pandas as pd

df = pd.DataFrame({
    'cpu': [40, 42, 41, 95, 40, 41],
    'memory': [60, 61, 60, 60, 61, 60],
})

results = describe_dataframe(df, context="Server Metrics")
print(results['cpu'].narrative)
# "The Server Metrics - cpu data shows a flat/stationary pattern..."

獲取結構化輸出

result = describe_series(data, output="full")

print(result.trend)          # TrendState.RISING_SHARP
print(result.volatility)     # VolatilityState.MODERATE
print(result.anomalies)      # [AnomalyInfo(index=4, value=500.0, z_score=4.2)]
print(result.compression_ratio)  # 0.95

用於API的JSON輸出

result = describe_series(data, output="json")
# Returns dict ready for JSON serialization

✨ 主要特性

• 高效壓縮：將原始數值數據轉換為簡潔的自然語言描述，實現95%以上的token縮減。
• 避免幻覺：提供確定性分析，降低大語言模型的幻覺風險。
• 多數據類型支持：支持NumPy、Pandas、Polars等多種數據類型。
• 多框架集成：可與Anthropic Claude、LangChain、CrewAI、MCP等框架集成。
• 高級工具支持：支持Anthropic的高級工具使用功能，實現複雜代理工作流中的高效工具編排。
• 交易模塊：提供專門的交易分析工具，適用於交易代理、投資組合經理和金融應用。

📦 安裝指南

pip install semantic-frame

或者使用uv進行安裝：

uv add semantic-frame

💻 使用示例

基礎用法

from semantic_frame import describe_series
import pandas as pd

data = pd.Series([100, 102, 99, 101, 500, 100, 98])
print(describe_series(data, context="Server Latency (ms)"))

輸出：

The Server Latency (ms) data shows a flat/stationary pattern with stable
variability. 1 anomaly detected at index 4 (value: 500.00).
Baseline: 100.00 (range: 98.00-500.00).

高級用法

# 使用Claude進行分析
import anthropic
from semantic_frame.integrations.anthropic import get_anthropic_tool, handle_tool_call

client = anthropic.Anthropic()
tool = get_anthropic_tool()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[tool],
    messages=[{"role": "user", "content": "Analyze this sales data: [100, 120, 115, 500, 118]"}]
)

# 處理響應中的工具調用
for block in response.content:
    if block.type == "tool_use" and block.name == "semantic_analysis":
        result = handle_tool_call(block.input)
        print(result)

📚 詳細文檔

支持的數據類型

• NumPy：np.ndarray
• Pandas：pd.Series、pd.DataFrame
• Polars：pl.Series、pl.DataFrame
• Python：list

分析功能

LLM集成

系統提示注入

from semantic_frame.interfaces import format_for_system_prompt

result = describe_series(data, output="full")
prompt = format_for_system_prompt(result)
# Returns formatted context block for system prompts

LangChain工具輸出

from semantic_frame.interfaces import format_for_langchain

output = format_for_langchain(result)
# {"output": "narrative...", "metadata": {...}}

多列代理上下文

from semantic_frame.interfaces import create_agent_context

results = describe_dataframe(df)
context = create_agent_context(results)
# Combined narrative for all columns with attention flags

框架集成

Anthropic Claude（原生工具使用）

pip install semantic-frame[anthropic]

import anthropic
from semantic_frame.integrations.anthropic import get_anthropic_tool, handle_tool_call

client = anthropic.Anthropic()
tool = get_anthropic_tool()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[tool],
    messages=[{"role": "user", "content": "Analyze this sales data: [100, 120, 115, 500, 118]"}]
)

# 處理響應中的工具使用
for block in response.content:
    if block.type == "tool_use" and block.name == "semantic_analysis":
        result = handle_tool_call(block.input)
        print(result)

LangChain

pip install semantic-frame[langchain]

from semantic_frame.integrations.langchain import get_semantic_tool

tool = get_semantic_tool()
# Use as a LangChain BaseTool in your agent

CrewAI

pip install semantic-frame[crewai]

from semantic_frame.integrations.crewai import get_crewai_tool

tool = get_crewai_tool()
# Use with CrewAI agents

MCP（模型上下文協議）

pip install semantic-frame[mcp]

運行MCP服務器：

mcp run semantic_frame.integrations.mcp:mcp

為MCP客戶端（如ElizaOS、Claude Desktop、Claude Code等）提供describe_data工具。

Claude Code

在Claude Code中添加Semantic Frame作為原生工具：

# 安裝MCP依賴
pip install semantic-frame[mcp]

# 將MCP服務器添加到Claude Code
claude mcp add semantic-frame -- uv run --project /path/to/semantic-frame mcp run /path/to/semantic-frame/semantic_frame/integrations/mcp.py

# 重啟Claude Code，然後驗證連接
claude mcp list
# semantic-frame: ... - ✓ Connected

配置完成後，讓Claude分析數據，它將自動使用describe_data工具。

高級工具使用（測試版）

功能特性

快速開始（高級）

import anthropic
from semantic_frame.integrations.anthropic import get_advanced_tool, handle_tool_call

client = anthropic.Anthropic()
tool = get_advanced_tool()  # 啟用所有高級功能

response = client.beta.messages.create(
    betas=["advanced-tool-use-2025-11-20"],
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search"},
        {"type": "code_execution_20250825", "name": "code_execution"},
        tool,
    ],
    messages=[{"role": "user", "content": "Analyze all columns in this dataset..."}]
)

配置選項

from semantic_frame.integrations.anthropic import (
    get_anthropic_tool,          # 標準（包含示例）
    get_tool_for_discovery,      # 用於工具搜索
    get_tool_for_batch_processing,  # 用於代碼執行
    get_advanced_tool,           # 啟用所有功能
)

MCP批量分析

from semantic_frame.integrations.mcp import describe_batch

# 一次分析多個序列
result = describe_batch(
    datasets='{"cpu": [45, 47, 95, 44], "memory": [60, 61, 60, 61]}',
)

完整文檔請參閱 docs/advanced-tool-use.md。

使用案例

加密貨幣交易

btc_prices = pd.Series(hourly_btc_prices)
insight = describe_series(btc_prices, context="BTC/USD Hourly")
# "The BTC/USD Hourly data shows a rapidly rising pattern with extreme variability.
#  Step up detected at index 142. 2 anomalies detected at indices 89, 203."

DevOps監控

cpu_data = pd.Series(cpu_readings)
insight = describe_series(cpu_data, context="CPU Usage %")
# "The CPU Usage % data shows a flat/stationary pattern with stable variability
#  until index 850, where a critical anomaly was detected..."

銷售分析

sales = pd.Series(daily_sales)
insight = describe_series(sales, context="Daily Revenue")
# "The Daily Revenue data shows a steadily rising pattern with weak cyclic pattern
#  detected. Baseline: $12,450 (range: $8,200-$18,900)."

IoT傳感器數據

temps = pl.Series("temperature", sensor_readings)
insight = describe_series(temps, context="Machine Temperature (C)")
# "The Machine Temperature (C) data is expanding with extreme outliers.
#  3 anomalies detected at indices 142, 156, 161."

交易模塊（v0.4.0）

專為交易代理、投資組合經理和金融應用提供專業的語義分析。

交易工具

快速示例

from semantic_frame.trading import (
    describe_trading_performance,
    describe_drawdown,
    describe_regime,
    describe_allocation,
)

# 交易績效分析
pnl = [100, -50, 75, -25, 150, -30, 80]
result = describe_trading_performance(pnl, context="My Bot")
print(result.narrative)
# "My Bot shows good performance with 57.1% win rate. Profit factor: 2.53..."

# 回撤分析
equity = [10000, 10500, 10200, 9800, 9500, 10100]
result = describe_drawdown(equity, context="Strategy")
print(result.narrative)
# "Strategy max drawdown: 9.5% (moderate). Currently recovering..."

# 市場狀態分析
returns = [0.01, 0.015, 0.02, -0.01, 0.025, 0.018]  # 每日收益率
result = describe_regime(returns, context="BTC")
print(result.narrative)
# "BTC is in a strong bullish regime. Conditions favor trend-following..."

# 投資組合分配（⚠️ 僅用於教育目的，不構成金融建議）
assets = {"BTC": [40000, 42000, 44000], "ETH": [2500, 2650, 2800]}
result = describe_allocation(assets, method="risk_parity")
print(result.narrative)
# "Suggested allocation: BTC (55%), ETH (45%). Risk: high..."

MCP集成

所有交易工具均可通過MCP使用：

semantic-frame-mcp

可用工具：describe_drawdown、describe_trading_performance、describe_rankings、describe_anomalies、describe_windows、describe_regime、describe_allocation

📖 完整交易文檔 | 快速參考

API參考

describe_series(data, context=None, output="text")

分析單個數據序列。

參數：

• data：輸入數據（NumPy數組、Pandas Series、Polars Series或列表）
• context：數據的可選標籤（出現在描述中）
• output：格式 - "text"（字符串）、"json"（字典）或"full"（SemanticResult）

返回值： 以請求格式返回語義描述。

describe_dataframe(df, context=None)

分析數據框中的所有數值列。

參數：

• df：Pandas或Polars數據框
• context：列上下文標籤的可選前綴

返回值： 一個字典，將列名映射到SemanticResult對象。

SemanticResult

完整的分析結果包含：

• narrative：人類可讀的文本描述
• trend：TrendState枚舉
• volatility：VolatilityState枚舉
• data_quality：DataQuality枚舉
• anomaly_state：AnomalyState枚舉
• anomalies：AnomalyInfo對象列表
• seasonality：可選的SeasonalityState
• distribution：可選的DistributionShape
• step_change：可選的StructuralChange（STEP_UP、STEP_DOWN、NONE）
• step_change_index：可選的整數（階躍變化發生的索引）
• profile：帶有統計信息的SeriesProfile
• compression_ratio：token縮減比率

🔧 技術細節

Semantic Frame在處理數值數據時，先使用NumPy進行確定性分析，然後將結果轉換為token高效的敘述。它通過線性迴歸斜率分析數據趨勢，使用變異係數衡量波動性，利用Z - 分數或IQR自適應方法檢測異常值等。在與大語言模型集成時，通過特定的接口函數將分析結果格式化為適合系統提示、LangChain工具輸出或多列代理上下文的形式。在交易模塊中，針對金融數據的特點，提供了一系列專業的分析工具，如權益曲線回撤分析、交易績效評估、市場狀態檢測等。

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。