Agent & Developer API Reference

View-Only OpenAPI 3.1 Specification & Structured JSON Datasets

MACHINE-READABLE SPECIFICATION // AGENT GATEWAY ● OPENAPI 3.1 • JSON • ZERO AUTH VIEW-ONLY

SPECIFICATION OpenAPI 3.1 (JSON)

Full schema for agents and tools.

↓ openapi.json

SPECIFICATION OpenAPI 3.1 (YAML)

Human-friendly schema format.

↓ openapi.yaml

DATASET SC-32 Reference (JSON)

60+ operations, shifts & stack deltas.

↓ sc32-reference.json

DATASET SC-6 Reference (JSON)

28 keys, modes, and superpowers.

↓ sc6-reference.json

---

1. Overview for Autonomous AI Agents

To support modern agentic coding workflows, calculator verification, and LLM-assisted curriculum generation, StackCalc publishes view-only, machine-readable specifications of its hardware architectures, button rubrics, and operational state machines.

Agents can query these endpoints to: 1. Look up exact keystrokes: Determine primary, yellow ([f]), and blue ([g]) shift sequences without hallucination. 2. Verify stack transitions (\(\Delta \text{Stack}\)): Inspect how \(X, Y, Z, T\) registers mutate before and after an operation (such as [÷R], [REP], or [SOLVE]). 3. Inspect mode parameters: Understand the active visual mode (e.g. Ten-Frame [▦], Clock [🕒], or 4-Stack XYZT).

---

2. Core API Endpoints

The API is structured as a lightweight, read-only resource model:

| HTTP Method | Route | Description | | :--- | :--- | :--- | | `GET` | `/v1/models` | List all supported calculator models (`sc32`, `sc6`) with summaries. | | `GET` | `/v1/models/{modelId}` | Retrieve full hardware architecture, display parameters, and register sets. | | `GET` | `/v1/models/{modelId}/operations` | Query all button operations with optional `?subsystem=` filtering. | | `GET` | `/v1/models/{modelId}/operations/{opId}` | Lookup a specific operation by mnemonic (e.g. `intDiv`, `rep`, `lastx`, `plot`, `poly`). | | `GET` | `/v1/models/{modelId}/modes` | List operational stack modes and tactile visual modes. |

---

3. Schema Architecture: The CalculatorOperation Object

Every operation in the StackCalc ecosystem is defined with deterministic stack transformation semantics:

{
  "id": "intDiv",
  "name": "Integer Division with Remainder",
  "key": "÷",
  "shift": "blue",
  "legend": "÷R",
  "subsystem": "Core Stack & Arithmetic",
  "description": "Performs integer division of Y by X. Places integer quotient in X and integer remainder in Y simultaneously. Divisor saved in LAST X.",
  "stack_delta": {
    "before": {
      "T": "t",
      "Z": "z",
      "Y": "dividend",
      "X": "divisor"
    },
    "after": {
      "T": "t",
      "Z": "z",
      "Y": "remainder",
      "X": "quotient"
    }
  },
  "example": "23 [ENTER] 4 [g] [÷R] -> Y: 3.0000 (R), X: 5.0000 (Q)"
}

---

4. Example: Agent Keystroke Retrieval

An agent assisting a student with a Texas UIL word problem or elementary division remainder can parse docs/api/sc32-reference.json or docs/api/sc6-reference.json directly to construct valid keystroke chains:

import json

with open("docs/api/sc32-reference.json") as f:
    sc32 = json.load(f)

# Find operation
op = next(o for o in sc32["operations"] if o["id"] == "intDiv")
print(f"Key: {op['key']}, Shift: {op['shift']}, Legend: {op.get('legend')}")
# Output: Key: ÷, Shift: blue, Legend: ÷R