tavily-tools 0.1.0

Tavily搜索结果格式化工具包 - 提供智能搜索和多格式输出功能

Tavily Tools

🚀 强大的Tavily搜索结果格式化工具包 - 提供智能搜索和多格式输出功能

🌟 功能特性

• 🎨 多种输出格式: 控制台美化输出、JSON结构化保存、HTML报告生成
• 📊 搜索质量分析: 自动分析搜索结果质量和评分分布
• ⚡ 快速格式化: 一键完成搜索和格式化操作
• 🔄 批量处理: 支持批量搜索和结果处理
• 🎯 交互式搜索: 用户友好的交互式界面
• 💾 智能保存: 自动生成时间戳文件名和目录管理
• 🛠️ CLI工具: 完整的命令行接口支持
• 📚 搜索历史: 搜索历史管理和导出功能
• 🌐 中文优化: 专门优化的中文界面和输出

📁 项目结构

tavily-tools/
├── src/tavily_tools/           # 主包目录 (src-layout)
│   ├── __init__.py            # 包初始化和主要导出
│   ├── core/                  # 核心业务逻辑
│   │   ├── __init__.py       
│   │   ├── formatter.py       # 搜索结果格式化器
│   │   └── search.py          # 搜索客户端封装
│   ├── config/                # 配置管理
│   │   ├── __init__.py       
│   │   └── settings.py        # 环境变量和配置管理
│   ├── utils/                 # 工具函数
│   │   ├── __init__.py       
│   │   └── helpers.py         # 通用辅助函数
│   └── cli/                   # 命令行接口
│       ├── __init__.py       
│       └── main.py            # CLI主程序
├── examples/                   # 使用示例
│   ├── __init__.py           
│   └── usage_examples.py      # 详细使用示例
├── tests/                     # 测试套件
│   ├── __init__.py           
│   └── test_formatter.py      # 格式化器测试
├── results/                   # 结果输出目录
├── env.template               # 环境变量模板
├── pyproject.toml             # 项目配置和依赖管理
├── requirements.txt           # 基础依赖（兼容性）
├── README.md                  # 项目文档
├── LICENSE                    # MIT许可证
└── .gitignore                 # Git忽略文件

🛠️ 安装与配置

方式一：开发安装（推荐）

# 克隆项目
git clone https://github.com/silenceboychen/tavily-tools.git
cd tavily-tools

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 开发模式安装
pip install -e .

# 或安装完整开发依赖
pip install -e ".[dev]"

方式二：直接安装

# 安装基础版本
pip install tavily-tools

# 安装完整版本（包含开发工具）
pip install "tavily-tools[dev]"

配置API密钥

1. 复制环境变量模板:

cp env.template .env

2. 编辑.env文件:

# 必需配置
TAVILY_API_KEY=your_tavily_api_key_here

# 可选配置
DEFAULT_SEARCH_QUERY=deepseek
RESULTS_SAVE_PATH=./results/
MAX_SEARCH_RESULTS=10

3. 获取API密钥:
   • 访问 Tavily官网
   • 注册账户并获取API密钥
   • 将密钥填入.env文件

🚀 快速开始

命令行使用

# 交互式搜索（推荐）
tavily-tools

# 快速搜索
tavily-tools -q "Python机器学习"

# 批量搜索并保存结果
tavily-tools -b "AI发展" "量子计算" "区块链" --save-json --save-html

# 显示配置信息
tavily-tools --config

# 验证环境配置
tavily-tools --validate-env

Python编程使用

基础使用

from tavily_tools import TavilyFormatter, SearchClient

# 创建搜索客户端
client = SearchClient()

# 执行搜索
response = client.search("人工智能最新发展")

# 格式化输出
formatter = TavilyFormatter(response)
formatter.print_full()

# 保存结果
formatter.save_json()
formatter.save_html()

高级功能

from tavily_tools import quick_format, batch_search, interactive_search

# 快速格式化（一键完成）
quick_format(
    response, 
    save_json=True, 
    save_html=True, 
    print_output=True
)

# 批量搜索
topics = ["机器学习", "深度学习", "神经网络"]
formatters = batch_search(topics, save_json=True)

# 交互式搜索
interactive_search()

搜索质量分析

# 详细质量分析
quality = formatter.analyze_quality()
print(f"平均评分: {quality['平均评分']:.3f}")
print(f"高质量结果: {quality['评分分布']['高质量(>0.7)']}条")

# 搜索历史管理
client = SearchClient()
client.search("查询1")
client.search("查询2")

# 查看搜索历史
history = client.get_search_history()
for item in history:
    print(f"{item['query']}: {item['results_count']}条结果")

# 导出搜索历史
client.export_history("my_search_history.json")

📚 详细文档

核心类和函数

TavilyFormatter

搜索结果格式化器，提供多种输出格式。

formatter = TavilyFormatter(response, save_path="./results/")

# 打印方法
formatter.print_summary()      # 打印搜索摘要
formatter.print_results()      # 打印搜索结果
formatter.print_full()         # 打印完整信息

# 数据转换
data = formatter.to_dict()     # 转换为结构化字典

# 文件输出
formatter.save_json()          # 保存为JSON文件
formatter.save_html()          # 生成HTML报告

# 质量分析
quality = formatter.analyze_quality()

SearchClient

搜索客户端封装，提供统一的搜索接口。

client = SearchClient(api_key="your_key")  # 可选，默认从配置读取

# 基础搜索
response = client.search("查询关键词")

# 搜索并格式化
formatter = client.search_and_format(
    query="查询关键词",
    save_json=True,
    save_html=True
)

