fix: main.py

- Create end-to-end tests - Add diagnose file to determine cause of failure for end-to-end tests
2025-08-17 02:11:58 +00:00
parent e59d5eea73
commit b745151d2c
6 changed files with 678 additions and 6 deletions
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -0,0 +1,155 @@
+# 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