refactor: streamline onboarding modal by removing unnecessary slide preparation logic and enhancing loading state management for improved user experience

2025-12-04 00:11:26 -05:00
parent a6c8e14db0
commit 5cd9a52668
242 changed files with 59643 additions and 61 deletions
--- a/.cursor/rules/openai.mdc
+++ b/.cursor/rules/openai.mdc
@@ -0,0 +1,246 @@
+---
+description: Comprehensive best practices and coding standards for projects using the openai library, covering code structure, performance, security, and common pitfalls.
+globs: *.py
+---
+# openai Library Best Practices and Coding Standards
+
+This document outlines best practices and coding standards for developing applications using the `openai` library. Following these guidelines will lead to more maintainable, performant, and secure code.
+
+## Library Information:
+- Name: openai
+- Tags: ai, ml, llm, api
+
+## 1. Code Organization and Structure
+
+### 1.1 Directory Structure Best Practices
+
+Adopt a clear and consistent directory structure to improve code organization and maintainability. Here's a recommended structure for projects using the openai library:
+
+
+project_root/
+├── src/                        # Source code directory
+│   ├── models/              # Definitions for your models (e.g., data classes, schemas)
+│   ├── services/             # Service layer for interacting with the OpenAI API
+│   │   ├── openai_service.py   # Encapsulates OpenAI API calls
+│   ├── utils/                # Utility functions
+│   ├── main.py               # Entry point of your application
+├── tests/                      # Tests directory
+│   ├── unit/                 # Unit tests
+│   ├── integration/          # Integration tests
+│   ├── conftest.py           # Pytest configuration file
+├── data/                       # Data storage (e.g., prompts, training data)
+├── docs/                       # Documentation
+├── .env                        # Environment variables
+├── requirements.txt            # Dependencies
+├── README.md                   # Project README
+
+
+### 1.2 File Naming Conventions
+
+-   Use descriptive and consistent file names.
+-   Python files should use snake_case (e.g., `openai_service.py`).
+-   Class names should use CamelCase (e.g., `OpenAIService`).
+-   Variable names should use snake_case (e.g., `api_key`).
+
+### 1.3 Module Organization
+
+-   Group related functionalities into modules.
+-   Avoid circular dependencies between modules.
+-   Use clear and concise module names.
+-   Use `__init__.py` files to define packages and control namespace.
+
+### 1.4 Component Architecture
+
+Consider using a layered architecture to separate concerns:
+
+-   **Presentation Layer:** Handles user interface or external API interactions.
+-   **Service Layer:** Encapsulates business logic and interacts with the OpenAI API.
+-   **Data Access Layer:** Handles data persistence and retrieval.
+
+This separation makes testing and maintenance easier.
+
+### 1.5 Code Splitting Strategies
+
+-   Split large files into smaller, more manageable modules based on functionality.
+-   Use abstract base classes and interfaces to define contracts between components.
+-   Apply the Single Responsibility Principle (SRP) to classes and functions.
+
+## 2. Common Patterns and Anti-patterns
+
+### 2.1 Design Patterns
+
+-   **Factory Pattern:** Use a factory to create OpenAI API client instances with different configurations.
+-   **Strategy Pattern:** Implement different prompt strategies based on the task.
+-   **Decorator Pattern:** Add logging, caching, or rate limiting to OpenAI API calls.
+
+### 2.2 Recommended Approaches
+
+-   **Prompt Engineering:** Follow best practices for prompt design. Place clear instructions at the beginning of prompts, be specific, and use examples.
+-   **Configuration:** Store API keys and other sensitive information in environment variables using a library like `python-dotenv`.
+-   **Asynchronous Calls:** Use `asyncio` and `aiohttp` for non-blocking API calls to improve performance.
+-   **Retries and Exponential Backoff:** Implement retry mechanisms with exponential backoff to handle transient API errors.
+
+### 2.3 Anti-patterns
+
+-   **Hardcoding API Keys:** Never hardcode API keys directly into your code. Always use environment variables.
+-   **Ignoring Rate Limits:** Implement rate limiting to avoid exceeding OpenAI API limits.
+-   **Lack of Error Handling:** Always handle API errors gracefully and provide informative error messages.
+-   **Overly Complex Prompts:** Keep prompts simple and focused. Break down complex tasks into smaller steps.
+-   **Mixing Concerns:** Avoid mixing presentation, business logic, and data access in the same component.
+
+### 2.4 State Management
+
+-   Use appropriate data structures to manage the state of your OpenAI interactions.
+-   Consider using a state management library if your application has complex state requirements.
+-   Avoid storing sensitive information in application state.
+
+### 2.5 Error Handling
+
+-   Use `try-except` blocks to catch potential exceptions.
+-   Log errors with sufficient context for debugging.
+-   Implement custom exception classes for specific error conditions.
+-   Handle rate limit errors and implement retry logic.
+
+## 3. Performance Considerations
+
+### 3.1 Optimization Techniques
+
+-   **Caching:** Cache API responses to reduce the number of API calls.
+-   **Batching:** Batch multiple API requests into a single request when possible.
+-   **Asynchronous Operations:** Use asynchronous programming to avoid blocking the main thread.
+-   **Token Optimization:** Reduce the number of tokens in your prompts to lower costs and improve response times.
+
+### 3.2 Memory Management
+
+-   Be mindful of the size of your prompts and responses, especially when working with large language models.
+-   Use generators to process large datasets in chunks.
+-   Clean up resources (e.g., file handles, network connections) promptly.
+
+### 3.3 Rendering Optimization (If Applicable)
+
+-   If your application involves rendering OpenAI-generated content, optimize the rendering process to minimize latency.
+
+### 3.4 Bundle Size Optimization (If Applicable)
+
+-   For web applications, minimize bundle size by using tree shaking and code splitting.
+
+### 3.5 Lazy Loading
+
+-   Use lazy loading to load modules or data only when they are needed.
+
+## 4. Security Best Practices
+
+### 4.1 Common Vulnerabilities
+
+-   **API Key Exposure:** Protect your OpenAI API key. Never commit it to version control or share it publicly.
+-   **Prompt Injection:** Validate and sanitize user inputs to prevent prompt injection attacks.
+-   **Data Leakage:** Avoid exposing sensitive data in prompts or API responses.
+
+### 4.2 Input Validation
+
+-   Validate all user inputs to prevent malicious or unexpected data from being sent to the OpenAI API.
+-   Sanitize inputs to remove potentially harmful characters or code.
+
+### 4.3 Authentication and Authorization
+
+-   Implement authentication and authorization mechanisms to protect your application and data.
+-   Use secure storage for API keys and other sensitive information.
+
+### 4.4 Data Protection
+
+-   Encrypt sensitive data at rest and in transit.
+-   Follow data privacy regulations (e.g., GDPR, CCPA).
+
+### 4.5 Secure API Communication
+
+-   Use HTTPS to encrypt communication with the OpenAI API.
+-   Verify the authenticity of the OpenAI API server using SSL certificates.
+
+## 5. Testing Approaches
+
+### 5.1 Unit Testing
+
+-   Write unit tests for individual components to ensure they function correctly in isolation.
+-   Use mocking and stubbing to isolate components from external dependencies (e.g., the OpenAI API).
+
+### 5.2 Integration Testing
+
+-   Write integration tests to verify that different components work together correctly.
+-   Test the interaction between your application and the OpenAI API.
+
+### 5.3 End-to-End Testing
+
+-   Write end-to-end tests to simulate user interactions and verify that the entire application works as expected.
+
+### 5.4 Test Organization
+
+-   Organize your tests into a clear and consistent directory structure.
+-   Use descriptive test names.
+-   Follow a consistent testing style.
+
+### 5.5 Mocking and Stubbing
+
+-   Use mocking libraries like `unittest.mock` or `pytest-mock` to mock the OpenAI API.
+-   Create stubs for API responses to control the behavior of the API during testing.
+
+## 6. Common Pitfalls and Gotchas
+
+### 6.1 Frequent Mistakes
+
+-   **Not handling API errors:** Implement proper error handling for OpenAI API calls.
+-   **Exceeding rate limits:** Implement rate limiting and exponential backoff to avoid exceeding API limits.
+-   **Incorrect prompt formatting:** Follow OpenAI's prompt engineering guidelines to optimize model performance.
+-   **Not validating inputs:** Validate user inputs to prevent prompt injection attacks and unexpected behavior.
+
+### 6.2 Edge Cases
+
+-   **Handling very long prompts:** Be aware of token limits and consider splitting long prompts into smaller chunks.
+-   **Dealing with ambiguous or unclear instructions:** Craft prompts carefully to provide clear and specific instructions.
+-   **Handling unexpected API responses:** Implement robust error handling to deal with unexpected API responses.
+
+### 6.3 Version-Specific Issues
+
+-   Be aware of changes between different versions of the `openai` library.
+-   Consult the release notes and migration guides when upgrading to a new version.
+
+### 6.4 Compatibility Concerns
+
+-   Ensure compatibility between the `openai` library and other libraries used in your project.
+-   Test your application thoroughly after upgrading any dependencies.
+
+### 6.5 Debugging Strategies
+
+-   Use logging to track the flow of your application and identify potential issues.
+-   Use a debugger to step through your code and inspect variables.
+-   Use unit tests to isolate and debug individual components.
+
+## 7. Tooling and Environment
+
+### 7.1 Recommended Development Tools
+
+-   **IDE:** VS Code, PyCharm
+-   **Virtual Environment Manager:** venv, conda, pipenv
+-   **Package Manager:** pip, poetry
+-   **Testing Framework:** pytest, unittest
+-   **Linting and Formatting:** pylint, flake8, black
+
+### 7.2 Build Configuration
+
+-   Use a `requirements.txt` or `pyproject.toml` file to manage dependencies.
+-   Use a build system like `setuptools` or `poetry` to package your application.
+
+### 7.3 Linting and Formatting
+
+-   Use a linter like `pylint` or `flake8` to enforce coding style guidelines.
+-   Use a formatter like `black` to automatically format your code.
+
+### 7.4 Deployment Best Practices
+
+-   Use a containerization technology like Docker to package your application and its dependencies.
+-   Deploy your application to a cloud platform like AWS, Azure, or Google Cloud.
+-   Use a process manager like `systemd` or `supervisor` to manage your application.
+
+### 7.5 CI/CD Integration
+
+-   Use a CI/CD pipeline to automate the build, test, and deployment process.
+-   Integrate your tests into the CI/CD pipeline to ensure that all changes are thoroughly tested before being deployed.