Spaces:
Sleeping
Sleeping
| # SAAP Quick Start Guide | |
| **satware Autonomous Agent Platform (SAAP)** - Local multi-agent orchestration platform | |
| ## ⚠️ CRITICAL SECURITY NOTICE | |
| **Before running the project, you MUST remediate hardcoded API keys!** | |
| The imported codebase contains **40+ hardcoded API keys** that must be replaced with environment variables before: | |
| - Running the application | |
| - Pushing to GitHub | |
| - Deploying to any environment | |
| **📋 Action Required:** See `SECURITY_REMEDIATION_REQUIRED.md` for detailed remediation steps. | |
| --- | |
| ## Prerequisites | |
| ### Required Software | |
| 1. **Python 3.10 or higher** | |
| ```bash | |
| python3 --version # Should be 3.10+ | |
| ``` | |
| 2. **Node.js 18 or higher** | |
| ```bash | |
| node --version # Should be v18+ | |
| npm --version | |
| ``` | |
| 3. **PostgreSQL Database** | |
| ```bash | |
| psql --version | |
| ``` | |
| - Installation: https://www.postgresql.org/download/ | |
| 4. **Git** (for version control) | |
| ```bash | |
| git --version | |
| ``` | |
| ### Optional (Recommended) | |
| - **Redis** (for caching and message queuing) | |
| - **Docker** (for containerized deployment) | |
| - **Docker Compose** (for multi-service orchestration) | |
| --- | |
| ## Installation Steps | |
| ### 1. Clone the Repository | |
| ```bash | |
| git clone https://github.com/satwareAG/saap.git | |
| cd saap | |
| ``` | |
| ### 2. Backend Setup | |
| #### 2.1 Create Python Virtual Environment | |
| ```bash | |
| # Create virtual environment | |
| python3 -m venv .venv | |
| # Activate it | |
| source .venv/bin/activate # On Linux/macOS | |
| # OR | |
| .venv\Scripts\activate # On Windows | |
| ``` | |
| #### 2.2 Install Python Dependencies | |
| ```bash | |
| pip install --upgrade pip | |
| pip install -r requirements.txt | |
| ``` | |
| #### 2.3 Configure Environment Variables | |
| ```bash | |
| # Copy the example environment file | |
| cp backend/.env.example backend/.env | |
| # Edit the .env file with your settings | |
| nano backend/.env # or use your preferred editor | |
| ``` | |
| **Required Configuration:** | |
| ```env | |
| # Database | |
| DATABASE_URL=postgresql://user:password@localhost:5432/saap_db | |
| # AI Provider API Keys (⚠️ SECURITY: Never commit these!) | |
| OPENROUTER_API_KEY=your_openrouter_api_key_here | |
| COLOSSUS_API_KEY=your_colossus_api_key_here | |
| # Application Settings | |
| DEBUG=True | |
| LOG_LEVEL=INFO | |
| ``` | |
| #### 2.4 Set Up Database | |
| ```bash | |
| # Create PostgreSQL database | |
| createdb saap_db | |
| # Run migrations (if applicable) | |
| cd backend | |
| alembic upgrade head | |
| cd .. | |
| ``` | |
| ### 3. Frontend Setup | |
| #### 3.1 Install Node.js Dependencies | |
| ```bash | |
| cd frontend | |
| npm install | |
| cd .. | |
| ``` | |
| --- | |
| ## Starting the Application | |
| ### Option 1: Using Startup Scripts (Recommended) | |
| #### Start Backend | |
| ```bash | |
| ./start_backend.sh | |
| ``` | |
| The backend will be available at: | |
| - **API:** http://localhost:8000 | |
| - **API Docs (Swagger):** http://localhost:8000/docs | |
| - **API Docs (ReDoc):** http://localhost:8000/redoc | |
| #### Start Frontend (in a new terminal) | |
| ```bash | |
| ./start_frontend.sh | |
| ``` | |
| The frontend will be available at: | |
| - **Application:** http://localhost:5173 | |
| ### Option 2: Manual Start | |
| #### Start Backend Manually | |
| ```bash | |
| # Activate virtual environment | |
| source .venv/bin/activate # Linux/macOS | |
| # OR | |
| .venv\Scripts\activate # Windows | |
| # Load environment variables | |
| export $(cat backend/.env | grep -v '^#' | xargs) | |
| # Start server | |
| cd backend | |
| python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000 | |
| ``` | |
| #### Start Frontend Manually | |
| ```bash | |
| cd frontend | |
| npm run dev | |
| ``` | |
| --- | |
| ## Verifying the Installation | |
| ### 1. Check Backend Health | |
| ```bash | |
| curl http://localhost:8000/health | |
| # Expected: {"status": "healthy"} | |
| ``` | |
| ### 2. Access API Documentation | |
| Open in browser: http://localhost:8000/docs | |
| ### 3. Access Frontend Application | |
| Open in browser: http://localhost:5173 | |
| --- | |
| ## Project Structure | |
| ``` | |
| saap/ | |
| ├── backend/ # Python FastAPI Backend | |
| │ ├── agents/ # AI Agent implementations | |
| │ │ ├── colossus_agent.py # Colossus (local) agent | |
| │ │ └── openrouter_agent*.py # OpenRouter agents | |
| │ ├── api/ # API endpoints | |
| │ ├── database/ # Database models & services | |
| │ ├── services/ # Business logic services | |
| │ ├── .env.example # Environment template | |
| │ └── main.py # FastAPI application entry | |
| │ | |
| ├── frontend/ # Vue.js 3 Frontend | |
| │ ├── src/ | |
| │ │ ├── components/ # Vue components | |
| │ │ ├── views/ # Page views | |
| │ │ ├── stores/ # Pinia state management | |
| │ │ └── services/ # API client services | |
| │ ├── package.json | |
| │ └── vite.config.js # Vite configuration | |
| │ | |
| ├── start_backend.sh # Backend startup script | |
| ├── start_frontend.sh # Frontend startup script | |
| ├── requirements.txt # Python dependencies | |
| └── README.md # Full documentation | |
| ``` | |
| --- | |
| ## Common Issues & Troubleshooting | |
| ### Issue: `ModuleNotFoundError` when starting backend | |
| **Solution:** Ensure virtual environment is activated and dependencies installed: | |
| ```bash | |
| source .venv/bin/activate | |
| pip install -r requirements.txt | |
| ``` | |
| ### Issue: Port already in use (8000 or 5173) | |
| **Solution:** Kill the process using the port: | |
| ```bash | |
| # Find process using port 8000 | |
| lsof -i :8000 # or: netstat -tulpn | grep 8000 | |
| # Kill the process | |
| kill -9 <PID> | |
| ``` | |
| ### Issue: Database connection errors | |
| **Solution:** | |
| 1. Verify PostgreSQL is running: `systemctl status postgresql` | |
| 2. Check DATABASE_URL in `backend/.env` | |
| 3. Ensure database exists: `createdb saap_db` | |
| ### Issue: Frontend shows "Network Error" | |
| **Solution:** | |
| 1. Verify backend is running on port 8000 | |
| 2. Check CORS settings in `backend/main.py` | |
| 3. Check browser console for specific errors | |
| ### Issue: Hardcoded API keys detected | |
| **Solution:** | |
| 1. **DO NOT push to GitHub yet!** | |
| 2. Follow `SECURITY_REMEDIATION_REQUIRED.md` | |
| 3. Replace all hardcoded keys with environment variables | |
| 4. Re-scan with Gitleaks: `gitleaks detect --no-git` | |
| --- | |
| ## Development Workflow | |
| ### Running Tests | |
| **Backend Tests:** | |
| ```bash | |
| cd backend | |
| pytest | |
| ``` | |
| **Frontend Tests:** | |
| ```bash | |
| cd frontend | |
| npm test | |
| ``` | |
| ### Code Quality Checks | |
| **Backend (Python):** | |
| ```bash | |
| # Linting | |
| ruff check . | |
| # Type checking | |
| mypy backend/ | |
| ``` | |
| **Frontend (JavaScript/TypeScript):** | |
| ```bash | |
| cd frontend | |
| npm run lint | |
| ``` | |
| --- | |
| ## Security Best Practices | |
| ### 🔒 Essential Security Rules | |
| 1. **Never commit API keys** to version control | |
| 2. **Always use environment variables** for sensitive data | |
| 3. **Run Gitleaks** before every commit: | |
| ```bash | |
| gitleaks detect --no-git | |
| ``` | |
| 4. **Update dependencies regularly**: | |
| ```bash | |
| pip list --outdated # Python | |
| npm outdated # Node.js | |
| ``` | |
| 5. **Use strong passwords** for database and services | |
| 6. **Enable HTTPS** in production environments | |
| --- | |
| ## Next Steps | |
| After successful startup: | |
| 1. ✅ **Complete Security Remediation** (see `SECURITY_REMEDIATION_REQUIRED.md`) | |
| 2. ✅ **Configure all agents** in the dashboard | |
| 3. ✅ **Test agent orchestration** with sample tasks | |
| 4. ✅ **Review API documentation** at http://localhost:8000/docs | |
| 5. ✅ **Set up development database** with test data | |
| 6. ✅ **Configure Redis/RabbitMQ** (optional, for advanced features) | |
| --- | |
| ## Additional Resources | |
| - **Full Documentation:** `README.md` | |
| - **Security Remediation:** `SECURITY_REMEDIATION_REQUIRED.md` | |
| - **Import Notes:** `IMPORT_NOTES.md` | |
| - **API Documentation:** http://localhost:8000/docs (when running) | |
| - **Project Repository:** https://github.com/satwareAG/saap | |
| --- | |
| ## Support & Contact | |
| - **Student:** Hanan Wandji Danga | |
| - **Organization:** satware AG | |
| - **Project:** Master's Thesis - SAAP Platform | |
| - **Timeline:** 2025-09-15 to 2026-03-14 | |
| For issues or questions, please create an issue on the GitHub repository. | |
| --- | |
| **Last Updated:** 2025-11-11 | |