Plexure API Search with Cursor

Comprehensive Cursor rules for building and maintaining a code search application that efficiently searches and analyzes code across various repositories. Integrates with CSV databases and automates processes using GitHub Actions.

Code Preservation Rules

When working on this codebase, always follow these preservation principles:

**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 Structure and Responsibilities

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 (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 (docs/ directory)

**api.md** - API documentation

**architecture.md** - System architecture

**deployment.md** - Deployment guide

**development.md** - Development guide

**testing.md** - Testing guide

Code Style Guidelines

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 Principles

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

**Circular dependencies are strictly forbidden**

Maintain clear separation of concerns

Testing Standards

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 Requirements

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

Dependency Management

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 Configuration

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 Optimization

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 Best Practices

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 and Observability

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 Guidelines

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

Usage Example

When working in Cursor, these rules will automatically guide your development:

1. **Making changes**: Always preserve existing code not related to your change

2. **Adding features**: Write tests first, maintain >80% coverage

3. **Refactoring**: Keep existing functionality intact, update tests if needed

4. **Documentation**: Update docstrings and README.md for any public API changes

5. **Dependencies**: Use Poetry to add new dependencies, document in README

6. **Performance**: Profile before optimizing, maintain <200ms response times

7. **Security**: Validate all inputs, never commit secrets

Important Constraints

Python 3.9+ required

Poetry for dependency management

Pytest for testing (>80% coverage)

PEP 8 style guidelines

100 character line limit

No circular dependencies

Never commit sensitive data

Never remove unrelated code

Plexure API Search with Cursor

Plexure API Search with Cursor

Code Preservation Rules

File Structure and Responsibilities

Core Files

Support Files

Configuration Files (project root)

Documentation Files (docs/ directory)

Code Style Guidelines

Project Structure Principles

Testing Standards

Documentation Requirements

Dependency Management

Environment Configuration

Model Management

Error Handling

Performance Optimization

Security Best Practices

Monitoring and Observability

Version Control Guidelines

Usage Example

Important Constraints

Reviews (0)