{ "openapi": "3.1.1", "info": { "title": "Twinworks Buffer Allocation Optimiser API", "version": "1.0.0", "summary": "Distribute a fixed number of buffer places over a line for maximum throughput.", "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://twinworksbufferallocation.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Distribute a fixed number of buffer places over a line for maximum throughput.", "description": "Solves the buffer allocation problem of a production line by simulation: a fixed total of buffer places (for example the floor space you have) is distributed over the buffers so that throughput is as high as possible. Greedy marginal allocation with common random numbers, compared against the current allocation with a paired confidence interval.\n\nMethodology:\n- Every buffer starts at the minimum capacity; then, one place at a time, each buffer is tried with one more place and the place goes to the buffer with the highest mean throughput (ties: lower mean lead time). This greedy marginal allocation is the standard heuristic for the buffer allocation problem of serial lines.\n- All candidates use the same random-number seeds (common random numbers), so differences are caused by the allocation and not by noise; the gain over the current allocation is a paired Student-t interval.\n\nGreedy allocation is a heuristic: it is optimal or near-optimal for typical serial lines but not guaranteed for every network. Confirm the result with more replications in the app.", "tags": [ "apps" ], "x-mcp-tool": "twinworks_buffer_allocation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwinworksBufferAllocationInput" }, "examples": { "example1": { "summary": "Bottleneck demo: 8 places over four buffers", "value": { "template": "bottleneck-buffer-sizing", "total": 8, "replications": 3, "horizonHours": 6 } }, "example2": { "summary": "3-station line: redistribute the current 10 places", "value": { "template": "three-station-line", "replications": 3 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwinworksBufferAllocationResult" } } } }, "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" } } } } } }, "TwinworksBufferAllocationInput": { "type": "object", "additionalProperties": false, "properties": { "model": { "title": "Model or project JSON", "description": "A Twinworks project (.twinworks.json, format \"twinworks-project\") or a bare model with \"nodes\" and \"links\". Times in seconds, lengths in metres. Leave empty and pick a template instead.", "type": "string", "maxLength": 400000 }, "template": { "title": "Or start from a template", "type": "string", "enum": [ "", "three-station-line", "line-with-failures", "assembly-two-feeders", "job-shop-routings", "bottleneck-buffer-sizing", "conveyor-packaging", "mm1-validation", "shared-forklifts" ], "default": "" }, "total": { "title": "Total buffer places", "description": "Places to distribute over the buffers. Default: the sum of the current capacities (same space, better placement).", "type": "integer", "minimum": 1, "maximum": 2000 }, "minCapacity": { "title": "Minimum per buffer", "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "buffers": { "title": "Buffer ids", "description": "Comma-separated ids (e.g. B1,B2,B3). Default: every buffer with a finite capacity.", "type": "string", "maxLength": 300 }, "replications": { "title": "Replications per candidate", "type": "integer", "minimum": 1, "maximum": 10, "default": 3 }, "horizonHours": { "title": "Run length per replication", "description": "Overrides the model setting.", "type": "number", "minimum": 0.1, "maximum": 2400, "x-unit": "h" } }, "required": [] }, "TwinworksBufferAllocationResult": { "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": [ "buffers", "total", "current", "best", "gain", "steps", "evaluations" ], "properties": { "buffers": { "type": "array", "items": { "type": "string" } }, "total": { "type": "integer" }, "minCapacity": { "type": "integer" }, "current": { "type": "object", "properties": { "capacities": { "type": "object" }, "throughput": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } }, "leadTime": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } }, "wip": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } } } }, "best": { "type": "object", "properties": { "capacities": { "type": "object" }, "throughput": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } }, "leadTime": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } }, "wip": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } } } }, "gain": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "integer" }, "added": { "type": [ "string", "null" ] }, "capacities": { "type": "object" }, "throughput": { "type": "object", "required": [ "mean", "lo", "hi", "halfWidth", "n" ], "properties": { "mean": { "type": "number" }, "lo": { "type": "number" }, "hi": { "type": "number" }, "halfWidth": { "type": "number" }, "n": { "type": "integer" } } } } } }, "placesForCurrentThroughput": { "type": [ "integer", "null" ], "description": "Smallest total of well-placed buffer places that reaches the current throughput." }, "evaluations": { "type": "integer" }, "model": { "type": "object", "description": "The model with the optimised capacities." } } }, "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" } } } } } } } }