Setup Environment

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:

1. Chat LLM: used by the appointment, consultation, task-classification, and user-behavior agents to understand user messages and generate replies.
2. 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:

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:

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

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.