Plexure API Search - Cursor Rules

Code Preservation Rules

• Never remove existing code that is not directly related to the current change scope
• Always maintain existing functionality unless explicitly requested to change
• Keep all existing imports and dependencies unless they are specifically being refactored
• Preserve existing error handling and logging mechanisms
• Maintain existing configuration options and defaults
• Keep all existing CLI commands and their functionality
• Do not remove or modify existing tests unless they are directly related to changes
• Preserve existing documentation unless it needs to be updated for new changes

File Specific Rules

Core Files

• searcher.py: Search engine core logic, query processing, and result ranking
• indexer.py: API contract indexing, vector creation, and database management
• embeddings.py: Vector embedding generation and model management
• cli.py: Command-line interface and user interaction handling
• config.py: Configuration management and environment variables
• cache.py: Caching mechanisms for search results and embeddings
• metrics.py: Performance tracking and statistical measurements
• validation.py: Input validation and data sanitization
• boosting.py: Search result ranking and score boosting logic
• expansion.py: Query expansion and enhancement
• consistency.py: Data consistency and validation checks
• quality.py: Search quality metrics and improvements
• understanding.py: Natural language processing and query understanding
• monitoring.py: System monitoring and logging

Support Files

• init.py: Package initialization and version info
• main.py: Entry point for command-line execution

Configuration Files (in project root)

• pyproject.toml: Project metadata and dependencies
• poetry.lock: Locked dependency versions
• .env: Environment variables (not in git)
• .env.sample: Example environment variables
• .gitignore: Git ignore patterns
• README.md: Project documentation
• LICENSE: Project license
• NOTICE: Third-party notices

Documentation Files (in docs/ directory)

• api.md: API documentation
• architecture.md: System architecture
• deployment.md: Deployment guide
• development.md: Development guide
• testing.md: Testing guide

Code Style

• Follow PEP 8 style guidelines for Python code
• Use type hints for all function parameters and return values
• Maximum line length: 100 characters
• Use docstrings for all public functions and classes
• Use consistent naming conventions across all files
• Add comments for complex logic or business rules
• Keep functions focused and single-purpose
• Use meaningful variable names that describe their purpose

Project Structure

• Keep all core logic in plexure_api_search/ directory
• Place all tests in tests/ directory
• Store configuration files in project root
• Keep documentation in docs/ directory
• Organize modules by feature/domain
• Use init.py files to control public APIs
• Keep circular dependencies strictly forbidden
• Maintain clear separation of concerns

Testing

• Write unit tests for all new functionality
• Maintain test coverage above 80%
• Place tests in tests/ directory
• Name test files with test_ prefix
• Test files must match source file names
• Include integration tests for critical paths
• Mock external dependencies appropriately
• Test error conditions and edge cases
• Use pytest fixtures for common setup
• Include performance tests for critical operations

Documentation

• Document all public APIs with docstrings
• Keep README.md up to date with new features
• Include usage examples in docstrings
• Document complex algorithms with comments
• Maintain API documentation in docs/
• Include type hints in documentation
• Document error conditions and handling
• Keep configuration options documented
• Include troubleshooting guides

Dependencies

• Use Poetry for dependency management
• Pin dependency versions in pyproject.toml
• Keep dependencies up to date
• Document new dependencies in README.md
• Use requirements-dev.txt for development dependencies
• Make optional dependencies truly optional
• Handle dependency conflicts gracefully
• Document minimum version requirements
• Test with multiple Python versions

Environment

• Use .env for environment variables
• Never commit sensitive data
• Keep .env.sample updated
• Use Python 3.9 or higher
• Document all environment variables
• Provide default values when appropriate
• Validate environment variables at startup
• Handle missing variables gracefully
• Support different environments (dev/prod)

Model Management

• Use public, well-established models by default
• Handle model loading errors gracefully
• Implement fallback models for robustness
• Cache model artifacts appropriately
• Monitor model performance metrics
• Support model versioning
• Handle tokenization errors gracefully
• Validate model compatibility
• Document model requirements and limitations

Error Handling

• Use specific exception types
• Log errors with appropriate context
• Implement graceful fallbacks
• Validate inputs early
• Handle resource cleanup properly
• Provide meaningful error messages
• Include error recovery mechanisms
• Monitor error rates and patterns
• Document error handling procedures

Performance

• Cache expensive operations
• Use vectorized operations where possible
• Monitor memory usage
• Keep response times under 200ms
• Profile performance-critical code
• Implement request timeouts
• Use connection pooling
• Implement rate limiting
• Monitor resource utilization
• Optimize database queries

Security

• Validate all inputs
• Sanitize API responses
• Use environment variables for secrets
• Follow security best practices
• Never log sensitive data
• Implement rate limiting
• Use secure communication
• Validate authentication tokens
• Implement access controls
• Monitor security events

Monitoring

• Log important operations
• Track performance metrics
• Monitor error rates
• Use structured logging
• Implement health checks
• Track resource utilization
• Monitor API latencies
• Implement alerting
• Track business metrics
• Monitor cache effectiveness

Version Control

• Write clear commit messages
• Follow semantic versioning
• Keep feature branches small
• Merge only after tests pass
• Use conventional commits format
• Review code changes
• Maintain changelog
• Tag releases properly
• Document breaking changes
• Keep main branch stable