app/DEVELOPMENT.md

SkyTalk API - Development Guide

Quick guide to get the SkyTalk API running and test it.

🚀 Quick Start

1. Setup Environment

# 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:

GOOGLE_API_KEY=your_actual_google_api_key_here

3. Run Tests

# Quick validation tests
python run_tests.py

# Full test suite
pytest

# Test count: Should show 54 tests passing

4. Start the API Server

# 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)

# 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

# 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

# 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