motia 0.7.2-beta.135-338519 → 0.7.2-beta.135-994416

package/dist/cjs/create/templates/nodejs/motia-workbench.json

@@ -2,27 +2,27 @@
   {
     "id": "basic-tutorial",
     "config": {
-      "steps/state-audit-cron.step.ts": {
+      "steps/petstore/state-audit-cron.step.ts": {
         "x": -165,
         "y": 217,
         "sourceHandlePosition": "right"
       },
-      "steps/process-food-order.step.ts": {
+      "steps/petstore/process-food-order.step.ts": {
         "x": 211,
         "y": 17,
         "sourceHandlePosition": "bottom",
         "targetHandlePosition": "left"
       },
-      "steps/api.step.ts": {
+      "steps/petstore/api.step.ts": {
         "x": -100,
         "y": 3,
         "sourceHandlePosition": "right",
         "targetHandlePosition": "left"
       },
-      "steps/notification.step.ts": {
+      "steps/petstore/notification.step.ts": {
         "x": 300,
         "y": 264
       }
     }
   }
-]
+]

package/dist/cjs/create/templates/nodejs/tutorial.tsx.txt

@@ -371,25 +371,35 @@ export const steps: TutorialStep[] = [
     before: [{ type: 'click', selector: workbenchXPath.closePanelButton }],
   },
   {
-    elementXpath: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial'),
+    elementXpath: workbenchXPath.endpoints.endpointsList,
     title: 'Endpoints Tool',
     description: () => (
       <p>
         This section will display all of the endpoints declared in your API Steps. It will list the HTTP method, the URL
         path, and the description declared in the Step configuration.
-        <br />
-        <br />
-        💡 Clicking on an endpoint from the list will open the endpoint overview which provides documentation on how to
-        use the endpoint and a tool to test the endpoint.
       </p>
     ),
     before: [{ type: 'click', selector: workbenchXPath.links.endpoints }],
   },
   {
-    elementXpath: workbenchXPath.sidebarContainer,
-    title: 'API Endpoint Docs',
+    elementXpath: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial'),
+    title: 'Endpoints Tool',
     description: () => (
       <p>
+        Clicking on an endpoint from the list will open the endpoint overview which provides documentation on how to use
+        the endpoint and a tool to test the endpoint.
+      </p>
+    ),
+  },
+  {
+    elementXpath: workbenchXPath.endpoints.callPanel,
+    title: 'API Endpoint Playground',
+    description: () => (
+      <p>
+        Once you click on an endpoint from the list, you will be able to test it by providing a request payload and
+        clicking on the <b>Play</b> button.
+        <br />
+        <br />
         This section will provide an overview of your API endpoint.
         <br />
         <br />
@@ -399,6 +409,25 @@ export const steps: TutorialStep[] = [
     ),
     before: [{ type: 'click', selector: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial') }],
   },
+  {
+    elementXpath: workbenchXPath.endpoints.specButton,
+    title: 'API Endpoint Specification',
+    description: () => (
+      <p>
+        Clicking on this button will open the specification of your API endpoint. Like response and request schemas.
+      </p>
+    ),
+  },
+  {
+    elementXpath: workbenchXPath.sidebarContainer,
+    title: 'API Endpoint Specification',
+    description: () => (
+      <p>
+        This is what you see when clicking on the <b>Details</b> button.
+      </p>
+    ),
+    before: [{ type: 'click', selector: workbenchXPath.endpoints.specButton }],
+  },
   {
     elementXpath: workbenchXPath.endpoints.callPanel,
     title: 'API Endpoint Test',
@@ -428,7 +457,10 @@ export const steps: TutorialStep[] = [
         </pre>
       </p>
     ),
-    before: [{ type: 'click', selector: workbenchXPath.endpoints.callTab }],
+    before: [
+      { type: 'click', selector: workbenchXPath.closePanelButton },
+      { type: 'click', selector: workbenchXPath.endpoints.bodyTab },
+    ],
   },
   {
     elementXpath: workbenchXPath.endpoints.playButton,

package/dist/cjs/create/templates/python/motia-workbench.json

@@ -2,22 +2,22 @@
   {
     "id": "basic-tutorial",
     "config": {
-      "steps/state_audit_cron_step.py": {
+      "steps/petstore/state_audit_cron_step.py": {
         "x": -38,
         "y": 683,
         "sourceHandlePosition": "right"
       },
-      "steps/process_food_order_step.py": {
+      "steps/petstore/process_food_order_step.py": {
         "x": 384,
         "y": 476,
         "targetHandlePosition": "left"
       },
-      "steps/notification_step.py": {
+      "steps/petstore/notification_step.py": {
         "x": 601,
         "y": 724,
         "targetHandlePosition": "left"
       },
-      "steps/api_step.py": {
+      "steps/petstore/api_step.py": {
         "x": 15,
         "y": 461,
         "sourceHandlePosition": "right"

package/dist/{esm/create/templates/python/steps → cjs/create/templates/python/steps/petstore}/api_step.py.txt

@@ -1,7 +1,7 @@
 from pydantic import BaseModel
 from typing import Optional
-from .services.pet_store import pet_store_service
-from .services.types import Pet
+from src.services.pet_store import pet_store_service
+from src.services.types import Pet
 
 class PetRequest(BaseModel):
     name: str

package/dist/cjs/create/templates/python/steps/{process_food_order_step.py.txt → petstore/process_food_order_step.py.txt}

@@ -1,6 +1,6 @@
 from pydantic import BaseModel
 from datetime import datetime
-from .services.pet_store import pet_store_service
+from src.services.pet_store import pet_store_service
 
 class InputSchema(BaseModel):
     id: str

package/dist/cjs/create/templates/python/tutorial.tsx.txt

@@ -360,7 +360,7 @@ export const steps: TutorialStep[] = [
     title: 'Endpoints',
     description: () => (
       <p>
-        Now that we've looked at Motia's Step types, let's trigger the API Step from the <b>endpoints</b> section in
+        Now that we've looked at Motia primitives, let's trigger the API Step from the <b>endpoints</b> section in
         Workbench.
         <br />
         <br />
@@ -371,25 +371,35 @@ export const steps: TutorialStep[] = [
     before: [{ type: 'click', selector: workbenchXPath.closePanelButton }],
   },
   {
-    elementXpath: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial'),
+    elementXpath: workbenchXPath.endpoints.endpointsList,
     title: 'Endpoints Tool',
     description: () => (
       <p>
         This section will display all of the endpoints declared in your API Steps. It will list the HTTP method, the URL
         path, and the description declared in the Step configuration.
-        <br />
-        <br />
-        💡 Clicking on an endpoint from the list will open the endpoint overview which provides documentation on how to
-        use the endpoint and a tool to test the endpoint.
       </p>
     ),
     before: [{ type: 'click', selector: workbenchXPath.links.endpoints }],
   },
   {
-    elementXpath: workbenchXPath.sidebarContainer,
-    title: 'API Endpoint Docs',
+    elementXpath: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial'),
+    title: 'Endpoints Tool',
     description: () => (
       <p>
+        Clicking on an endpoint from the list will open the endpoint overview which provides documentation on how to use
+        the endpoint and a tool to test the endpoint.
+      </p>
+    ),
+  },
+  {
+    elementXpath: workbenchXPath.endpoints.callPanel,
+    title: 'API Endpoint Playground',
+    description: () => (
+      <p>
+        Once you click on an endpoint from the list, you will be able to test it by providing a request payload and
+        clicking on the <b>Play</b> button.
+        <br />
+        <br />
         This section will provide an overview of your API endpoint.
         <br />
         <br />
@@ -399,6 +409,25 @@ export const steps: TutorialStep[] = [
     ),
     before: [{ type: 'click', selector: workbenchXPath.endpoints.endpoint('POST', '/basic-tutorial') }],
   },
+  {
+    elementXpath: workbenchXPath.endpoints.specButton,
+    title: 'API Endpoint Specification',
+    description: () => (
+      <p>
+        Clicking on this button will open the specification of your API endpoint. Like response and request schemas.
+      </p>
+    ),
+  },
+  {
+    elementXpath: workbenchXPath.sidebarContainer,
+    title: 'API Endpoint Specification',
+    description: () => (
+      <p>
+        This is what you see when clicking on the <b>Details</b> button.
+      </p>
+    ),
+    before: [{ type: 'click', selector: workbenchXPath.endpoints.specButton }],
+  },
   {
     elementXpath: workbenchXPath.endpoints.callPanel,
     title: 'API Endpoint Test',
@@ -428,7 +457,10 @@ export const steps: TutorialStep[] = [
         </pre>
       </p>
     ),
-    before: [{ type: 'click', selector: workbenchXPath.endpoints.callTab }],
+    before: [
+      { type: 'click', selector: workbenchXPath.closePanelButton },
+      { type: 'click', selector: workbenchXPath.endpoints.bodyTab },
+    ],
   },
   {
     elementXpath: workbenchXPath.endpoints.playButton,

package/dist/cjs/cursor-rules/dot-files/.cursor/index.mdc

@@ -4,14 +4,6 @@ globs:
 alwaysApply: true
 ---
 
-## Adding migration
-
-Make sure to use [migration guide](./architecture/database/database-migration.mdc) to create a new migration.
-
-## Database integration
-
-Whenever database is used, please use [database guide](./architecture/database/database.mdc) to create a database connection and methods.
-
 ## Real time events
 
 Make sure to use [real time events guide](./rules/motia/realtime-streaming.mdc) to create a new real time event.
@@ -20,6 +12,22 @@ Make sure to use [real time events guide](./rules/motia/realtime-streaming.mdc)
 
 Make sure to use [state management guide](./rules/motia/state-management.mdc) to create a new state management.
 
+## Creating HTTP Endpoints
+
+Make sure to use [API steps guide](./rules/motia/api-steps.mdc) to create new HTTP endpoints.
+
+## Background Tasks
+
+Make sure to use [event steps guide](./rules/motia/event-steps.mdc) to create new background tasks.
+
+## Scheduled Tasks
+
+Make sure to use [cron steps guide](./rules/motia/cron-steps.mdc) to create new scheduled tasks.
+
+## Virtual Steps & Flow Visualization
+
+Make sure to use [virtual steps guide](./rules/motia/virtual-steps.mdc) when connecting nodes virtually and creating smooth flows in Workbench.
+
 ## Authentication
 
 If ever need to add authentication, make sure to use middleware to authenticate the request.

package/dist/cjs/cursor-rules/dot-files/.cursor/rules/motia/api-steps.mdc

@@ -18,13 +18,16 @@ Steps need to be created in the `steps` folder, it can be in subfolders.
 
 Defining an API Step is done by two elements. Configuration and Handler.
 
-### Zod Usage
+### Schema Definition
 
-Motia relies on Zod to define body and response schemas. In Python and other languages, it uses JSON Schema.
+- **TypeScript/JavaScript**: Motia uses Zod schemas for automatic validation of request/response data
+- **Python**: Motia uses JSON Schema format. You can optionally use Pydantic models to generate JSON Schemas and handle manual validation in your handlers
 
 ### Configuration
 
-You need to export a config constant via `export const config` that is a `ApiRouteConfig` type.
+**TypeScript/JavaScript**: You need to export a config constant via `export const config` that is a `ApiRouteConfig` type.
+
+**Python**: You need to define a `config` dictionary with the same properties as the TypeScript `ApiRouteConfig`.
 
 ```typescript
 export type Emit = string | { 
@@ -189,13 +192,24 @@ export type ApiRouteHandler<
 
 ### Handler definition
 
+**TypeScript/JavaScript:**
 ```typescript
 export const handler: Handlers['CreateResource'] = async (req, { emit, logger, state, streams }) => {
   // Implementation
 }
 ```
 
-### Example
+**Python:**
+```python
+async def handler(req, context):
+    # req: dictionary containing pathParams, queryParams, body, headers
+    # context: object containing emit, logger, state, streams, trace_id
+    pass
+```
+
+### Examples
+
+#### TypeScript Example
 
 ```typescript
 import { ApiRouteConfig, Handlers } from 'motia';
@@ -314,4 +328,98 @@ export const handler: Handlers['CreateResource'] = async (req, { emit, logger })
     };
   }
 };
+```
+
+#### Python Example
+
+```python
+from pydantic import BaseModel, Field
+from typing import Optional, Dict, Any
+
+class ResourceData(BaseModel):
+    title: str = Field(..., min_length=1, description="Title cannot be empty")
+    description: Optional[str] = None
+    category: str = Field(..., min_length=1, description="Category is required")
+    metadata: Optional[Dict[str, Any]] = None
+
+class ResourceResponse(BaseModel):
+    id: str
+    title: str
+    category: str
+    status: str
+
+class ErrorResponse(BaseModel):
+    error: str
+
+config = {
+    "type": "api",
+    "name": "CreateResource",
+    "path": "/resources",
+    "method": "POST",
+    "emits": ["send-email"],
+    "flows": ["resource-management"],
+    "bodySchema": ResourceData.model_json_schema(),
+    "responseSchema": {
+        201: ResourceResponse.model_json_schema(),
+        400: ErrorResponse.model_json_schema()
+    }
+}
+
+async def handler(req, context):
+    try:
+        body = req.get("body", {})
+        
+        # Optional: Validate input manually using Pydantic (Motia doesn't do this automatically)
+        resource_data = ResourceData(**body)
+        
+        context.logger.info("Attempting to create resource", {
+            "title": resource_data.title, 
+            "category": resource_data.category
+        })
+        
+        # Process the resource creation
+        result = await service.create_resource({
+            "title": resource_data.title,
+            "description": resource_data.description,
+            "category": resource_data.category,
+            "metadata": resource_data.metadata
+        })
+
+        # Emit event to trigger other steps
+        await context.emit({
+            "topic": "send-email",
+            "data": {
+                "resource": result,
+                "user_id": "example-user"
+            }
+        })
+        
+        context.logger.info("Resource created successfully", {
+            "resource_id": result.get("id"),
+            "title": result.get("title"),
+            "category": result.get("category")
+        })
+
+        return {
+            "status": 201,
+            "body": {
+                "id": result.get("id"),
+                "title": result.get("title"),
+                "category": result.get("category"),
+                "status": "active"
+            }
+        }
+        
+    except ValidationError as e:
+        context.logger.error("Resource creation failed - Pydantic validation error", {"error": str(e)})
+        return {
+            "status": 400,
+            "body": {"error": "Validation failed"}
+        }
+    except Exception as e:
+        context.logger.error("Resource creation failed", {"error": str(e)})
+        return {
+            "status": 500,
+            "body": {"error": "Creation failed"}
+        }
 ```

package/dist/cjs/cursor-rules/dot-files/.cursor/rules/motia/cron-steps.mdc

@@ -26,7 +26,9 @@ Defining a CRON Step is done by two elements. Configuration and Handler.
 
 ### Configuration
 
-You need to export a config constant via `export const config` that is a `CronConfig` type.
+**TypeScript/JavaScript**: You need to export a config constant via `export const config` that is a `CronConfig` type.
+
+**Python**: You need to define a `config` dictionary with the same properties as the TypeScript `CronConfig`.
 
 ```typescript
 export type Emit = string | { 
@@ -98,6 +100,7 @@ export type CronConfig = {
 
 The handler is a function that is exported via `export const handler` that is a `CronHandler` type.
 
+**TypeScript/JavaScript:**
 ```typescript
 /**
  * CRON handler accepts only one argument, the FlowContext.
@@ -109,6 +112,13 @@ export const handler: Handlers['CronJobEvery5Minutes'] = async ({ logger, emit,
 }
 ```
 
+**Python:**
+```python
+async def handler(context):
+    # context: object containing emit, logger, state, streams, trace_id
+    context.logger.info("CRON Job Every 5 Minutes started")
+```
+
 ### Examples of Cron expressions
 
 - `0 0 * * *`: Runs daily at midnight
@@ -127,7 +137,9 @@ export const handler: Handlers['CronJobEvery5Minutes'] = async ({ logger, emit,
 - Collecting metrics from third-party services
 - Reconciling data from different sources
 
-## Example
+## Examples
+
+### TypeScript Example
 
 ```typescript
 export const config: CronConfig = {
@@ -138,7 +150,22 @@ export const config: CronConfig = {
   flows: ['example-flow']
 };
 
-export const handler: Handlers['CronJobEvery5Minutes'] = async (_, { logger }) => {
+export const handler: Handlers['CronJobEvery5Minutes'] = async ({ logger }) => {
   logger.info('Cron job started')
 }
+```
+
+### Python Example
+
+```python
+config = {
+    "type": "cron",
+    "name": "CronJobEvery5Minutes",
+    "cron": "*/5 * * * *",  # Run every 5 minutes
+    "emits": [],  # No emits in this example
+    "flows": ["example-flow"]
+}
+
+async def handler(context):
+    context.logger.info("Cron job started")
 ```

package/dist/cjs/cursor-rules/dot-files/.cursor/rules/motia/event-steps.mdc

@@ -28,13 +28,16 @@ Steps need to be created in the `steps` folder, it can be in subfolders.
 
 Defining an API Step is done by two elements. Configuration and Handler.
 
-### Zod Usage
+### Schema Definition
 
-Motia relies on Zod to define body and response schemas. In Python and other languages, it uses JSON Schema.
+- **TypeScript/JavaScript**: Motia uses Zod schemas for automatic validation of input data
+- **Python**: Motia uses JSON Schema format. You can optionally use Pydantic models to generate JSON Schemas and handle manual validation in your handlers
 
 ### Configuration
 
-You need to export a config constant via `export const config` that is a `EventConfig` type.
+**TypeScript/JavaScript**: You need to export a config constant via `export const config` that is a `EventConfig` type.
+
+**Python**: You need to define a `config` dictionary with the same properties as the TypeScript `EventConfig`.
 
 ```typescript
 export type Emit = string | { 
@@ -119,17 +122,28 @@ The handler is a function that is exported via `export const handler` that is a
 
 ### Handler definition
 
+**TypeScript/JavaScript:**
 ```typescript
 /**
  * Input is inferred from the Event Step config['input']
  * Context is the FlowContext
  */
-export const handler: Handlers['CreateResource'] = async (input, { emit, logger, state, streams }) => {
+export const handler: Handlers['SendEmail'] = async (input, { emit, logger, state, streams }) => {
   // Implementation
 }
 ```
 
-### Example
+**Python:**
+```python
+async def handler(input_data, context):
+    # input_data: dictionary with the event data (matches the input schema)
+    # context: object containing emit, logger, state, streams, trace_id
+    pass
+```
+
+### Examples
+
+#### TypeScript Example
 
 ```typescript
 import { EventConfig, Handlers } from 'motia';
@@ -152,6 +166,53 @@ export const config: EventConfig = {
 };
 
 export const handler: Handlers['SendEmail'] = async (input, { emit, logger }) => {
-  logger.info('Email sent successfully', { email, templateId, templateData });
+  const { email, templateId, templateData } = input;
+  
+  // Process email sending logic here
+  await emailService.send({
+    to: email,
+    templateId,
+    data: templateData
+  });
+  
+  logger.info('Email sent successfully', { email, templateId });
 };
+```
+
+#### Python Example
+
+```python
+from pydantic import BaseModel
+from typing import Dict, Any
+
+class EmailData(BaseModel):
+    email: str
+    template_id: str
+    template_data: Dict[str, Any]
+
+config = {
+    "type": "event",
+    "name": "SendEmail",
+    "description": "Sends email notification to the user",
+    "subscribes": ["send-email"],
+    "emits": [],
+    "input": EmailData.model_json_schema(),
+    "flows": ["resource-management"]
+}
+
+async def handler(input_data, context):
+    # Optional: Validate input manually using Pydantic (Motia doesn't do this automatically)
+    email_data = EmailData(**input_data)
+    
+    # Process email sending logic here
+    await email_service.send({
+        "to": email_data.email,
+        "template_id": email_data.template_id,
+        "data": email_data.template_data
+    })
+    
+    context.logger.info("Email sent successfully", {
+        "email": email_data.email,
+        "template_id": email_data.template_id
+    })
 ```