Skip to content

Provenance and Export ​

Every GhostScience computation produces an immutable provenance record and can be exported to multiple formats for reproducibility, collaboration, and regulatory submissions.

Computation Provenance ​

The provenance system records a ComputationRecord for every PhD tool execution. Each record is SHA-256 hashed for tamper detection and scoped to the user's organization.

Record Fields ​

FieldDescription
idUnique record identifier
timestampISO 8601 UTC
user_id / organization_idScoped to tenant
session_idChat or API session
tool_nameWhich scientific tool ran
tool_parametersStructured JSON of the tool call parameters
original_inputUser's expression in original syntax
generated_codeFull Python source sent to the sandbox
environment_hashSHA-256 of (image ID + library versions + config)
image_idDocker image identifier
library_versionsPinned versions of all scientific libraries
wall_time_ms / cpu_time_msExecution timing
peak_memory_bytes / gpu_time_msResource consumption
result_hashSHA-256 of the structured result
result_summaryCondensed output (capped at 2 KB)
method_rationaleLLM's explanation of solver selection
unit_verificationPass/fail dimensional consistency
uncertainty_summaryPropagated measurement uncertainties
physical_constantsConstants used, with CODATA edition year
rng_seedsRandom number generator seeds for reproducibility
data_lineageFile IDs and Dymium source IDs referenced
parent_computation_idPreceding computation in a chain

Multi-Org Fields (Clean Room) ​

When a computation runs in a Federated Clean Room, additional fields are populated:

FieldDescription
participating_orgsOrganization IDs involved
attestation_signaturesPer-org attestation hashes
input_lineage_per_orgWhat each org contributed (visible only to that org)
result_release_statusApprove/reject per org
clean_room_idLink to the clean room

Tamper Detection ​

Every record is hashed with SHA-256 over a canonical JSON representation. The verify endpoint re-computes the hash and compares it to the stored value, detecting any modification.

POST /api/phd/reproduce/{computation_id}

Returns matches: true/false with both hashes for comparison.

Regulatory Compliance ​

Provenance records satisfy:

RegulationRequirement Met
FDA 21 CFR Part 11Electronic records with audit trail, attributable to individuals, system validation evidence
SOX Section 404Internal controls documentation, complete computation chain
HIPAAAudit trail for PHI computations, access controls
NERC CIPProvenance for bulk electric system reliability computations
ITAR / DFARSClassification markings, access controls, air-gapped deployment

Reproducibility ​

GhostScience guarantees bitwise-identical results for deterministic computations:

  1. All generated code sets explicit random seeds
  2. NumPy, SciPy, and JAX random generators are seeded from the provenance record
  3. The environment hash (image ID + library versions + config) enables exact environment reconstruction
  4. The verification endpoint (POST /api/phd/reproduce/{id}) re-executes the stored generated_code in a fresh sandbox and compares result hashes

Multi-Format Export ​

Computations can be exported via the API:

GET /api/phd/compute/{id}/export?format=python

Supported Formats ​

FormatAliasOutput
PythonpyStandalone script with shebang, docstring header (ID, tool, timestamp), parameters JSON, and generated code
MATLABmComment header with provenance metadata, body converted from NumPy to MATLAB-style syntax
JuliajlJulia comments with provenance, body converted from Python to Julia-style syntax
LaTeXtexFull article document: tool info, parameters as verbatim block, result summary, code excerpt (escaped)
Jupyteripynb, notebookNotebook with markdown cells for metadata and code cells for the computation
CcPython code embedded as a C comment block with a placeholder main() scaffold
DockerdockerfileComplete Dockerfile using the PhD sandbox image, embedding the computation as a reproducible script

Every export includes provenance metadata, library versions, and units.

SDK Usage ​

python
from ghostscience import GhostScienceClient

client = GhostScienceClient(api_key="gst_...")

result = client.symbolic_math(
    expression="x**3 + 2*x",
    operation="integrate",
)

latex_doc = client.export(result["computation_id"], format="latex")
jupyter = client.export(result["computation_id"], format="jupyter")

Session History ​

Retrieve the computation history for a session:

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

Returns a chronological list of provenance records for the session, scoped to the requesting organization.

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