# 记忆配置示例
memory_config = {
    "episodic_decay": 0.15,      # 事件记忆衰减率 15%/天
    "semantic_persistence": True,   # 语义记忆持久化
    "importance_threshold": 0.3,   # 重要性阈值
}

from shannon import Agent
from shannon.humancore import HumanApproval

agent = Agent(
    model="claude-sonnet-4-20250514",
    role="financial_advisor",
    tools=["stock_api", "news_scraper"],
    humancore=HumanApproval(
        approval_types=["trade", "risk_assessment"],
        timeout_seconds=300
    )
)

# Agent 在执行交易前会暂停，等待人类批准
result = agent.run("Buy 100 shares of NVDA")
# → Agent pauses: "我想执行这笔交易，请确认：[批准/修改/取消]"

class Agent:
    """Shannon Agent 核心类"""
    def __init__(
        self,
        model: str,                    # LLM 模型标识
        role: str,                     # Agent 角色描述
        goal: str,                     # Agent 目标
        memory: Memory = None,          # 记忆系统（可选）
        tools: List[Tool] = None,     # 可用工具列表
        humancore: HumanCore = None,   # 人类反馈配置
        **config
    ):
        self.model = model
        self.role = role
        self.goal = goal
        self.memory = memory or HierarchicalMemory()
        self.tools = ToolRegistry(tools)
        self.humancore = humancore
        self.supervisor = Supervisor(self)
        self.executor = Executor(self)

class HierarchicalMemory:
    """三层记忆系统"""
    def __init__(
        self,
        episodic: EpisodicMemory,
        semantic: SemanticMemory,
        working: WorkingMemory
    ):
        self.episodic = episodic    # 事件记忆
        self.semantic = semantic    # 语义记忆
        self.working = working     # 工作记忆
    
    def store(self, content: str, memory_type: str, importance: float):
        """存储记忆，自动分类到对应层级"""
        if memory_type == "event":
            self.episodic.add(content, importance)
        elif memory_type == "fact":
            self.semantic.add(content, importance)
        else:
            self.working.update(content)
    
    def retrieve(self, query: str, depth: str = "all") -> List[str]:
        """检索记忆"""
        results = []
        if depth in ["all", "working"]:
            results.extend(self.working.query(query))
        if depth in ["all", "episodic"]:
            results.extend(self.episodic.query(query))
        if depth in ["all", "semantic"]:
            results.extend(self.semantic.query(query))
        return results

# 方式一：装饰器注册
@agent.tool_registry.register
def web_search(query: str) -> str:
    """网络搜索工具"""
    return search(query)

# 方式二：运行时注册
agent.tools.register(
    name="database_query",
    func=execute_sql,
    description="执行 SQL 数据库查询",
    parameters={"type": "object", "properties": {...}}
)

# 方式三：远程工具注册
agent.tools.register_remote(
    url="https://api.example.com/tools",
    auth=api_key
)

class ToolRegistry:
    """工具注册表"""
    def __init__(self):
        self._tools: Dict[str, Tool] = {}
        self._metadata: Dict[str, ToolMetadata] = {}
    
    def register(self, tool: Tool, name: str = None):
        name = name or tool.name
        self._tools[name] = tool
        self._metadata[name] = ToolMetadata(
            name=name,
            description=tool.description,
            parameters=tool.parameters,
            tags=tool.tags or []
        )
    
    def discover(self, query: str) -> List[Tool]:
        """基于查询语义发现相关工具"""
        return semantic_search(
            query, 
            self._metadata,
            threshold=0.7
        )

# 启用思考流
for event in agent.run_stream("分析今年的 AI 发展趋势"):
    if event.type == "thought":
        print(f"🤔 思考: {event.content}")
    elif event.type == "action":
        print(f"⚡ 行动: {event.content}")
    elif event.type == "observation":
        print(f"📝 观察: {event.content}")
    elif event.type == "final":
        print(f"✅ 最终回答: {event.content}")

from shannon.observability import tracer

# 启用追踪
tracer.enable(
    service_name="shannon-agent",
    exporter="jaeger",  # 支持 jaeger, zipkin, console
    endpoint="http://localhost:14268/api/traces"
)

# 自动追踪所有 Agent 操作
with tracer.start_as_current_span("agent_run") as span:
    span.set_attribute("agent.role", agent.role)
    span.set_attribute("agent.model", agent.model)
    result = agent.run(task)
    span.set_attribute("result.length", len(result))

from shannon.retry import RetryConfig, exponential_backoff

@agent.retry(
    config=RetryConfig(
        max_attempts=3,
        backoff=exponential_backoff(base=2),
        retry_on=["RateLimitError", "NetworkError"]
    )
)
def uncertain_operation():
    """不稳定操作，自动重试"""
    return risky_api_call()

from shannon.circuit_breaker import CircuitBreaker

# 为外部 API 设置熔断器
api_breaker = CircuitBreaker(
    failure_threshold=5,      # 5 次失败后打开
    recovery_timeout=60,     # 60 秒后尝试半开
    expected_exception=APIError
)

@api_breaker
def call_external_service():
    return http_get("https://api.example.com")

pip install shannon-ai

# 或从源码安装
git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
pip install -e .

from shannon import Agent

# 创建研究助手 Agent
researcher = Agent(
    model="claude-sonnet-4-20250514",
    role="research_assistant",
    goal="帮助用户高效地进行研究和信息收集",
    tools=["web_search", "document_reader", "note_taker"]
)

# 运行任务
result = researcher.run(
    "研究 GPT-5 的最新进展及其对教育领域的影响"
)

print(result)

from shannon import Agent
from shannon.memory import HierarchicalMemory

# 创建带持久记忆的 Agent
memory = HierarchicalMemory(
    episodic=EpisodicMemory(capacity=1000),
    semantic=SemanticMemory(persistent=True),
    working=WorkingMemory(max_size=10)
)

assistant = Agent(
    model="claude-sonnet-4-20250514",
    role="personal_assistant",
    goal="成为用户的私人助理",
    memory=memory
)

# 后续对话中，Agent 会记住之前的重要信息
assistant.run("我的名字叫张三")
assistant.run("我最近在学习 Python")  # Agent 会记住这些信息
assistant.run("我叫什么名字？我在学什么？")  # → "您叫张三，在学 Python"