{
  "openapi": "3.1.1",
  "info": {
    "title": "Ohmforge DC Operating Point API",
    "version": "1.0.0",
    "summary": "SPICE netlist in, node voltages, branch currents, power and overload warnings out.",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://ohmforgedcoperatingpoint.usefulweb.site"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "SPICE netlist in, node voltages, branch currents, power and overload warnings out.",
        "description": "Solves the DC operating point of a circuit with Ohmforge's SPICE-style engine (Modified Nodal Analysis, Newton–Raphson with junction limiting, damping, gmin and source stepping). Returns every node voltage, the current and power of every element, total supply power, parts beyond their ratings and plain-language convergence diagnostics.\n\nMethodology:\n- The netlist is parsed (SPICE subset) and compiled into Modified Nodal Analysis unknowns: one voltage per node plus one current per voltage source, inductor and controlled-source output.\n- Nonlinear devices (Shockley diode with series resistance and breakdown, Ebers–Moll BJT with Early effect, Shichman–Hodges level-1 MOSFET) are linearised at each Newton–Raphson iteration; junction voltages are limited with the SPICE3 pnjlim rule.\n- If plain Newton–Raphson fails, the solver retries with damping (≤ 0.5 V per iteration), then gmin stepping (1e-2 S → 1e-12 S to ground on every node) and finally source stepping (all sources ramped 0 → 100 %). Every attempt is reported in plain words.\n- Topology checks run first: missing ground, loops of voltage sources/inductors (no unique solution) and nodes without a DC path to ground.\n- Element power is Σ(terminal current × node voltage); sources show negative power when delivering. Ratings (resistor watts, LED current, diode/transistor limits, capacitor voltage) are compared with the result.\n\nTeaching-grade simulation: device models are simplified (Ebers–Moll BJT, level-1 MOSFET, behavioural op-amps and 555) and part ratings are typical values. Verify real designs on the bench and against manufacturer data before building anything connected to mains voltage.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "ohmforge_dc_operating_point",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OhmforgeDcOperatingPointInput"
              },
              "examples": {
                "example1": {
                  "summary": "Voltage divider (10 V, 1k/3k → 7.5 V)",
                  "value": {
                    "netlist": "* Voltage divider\nV1 in 0 DC 10\nR1 in out 1k\nR2 out 0 3k\n.op\n.end"
                  }
                },
                "example2": {
                  "summary": "Transistor switching an LED",
                  "value": {
                    "netlist": "* LED with series resistor and a 2N3904 switch\nVCC vcc 0 9\nRB vcc b 10k\nRC vcc a 470\nD1 a c LED_RED\nQ1 c b 0 2N3904\n.op"
                  }
                },
                "example3": {
                  "summary": "Diode forward drop (Shockley)",
                  "value": {
                    "netlist": "* Shockley diode check\nV1 in 0 5\nR1 in a 1k\nD1 a 0 DMOD\n.model DMOD D(IS=1e-14 N=1)\n.op"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OhmforgeDcOperatingPointResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "OhmforgeDcOperatingPointInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "netlist": {
            "title": "SPICE netlist",
            "description": "Subset: R C L V I D Q M E G K, .model, SIN/PULSE/PWL sources, engineering suffixes (k, m, u, n, p, meg). Node 0 is ground. Leave empty when you pass an Ohmforge project instead.",
            "type": "string",
            "maxLength": 60000
          },
          "project": {
            "title": "Ohmforge project JSON (optional)",
            "description": "Alternative to the netlist: a .ohmforge.json project as saved by the app (format \"ohmforge\", version 1).",
            "type": "string",
            "maxLength": 200000
          }
        },
        "required": []
      },
      "OhmforgeDcOperatingPointResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "required": [
              "converged",
              "nodes",
              "elements",
              "stress",
              "diagnostics"
            ],
            "properties": {
              "title": {
                "type": "string"
              },
              "converged": {
                "type": "boolean"
              },
              "strategy": {
                "type": "string"
              },
              "iterations": {
                "type": "integer"
              },
              "nodes": {
                "type": "object",
                "additionalProperties": {
                  "type": "number"
                },
                "description": "Node voltages in V (ground = 0 is implicit)."
              },
              "elements": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "current": {
                      "type": "number"
                    },
                    "voltage": {
                      "type": "number"
                    },
                    "power": {
                      "type": "number"
                    },
                    "state": {
                      "type": "string"
                    }
                  }
                }
              },
              "totalSupplyPower": {
                "type": "number"
              },
              "stress": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "element": {
                      "type": "string"
                    },
                    "level": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              },
              "diagnostics": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}