Skip to content

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 info succeeds)
  • [ ] 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.tool

Step 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=runsc

1.2 Restart the backend ​

bash
cd securechat/backend
uvicorn app.main:app --reload --port 8000

1.3 Verify ​

bash
curl -s http://localhost:8000/api/phd/health | python3 -m json.tool

Expected 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:latest

2.2 Verify the image ​

bash
docker images ghostai-phd-sandbox

Expected output:

REPOSITORY              TAG       IMAGE ID       CREATED         SIZE
ghostai-phd-sandbox     latest    abc123def456   10 seconds ago  2.1GB

2.3 Verify sandbox availability ​

bash
curl -s http://localhost:8000/api/phd/health | python3 -m json.tool

Expected 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:latest

Step 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']}")
EOF

Expected output:

Status: ok
Sandbox: True
PhD Mode: True

Step 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))
EOF

4.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 milliseconds
  • result.latex — LaTeX-rendered result
  • result.steps — step-by-step derivation
  • result.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/4

Step 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:

FieldDescription
computation_idUnique identifier
tool_nameWhich scientific tool was used
result_hashSHA-256 of the result payload
wall_time_msExecution time
result.codeThe generated Python code
created_atTimestamp

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 ​

FormatDescription
pythonStandalone Python script with imports and comments
matlabMATLAB .m file
juliaJulia script
latexPublication-ready LaTeX document
jupyterJupyter notebook (.ipynb)
cC implementation with numerical libraries
dockerDockerfile 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: True

9.2 What happens under the hood ​

The reproduce endpoint:

  1. Retrieves the original provenance record (tool, parameters, environment hash)
  2. Launches a new sandbox with the same Docker image
  3. Re-executes the generated code with the same RNG seeds
  4. 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.py

This 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.py

This 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:

RangeTopic
01–10Core PhD tools
11–15Federated Clean Room
16DSL Parser
17–21PhD Advisor Brain
22Science Workspace
23–24Export & Validation
25–27GPU, Verticals, Secure Data
28–30Platform Extensions
31–32Cross-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:

  1. Verify Docker is running: docker info
  2. Verify the image exists: docker images ghostai-phd-sandbox
  3. If missing, rebuild: cd infrastructure/docker/sandbox && docker build -f Dockerfile.phd -t ghostai-phd-sandbox:latest .
  4. Verify the SANDBOX_IMAGE env 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:

  1. Verify the backend is running: curl http://localhost:8000/health
  2. Verify base_url in the client matches the backend address
  3. 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 ​


Lab Summary ​

StepTopicDuration
1Enable PhD Mode3 min
2Build PhD Sandbox Image5 min
3Install Python SDK2 min
4First Computation — Symbolic Math5 min
5All Eight Tools10 min
6Multi-Syntax DSL Input5 min
7Provenance Record5 min
8Export Results5 min
9Reproduce Computation3 min
10Create a Workspace5 min
11Workspace Branching3 min
12Run Example Scripts3 min
Total~54 min

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