Travel Guide Agent

Travel Guide Agent is a local-first MVP for generating structured, practical, and professional travel plans in Chinese.
Travel Guide Agent 是一个面向本地运行的 MVP，用于生成结构化、实用、专业的中文旅游攻略。

It is built with FastAPI and an OpenAI-compatible SDK, and currently uses the DeepSeek API by default.
它基于 FastAPI 和 OpenAI-compatible SDK 构建，当前默认使用 DeepSeek API。

Overview / 项目概览

This version focuses on the core itinerary-generation workflow: turning free-form user travel requests into structured travel plans.
当前版本聚焦核心行程生成链路，即把自然语言旅行需求转换为结构化旅行攻略。

The agent is designed to behave like a professional travel advisor rather than a general encyclopedia.
这个 Agent 的定位是专业旅行顾问，而不是泛百科介绍器。

Current MVP Scope / 当前 MVP 功能范围

• Area overview / 区域概况
• Recommended trip length / 推荐游玩天数
• Daily itinerary planning / 每日行程安排
• Daily highlights and attractions / 每天的主要景点
• Basic transport advice / 简单交通建议
• Basic budget reference / 基础预算参考
• Common travel pitfalls / 避坑提醒

Not Supported Yet / 暂不支持

• Real-time flight or hotel search / 实时机票酒店查询
• Real-time restaurant opening hours / 实时餐厅营业时间
• Real-time attraction status / 实时景点开放状态
• Advanced map route optimization / 复杂地图路线优化
• Booking services / 预订服务
• Login system / 登录系统
• Payment system / 支付系统
• User database / 用户数据库
• RAG / 检索增强生成
• Map API integration / 地图 API 集成

Project Structure / 项目结构

travel-guide-agent/
├── app/
│   ├── __init__.py
│   ├── agent.py
│   ├── cli.py
│   ├── config.py
│   ├── llm/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── deepseek_client.py
│   │   └── provider.py
│   ├── main.py
│   ├── prompts/
│   ├── schemas/
│   ├── services/
│   ├── tools/
│   └── utils/
├── tests/
│   ├── __init__.py
│   ├── test_llm_provider.py
│   └── test_planner.py
├── .env.example
├── .gitignore
├── requirements.txt
├── start_agent.sh
└── README.md

Requirements / 环境要求

• Python 3.12+ recommended / 推荐 Python 3.12+
• A valid DeepSeek API key / 可用的 DeepSeek API key

Environment Configuration / 环境变量配置

Copy the example file first:
先复制示例文件：

cp .env.example .env

Then fill in the required values in .env:
然后在 .env 中填写必要配置：

LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-xxxxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-v4-flash
USD_TO_CNY_RATE=6.77
OPENAI_API_KEY=
OPENAI_MODEL=gpt-4.1-mini

The project keeps OpenAI-related fields for future extensibility, but the current default provider is DeepSeek.
项目保留了 OpenAI 相关配置位以便后续扩展，但当前默认 provider 是 DeepSeek。

Install Dependencies / 安装依赖

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run the API Server / 启动 API 服务

uvicorn app.main:app --reload

Default local URL:
默认本地访问地址：

http://127.0.0.1:8000

Launch the Interactive Agent / 启动交互式 Agent

If you want a simpler flow, use the startup script below. It will prepare the environment, ask for your DeepSeek API key, and launch a terminal chat session.
如果你想要更省事的启动方式，可以使用下面的脚本。它会自动准备环境、提示你输入 DeepSeek API key，并直接启动终端对话模式。

zsh start_agent.sh

What the script does / 脚本会自动执行：

• Check and create .venv if needed / 检查并在需要时创建 .venv
• Install dependencies if needed / 在需要时安装依赖
• Copy .env.example to .env if .env does not exist / 若 .env 不存在则自动复制
• Prompt for DEEPSEEK_API_KEY / 提示输入 DEEPSEEK_API_KEY
• Start the interactive chat CLI / 启动交互式命令行对话

Important notes / 注意事项：

