Skip to content

Python SDK Reference ​

The ghostscience Python SDK provides a typed client for the GhostScience API. It covers PhD compute, workspace, and clean room endpoints.

Installation ​

bash
# From the repo
cd securechat/sdk
pip install -e .

# Or install from the package
pip install ghostscience

Requirements: Python 3.10+, requests >= 2.28.

Quick Start ​

python
from ghostscience import GhostScienceClient

client = GhostScienceClient(
    api_key="gst_your_api_key",
    base_url="https://your-ghostai-host",
)

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

Constructor ​

python
GhostScienceClient(api_key: str, base_url: str = "https://api.ghostai.com")
ParameterTypeDefaultDescription
api_keystring(required)Bearer token for authentication
base_urlstringhttps://api.ghostai.comGhostAI deployment URL

PhD Compute Methods ​

symbolic_math(expression, operation, variable="x", **kwargs) ​

Convenience wrapper around compute("symbolic_math", ...).

ParameterTypeDescription
expressionstringMathematical expression (any syntax)
operationstringsolve, integrate, differentiate, simplify, series, limit
variablestringVariable name (default x)

numerical_solve(problem_type, equations, **kwargs) ​

ParameterTypeDescription
problem_typestringode, linear_system, eigenvalue, root_finding
equationsstringSystem of equations

statistical_analysis(analysis_type, data="", **kwargs) ​

ParameterTypeDescription
analysis_typestringhypothesis_test, regression, time_series, descriptive
datastringInput data

optimize(objective, **kwargs) ​

ParameterTypeDescription
objectivestringObjective function

compute(tool_name, session_id="", skip_provenance=False, **parameters) ​

The general-purpose compute method. All convenience methods delegate to this.

ParameterTypeDefaultDescription
tool_namestring(required)Tool name
session_idstring""Session for history tracking
skip_provenancebooleanFalseSkip provenance recording
**parametersanyTool-specific parameters

Returns: dict with computation_id, tool_name, result, result_hash, wall_time_ms, cached.

get_result(computation_id) ​

Retrieve a stored computation record by ID.

reproduce(computation_id) ​

Re-execute stored code for bitwise verification. Uses a 300-second timeout (vs. 120 seconds for other calls).

Returns: dict with matches, original_result_hash, reproduced_result_hash, exit_code, stderr, wall_time_ms.

export(computation_id, format) ​

Export a computation to the specified format. Returns the raw text content.

Format valuesDescription
python, pyStandalone Python script
matlab, mMATLAB-style code
julia, jlJulia code
latex, texLaTeX document
jupyter, ipynb, notebookJupyter notebook JSON
cC code scaffold
dockerfileReproducible Dockerfile

session_history(session_id, limit=50) ​

List computation records for a session.

capabilities() ​

List available PhD tools with JSON Schema parameter descriptions.

health() ​

PhD subsystem health check.

Workspace Methods ​

create_workspace(name, description="") ​

Create a new workspace.

list_workspaces() ​

List all workspaces accessible to the authenticated user.

get_workspace(workspace_id) ​

Get workspace details including all cells.

upsert_cell(workspace_id, cell_id, cell_type="computation", content="", position=0) ​

Create or update a cell in a workspace.

run_cell(workspace_id, cell_id) ​

Execute a computation cell in the PhD sandbox.

create_branch(workspace_id, name, parent_branch="main") ​

Create a new branch in a workspace.

list_branches(workspace_id) ​

List all branches for a workspace.

Clean Room Methods ​

create_clean_room(name, description="", computation_template="") ​

Create a new federated clean room.

list_clean_rooms(status=None) ​

List clean rooms the caller's org participates in. Optionally filter by status.

get_clean_room(clean_room_id) ​

Get clean room details including participants.

invite_to_clean_room(clean_room_id, target_org_id) ​

Invite another organization to the clean room.

accept_clean_room(clean_room_id) ​

Accept an invitation to join a clean room.

set_clean_room_template(clean_room_id, computation_template, sandbox_config=None) ​

Set the computation template and sandbox configuration. Generates the attestation bundle.

attest_clean_room(clean_room_id, bundle_hash) ​

Submit attestation with the combined hash from the attestation bundle.

get_attestation_status(clean_room_id) ​

Get attestation status for all participants.

release_clean_room_result(clean_room_id, approve, reason="") ​

Approve or reject the release of escrowed results.

ParameterTypeDescription
approvebooleanTrue to approve, False to reject
reasonstringRejection reason (optional)

get_clean_room_results(clean_room_id) ​

Retrieve released results (or escrow summary if not yet released).

get_clean_room_provenance(clean_room_id) ​

Get this org's provenance records for the clean room.

CLI ​

The package installs a ghostscience console command:

bash
$ ghostscience
GhostScience Python SDK v0.1.0
Usage: from ghostscience import GhostScienceClient

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