# 搜索历史管理
history = client.get_search_history()
client.export_history("history.json")
client.clear_history()

配置管理

from tavily_tools.config import get_config, get_tavily_client

# 获取配置
config = get_config()
config.show_config()

# 获取预配置的客户端
client = get_tavily_client()

命令行选项

# 基本操作
tavily-tools -q "查询"                    # 单次搜索
tavily-tools -b "查询1" "查询2"           # 批量搜索
tavily-tools -i                          # 交互式模式

# 输出选项
tavily-tools -q "查询" --save-json        # 保存JSON
tavily-tools -q "查询" --save-html        # 生成HTML报告
tavily-tools -q "查询" --no-print         # 不打印到控制台

# 配置和信息
tavily-tools --config                    # 显示配置
tavily-tools --validate-env              # 验证环境
tavily-tools --version                   # 显示版本

# 调试选项
tavily-tools -q "查询" --verbose          # 详细输出
tavily-tools -q "查询" --quiet            # 安静模式

🔧 开发指南

环境设置

# 克隆项目
git clone https://github.com/silenceboychen/tavily-tools.git
cd tavily-tools

# 安装开发依赖
pip install -e ".[dev]"

# 安装pre-commit钩子
pre-commit install

代码质量工具

# 代码格式化
black src/ tests/ examples/
isort src/ tests/ examples/

# 静态检查
flake8 src/ tests/ examples/
mypy src/

# 运行测试
pytest tests/ --cov=src/tavily_tools

构建和发布

# 构建包
python -m build

# 本地安装测试
pip install dist/tavily_tools-0.1.0-py3-none-any.whl

# 发布到PyPI（需要配置token）
twine upload dist/*

📊 使用示例

示例1：基础搜索和格式化

from tavily_tools import SearchClient, TavilyFormatter

# 执行搜索
client = SearchClient()
response = client.search("Python机器学习库推荐")

# 创建格式化器
formatter = TavilyFormatter(response)

# 显示搜索摘要
formatter.print_summary()
# 输出：
# ============================================================
# 🔍 查询: Python机器学习库推荐
# ⏱️  用时: 1.234秒
# 📊 结果: 10条
# ============================================================

# 保存结果
json_file = formatter.save_json()
html_file = formatter.save_html()

示例2：批量搜索和质量分析

from tavily_tools import batch_search

# 定义搜索主题
topics = [
    "人工智能最新突破",
    "量子计算发展现状", 
    "区块链技术应用"
]

# 批量搜索
formatters = batch_search(
    topics=topics,
    save_json=True,
    save_html=False,
    print_progress=True
)

# 分析结果质量
for i, formatter in enumerate(formatters):
    quality = formatter.analyze_quality()
    print(f"{topics[i]}:")
    print(f"  结果数: {quality['结果总数']}")
    print(f"  平均评分: {quality['平均评分']:.3f}")
    print(f"  高质量结果: {quality['评分分布']['高质量(>0.7)']}条")

示例3：自定义配置和高级功能

from tavily_tools import SearchClient, TavilyFormatter
from tavily_tools.config import get_config

# 显示当前配置
config = get_config()
config.show_config()

# 创建客户端并执行多次搜索
client = SearchClient()

queries = ["深度学习", "计算机视觉", "自然语言处理"]
for query in queries:
    print(f"\n🔍 搜索: {query}")
    
    # 执行搜索
    response = client.search(query)
    
    # 快速分析
    formatter = TavilyFormatter(response)
    quality = formatter.analyze_quality()
    
    print(f"✅ 完成 | 结果: {quality['结果总数']}条 | 评分: {quality['平均评分']:.3f}")

# 查看搜索历史
print("\n📚 搜索历史:")
history = client.get_search_history()
for i, item in enumerate(history, 1):
    print(f"  {i}. {item['query']} - {item['results_count']}条结果")

# 导出历史
history_file = client.export_history()
print(f"\n📁 搜索历史已导出: {history_file}")

🤝 贡献指南

欢迎任何形式的贡献！请查看以下指南：

1. Fork 项目
2. 创建功能分支: git checkout -b feature/amazing-feature
3. 提交更改: git commit -m 'Add amazing feature'
4. 推送分支: git push origin feature/amazing-feature
5. 开启 Pull Request

贡献类型

• 🐛 Bug修复
• ✨ 新功能开发
• 📚 文档改进
• 🎨 界面优化
• ⚡ 性能优化
• 🧪 测试覆盖

🆘 问题排查

常见问题

Q: 报错"未找到TAVILY_API_KEY环境变量"

# 解决方案：
1. 复制环境变量模板：cp env.template .env
2. 编辑.env文件，填入真实的API密钥
3. 确保.env文件在项目根目录

Q: 模块导入错误

# 解决方案：
1. 确保已安装项目：pip install -e .
2. 检查Python路径：python -c "import tavily_tools; print('OK')"
3. 激活正确的虚拟环境

Q: 搜索结果为空

# 解决方案：
1. 检查网络连接
2. 验证API密钥有效性：tavily-tools --validate-env
3. 尝试简化搜索查询

调试模式

# 启用详细输出
tavily-tools -q "查询" --verbose

# 查看配置信息
tavily-tools --config --verbose

# 验证环境
tavily-tools --validate-env

📄 许可证

本项目基于 MIT许可证 开源。

🔗 相关链接

• Tavily官网 - 获取API密钥
• 项目主页
• 问题反馈

---

⭐ 如果这个项目对您有帮助，请给我一个Star！ ⭐

Made with ❤️ by Morty