• The API key entered here is only used for the current session and is not automatically written to .env
  在这里输入的 API key 仅在当前会话内生效，不会自动写入 .env
• You can exit the chat by typing exit, quit, or q
  你可以输入 exit、quit 或 q 退出对话

Example prompt / 示例输入：

Tokyo for 5 days, I like anime and food, and I don't want the trip to feel too tiring.
东京 5 天，喜欢动漫和美食，不想太累

Test the API / 测试接口

Health Check / 健康检查

curl http://127.0.0.1:8000/health

Generate a Travel Plan / 生成旅行攻略

curl -X POST "http://127.0.0.1:8000/api/plan" \
  -H "Content-Type: application/json" \
  -d '{"user_input":"东京 5 天，喜欢动漫和美食，不想太累"}'

Example Response / 示例返回

{
  "success": true,
  "data": {
    "answer_markdown": "【城市概况】\n...\n【避坑提醒】\n...",
    "answer_markdown_path": "/absolute/path/to/outputs/tokyo-5-days-20260602-120000.md",
    "detected_city": "东京",
    "detected_days": 5,
    "need_day_recommendation": false,
    "token_usage": {
      "prompt_tokens": 1200,
      "completion_tokens": 1800,
      "total_tokens": 3000,
      "estimated_cost_usd": 0.000672,
      "estimated_cost_cny": 0.004549,
      "pricing_note": "Estimated cost based on current pricing."
    },
    "budget_references": [],
    "daily_plans": [],
    "itinerary_items": [],
    "transport_advice": [],
    "pitfall_reminders": []
  }
}

Markdown Output / Markdown 输出

Each successful /api/plan request saves one complete travel plan as a single .md file under the local outputs/ directory.
每次成功调用 /api/plan，都会把整份完整攻略保存为一个 .md 文件，放在本地 outputs/ 目录下。

The saved file path is returned in answer_markdown_path.
保存路径会通过 answer_markdown_path 字段返回。

Token Usage and Cost Estimate / Token 用量与费用估算

The response includes token usage, estimated USD cost, and estimated CNY cost.
接口返回中会包含 token 用量、美元费用估算和人民币费用估算。

The CNY estimate is calculated using USD_TO_CNY_RATE.
人民币估算通过 USD_TO_CNY_RATE 进行换算。

This is an estimate only and may differ from the actual provider billing amount.
这里展示的是估算值，可能与供应商最终计费存在差异。

Error Response Format / 错误返回格式

{
  "success": false,
  "error": {
    "message": "Error message / 错误说明"
  }
}

Common Issues / 常见问题

1. DEEPSEEK_API_KEY missing
   Make sure DEEPSEEK_API_KEY is set in .env, or enter it when using zsh start_agent.sh.
   请确认 .env 中已配置 DEEPSEEK_API_KEY，或者在使用 zsh start_agent.sh 时手动输入。

2. 401 Unauthorized
   This usually means the token is incorrect, expired, or not authorized.
   这通常表示 token 错误、已过期，或者权限不足。

3. model not found
   Check whether DEEPSEEK_MODEL is correct. The current default is deepseek-v4-flash.
   请检查 DEEPSEEK_MODEL 是否正确，当前默认值为 deepseek-v4-flash。

4. insufficient balance
   This usually means your account balance or available quota is insufficient.
   这通常表示你的账户余额或可用额度不足。

5. Do not commit .env
.env contains secrets and must not be pushed to GitHub. It is already ignored by .gitignore.
   .env 包含敏感信息，不应提交到 GitHub；项目已通过 .gitignore 忽略该文件。

Future Improvements / 后续扩展方向

• Add OpenAIClient under app/llm/ / 在 app/llm/ 下新增 OpenAIClient
• Integrate a real travel knowledge base or RAG / 接入真实旅行知识库或 RAG
• Add route-planning or map features / 增加路线规划或地图能力
• Integrate hotel, flight, and restaurant search / 接入酒店、机票和餐厅搜索
• Support multi-city travel planning / 支持多城市联游规划
• Provide richer structured output for frontend rendering / 为前端渲染提供更丰富的结构化输出