Skip to content

Latest commit

 

History

History
63 lines (56 loc) · 3.61 KB

windsurfrules.md

File metadata and controls

63 lines (56 loc) · 3.61 KB

Key Principles

  • Write concise, technical responses with accurate Python examples using Modal’s latest syntax.
  • Use functional, declarative programming; avoid classes where possible.
  • Prefer iterative, modular designs over code duplication.
  • Use descriptive variable names with auxiliary verbs (e.g., is_active, has_permission).
  • Use lowercase with underscores for directories and files (e.g., routers/user_routes.py).
  • Favor named exports for routes and utility functions.
  • Use the Receive an Object, Return an Object (RORO) pattern.

Python/Modal

  • Use def for pure functions and async def for asynchronous operations.
  • Use type hints for all function signatures; prefer Pydantic models (v2) over raw dictionaries for input validation.
  • Organize your file structure into Modal app functions, sub-routes, utilities, static content, and types (models, schemas).
  • Avoid unnecessary curly braces in conditional statements.
  • For single-line conditionals, omit braces (e.g., if condition: do_something()).

Error Handling and Validation

  • Prioritize error handling and edge cases:
    • Handle errors and invalid states at the start of functions (use guard clauses).
    • Use early returns to avoid deep nesting; keep the “happy path” clear at the end.
    • Avoid unnecessary else statements by using the if-return pattern.
    • Implement proper error logging and user-friendly messages.
    • Use custom error types or error factories for consistent error handling.

Dependencies

  • Modal (with the latest SDK and migration guide updates)
  • FastAPI
  • Pydantic v2
  • Async database libraries (e.g. asyncpg, aiomysql)
  • SQLAlchemy 2.0 (if using ORM features)
  • Modal’s GPU and image builder libraries

Modal-Specific Guidelines

  • Use Modal’s functional decorators (e.g., @app.function(), @modal.web_endpoint(), @modal.asgi_app()) for declaring endpoints and background functions.
  • Define container images with method chaining (e.g., 
    image = (
    modal.Image.debian_slim(python_version="3.11")
    .pip_install("fastapi[standard]")
    .add_local_python_source("helpers")
)
    ) rather than relying on deprecated APIs.
  • Replace deprecated constructs (e.g., Mount, @modal.build) with the new image-building methods and explicit inclusion parameters (e.g., include_source).
  • Rely on Modal’s dependency injection system to manage shared state and resources.
  • Use HTTPException (or equivalent) for predictable error responses in web endpoints.
  • Leverage middleware for logging, error monitoring, and performance optimizations.

Performance Optimization

  • Minimize blocking I/O; use asynchronous operations for database calls and external API requests.
  • Implement caching for static or frequently accessed data using in-memory stores or Redis.
  • Optimize data serialization/deserialization with Pydantic.
  • Employ lazy loading techniques for large datasets and substantial API responses.

Key Conventions

  1. Rely on Modal’s dependency injection system to manage state and shared resources.
  2. Prioritize API performance metrics (response time, latency, throughput).
  3. Limit blocking operations in routes:
    • Favor asynchronous, non-blocking flows.
    • Use dedicated async functions for database and external API operations.
    • Structure routes and dependencies clearly to optimize readability and maintainability.

Refer to Modal’s latest documentation and migration guide for detailed instructions on updated APIs—such as deprecating legacy methods (e.g., Image.copy_*, Mount) in favor of explicit, modular, and declarative constructs.