b745151d2c
- Create end-to-end tests - Add diagnose file to determine cause of failure for end-to-end tests
155 lines
4.4 KiB
Markdown
155 lines
4.4 KiB
Markdown
# SkyTalk API - Development Guide
|
|
|
|
Quick guide to get the SkyTalk API running and test it.
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### 1. Setup Environment
|
|
```bash
|
|
# Create and activate virtual environment
|
|
uv venv
|
|
source .venv/bin/activate # Linux/Mac
|
|
# .venv\Scripts\activate # Windows
|
|
|
|
# Install dependencies
|
|
uv pip install -r requirements.txt
|
|
```
|
|
|
|
### 2. Configure Environment Variables
|
|
Edit `.env` file and add your Google API key:
|
|
```bash
|
|
GOOGLE_API_KEY=your_actual_google_api_key_here
|
|
```
|
|
|
|
### 3. Run Tests
|
|
```bash
|
|
# Quick validation tests
|
|
python run_tests.py
|
|
|
|
# Full test suite
|
|
pytest
|
|
|
|
# Test count: Should show 54 tests passing
|
|
```
|
|
|
|
### 4. Start the API Server
|
|
```bash
|
|
# Method 1: Direct Python
|
|
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
|
|
|
# Method 2: Using the main.py script
|
|
python app/main.py
|
|
```
|
|
|
|
### 5. Test the API
|
|
|
|
#### Option A: Automated Testing (Recommended)
|
|
```bash
|
|
# Start server and run comprehensive tests
|
|
python test_api_manual.py --start-server
|
|
|
|
# Or test against already running server
|
|
python test_api_manual.py
|
|
```
|
|
|
|
#### Option B: Manual Testing with curl
|
|
```bash
|
|
# Make the script executable
|
|
chmod +x test_api_curl.sh
|
|
|
|
# Run the tests (requires jq for JSON formatting)
|
|
./test_api_curl.sh
|
|
```
|
|
|
|
#### Option C: Interactive Testing
|
|
1. Open browser to http://localhost:8000/docs
|
|
2. Use the interactive Swagger UI to test endpoints
|
|
3. Start with `/sessions/start` with topic like "AI ethics"
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
app/
|
|
├── api/ # FastAPI endpoints (future: organized by domain)
|
|
├── services/ # Business logic and AI agents
|
|
│ ├── interviewer.py # RAG-powered Socratic interviewer
|
|
│ ├── synthesizer.py # Transcript → Zettels + Links
|
|
│ ├── vector.py # ChromaDB + embeddings
|
|
│ └── session_service.py # Orchestrates the full pipeline
|
|
├── data/ # Database layer
|
|
│ ├── models/ # SQLModel schemas + API models
|
|
│ ├── repositories/ # Async CRUD operations
|
|
│ └── database.py # Async SQLite setup
|
|
├── core/ # Configuration and utilities
|
|
│ ├── config.py # Pydantic settings
|
|
│ ├── prompts/ # External prompt files
|
|
│ └── prompt_loader.py # Prompt management
|
|
└── main.py # FastAPI app with lifespan management
|
|
```
|
|
|
|
## 🔄 API Workflow
|
|
|
|
1. **Start Session**: `POST /sessions/start` with a topic
|
|
2. **Conversation**: `POST /sessions/sendMessage` back and forth
|
|
3. **Auto-End**: AI detects natural conclusion with `[END_SESSION]`
|
|
4. **Background Synthesis**: Async processing begins automatically
|
|
5. **Check Status**: `GET /sessions/getStatus` to monitor progress
|
|
6. **Result**: Session status becomes "completed" with generated notes
|
|
|
|
## 🧪 Testing Strategy
|
|
|
|
- **Unit Tests**: 54 tests covering all core functionality
|
|
- **Integration Tests**: `test_api_manual.py` for end-to-end workflows
|
|
- **Manual Tests**: `test_api_curl.sh` for quick verification
|
|
- **Development Tests**: `run_tests.py` for rapid validation
|
|
|
|
## 🔧 Development Commands
|
|
|
|
```bash
|
|
# Code quality (run before committing)
|
|
black . # Format code
|
|
mypy . # Type checking
|
|
ruff check . # Linting
|
|
|
|
# Database operations
|
|
rm skytalk.db* # Reset database
|
|
rm -rf chroma_db/ # Reset vector store
|
|
|
|
# Run specific test categories
|
|
pytest tests/test_models.py -v
|
|
pytest tests/test_vector_service.py -v
|
|
pytest tests/test_interviewer_agent.py -v
|
|
```
|
|
|
|
## 🐛 Common Issues
|
|
|
|
### API Key Issues
|
|
- Make sure `GOOGLE_API_KEY` is set in `.env`
|
|
- Verify the key has access to Gemini API and embedding models
|
|
|
|
### Database Issues
|
|
- Delete `skytalk.db` to reset the database
|
|
- Check file permissions in the project directory
|
|
|
|
### ChromaDB Issues
|
|
- Delete `chroma_db/` directory to reset vector store
|
|
- Ensure sufficient disk space for embeddings
|
|
|
|
### Import Issues
|
|
- Ensure virtual environment is activated
|
|
- Run `uv pip install -r requirements.txt` again
|
|
|
|
## 📊 Monitoring
|
|
|
|
- **Logs**: Check console output for detailed logging
|
|
- **Database**: Use SQLite browser to inspect `skytalk.db`
|
|
- **Vector Store**: ChromaDB data in `chroma_db/` directory
|
|
- **Health**: `GET /health` endpoint for service status
|
|
|
|
## 🚀 Next Steps
|
|
|
|
- **Authentication**: Add user accounts and JWT tokens
|
|
- **Rate Limiting**: Implement API rate limiting
|
|
- **Monitoring**: Add structured logging and metrics
|
|
- **Deployment**: Containerize with Docker
|
|
- **Frontend**: Build web interface consuming this API |