This guide helps you set up the development environment for Kavya with automatic linting and testing on commit.
-
Clone and navigate to the project:
cd kavya -
Set up the development environment:
./setup-dev.sh
This script will:
- Create a virtual environment if needed
- Install development dependencies (Black, isort, pre-commit)
- Install main project dependencies
- Set up pre-commit hooks
- Test the configuration
-
Activate the virtual environment (if not already active):
source venv/bin/activate
The project uses intelligent pre-commit hooks that automatically run on every commit with smart test selection based on what files you change:
The hook intelligently decides which tests to run based on your changes:
-
📄 Documentation only (
.md,.txt, etc.):- ✅ Linting only, no API tests (saves time!)
-
📝 Python file changes:
- ✅ Black formatter (auto-fixes formatting)
- ✅ isort import sorter (auto-fixes import order)
- ✅ Core API tests:
streaming-completion.sh- Tests streaming responsesnon-streaming-completion.sh- Tests non-streaming responsesstructured-completion.sh- Tests structured outputimage-analysis.sh- Tests image processing
-
🌐 Web search changes (
web_search.py):- ✅ Core tests + specialized web search tests:
web-search-streaming.sh- Tests web search with streamingweb-search-non-streaming.sh- Tests web search without streaming
- ✅ Core tests + specialized web search tests:
-
🔄 Controller/Provider changes (
controller.py,provider_chain.py):- ✅ Core tests + fallback/provider tests:
fallback-anthropic-openai.sh- Tests provider fallbacksfallback-groq-openai.sh- Tests provider switching- All
fallback-*.shtests (with 30s timeout)
- ✅ Core tests + fallback/provider tests:
-
⚙️ Configuration changes (
.yaml,.json,.env):- ✅ All tests run (config changes can affect API behavior)
- ✅ Automatically finds and activates
venv/or.venv/ - ✅ No manual activation needed - hook handles it for you
- ✅ Graceful fallback when tools aren't available
- ✅ Auto-fixes: Formatting issues are automatically fixed and staged
- ✅ Auto-commits: Fixed files are automatically included in your commit
- ❌ Blocks commits: If tests fail or issues can't be auto-fixed
- 🚀 Performance optimized: Only runs relevant tests for your changes
# Format all Python files
python -m black .
# Sort all imports
python -m isort .
# Run all pre-commit hooks manually
pre-commit run --all-files
# Run hooks on specific files
pre-commit run --files kavya/models.py# Run individual API tests
./tests/streaming-completion.sh
./tests/non-streaming-completion.sh
./tests/structured-completion.sh
./tests/image-analysis.sh
# Run all API tests
find tests -name "*.sh" -executable -exec {} \;# Check if hook is installed and executable
ls -la .git/hooks/pre-commit
# Reinstall hooks
pre-commit install --overwrite# Install development dependencies
pip install -r requirements-dev.txt
# Or install specific tools
pip install black==24.4.2 isort==5.13.2# Make sure the server is running
python -m kavya.openai_server --port 8080
# Check server health
curl http://localhost:8080/health
# Run tests with verbose output
./tests/non-streaming-completion.sh -v# Skip all hooks (only use for emergencies)
git commit --no-verify
# Skip specific hooks
SKIP=black,isort git commit.pre-commit-config.yaml- Pre-commit framework configuration.git/hooks/pre-commit- Manual pre-commit hook scriptrequirements-dev.txt- Development dependencies- GitHub Actions -
.github/workflows/lint.ymluses same tools
Install these extensions for the best experience:
- Python
- Black Formatter
- isort
Add to your VS Code settings:
{
"python.formatting.provider": "black",
"python.sortImports.provider": "isort",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.organizeImports": true
}
}# 1. Update documentation
vim README.md
# 2. Stage and commit
git add README.md
git commit -m "Update API documentation"
# The hook will:
# 🔄 Activate virtual environment automatically
# 📄 Detect only docs changed
# ⏭️ Skip all API tests (saves ~30 seconds!)
# ✅ Complete in ~1 second# 1. Make your changes
vim kavya/models.py
# 2. Stage and commit
git add kavya/models.py
git commit -m "Add reasoning support to models"
# The hook will:
# 🔄 Activate virtual environment automatically
# 🖤 Check and fix formatting with Black
# 📦 Check and fix imports with isort
# 🧪 Run core API tests (streaming, non-streaming, structured, image)
# ✅ Auto-stage any fixes
# ❌ Block commit if tests fail# 1. Modify web search logic
vim kavya/web_search.py
# 2. Stage and commit
git add kavya/web_search.py
git commit -m "Improve web search query generation"
# The hook will:
# 🔄 Activate virtual environment automatically
# 🖤 Fix formatting issues
# 🧪 Run core API tests
# 🌐 PLUS run specialized web search tests
# ✅ Ensure web search functionality works end-to-end# 1. Update provider fallback logic
vim kavya/controller.py
# 2. Stage and commit
git add kavya/controller.py
git commit -m "Improve provider fallback handling"
# The hook will:
# 🔄 Activate virtual environment automatically
# 🖤 Fix formatting issues
# 🧪 Run core API tests
# 🔄 PLUS run all fallback tests (anthropic-openai, groq-openai, etc.)
# ✅ Verify provider switching works correctly# 1. Update configuration
vim config.yaml
# 2. Stage and commit
git add config.yaml
git commit -m "Add new model configurations"
# The hook will:
# ⚙️ Detect config changes
# 🧪 Run full test suite (config affects API behavior)
# ✅ Ensure all functionality still works with new config