AI 資料助理

🧠 A spec-kit powered, specification-driven AI Data Assistant — LLM decides, functions execute, specs guarantee reliability. No hallucination, only real data.

透過自然語言查詢天氣、匯率、股價的 AI 助理，使用 OpenAI Function Calling 自動選擇適當的工具。

亮點

• 🎯 規格驅動開發 (Spec-Driven Development) — 使用 spec-kit 從規格到實作，確保需求與程式碼一致
• 🤖 LLM 決策，Function 執行 — AI 負責理解意圖，專用工具負責取得真實資料
• ✅ 零幻覺 (No Hallucination) — 所有資料來自即時 API，不依賴 LLM 記憶
• 🔌 可擴展架構 — BaseTool 抽象類別 + ToolRegistry 自動註冊，輕鬆新增工具

功能

• 天氣查詢：查詢全球城市天氣（OpenWeatherMap）
• 匯率換算：即時匯率查詢與金額換算（ExchangeRate-API）
• 股價查詢：台股、美股即時股價（yfinance）

技術架構

• Backend: FastAPI + OpenAI API (Function Calling)
• Frontend: Streamlit
• Tools: BaseTool 抽象類別 + ToolRegistry 自動註冊

快速開始

1. 環境設定

# 安裝 uv（如果還沒有）
pip install uv

# 建立虛擬環境並安裝依賴
uv sync --all-extras

# 安裝 pre-commit hooks
uv run pre-commit install

2. 設定 API Keys

複製 .env.example 為 .env 並填入你的 API Keys：

cp .env.example .env

需要的 API Keys：

• OpenAI API Key
• OpenWeatherMap API Key
• ExchangeRate-API Key

3. 啟動服務

方式一：本地開發

啟動 API Server：

uv run uvicorn app.main:app --reload

啟動 Streamlit UI（另開終端）：

uv run streamlit run ui/streamlit_app.py

方式二：Docker Compose

docker compose up --build

4. 使用

開啟瀏覽器：

• API 文件：http://localhost:8000/docs
• Streamlit UI：http://localhost:8501

使用範例

使用者：台北今天天氣如何？
助理：台北目前氣溫 25°C，天氣晴朗...

使用者：100 美金換台幣多少？
助理：100 美金約等於 3,150 台幣...

使用者：台積電現在股價多少？
助理：台積電 (2330.TW) 目前股價 580 元...

專案結構

.
├── app/
│   ├── api/          # FastAPI 路由
│   ├── llm/          # LLM 整合（OpenAI）
│   ├── schemas/      # Pydantic 模型
│   └── tools/        # 查詢工具（天氣、匯率、股價）
├── ui/
│   └── streamlit_app.py  # Streamlit 聊天介面
├── tests/
│   ├── unit/         # 單元測試
│   └── integration/  # 整合測試
└── specs/            # 功能規格文件

開發

# 執行測試
uv run pytest

# 程式碼檢查
uv run ruff check .

# 格式化
uv run ruff format .

License

MIT