smartagents-py 0.1.0__tar.gz

smartagents_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 edgetalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smartagents_py-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: smartagents-py
+Version: 0.1.0
+Summary: A lightweight agent framework based on LLM
+Author-email: edgetalker <kevinpan998@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 edgetalker
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/edgetalker/smartagents
+Project-URL: Repository, https://github.com/edgetalker/smartagents
+Project-URL: Issues, https://github.com/edgetalker/smartagents/issues
+Keywords: agent,llm,ai,openai
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: tavily-python>=0.3.0
+Requires-Dist: google-search-results>=2.4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# 🤖 SmartAgents
+
+*从零实现LLM Agent框架 - 教学级实现与工程化实践*
+
+[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+[🚀 快速开始](#快速开始) • [📖 文档](docs/) • [🎯 示例](examples/) • [🤝 贡献指南](CONTRIBUTING.md)
+
+</div>
+
+---
+
+## ✨ 项目亮点
+
+- 🎓 **低耦合架构**: 清晰的模块组织和渐进式实现，适合学习Agent内部机制
+- 🏗️ **工程化实践**: 模块化架构、完整测试、CI/CD流程
+- 🔧 **生产可用**: 支持DeepSeek/OpenAI等多Provider，自动检测服务商
+- 📚 **功能完整**: 内置多种工具调用、工具链、工具异步调用
+
+## 🎬 快速演示
+```python
+from smart_agents import SimpleAgent
+from smart_agents.llm import SimpleAgentLLM
+from smart_agents.tools import ToolRegistry
+from smart_agents.tools.bulitin import SearchTool
+# 初始化LLM
+llm = SmartAgentLLM()
+
+# 初始化工具
+searchTool = SearchTool()
+tool_registry.register_tool(searchTool)
+
+# 初始化Agent
+agent = SimpleAgent(
+    name="工具增强助手",
+    llm=llm,
+    system_prompt="你是一个智能助手，可以使用工具来帮助用户。",
+    tool_registry=tool_registry,
+    enable_tool_calling=True
+)
+
+response = agent.run("2026年小米手机最新款是什么，有什么卖点")
+print(f"工具增强助手响应: {response}")
+# 2026年小米手机的最新款型有几个比较主要的系列：
+
+# 1. Redmi Note系列：主打千元长续航、耐用抗造，适合长辈、户外、备用机。
+# 2. Redmi K系列：主打电竞性能、性价比旗舰，适合学生、游戏玩家。...
+```
+
+## 📊 架构设计
+```
+┌─────────────────────────────────────────┐
+│          User Interface (API)          │
+└──────────────┬──────────────────────────┘
+               │
+┌──────────────▼──────────────────────────┐
+│         Agent Core (ReAct)             │
+│  ┌────────┐ ┌────────┐ ┌──────────┐   │
+│  │Planning│ │Executor│ │Reflexion │   │
+│  └────────┘ └────────┘ └──────────┘   │
+└──────────────┬──────────────────────────┘
+               │
+    ┌──────────┼──────────┐
+    │          │          │
+┌───▼───┐  ┌──▼───┐  ┌──▼─────┐
+│Memory │  │Tools │  │LLM Prov│
+│System │  │      │  │        │
+└───────┘  └──────┘  └────────┘
+```
+
+## 🚀 快速开始
+
+### 安装
+```bash
+# 使用pip安装
+pip install smart_agents
+
+# 或从源码安装
+git clone https://github.com/edgetalker/smart_agents.git
+cd hello-agents
+```
+
+### 配置
+```bash
+cp .env.example .env
+# 编辑.env文件，填入API密钥
+```
+
+## 📖 核心功能
+
+### 1️⃣ ReAct执行循环
+```python
+# Agent自动进行推理-行动循环
+agent.run("帮我查询AAPL股票价格并分析走势")
+
+# 内部执行过程：
+# Thought: 需要先获取股票价格
+# Action: get_stock_price("AAPL")
+# Observation: $178.32
+# Thought: 需要分析历史数据
+# Action: analyze_trend("AAPL", days=30)
+# Observation: 上涨趋势...
+# Final Answer: ...
+```
+
+### 2️⃣ 向量记忆系统
+```python
+# 长期记忆存储与检索
+agent.memory.store("用户偏好Python开发")
+relevant = agent.memory.retrieve("编程语言")
+# 自动召回相关上下文
+```
+
+### 3️⃣ 自定义工具
+```python
+from smart_agents.tools import Tool
+
+@Tool(
+    name="database_query",
+    description="查询MySQL数据库"
+)
+async def query_db(sql: str) -> str:
+    # 你的实现
+    return results
+```
+
+## 🗺️ 开发路线图
+
+- [x] 基础Agent框架 (v0.1.0)
+- [x] ReAct执行循环 (v0.2.0)
+- [x] 向量记忆系统 (v0.3.0)
+- [ ] Reflexion自我反思 (v0.4.0)
+- [ ] 多Agent协作 (v0.5.0)
+- [ ] 生产优化与部署 (v1.0.0)
+
+## 🤝 贡献
+
+欢迎提交Issue和Pull Request!
+
+
+## 📄 许可证
+
+[MIT License](LICENSE) © edgetalker
+
+## 🙏 致谢
+
+- DataWhale HelloAgents项目启发
+- MIT 6.5940课程的优化技术
+- LangChain社区的最佳实践
+
+## 📧 联系方式
+
+- GitHub: [@edgetalker](https://github.com/edgetalker)
+- Email: kevinpan998@gmail.com
+
+---
+
+<div align="center">
+如果这个项目对你有帮助，请给个⭐️支持一下！
+</div>

smartagents_py-0.1.0/README.md

@@ -0,0 +1,164 @@
+<div align="center">
+
+# 🤖 SmartAgents
+
+*从零实现LLM Agent框架 - 教学级实现与工程化实践*
+
+[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+[🚀 快速开始](#快速开始) • [📖 文档](docs/) • [🎯 示例](examples/) • [🤝 贡献指南](CONTRIBUTING.md)
+
+</div>
+
+---
+
+## ✨ 项目亮点
+
+- 🎓 **低耦合架构**: 清晰的模块组织和渐进式实现，适合学习Agent内部机制
+- 🏗️ **工程化实践**: 模块化架构、完整测试、CI/CD流程
+- 🔧 **生产可用**: 支持DeepSeek/OpenAI等多Provider，自动检测服务商
+- 📚 **功能完整**: 内置多种工具调用、工具链、工具异步调用
+
+## 🎬 快速演示
+```python
+from smart_agents import SimpleAgent
+from smart_agents.llm import SimpleAgentLLM
+from smart_agents.tools import ToolRegistry
+from smart_agents.tools.bulitin import SearchTool
+# 初始化LLM
+llm = SmartAgentLLM()
+
+# 初始化工具
+searchTool = SearchTool()
+tool_registry.register_tool(searchTool)
+
+# 初始化Agent
+agent = SimpleAgent(
+    name="工具增强助手",
+    llm=llm,
+    system_prompt="你是一个智能助手，可以使用工具来帮助用户。",
+    tool_registry=tool_registry,
+    enable_tool_calling=True
+)
+
+response = agent.run("2026年小米手机最新款是什么，有什么卖点")
+print(f"工具增强助手响应: {response}")
+# 2026年小米手机的最新款型有几个比较主要的系列：
+
+# 1. Redmi Note系列：主打千元长续航、耐用抗造，适合长辈、户外、备用机。
+# 2. Redmi K系列：主打电竞性能、性价比旗舰，适合学生、游戏玩家。...
+```
+
+## 📊 架构设计
+```
+┌─────────────────────────────────────────┐
+│          User Interface (API)          │
+└──────────────┬──────────────────────────┘
+               │
+┌──────────────▼──────────────────────────┐
+│         Agent Core (ReAct)             │
+│  ┌────────┐ ┌────────┐ ┌──────────┐   │
+│  │Planning│ │Executor│ │Reflexion │   │
+│  └────────┘ └────────┘ └──────────┘   │
+└──────────────┬──────────────────────────┘
+               │
+    ┌──────────┼──────────┐
+    │          │          │
+┌───▼───┐  ┌──▼───┐  ┌──▼─────┐
+│Memory │  │Tools │  │LLM Prov│
+│System │  │      │  │        │
+└───────┘  └──────┘  └────────┘
+```
+
+## 🚀 快速开始
+
+### 安装
+```bash
+# 使用pip安装
+pip install smart_agents
+
+# 或从源码安装
+git clone https://github.com/edgetalker/smart_agents.git
+cd hello-agents
+```
+
+### 配置
+```bash
+cp .env.example .env
+# 编辑.env文件，填入API密钥
+```
+
+## 📖 核心功能
+
+### 1️⃣ ReAct执行循环
+```python
+# Agent自动进行推理-行动循环
+agent.run("帮我查询AAPL股票价格并分析走势")
+
+# 内部执行过程：
+# Thought: 需要先获取股票价格
+# Action: get_stock_price("AAPL")
+# Observation: $178.32
+# Thought: 需要分析历史数据
+# Action: analyze_trend("AAPL", days=30)
+# Observation: 上涨趋势...
+# Final Answer: ...
+```
+
+### 2️⃣ 向量记忆系统
+```python
+# 长期记忆存储与检索
+agent.memory.store("用户偏好Python开发")
+relevant = agent.memory.retrieve("编程语言")
+# 自动召回相关上下文
+```
+
+### 3️⃣ 自定义工具
+```python
+from smart_agents.tools import Tool
+
+@Tool(
+    name="database_query",
+    description="查询MySQL数据库"
+)
+async def query_db(sql: str) -> str:
+    # 你的实现
+    return results
+```
+
+## 🗺️ 开发路线图
+
+- [x] 基础Agent框架 (v0.1.0)
+- [x] ReAct执行循环 (v0.2.0)
+- [x] 向量记忆系统 (v0.3.0)
+- [ ] Reflexion自我反思 (v0.4.0)
+- [ ] 多Agent协作 (v0.5.0)
+- [ ] 生产优化与部署 (v1.0.0)
+
+## 🤝 贡献
+
+欢迎提交Issue和Pull Request!
+
+
+## 📄 许可证
+
+[MIT License](LICENSE) © edgetalker
+
+## 🙏 致谢
+
+- DataWhale HelloAgents项目启发
+- MIT 6.5940课程的优化技术
+- LangChain社区的最佳实践
+
+## 📧 联系方式
+
+- GitHub: [@edgetalker](https://github.com/edgetalker)
+- Email: kevinpan998@gmail.com
+
+---
+
+<div align="center">
+如果这个项目对你有帮助，请给个⭐️支持一下！
+</div>

smartagents_py-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smartagents-py"
+version = "0.1.0"
+description = "A lightweight agent framework based on LLM"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [
+    { name = "edgetalker", email = "kevinpan998@gmail.com" }
+]
+keywords = ["agent", "llm", "ai", "openai"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+# 运行时依赖
+dependencies = [
+    "openai>=1.0.0",
+    "pydantic>=2.0.0",
+    "requests>=2.25.0",
+    "python-dotenv>=1.0.0",
+    "tavily-python>=0.3.0",
+    "google-search-results>=2.4.0",  # serpapi 的正确包名
+]
+
+[project.optional-dependencies]
+# 开发依赖：pip install smartagents[dev]
+dev = [
+    "pytest>=7.0.0",
+    "black>=22.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/edgetalker/smartagents"
+Repository = "https://github.com/edgetalker/smartagents"
+Issues = "https://github.com/edgetalker/smartagents/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["smart_agents*"]
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]

smartagents_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smartagents_py-0.1.0/smart_agents/__init__.py

@@ -0,0 +1,35 @@
+"""SmartAgents - A lightweight agent framework based on LLM"""
+
+__version__ = "0.1.0"
+
+from smart_agents.agents.simple_agent import SimpleAgent
+from smart_agents.agents.react_agent import ReActAgent
+from smart_agents.core.config import Config
+from smart_agents.core.llm import SmartAgentLLM
+from smart_agents.core.message import Message
+
+from .tools.registry import ToolRegistry, global_registry
+from .tools.builtin.search import SearchTool 
+from .tools.builtin.calculator import CalculatorTool
+from .tools.chain import ToolChain, ToolChainManager
+from .tools.async_executor import AsyncToolExecutor
+
+__all__ = [
+    # 核心组件
+    "Config",
+    "SmartAgentLLM",
+    "Message",
+
+    # Agent 范式
+    "SimpleAgent",
+    "ReActAgent",
+
+    # 工具系统
+    "ToolRegistry",
+    "global_registry",
+    "SearchTool",
+    "CalculatorTool",
+    "ToolChain",
+    "ToolChainManager",
+    "AsyncToolExecutor",
+]

smartagents_py-0.1.0/smart_agents/agents/__init__.py

@@ -0,0 +1,9 @@
+"""Agent实现模块 - HelloAgents原生Agent范式"""
+
+from .simple_agent import SimpleAgent
+from .react_agent import ReActAgent
+
+__all__ = [
+    "SimpleAgent",
+    "ReActAgent",
+]

smartagents_py-0.1.0/smart_agents/agents/react_agent.py

@@ -0,0 +1,101 @@
+from typing import Optional
+
+from ..core.config import Config
+from ..core.agent import Agent
+from ..core.llm import SmartAgentLLM
+from ..tools.registry import ToolRegistry
+from ..core.message import Message
+
+DEFAULT_REACT_PROMPT = """你是一个具备推理和行动能力的AI助手。你可以通过思考分析问题，然后调用合适的工具来获取信息，最终给出准确的答案。
+
+## 可用工具
+{tools}
+
+## 工作流程
+请严格按照以下格式进行回应，每次只能执行一个步骤:
+
+Thought: 分析当前问题，思考需要什么信息或采取什么行动。
+Action: 选择一个行动，格式必须是以下之一:
+- `{{tool_name}}[{{tool_input}}]` - 调用指定工具
+- `Finish[最终答案]` - 当你有足够信息给出最终答案时
+
+## 重要提醒
+1. 每次回应必须包含Thought和Action两部分
+2. 工具调用的格式必须严格遵循:工具名[参数]
+3. 只有当你确信有足够信息回答问题时，才使用Finish
+4. 如果工具返回的信息不够，继续使用其他工具或相同工具的不同参数
+
+## 当前任务
+**Question:** {question}
+
+## 执行历史
+{history}
+
+现在开始你的推理和行动:
+"""
+
+class ReActAgent(Agent):
+    """
+    ReAct(Reasoning and Action) Agent
+    结合推理和行动的智能体
+    """
+    def __init__(
+        self, 
+        name: str, 
+        llm: SmartAgentLLM, 
+        system_prompt: Optional[str] = None,
+        config: Optional[Config] = None,
+        tool_registry: Optional['ToolRegistry'] = None,
+        max_steps: int = 5,
+        custom_prompt: Optional[str] = None
+    ):
+        super().__init__(self, name, llm, system_prompt, config)
+        self.tool_registry = tool_registry
+        self.max_steps = max_steps
+        self.current_history: list[str] = []
+        self.prompt_template = custom_prompt if custom_prompt else DEFAULT_REACT_PROMPT
+
+    def run(self, input_text: str, **kwargs) -> str:
+        self.current_history = []
+        current_step = 0
+
+        print(f"🤖 {self.name} 开始处理问题：{input_text}")
+
+        while current_step < self.max_steps:
+            current_step += 1
+            
+            # 获取提示词
+            tools_desc = self.tool_registry.get_tools_description()
+            history_str = "\n".join(self.current_history)
+            prompt = self.prompt_template.format(
+                tools = tools_desc,
+                question = input_text,
+                history = history_str
+            )
+
+            # 调用llm
+            messages = [{"role": "user", "content": prompt}]
+            response_text = self.llm.invoke(messages, **kwargs)
+
+            # 解析输出
+            thought, action = self._parse_output(response_text)
+
+            # 检查是否完成
+            if action and action.startswith('Finish'):
+                final_answer = self._parse_action_input(action)
+                self.add_message(Message(input_text, "user"))
+                self.add_message(Message(final_answer, "assistant"))
+                return final_answer
+
+            # 执行工具调用
+            if action:
+                tool_name, tool_input = self._parse_action(action)
+                observation = self.tool_registry.execute_tool(tool_name, tool_input)
+                self.current_history.append(f"Action: {action}")
+                self.current_history.append(f"Observation: {observation}")
+
+        # 达到最大步数
+        final_answer = "抱歉，我无法在限定步数内完成这个任务。"
+        self.add_message(Message(input_text, "user"))
+        self.add_message(Message(final_answer, "assistant"))
+        return final_answer