Plexure API Search Cursor Rules

Apply these rules when building semantic API search platforms with vector embeddings, natural language processing, and API contract indexing.

Code Preservation Principles

**Critical: Never remove existing functionality without explicit approval**

Core File Responsibilities

**Search Engine Components:**

**Infrastructure Components:**

Code Style Standards

Follow PEP 8 with these specific requirements:

Example:

```python

def calculate_semantic_similarity(

query_embedding: np.ndarray,

document_embedding: np.ndarray,

boost_factor: float = 1.0

) -> float:

"""Calculate cosine similarity between query and document embeddings.

Args:

query_embedding: Query vector representation

document_embedding: Document vector representation

boost_factor: Score multiplier for ranking adjustments

Returns:

Similarity score between 0 and 1

"""

similarity = np.dot(query_embedding, document_embedding)

return min(similarity * boost_factor, 1.0)

```

Project Structure

Maintain this directory organization:

```

plexure-api-search/

├── plexure_api_search/ # Core logic (all modules go here)

│ ├── __init__.py

│ ├── searcher.py

│ ├── indexer.py

│ ├── embeddings.py

│ ├── cli.py

│ ├── config.py

│ └── ...

├── tests/ # All tests

│ ├── test_searcher.py

│ ├── test_indexer.py

│ └── ...

├── docs/ # Documentation

│ ├── api.md

│ ├── architecture.md

│ ├── deployment.md

│ ├── development.md

│ └── testing.md

├── pyproject.toml # Project metadata and dependencies

├── poetry.lock # Locked dependency versions

├── .env.sample # Example environment variables

├── .gitignore

├── README.md

├── LICENSE

└── NOTICE

```

**Key principles:**

Testing Requirements

Maintain rigorous test coverage:

Example test structure:

```python

import pytest

from plexure_api_search.searcher import SemanticSearcher

@pytest.fixture

def mock_embeddings():

"""Provide mock embedding vectors for testing."""

return np.random.rand(10, 768)

def test_search_returns_results(mock_embeddings):

"""Test that search returns ranked results."""

searcher = SemanticSearcher()

results = searcher.search("user authentication API")

assert len(results) > 0

assert results[0].score >= results[-1].score

def test_search_handles_empty_query():

"""Test graceful handling of empty queries."""

searcher = SemanticSearcher()

results = searcher.search("")

assert len(results) == 0

```

Documentation Standards

Keep documentation comprehensive and current:

Dependency Management

Use Poetry for all dependency management:

Example `pyproject.toml` section:

```toml

[tool.poetry.dependencies]

python = "^3.9"

numpy = "^1.24.0"

sentence-transformers = "^2.2.0"

chromadb = "^0.4.0"

click = "^8.1.0"

[tool.poetry.group.dev.dependencies]

pytest = "^7.4.0"

pytest-cov = "^4.1.0"

black = "^23.7.0"

mypy = "^1.4.0"

```

Environment Configuration

Use `.env` for environment-specific configuration:

Example `.env.sample`:

```bash

Embedding Model Configuration

EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2

EMBEDDING_DIMENSION=384

Database Configuration

VECTOR_DB_PATH=./data/chroma_db

CACHE_TTL_SECONDS=3600

Performance Tuning

MAX_SEARCH_RESULTS=50

QUERY_TIMEOUT_SECONDS=30

```

Model Management

Handle embedding models robustly:

Example model loading:

```python

from sentence_transformers import SentenceTransformer

def load_embedding_model(model_name: str, fallback: str = "all-MiniLM-L6-v2") -> SentenceTransformer:

"""Load embedding model with fallback."""

try:

return SentenceTransformer(model_name)

except Exception as e:

logger.warning(f"Failed to load {model_name}, using fallback: {e}")

return SentenceTransformer(fallback)

```

Error Handling

Implement comprehensive error handling:

Performance Optimization

Keep search response times under 200ms:

Example caching:

```python

from functools import lru_cache

@lru_cache(maxsize=1000)

def get_embedding(text: str) -> np.ndarray:

"""Get text embedding with LRU cache."""

return embedding_model.encode(text)

```

Security Best Practices

Protect sensitive data and prevent abuse:

Monitoring and Observability

Track system health and performance:

Example structured logging:

```python

import logging

import json

logger = logging.getLogger(__name__)

def log_search(query: str, results_count: int, latency_ms: float):

"""Log search operation with structured data."""

logger.info(json.dumps({

"event": "search",

"query": query,

"results_count": results_count,

"latency_ms": latency_ms,

"timestamp": datetime.utcnow().isoformat()

}))

```

Version Control

Follow conventional commits format:

Example commit messages:

```

feat(search): add query expansion with synonyms

fix(indexer): handle malformed API contracts gracefully

docs(readme): update model requirements section

refactor(cache): extract cache logic into separate module

```

Implementation Checklist

When adding new features:

1. Design the feature with clear interfaces

2. Write tests first (TDD approach)

3. Implement core logic with type hints

4. Add comprehensive docstrings

5. Update relevant documentation

6. Add monitoring and logging

7. Test error conditions

8. Profile performance if critical path

9. Update CHANGELOG.md

10. Review code preservation rules

Common Patterns

**Query Processing Pipeline:**

```python

query = validate_input(raw_query)

expanded_query = expand_query(query)

embedding = generate_embedding(expanded_query)

results = vector_search(embedding)

boosted_results = apply_boosting(results, query_metadata)

return rank_and_format(boosted_results)

```

**Indexing Pipeline:**

```python

api_contracts = load_contracts(source_path)

validated_contracts = validate_contracts(api_contracts)

embeddings = generate_embeddings_batch(validated_contracts)

index_to_vector_db(embeddings, metadata)

update_search_index()

invalidate_cache()

```

Anti-Patterns to Avoid