Skip to content

PhD Compute API ​

The PhD Compute API provides programmatic access to GhostScience scientific tools. All endpoints require authentication and are gated behind the PHD_MODE_ENABLED setting (returns 403 when disabled).

Base path: /api/phd

Authentication ​

All requests require a Bearer token in the Authorization header:

Authorization: Bearer gst_your_api_key

Endpoints ​

Execute a Computation ​

POST /api/phd/compute

Run a scientific tool and return structured output with provenance.

Request Body

FieldTypeRequiredDescription
tool_namestringyesOne of: symbolic_math, numerical_solve, statistical_analysis
parametersobjectnoTool-specific parameters (see below)
session_idstringnoLink computation to a session for history tracking
skip_provenancebooleannoSkip provenance recording (default false)

Response

json
{
  "computation_id": "550e8400-e29b-41d4-a716-446655440000",
  "tool_name": "symbolic_math",
  "result": {
    "latex": "\\frac{x^3}{3}",
    "steps": ["..."],
    "code": "...",
    "warnings": []
  },
  "result_hash": "sha256...",
  "wall_time_ms": 1234.5,
  "cached": false
}

Error Response (422)

json
{
  "detail": {
    "error": "SymPy parse error: ...",
    "metadata": {}
  }
}

Tool Parameters ​

symbolic_math ​

ParameterTypeRequiredValues
expressionstringyesMathematical expression (any syntax)
operationstringyessolve, integrate, differentiate, simplify, series, limit
variablestringnoVariable name (default x)
assumptionsobjectnoSymPy assumptions (e.g., {"positive": true})

numerical_solve ​

ParameterTypeRequiredValues
problem_typestringyesode, linear_system, eigenvalue, root_finding
equationsstringyesSystem of equations
parametersobjectnoSolver parameters
methodstringnoSpecific solver method

statistical_analysis ​

ParameterTypeRequiredValues
analysis_typestringyeshypothesis_test, regression, time_series, descriptive
datastringnoInput data
parametersobjectnoAnalysis parameters

Get a Computation ​

GET /api/phd/compute/{computation_id}

Retrieve a stored computation record by ID. Organization-scoped -- only records belonging to the caller's org are returned.

Response: Full provenance record with JSON-parsed fields for tool_parameters, library_versions, physical_constants, rng_seeds, data_lineage, participating_orgs, attestation_signatures, input_lineage_per_org, and result_release_status.


Export a Computation ​

GET /api/phd/compute/{computation_id}/export?format={format}

Export a stored computation to a different format.

Query Parameters

ParameterTypeValues
formatstringpython (or py), matlab (or m), julia (or jl), latex (or tex), jupyter (or ipynb, notebook), c, dockerfile

Response: Plain text (text/plain) for most formats, or application/json for Jupyter notebooks.

Errors: 404 if the computation is not found, 400 for unsupported format.


Reproduce a Computation ​

POST /api/phd/reproduce/{computation_id}

Re-execute the stored generated_code in a fresh sandbox and compare result hashes for bitwise verification.

Response

json
{
  "computation_id": "550e8400-...",
  "matches": true,
  "original_result_hash": "sha256...",
  "reproduced_result_hash": "sha256...",
  "exit_code": 0,
  "stderr": "",
  "wall_time_ms": 2345.6
}

Errors: 404 if not found, 400 if no generated_code is stored, 503 if the sandbox is unavailable.


Session History ​

GET /api/phd/session/{session_id}/history?limit=50

List computation records for a session within the caller's organization.

Query Parameters

ParameterTypeDefaultDescription
limitinteger50Max records to return

Response

json
{
  "session_id": "sess-abc",
  "computations": [{ "...": "..." }]
}

Health Check ​

GET /api/phd/health

PhD subsystem health: sandbox availability and computation cache status.

Response

json
{
  "status": "ok",
  "sandbox_available": true,
  "cache_connected": true,
  "cache_backend": "redis",
  "phd_mode_enabled": true
}

status is ok when the sandbox is available, degraded otherwise.


Capabilities ​

GET /api/phd/capabilities

List available PhD tools with JSON Schema parameter descriptions.

Response

json
{
  "tools": [
    {
      "name": "symbolic_math",
      "description": "Symbolic algebra/calculus via SymPy (LaTeX and steps).",
      "parameters_schema": {
        "type": "object",
        "required": ["expression", "operation"],
        "properties": {
          "expression": { "type": "string" },
          "operation": {
            "type": "string",
            "enum": ["solve", "integrate", "differentiate", "simplify", "series", "limit"]
          },
          "variable": { "type": "string", "default": "x" },
          "assumptions": { "type": "object" }
        }
      }
    }
  ]
}

SOC 2 Type II Certified | BAA Available | HIPAA-Ready