Psynapse Backend

The Psynapse backend is a FastAPI server that handles node graph execution. This decouples the compute from the UI, allowing for more scalable and testable node execution.

Architecture

Components

1. FastAPI Server (psynapse/backend/server.py)
2. Provides REST API endpoints for node operations

3. Handles graph execution requests

4. Node Schemas (psynapse/backend/node_schemas.py)

5. Defines the schema for available nodes

6. Specifies parameters and return types for each node

7. Graph Executor (psynapse/backend/executor.py)

8. Executes node graphs
9. Manages node dependencies and caching
10. Returns results for ViewNodes

Frontend Integration

1. Graph Serializer (psynapse/core/serializer.py)
2. Converts the UI node graph to a JSON format

3. Serializes nodes and edges for backend consumption

4. Backend Client (psynapse/editor/backend_client.py)

5. HTTP client for communicating with the backend
6. Provides sync wrappers for async operations

API Endpoints

GET /nodes

Returns the schema of all available nodes.

Response:

{
  "nodes": [
    {
      "name": "add",
      "params": [
        {"name": "a", "type": "float"},
        {"name": "b", "type": "float"}
      ],
      "returns": [
        {"name": "result", "type": "float"}
      ]
    }
  ]
}

POST /execute

Executes a node graph and returns results.

Request:

{
  "nodes": [
    {
      "id": "node_0",
      "type": "add",
      "input_sockets": [
        {"id": "node_0_input_0", "name": "a", "value": 5.0},
        {"id": "node_0_input_1", "name": "b", "value": 3.0}
      ],
      "output_sockets": [
        {"id": "node_0_output_0", "name": "result"}
      ]
    },
    {
      "id": "node_1",
      "type": "view",
      "input_sockets": [
        {"id": "node_1_input_0", "name": "value", "value": null}
      ],
      "output_sockets": []
    }
  ],
  "edges": [
    {
      "start_socket": "node_0_output_0",
      "end_socket": "node_1_input_0"
    }
  ]
}

Response:

{
  "results": {
    "node_1": {
      "value": 8.0,
      "error": null
    }
  }
}

GET /health

Health check endpoint.

Response:

{
  "status": "ok"
}

Running the Backend

Method 1: Using the helper script

uv run python start_backend.py

Method 2: Using uvicorn directly

uvicorn psynapse.backend.server:app --reload

Method 3: Using uvicorn with custom host/port

uvicorn psynapse.backend.server:app --reload --host 0.0.0.0 --port 8000

Usage Workflow

1. Start the backend server

   uv run python start_backend.py
   

2. Launch the Psynapse editor

   uv run psynapse
   

3. Build your node graph

4. Drag nodes from the library panel

5. Connect nodes by dragging from output to input sockets

6. Execute the graph

7. Click the "▶ Run Graph" button
8. The frontend will serialize the graph and send it to the backend
9. Results will be displayed in ViewNodes

Development

Adding New Node Types

To add a new node type:

1. Add the node schema in psynapse/backend/node_schemas.py:

   {
       "name": "new_node",
       "params": [
           {"name": "param1", "type": "float"},
       ],
       "returns": [
           {"name": "result", "type": "float"},
       ],
   }
   

2. Implement the execution logic in psynapse/backend/executor.py:

   elif node_type == "new_node":
       param1 = float(inputs.get("param1", 0.0))
       return some_computation(param1)
   

3. Create the frontend node class in psynapse/nodes/:

   class NewNode(Node):
       def __init__(self):
           super().__init__(
               title="New Node",
               inputs=[("Param1", SocketDataType.FLOAT)],
               outputs=[("Result", SocketDataType.FLOAT)],
           )
   

4. Register the node in the serializer mapping (psynapse/core/serializer.py):

   NODE_TYPE_MAP = {
       NewNode: "new_node",
       # ... other nodes
   }
   

Testing

Test the backend endpoints using curl or any HTTP client:

# Health check
curl http://localhost:8000/health

# Get node schemas
curl http://localhost:8000/nodes

# Execute a graph
curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -d '{"nodes": [...], "edges": [...]}'