Appearance
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
| Field | Description |
|---|---|
id | Unique record identifier |
timestamp | ISO 8601 UTC |
user_id / organization_id | Scoped to tenant |
session_id | Chat or API session |
tool_name | Which scientific tool ran |
tool_parameters | Structured JSON of the tool call parameters |
original_input | User's expression in original syntax |
generated_code | Full Python source sent to the sandbox |
environment_hash | SHA-256 of (image ID + library versions + config) |
image_id | Docker image identifier |
library_versions | Pinned versions of all scientific libraries |
wall_time_ms / cpu_time_ms | Execution timing |
peak_memory_bytes / gpu_time_ms | Resource consumption |
result_hash | SHA-256 of the structured result |
result_summary | Condensed output (capped at 2 KB) |
method_rationale | LLM's explanation of solver selection |
unit_verification | Pass/fail dimensional consistency |
uncertainty_summary | Propagated measurement uncertainties |
physical_constants | Constants used, with CODATA edition year |
rng_seeds | Random number generator seeds for reproducibility |
data_lineage | File IDs and Dymium source IDs referenced |
parent_computation_id | Preceding computation in a chain |
Multi-Org Fields (Clean Room)
When a computation runs in a Federated Clean Room, additional fields are populated:
| Field | Description |
|---|---|
participating_orgs | Organization IDs involved |
attestation_signatures | Per-org attestation hashes |
input_lineage_per_org | What each org contributed (visible only to that org) |
result_release_status | Approve/reject per org |
clean_room_id | Link 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:
| Regulation | Requirement Met |
|---|---|
| FDA 21 CFR Part 11 | Electronic records with audit trail, attributable to individuals, system validation evidence |
| SOX Section 404 | Internal controls documentation, complete computation chain |
| HIPAA | Audit trail for PHI computations, access controls |
| NERC CIP | Provenance for bulk electric system reliability computations |
| ITAR / DFARS | Classification markings, access controls, air-gapped deployment |
Reproducibility
GhostScience guarantees bitwise-identical results for deterministic computations:
- All generated code sets explicit random seeds
- NumPy, SciPy, and JAX random generators are seeded from the provenance record
- The environment hash (image ID + library versions + config) enables exact environment reconstruction
- The verification endpoint (
POST /api/phd/reproduce/{id}) re-executes the storedgenerated_codein a fresh sandbox and compares result hashes
Multi-Format Export
Computations can be exported via the API:
GET /api/phd/compute/{id}/export?format=pythonSupported Formats
| Format | Alias | Output |
|---|---|---|
| Python | py | Standalone script with shebang, docstring header (ID, tool, timestamp), parameters JSON, and generated code |
| MATLAB | m | Comment header with provenance metadata, body converted from NumPy to MATLAB-style syntax |
| Julia | jl | Julia comments with provenance, body converted from Python to Julia-style syntax |
| LaTeX | tex | Full article document: tool info, parameters as verbatim block, result summary, code excerpt (escaped) |
| Jupyter | ipynb, notebook | Notebook with markdown cells for metadata and code cells for the computation |
| C | c | Python code embedded as a C comment block with a placeholder main() scaffold |
| Docker | dockerfile | Complete 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=50Returns a chronological list of provenance records for the session, scoped to the requesting organization.
Related
- GhostScience -- PhD computing engine overview
- Clean Room -- multi-org provenance with per-org audit records
- PhD API Reference -- endpoint documentation
- SDK Reference -- Python client library
- Examples -- scripts 10, 18, 23, and 32 cover export and provenance