Appearance
GhostScience Full Lab
Twelve steps. One hour. From zero to PhD-level scientific computing.
This lab walks you through the complete GhostScience setup and workflow — from enabling PhD Mode and building the sandbox Docker image, through running all eight scientific tools, to exporting results and creating persistent workspaces.
Prerequisites
Before starting, ensure you have:
- [ ] Docker Desktop or Docker Engine installed and running (
docker infosucceeds) - [ ] Python 3.10+ installed (
python3 --version) - [ ] pip installed (
pip --version) - [ ] GhostAI deployment running (backend on port 8000)
- [ ] GhostAI API key — obtain from your admin or create one via the admin panel
- [ ] Git access to the GhostAI repository
Verify prerequisites
bash
docker info > /dev/null 2>&1 && echo "Docker: OK" || echo "Docker: MISSING"
python3 --version
pip --version
curl -s http://localhost:8000/health | python3 -m json.toolStep 1: Enable PhD Mode
Duration: 3 minutes Goal: Enable PhD Mode and the sandboxed execution environment.
1.1 Edit your backend configuration
Open securechat/backend/.env (or create it from .env.example) and set the following:
bash
# PhD Mode
PHD_MODE_ENABLED=true
# Sandbox execution
SANDBOX_ENABLED=true
SANDBOX_TIMEOUT=300
SANDBOX_MAX_MEMORY=4g
SANDBOX_MAX_CPU=2
SANDBOX_IMAGE=ghostai-phd-sandbox:latest
# Optional: enable gVisor for kernel isolation
SANDBOX_RUNTIME=runsc1.2 Restart the backend
bash
cd securechat/backend
uvicorn app.main:app --reload --port 80001.3 Verify
bash
curl -s http://localhost:8000/api/phd/health | python3 -m json.toolExpected output:
json
{
"status": "ok",
"sandbox_available": false,
"cache_connected": true,
"cache_backend": "memory",
"phd_mode_enabled": true
}sandbox_available is false because we haven't built the Docker image yet. That's next.
Step 2: Build the PhD Sandbox Docker Image
Duration: 5 minutes Goal: Build the hardened Docker image containing 50+ scientific Python libraries.
2.1 Build the CPU image
bash
cd infrastructure/docker/sandbox
docker build -f Dockerfile.phd -t ghostai-phd-sandbox:latest .This installs NumPy, SciPy, SymPy, Matplotlib, Plotly, pandas, scikit-learn, python-control, JAX, and 40+ other scientific libraries in a hardened Alpine-based image with a non-root user.
Expected output (last lines):
Successfully built abc123def456
Successfully tagged ghostai-phd-sandbox:latest2.2 Verify the image
bash
docker images ghostai-phd-sandboxExpected output:
REPOSITORY TAG IMAGE ID CREATED SIZE
ghostai-phd-sandbox latest abc123def456 10 seconds ago 2.1GB2.3 Verify sandbox availability
bash
curl -s http://localhost:8000/api/phd/health | python3 -m json.toolExpected output:
json
{
"status": "ok",
"sandbox_available": true,
"cache_connected": true,
"cache_backend": "memory",
"phd_mode_enabled": true
}sandbox_available is now true. The sandbox is ready.
2.4 (Optional) Build the GPU image
If you have NVIDIA GPUs and need CUDA/JAX/PyTorch acceleration:
bash
docker build -f Dockerfile.phd-gpu -t ghostai-phd-sandbox-gpu:latest .Update .env:
bash
SANDBOX_IMAGE=ghostai-phd-sandbox-gpu:latestStep 3: Install the Python SDK
Duration: 2 minutes Goal: Install the ghostscience Python SDK for programmatic access.
3.1 Install
bash
cd securechat/sdk
pip install -e .3.2 Verify
python
python3 -c "from ghostscience import GhostScienceClient; print('SDK installed')"3.3 Set your API key
bash
export GHOSTSCIENCE_API_KEY="gst_your_api_key_here"3.4 Test the connection
python
python3 << 'EOF'
import os
from ghostscience import GhostScienceClient
client = GhostScienceClient(
api_key=os.environ["GHOSTSCIENCE_API_KEY"],
base_url="http://localhost:8000"
)
health = client.health()
print(f"Status: {health['status']}")
print(f"Sandbox: {health['sandbox_available']}")
print(f"PhD Mode: {health['phd_mode_enabled']}")
EOFExpected output:
Status: ok
Sandbox: True
PhD Mode: TrueStep 4: Run Your First Computation — Symbolic Math
Duration: 5 minutes Goal: Execute a symbolic integration and understand the response structure.
4.1 Run the computation
python
python3 << 'EOF'
import os, json
from ghostscience import GhostScienceClient
client = GhostScienceClient(
api_key=os.environ["GHOSTSCIENCE_API_KEY"],
base_url="http://localhost:8000"
)
result = client.symbolic_math(
expression="x**2 * sin(x)",
operation="integrate",
variable="x"
)
print(json.dumps(result, indent=2, default=str))
EOF4.2 Understand the response
Expected structure:
json
{
"computation_id": "a1b2c3d4-...",
"tool_name": "symbolic_math",
"result_hash": "sha256:...",
"wall_time_ms": 1543,
"result": {
"latex": "-x^{2} \\cos{x} + 2 x \\sin{x} + 2 \\cos{x}",
"steps": [
"Apply integration by parts: u = x², dv = sin(x)dx",
"du = 2x dx, v = -cos(x)",
"= -x²cos(x) + ∫2x cos(x) dx",
"Apply integration by parts again: u = 2x, dv = cos(x)dx",
"= -x²cos(x) + 2x sin(x) - ∫2 sin(x) dx",
"= -x²cos(x) + 2x sin(x) + 2cos(x) + C"
],
"code": "from sympy import *\nx = Symbol('x')\nresult = integrate(x**2 * sin(x), x)\n...",
"warnings": []
}
}Key fields:
computation_id— unique ID for this computation (used for export, reproduce, provenance)result_hash— SHA-256 of the result (used for tamper detection)wall_time_ms— execution time in millisecondsresult.latex— LaTeX-rendered resultresult.steps— step-by-step derivationresult.code— the generated Python code that ran in the sandbox
Step 5: Explore All Eight Tools
Duration: 10 minutes Goal: Run one computation with each of the eight scientific tools.
5.1 Symbolic Math (already done in Step 4)
5.2 Numerical Solve — Lorenz Attractor
python
result = client.numerical_solve(
problem_type="ode",
equations="dx/dt = 10*(y-x), dy/dt = x*(28-z)-y, dz/dt = x*y - 8/3*z",
initial_conditions="[1, 1, 1]",
t_span="[0, 50]"
)
print(f"Solver: {result['result'].get('method', 'auto')}")
print(f"Steps: {result['result'].get('step_count', 'N/A')}")
print(f"Wall time: {result['wall_time_ms']}ms")5.3 Statistical Analysis — Regression
python
result = client.statistical_analysis(
analysis_type="regression",
data="generate:200 points, linear trend, noise=0.3",
diagnostics=True
)
print(f"R²: {result['result'].get('r_squared', 'N/A')}")5.4 Optimization — Rosenbrock
python
result = client.optimize(
objective="(1-x)**2 + 100*(y-x**2)**2",
method="L-BFGS-B",
initial_guess="[-1, 1]"
)
print(f"Optimum: {result['result'].get('optimal_point', 'N/A')}")
print(f"Min value: {result['result'].get('optimal_value', 'N/A')}")5.5 Control Systems — PID Design
python
result = client.compute(
"control_systems",
transfer_function="1/(s**2 + 2*s + 1)",
controller_type="PID",
objective="minimal overshoot"
)
print(f"Kp={result['result'].get('Kp')}, Ki={result['result'].get('Ki')}, Kd={result['result'].get('Kd')}")5.6 Signal Processing — FFT
python
result = client.compute(
"signal_processing",
operation="fft_analysis",
signal="7Hz + 50Hz + noise",
sample_rate=256,
filter_type="lowpass",
cutoff_freq=20
)
print(f"Detected frequencies: {result['result'].get('peaks', 'N/A')}")5.7 Monte Carlo Simulation
python
result = client.compute(
"simulate",
simulation_type="monte_carlo",
model="demand=Normal(100,15), price=Uniform(8,12), revenue=demand*price",
trials=10000
)
print(f"Mean revenue: {result['result'].get('mean', 'N/A')}")
print(f"95% CI: {result['result'].get('ci_95', 'N/A')}")5.8 Method Comparison
python
result = client.compute(
"compare_methods",
problem="Van der Pol oscillator, mu=1000",
methods=["RK45", "BDF", "LSODA"],
metrics=["accuracy", "step_count", "wall_time"]
)
for method in result['result'].get('comparison', []):
print(f"{method['name']}: {method['step_count']} steps, {method['wall_time_ms']}ms")
print(f"Recommendation: {result['result'].get('recommendation', 'N/A')}")Step 6: Multi-Syntax Input via DSL Parser
Duration: 5 minutes Goal: Send the same problem in LaTeX, MATLAB, natural language, and Python and verify identical results.
6.1 Four syntax variants
python
import json
prompts = {
"latex": r"\int_0^1 x^3 \, dx",
"matlab": "integral(@(x) x.^3, 0, 1)",
"natural": "Integrate x cubed from 0 to 1",
"python": "from sympy import integrate, Symbol; x = Symbol('x'); integrate(x**3, (x, 0, 1))"
}
results = {}
for syntax, expr in prompts.items():
r = client.symbolic_math(expression=expr, operation="evaluate")
results[syntax] = r["result"].get("value", r["result"].get("latex", "?"))
print(f"{syntax:10s} → {results[syntax]}")
# Verify all produce the same answer
values = set(str(v) for v in results.values())
assert len(values) == 1, f"Mismatch: {results}"
print(f"\nAll four syntaxes produce: {values.pop()}")Expected output:
latex → 1/4
matlab → 1/4
natural → 1/4
python → 1/4
All four syntaxes produce: 1/4Step 7: Inspect a Provenance Record
Duration: 5 minutes Goal: Understand the computation provenance audit trail.
7.1 Run a computation and capture the ID
python
result = client.symbolic_math(
expression="Matrix([[4, 1], [2, 3]])",
operation="eigenvalues"
)
comp_id = result["computation_id"]
print(f"Computation ID: {comp_id}")7.2 Retrieve the full provenance record
python
record = client.get_result(comp_id)
print(json.dumps(record, indent=2, default=str))Key provenance fields:
| Field | Description |
|---|---|
computation_id | Unique identifier |
tool_name | Which scientific tool was used |
result_hash | SHA-256 of the result payload |
wall_time_ms | Execution time |
result.code | The generated Python code |
created_at | Timestamp |
7.3 Verify hash integrity
The result_hash is computed from the result payload. You can verify it client-side:
python
import hashlib
result_str = json.dumps(record["result"], sort_keys=True)
computed_hash = "sha256:" + hashlib.sha256(result_str.encode()).hexdigest()
print(f"Stored hash: {record['result_hash']}")
print(f"Computed hash: {computed_hash}")
print(f"Match: {record['result_hash'] == computed_hash}")Step 8: Export Results
Duration: 5 minutes Goal: Export a computation to multiple formats.
8.1 Export to Python
python
python_code = client.export(comp_id, format="python")
print("=== Python Export ===")
print(python_code[:500])8.2 Export to LaTeX
python
latex_doc = client.export(comp_id, format="latex")
print("=== LaTeX Export ===")
print(latex_doc[:500])8.3 Export to MATLAB
python
matlab_code = client.export(comp_id, format="matlab")
print("=== MATLAB Export ===")
print(matlab_code[:500])8.4 All supported formats
| Format | Description |
|---|---|
python | Standalone Python script with imports and comments |
matlab | MATLAB .m file |
julia | Julia script |
latex | Publication-ready LaTeX document |
jupyter | Jupyter notebook (.ipynb) |
c | C implementation with numerical libraries |
docker | Dockerfile reproducing the exact environment |
python
for fmt in ["python", "matlab", "julia", "latex", "jupyter", "c", "docker"]:
content = client.export(comp_id, format=fmt)
lines = content.count("\n") + 1
print(f"{fmt:10s} → {lines} lines")Step 9: Reproduce a Computation
Duration: 3 minutes Goal: Prove bitwise reproducibility by re-running a computation and comparing hashes.
9.1 Reproduce
python
reproduction = client.reproduce(comp_id)
print(f"Original hash: {result['result_hash']}")
print(f"Reproduction hash: {reproduction['result_hash']}")
print(f"Match: {result['result_hash'] == reproduction['result_hash']}")Expected output:
Original hash: sha256:a1b2c3...
Reproduction hash: sha256:a1b2c3...
Match: True9.2 What happens under the hood
The reproduce endpoint:
- Retrieves the original provenance record (tool, parameters, environment hash)
- Launches a new sandbox with the same Docker image
- Re-executes the generated code with the same RNG seeds
- Computes the result hash and compares to the original
If the hashes match, the result is cryptographically verified as identical.
Step 10: Create a Workspace
Duration: 5 minutes Goal: Create a persistent, notebook-style workspace with multiple cells.
10.1 Create the workspace
python
ws = client.create_workspace(
name="Eigenvalue Analysis",
description="Computing and analyzing matrix eigenvalues"
)
ws_id = ws["id"]
print(f"Workspace ID: {ws_id}")10.2 Add cells
python
# Cell 1: Define the matrix
client.upsert_cell(
workspace_id=ws_id,
cell_id="cell-1",
cell_type="markdown",
content="# Eigenvalue Analysis\n\nCompute eigenvalues of a 3x3 symmetric matrix.",
position=0
)
# Cell 2: Compute eigenvalues
client.upsert_cell(
workspace_id=ws_id,
cell_id="cell-2",
cell_type="computation",
content="symbolic_math(expression='Matrix([[2,1,0],[1,3,1],[0,1,2]])', operation='eigenvalues')",
position=1
)
# Cell 3: Verify with characteristic polynomial
client.upsert_cell(
workspace_id=ws_id,
cell_id="cell-3",
cell_type="computation",
content="symbolic_math(expression='Matrix([[2,1,0],[1,3,1],[0,1,2]])', operation='charpoly')",
position=2
)10.3 Run cells
python
r2 = client.run_cell(ws_id, "cell-2")
print(f"Eigenvalues: {r2['result']}")
r3 = client.run_cell(ws_id, "cell-3")
print(f"Char poly: {r3['result']}")10.4 View the workspace
python
ws_full = client.get_workspace(ws_id)
print(f"Name: {ws_full['name']}")
print(f"Cells: {len(ws_full['cells'])}")
for cell in ws_full["cells"]:
print(f" [{cell['cell_type']:12s}] {cell['cell_id']} — {cell['content'][:50]}...")Step 11: Workspace Branching
Duration: 3 minutes Goal: Create an experiment branch to try a different approach without affecting the main workspace.
11.1 Create a branch
python
branch = client.create_branch(
workspace_id=ws_id,
name="experiment-svd",
parent_branch="main"
)
print(f"Branch: {branch['name']}, parent: {branch['parent_branch']}")11.2 Add a cell on the branch
python
client.upsert_cell(
workspace_id=ws_id,
cell_id="cell-4-svd",
cell_type="computation",
content="symbolic_math(expression='Matrix([[2,1,0],[1,3,1],[0,1,2]])', operation='svd')",
position=3
)11.3 List branches
python
branches = client.list_branches(ws_id)
for b in branches.get("branches", []):
print(f" {b['name']} (parent: {b.get('parent_branch', 'none')})")Expected output:
main (parent: none)
experiment-svd (parent: main)Step 12: Run an Example Script
Duration: 3 minutes Goal: Run one of the 32 pre-built example scripts to verify end-to-end functionality.
12.1 Run the symbolic calculus example
bash
cd docs/examples
python3 01_symbolic_calculus.pyThis script runs several symbolic computations (integration, differentiation, series expansion) and prints the results.
12.2 Run the export formats example
bash
python3 10_export_formats.pyThis script runs a computation and exports it to all seven formats, printing a summary of each.
12.3 Explore the full example catalog
The docs/examples/ directory contains 32 scripts organized by topic:
| Range | Topic |
|---|---|
| 01–10 | Core PhD tools |
| 11–15 | Federated Clean Room |
| 16 | DSL Parser |
| 17–21 | PhD Advisor Brain |
| 22 | Science Workspace |
| 23–24 | Export & Validation |
| 25–27 | GPU, Verticals, Secure Data |
| 28–30 | Platform Extensions |
| 31–32 | Cross-Cutting |
Troubleshooting
PhD Mode disabled
Symptom: GET /api/phd/health returns "phd_mode_enabled": false
Fix: Ensure PHD_MODE_ENABLED=true is in your .env file and restart the backend.
Sandbox not available
Symptom: GET /api/phd/health returns "sandbox_available": false
Fix:
- Verify Docker is running:
docker info - Verify the image exists:
docker images ghostai-phd-sandbox - If missing, rebuild:
cd infrastructure/docker/sandbox && docker build -f Dockerfile.phd -t ghostai-phd-sandbox:latest . - Verify the
SANDBOX_IMAGEenv var matches the image tag
SDK import error
Symptom: ModuleNotFoundError: No module named 'ghostscience'
Fix: Install the SDK: cd securechat/sdk && pip install -e .
Connection refused
Symptom: requests.exceptions.ConnectionError
Fix:
- Verify the backend is running:
curl http://localhost:8000/health - Verify
base_urlin the client matches the backend address - If using Docker Compose, use the service name:
http://backend:8000
Computation timeout
Symptom: HTTP 504 or timeout after 300 seconds
Fix: Increase the timeout: SANDBOX_TIMEOUT=600 in .env. Complex computations (Monte Carlo, large ODEs) may need more time.
Docker permission denied
Symptom: permission denied while trying to connect to the Docker daemon socket
Fix: Add your user to the docker group: sudo usermod -aG docker $USER and restart your shell. Or use sudo for Docker commands.
gVisor not available
Symptom: OCI runtime create failed: ... runsc: executable file not found
Fix: Install gVisor following the official instructions. Or remove SANDBOX_RUNTIME=runsc from .env to use standard Docker isolation (less secure but functional for development).
What's Next
- Federated Clean Room: Set up a two-org clean room with the Clean Room Full Lab
- Demo Practice: Run through the GhostScience Demo Script to practice presenting these features
- Canvas: Build interactive visualizations with the Canvas Demo Script
- Deep Dive: Explore the GhostScience documentation for architecture details, security model, and compliance mappings
- API Reference: See the full PhD API reference, Workspace API, and SDK reference
Lab Summary
| Step | Topic | Duration |
|---|---|---|
| 1 | Enable PhD Mode | 3 min |
| 2 | Build PhD Sandbox Image | 5 min |
| 3 | Install Python SDK | 2 min |
| 4 | First Computation — Symbolic Math | 5 min |
| 5 | All Eight Tools | 10 min |
| 6 | Multi-Syntax DSL Input | 5 min |
| 7 | Provenance Record | 5 min |
| 8 | Export Results | 5 min |
| 9 | Reproduce Computation | 3 min |
| 10 | Create a Workspace | 5 min |
| 11 | Workspace Branching | 3 min |
| 12 | Run Example Scripts | 3 min |
| Total | ~54 min |