Appearance
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 ghostscienceRequirements: 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")| Parameter | Type | Default | Description |
|---|---|---|---|
api_key | string | (required) | Bearer token for authentication |
base_url | string | https://api.ghostai.com | GhostAI deployment URL |
PhD Compute Methods
symbolic_math(expression, operation, variable="x", **kwargs)
Convenience wrapper around compute("symbolic_math", ...).
| Parameter | Type | Description |
|---|---|---|
expression | string | Mathematical expression (any syntax) |
operation | string | solve, integrate, differentiate, simplify, series, limit |
variable | string | Variable name (default x) |
numerical_solve(problem_type, equations, **kwargs)
| Parameter | Type | Description |
|---|---|---|
problem_type | string | ode, linear_system, eigenvalue, root_finding |
equations | string | System of equations |
statistical_analysis(analysis_type, data="", **kwargs)
| Parameter | Type | Description |
|---|---|---|
analysis_type | string | hypothesis_test, regression, time_series, descriptive |
data | string | Input data |
optimize(objective, **kwargs)
| Parameter | Type | Description |
|---|---|---|
objective | string | Objective function |
compute(tool_name, session_id="", skip_provenance=False, **parameters)
The general-purpose compute method. All convenience methods delegate to this.
| Parameter | Type | Default | Description |
|---|---|---|---|
tool_name | string | (required) | Tool name |
session_id | string | "" | Session for history tracking |
skip_provenance | boolean | False | Skip provenance recording |
**parameters | any | Tool-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 values | Description |
|---|---|
python, py | Standalone Python script |
matlab, m | MATLAB-style code |
julia, jl | Julia code |
latex, tex | LaTeX document |
jupyter, ipynb, notebook | Jupyter notebook JSON |
c | C code scaffold |
dockerfile | Reproducible 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.
| Parameter | Type | Description |
|---|---|---|
approve | boolean | True to approve, False to reject |
reason | string | Rejection 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 GhostScienceClientRelated
- PhD API -- REST endpoint documentation
- Clean Room API -- federated computation endpoints
- Workspace API -- workspace endpoints
- Examples -- 32 runnable example scripts