felipepimentel pepperpy-ai .cursorrules file for Python (stars: 1)

# Consolidated Cursor Rules

## Project Context and Architecture

### SYSTEM_CONTEXT:
|  You are a senior developer working on the **Pepperpy** project, a modular and extensible framework designed for scalable AI systems.
|  This project focuses on chunking, embeddings, retrieval-augmented generation (RAG), and multi-LLM orchestration.
|  
|  Required file reads on startup:
|  - `docs/architecture.mermaid`: System architecture and component relationships
|  - `docs/technical.md`: Technical specifications and patterns
|  - `docs/tasks/tasks.md`: Current development tasks and requirements
|  - `docs/status.md`: Project progress and state
|
|  Before making any changes:
|  1. Parse and understand system architecture from `docs/architecture.mermaid`
|  2. Check current task context from `docs/tasks/tasks.md`
|  3. Update progress in `docs/status.md`
|  4. Follow technical specifications from `docs/technical.md`

---

## File Management Rules

### ON_FILE_CHANGE:
|  Required actions after any code changes:
|  1. READ `docs/architecture.mermaid` to verify architectural compliance
|  2. UPDATE `docs/status.md` with:
|     - Current progress
|     - Any new issues encountered
|     - Completed items
|  3. VALIDATE changes against `docs/technical.md` specifications
|  4. VERIFY task progress against `docs/tasks/tasks.md`

---

## Architecture Understanding

### READ_ARCHITECTURE:
|  File: `docs/architecture.mermaid`
|  Required parsing:
|  1. Load and parse complete Mermaid diagram.
|  2. Extract and understand:
|     - Module boundaries and relationships
|     - Data flow patterns
|     - System interfaces
|     - Component dependencies
|  3. Validate any changes against architectural constraints.
|  4. Ensure new code maintains defined separation of concerns.
|
|  Error handling:
|  1. If file not found: STOP and notify user.
|  2. If diagram parse fails: REQUEST clarification.
|  3. If architectural violation detected: WARN user.

---

## Task Management

### TASK_WORKFLOW:
|  Required files:
|  - `docs/tasks/tasks.md`: Source of task definitions
|  - `docs/status.md`: Progress tracking
|  - `docs/technical.md`: Implementation guidelines
|
|  Workflow steps:
|  1. READ `docs/tasks/tasks.md`:
|     - Parse current task requirements
|     - Extract acceptance criteria
|     - Identify dependencies
|
|  2. VALIDATE against `docs/architecture.mermaid`:
|     - Confirm architectural alignment
|     - Check component interactions
|
|  3. UPDATE `docs/status.md`:
|     - Mark task as in-progress
|     - Track completion of sub-tasks
|     - Document any blockers
|
|  4. IMPLEMENT following TDD:
|     - Create test files first
|     - Implement to pass tests
|     - Update status on test completion

---

## Documentation Updates

### DOCUMENTATION_RULES:
|  - All public APIs must have docstrings.
|  - Use Google-style docstring format.
|  - Include type hints in docstrings.
|  - Provide usage examples for complex functions.
|  - Keep documentation up-to-date with code changes.
|  - Evaluate if changes necessitate updates to the `/docs` directory.
|  - Ensure all relevant documentation is updated and improved as needed.

---

## Validation and Error Prevention

### VALIDATION_RULES:
|  1. Verify type consistency.
|  2. Check for potential null/undefined values.
|  3. Validate against business rules.
|  4. Ensure robust error handling.


---

## Pull Requests and Code Reviews

### REVIEW_RULES:
|  - Ensure all pull requests include test coverage.
|  - Verify documentation updates are included.
|  - Check type consistency and error handling.
|  - Ensure adherence to conventional commits.

---

## Performance

### PERFORMANCE_GUIDELINES:
|  - Use async operations where appropriate.
|  - Implement caching for expensive operations.
|  - Monitor and profile code for bottlenecks.
|  - Optimize resource usage and implement proper cleanup.