prazy1208/text2sql

1# Installation Requirements2 3**Text-to-SQL Multi-Agent System — Installation Only**4 5This document covers system and Python environment setup only. No schema, application code, or runtime configuration is included.6 7---8 9## A. System-Level Installations10 11### A.1 Python Version Verification12 13Requirement: **Python 3.10 or higher**.14 15**Check installed version:**16 17```bash18python --version19```20 21If missing or older than 3.10, install from [python.org](https://www.python.org/downloads/) and ensure **"Add Python to PATH"** is checked (Windows).22 23### A.2 pip Upgrade24 25Use a current pip to avoid dependency resolution issues:26 27```bash28python -m pip install --upgrade pip29```30 31---32 33## B. Python Dependency Installation34 35Use a **virtual environment** (create and activate it before installing).36 37### B.1 Install from requirements.txt38 39From the project root (with venv activated):40 41```bash42pip install -r requirements.txt43```44 45### B.2 Package Roles and Notes46 47| Package | Purpose | Notes |48|--------|---------|--------|49| **fastapi** | Web API framework | Core application server. |50| **uvicorn** | ASGI server | Runs FastAPI in production and development. |51| **pydantic** | Data validation | Used by FastAPI for request/response models; required explicitly for type-safe config and helpers. |52| **python-dotenv** | Environment variables | Loads `.env` for secrets and config. |53| **faiss-cpu** | Vector similarity search (CPU) | Used for embeddings/retrieval without GPU. |54 55### B.3 Compatibility56 57- **Windows:** All listed packages provide wheels; `faiss-cpu` works without extra system libraries.58- **macOS:** Same; on Apple Silicon use ARM-compatible wheels (provided by the packages above).59- **Python:** Keep to **3.10+** as specified; 3.11 or 3.12 are supported by this stack.60 61---62 63## C. FAISS Installation Notes64 65### C.1 CPU-Only Installation66 67Use the CPU-only package (no CUDA):68 69```bash70pip install faiss-cpu71```72 73Do **not** install `faiss` or `faiss-gpu` unless you intend to use a GPU and have the correct CUDA stack.74 75### C.2 Common Issues76 77- **ImportError or link errors:** Uninstall any existing `faiss` or `faiss-gpu`, then install only `faiss-cpu`.78- **Wrong platform:** Ensure `faiss-cpu` is installed in the same environment and Python version you use to run the app.79- **Slow install:** First install can take a minute while the wheel is downloaded and unpacked.80 81### C.3 Verify FAISS82 83```bash84python -c "import faiss; print(f'FAISS {faiss.__version__} OK')"85```86 87No error and a version string means FAISS is usable.88 89---90 91## E. Verification Checklist92 93Run these in order with the virtual environment activated:94 95| Step | Command | Expected |96|------|---------|----------|97| 1. Python | `python --version` | `Python 3.10.x` or higher |98| 2. pip | `pip --version` | Version and path inside your venv |99| 3. FastAPI | `python -c "import fastapi; print('FastAPI OK')"` | `FastAPI OK` |100| 4. Uvicorn | `python -c "import uvicorn; print('Uvicorn OK')"` | `Uvicorn OK` |101| 5. Pydantic | `python -c "import pydantic; print('Pydantic OK')"` | `Pydantic OK` |102| 6. dotenv | `python -c "import dotenv; print('dotenv OK')"` | `dotenv OK` |103| 7. FAISS | `python -c "import faiss; print('FAISS OK')"` | `FAISS OK` |104 105If every step prints OK, the installation is complete.106 107---108 109## Sequential Command List110 111Run in order (venv already created and activated):112 113```bash114# 1. Confirm Python 3.10+115python --version116 117# 2. Upgrade pip118python -m pip install --upgrade pip119 120# 3. Install all Python dependencies121pip install -r requirements.txt122 123# 4. Verify stack124python -c "import fastapi; import uvicorn; import pydantic; import dotenv; import faiss; print('All packages OK')"125```126 127---128 129*Document scope: installation only. No database schema, application code, or deployment steps.*130