# 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