| name | setup-environment |
| description | One-shot environment bootstrapper for the Smart Appointment AI Agent. Creates a Python virtual environment, installs dependencies from requirements.txt, scaffolds a .env file with generic OpenAI-compatible LLM / embedding / OpenWeather keys, prepares the data directory, and verifies the install. Use when user says "setup environment", "一键配置", "初始化环境", "install deps", "配置环境", "setup", "bootstrap", "搭建环境", or whenever a fresh checkout needs to be made runnable. |
Setup Environment
One trigger completes check Python → create venv → install deps → scaffold .env → init data dir → verify → (optional) launch app.
Optional modifiers:
--run after setup, also start uvicorn on 127.0.0.1:8001--force recreate the .venv from scratch--no-verify skip the import-time verification step
Pipeline
Check Python (3.10–3.12)
↓
Create / reuse .venv
↓
Activate venv (idempotent)
↓
pip install -r requirements.txt
↓
Ensure .env (copy from .env.example if missing, then prompt for model keys)
↓
Ensure data/ directory exists
↓
Verify imports (fastapi, langchain, faiss, sqlalchemy, mcp …)
↓
[optional] uvicorn app:app --host 127.0.0.1 --port 8001
⚠️ Always use the project-local Python environment for this repository.
Do not run this project with global/system python, pip, pytest, or uvicorn; global Python may be 3.13+ and incompatible with LangChain 0.3.x.
Activate .venv first, or call the project interpreter directly.
- Windows (PowerShell):
.\.venv\Scripts\Activate.ps1
- Windows (cmd):
.\.venv\Scripts\activate.bat
- macOS / Linux:
source .venv/bin/activate
- Direct Windows Python:
.\.venv\Scripts\python.exe
Quick Start
Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File .github\skills\setup-environment\scripts\setup.ps1
macOS / Linux
bash .github/skills/setup-environment/scripts/setup.sh
The script is idempotent: re-running only patches whatever is missing.
Step-by-Step (when running manually)
1. Check Python
Required: Python 3.10, 3.11, or 3.12.
⚠ Python 3.13 / 3.14 are not supported. PEP 649 deferred annotation evaluation in 3.13+ breaks LangChain 0.3.x / pydantic forward-ref evaluation (TypeError: 'function' object is not subscriptable). The setup script detects this and refuses to continue. On Windows, install Python 3.12 from python.org or via winget install --id Python.Python.3.12 -e. The script will auto-pick py -3.12 if available.
python --version
If missing or incompatible, stop and ask the user to install Python 3.10–3.12.
2. Create the virtual environment
python -m venv .venv
If --force was passed, delete .venv first.
3. Activate
# Windows
.\.venv\Scripts\Activate.ps1
# Unix
source .venv/bin/activate
4. Fill model configuration before continuing
Before installing dependencies or launching the app, ensure .env has real model settings. If .env is missing, copy .env.example to .env, then pause and ask the user to fill these fields.
This project uses two different model capabilities:
- Chat LLM: used by the appointment, consultation, task-classification, and user-behavior agents to understand user messages and generate replies.
- Embedding model: used by RAG retrieval and technician similarity matching to convert text into vectors.
Do not assume every provider offers both. Chat and embedding settings are intentionally separated in .env:
MODEL_PROVIDER=...
LLM_API_KEY=...
LLM_BASE_URL=...
LLM_MODEL=...
EMBEDDING_PROVIDER=...
EMBEDDING_API_KEY=...
EMBEDDING_BASE_URL=...
EMBEDDING_MODEL=...
The API key may be the same when one provider supplies both capabilities, such as Qwen, Zhipu, OpenAI, or Azure OpenAI. It may need to be different when the chat provider does not provide embeddings, such as DeepSeek.
Provider choices:
| Provider | Chat LLM | Embedding | Where to get key | Fill in .env |
|---|
| Qwen | Yes | Yes | Alibaba Cloud Bailian / DashScope console | MODEL_PROVIDER=qwen, EMBEDDING_PROVIDER=qwen; fill LLM_* and EMBEDDING_*. The API key can usually be the same. |
| DeepSeek | Yes | Usually no general embedding API | DeepSeek Platform | MODEL_PROVIDER=deepseek; fill LLM_*. Choose another provider for EMBEDDING_PROVIDER, usually Qwen, Zhipu, OpenAI, or Azure. |
| Zhipu | Yes | Yes | BigModel console | MODEL_PROVIDER=zhipu, EMBEDDING_PROVIDER=zhipu; fill LLM_* and EMBEDDING_*. |
| OpenAI | Yes | Yes | OpenAI Platform | MODEL_PROVIDER=openai, EMBEDDING_PROVIDER=openai; fill LLM_* and EMBEDDING_*. |
| Azure OpenAI | Yes | Yes | Azure Portal | Use MODEL_PROVIDER=azure and/or EMBEDDING_PROVIDER=azure, then add and fill the matching AZURE_OPENAI_* values. |
Recommended examples:
# Qwen for both chat and embeddings
MODEL_PROVIDER=qwen
LLM_API_KEY=your_qwen_key
LLM_BASE_URL=your_qwen_openai_compatible_chat_base_url
LLM_MODEL=your_qwen_chat_model
EMBEDDING_PROVIDER=qwen
EMBEDDING_API_KEY=your_qwen_key
EMBEDDING_BASE_URL=your_qwen_openai_compatible_embedding_base_url
EMBEDDING_MODEL=your_qwen_embedding_model
# DeepSeek for chat, Qwen for embeddings
MODEL_PROVIDER=deepseek
LLM_API_KEY=your_deepseek_key
LLM_BASE_URL=your_deepseek_openai_compatible_chat_base_url
LLM_MODEL=your_deepseek_chat_model
EMBEDDING_PROVIDER=qwen
EMBEDDING_API_KEY=your_qwen_key
EMBEDDING_BASE_URL=your_qwen_openai_compatible_embedding_base_url
EMBEDDING_MODEL=your_qwen_embedding_model
Stop here if any value still looks like your_..._here. Tell the user: “Please fill .env, then tell me it is ready, and I will continue setup.”
5. Install dependencies
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
faiss-cpu may take 1–2 minutes on first install — that is normal.
6. Validate .env
If a .env already exists, leave it alone. Otherwise copy .env.example to .env. Then check the values:
| Key | Required | Notes |
|---|
MODEL_PROVIDER | ✅ | qwen, deepseek, zhipu, openai, openai-compatible, or azure |
LLM_API_KEY | ✅ for non-Azure | Chat model API key |
LLM_BASE_URL | ✅ for non-Azure | OpenAI-compatible base URL provided by the selected provider |
LLM_MODEL | ✅ for non-Azure | Chat model name provided by the selected provider |
EMBEDDING_PROVIDER | ✅ | Usually qwen, zhipu, openai, or azure |
EMBEDDING_API_KEY | ✅ for non-Azure | Embedding model API key; can match LLM_API_KEY |
EMBEDDING_BASE_URL | ✅ for non-Azure | OpenAI-compatible embedding base URL provided by the selected provider |
EMBEDDING_MODEL | ✅ for non-Azure | Embedding model name provided by the selected provider |
AZURE_OPENAI_* | ✅ only for Azure | Used when provider is azure |
OPENWEATHER_API_KEY | ⚠ optional | Used by the MCP weather tool |
If any required key still equals the placeholder (your_..._here), pause and ask the user to fill it in before continuing. Never commit a populated .env.
7. Ensure data directory
New-Item -ItemType Directory -Force -Path data | Out-Null
The app writes the SQLite DB and FAISS index cache here on first launch.
8. Verify
.\.venv\Scripts\python.exe .github\skills\setup-environment\scripts\verify_env.py
This script imports the critical packages and validates the model provider variables.
9. (Optional) Launch
.\.venv\Scripts\python.exe -m uvicorn app:app --host 127.0.0.1 --port 8001 --reload
Open http://127.0.0.1:8001/docs to confirm.
Troubleshooting
| Symptom | Fix |
|---|
Activate.ps1 cannot be loaded because running scripts is disabled | Run PowerShell as user and execute: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned, or invoke with powershell -ExecutionPolicy Bypass -File ... |
faiss-cpu build fails on Windows | Upgrade pip first (python -m pip install --upgrade pip), ensure Python is 64-bit, retry |
mcp package not found | Confirm Python is 3.10–3.12; mcp>=1.0.0 requires modern Python |
TypeError: 'function' object is not subscriptable during LangChain import | You are on Python 3.13/3.14. PEP 649 breaks LangChain 0.3.x. Install Python 3.12 and rebuild .venv (-Force) |
ModuleNotFoundError after install | The shell is using system Python. Re-activate .venv and re-run |
| Port 8001 already in use | Stop the previous server or pass --port 8002 to uvicorn |
| Model auth errors at startup | Re-check MODEL_PROVIDER, LLM_API_KEY, LLM_BASE_URL, LLM_MODEL, and embedding settings in .env |
Files in this skill
.github/skills/setup-environment/
├── SKILL.md ← this file
└── scripts/
├── setup.ps1 ← one-shot bootstrapper for Windows
├── setup.sh ← one-shot bootstrapper for macOS/Linux
└── verify_env.py ← import-level smoke test
A .env.example template lives at the project root (sibling of requirements.txt) so the bootstrap scripts can copy it on a clean checkout.
