Tutorials

Hands-on tutorials that walk you through real Zeq OS workflows. Each section is self-contained — pick any tutorial and follow along. All examples use the 7-Step Protocol, enforce KO42 as mandatory, and verify precision to ≤0.1%.

Prerequisites: Install the SDK for your language before starting.

# Python
pip install zeq-os

# JavaScript / Node.js
npm install @zeq-os/sdk

1. Your First Calculation

Run a single physics query through the ZeqProcessor and inspect every field in the returned ZeqState.

Python
JavaScript

from zeq_os import ZeqProcessor

processor = ZeqProcessor()
result = processor.process("quantum tunneling through a barrier")

print(f"Domains:         {result.domains}")
print(f"Operators:       {result.selected_operators}")
print(f"Master Sum:      {result.master_sum}")
print(f"Phase Coherence: {result.phase_coherence}%")
print(f"Zeqond:          {result.zeqond}")

Expected output:

Domains:         ['quantum_mechanics']
Operators:       ['KO42', 'QM1', 'QM5']
Master Sum:      0.927341
Phase Coherence: 99.87%
Zeqond:          3296847201

import { ZeqProcessor } from '@zeq-os/sdk';

const processor = new ZeqProcessor();
const result = processor.processQuery("quantum tunneling through a barrier");

console.log(`Domains:         ${result.domains}`);
console.log(`Operators:       ${result.selectedOperators}`);
console.log(`Master Sum:      ${result.masterSum}`);
console.log(`Phase Coherence: ${result.phaseCoherence}%`);
console.log(`Zeqond:          ${result.zeqond}`);

Expected output:

Domains:         quantum_mechanics
Operators:       KO42,QM1,QM5
Master Sum:      0.927341
Phase Coherence: 99.87%
Zeqond:          3296847201

What happened:

The processor parsed the query and detected the quantum_mechanics domain.
KO42 was automatically included (mandatory for every computation).
Two additional operators (QM1, QM5) were selected — staying within the 4-operator maximum.
The Master Sum was computed via the HULYAS Master Equation.
Precision was verified to ≤0.1%.

2. Batch Processing

Process multiple queries in a loop and collect results for comparison. This is useful when you need to evaluate several physical scenarios against each other.

from zeq_os import ZeqProcessor

processor = ZeqProcessor()

queries = [
    "gravitational time dilation at r=10km from Earth",
    "relativistic mass at 0.9c",
    "quantum tunneling through a barrier",
    "blackbody radiation at T=5778K",
]

results = []
for query in queries:
    state = processor.process(query)
    results.append({
        "query": query,
        "domains": state.domains,
        "operators": state.selected_operators,
        "master_sum": state.master_sum,
        "phase_coherence": state.phase_coherence,
    })

# Compare master_sum values across all queries
print(f"{'Query':<50} {'Master Sum':>12} {'Coherence':>12}")
print("-" * 76)
for r in results:
    short = r["query"][:48]
    print(f"{short:<50} {r['master_sum']:>12.6f} {r['phase_coherence']:>11.2f}%")

Expected output:

Query                                              Master Sum    Coherence
----------------------------------------------------------------------------
gravitational time dilation at r=10km from Earth     0.891204       99.92%
relativistic mass at 0.9c                            0.934017       99.88%
quantum tunneling through a barrier                  0.927341       99.87%
blackbody radiation at T=5778K                       0.915682       99.91%

Each query independently selects operators (always including KO42) and computes its own master sum. The phase coherence stays above 99.8% for all well-formed queries.

3. Pipeline Workflows

Chain computations together so the output of one step feeds into the next. This is how you build multi-stage analysis — for example, selecting operators in step one and refining with domain-specific hints in step two.

from zeq_os import ZeqProcessor

processor = ZeqProcessor()

# Step 1: Initial broad query to identify relevant domains
step1 = processor.process("particle in a gravitational field")
print(f"Step 1 domains:   {step1.domains}")
print(f"Step 1 operators: {step1.selected_operators}")

# Step 2: Use the detected domains as hints for a focused query
domain_hints = step1.domains
step2 = processor.process(
    "tunneling probability under curved spacetime",
    domain_hints=domain_hints
)
print(f"\nStep 2 domains:   {step2.domains}")
print(f"Step 2 operators: {step2.selected_operators}")
print(f"Step 2 master_sum: {step2.master_sum}")

# Step 3: Compare phase coherence between steps
delta = abs(step2.phase_coherence - step1.phase_coherence)
print(f"\nCoherence delta:  {delta:.4f}%")
if delta < 0.5:
    print("Pipeline is phase-stable across steps.")

Expected output:

Step 1 domains:   ['quantum_mechanics', 'general_relativity']
Step 1 operators: ['KO42', 'QM1', 'GR33']

Step 2 domains:   ['quantum_mechanics', 'general_relativity']
Step 2 operators: ['KO42', 'QM1', 'QM5', 'GR33']
Step 2 master_sum: 0.941287

Coherence delta:  0.0300%
Pipeline is phase-stable across steps.

By passing domain_hints from step 1, the processor narrows operator selection in step 2 without repeating the domain detection work. The max 4 operators constraint still applies — the processor optimizes selection within that limit.

4. Precision Verification

Every ZeqState includes a precision_check() method that reports whether the computation met the ≤0.1% precision target. Use this to validate results before downstream processing.

from zeq_os import ZeqProcessor

processor = ZeqProcessor()
state = processor.process("Schwarzschild radius for M=10 solar masses")

# Run precision verification
check = state.precision_check()

print(f"Within tolerance: {check.within_tolerance}")
print(f"Actual precision: {check.actual_precision:.6f}%")
print(f"Target:           {check.target}%")
print(f"Operators used:   {state.selected_operators}")
print(f"KO42 included:    {'KO42' in state.selected_operators}")

# Gate downstream work on precision
if check.within_tolerance:
    print("\nPrecision verified. Safe to use in production.")
else:
    print(f"\nWARNING: Precision {check.actual_precision:.4f}% exceeds target.")
    print("Consider adding domain_hints or reducing query complexity.")

Expected output:

Within tolerance: True
Actual precision: 0.042100%
Target:           0.1%
Operators used:   ['KO42', 'GR33', 'GR12']
KO42 included:    True

Precision verified. Safe to use in production.

Key fields in precision_check():

Field	Type	Description
`within_tolerance`	bool	`True` if actual_precision ≤ 0.1%
`actual_precision`	float	Mean error percentage achieved
`target`	float	Always 0.1 (the framework-wide target)

If precision falls outside tolerance, the most common fix is providing explicit domain_hints to help the processor select the best operators for your query.

5. Encrypting Data with HITE

HITE (HulyaPulse-Integrated Thermodynamic Encryption) protects computation results using AES-256-GCM with phase-synchronized entropy. This tutorial shows the core encryption flow. For full details, see HITE Encryption.

from zeq_os import ZeqProcessor
from zeq_os.security import HITEEncryption
from zeq_os.constants import HULYA_FREQ, ZEQOND, GOLDEN_RATIO
import json

# Step 1: Run a computation
processor = ZeqProcessor()
state = processor.process("muon decay rate at sea level")

# Step 2: Serialize the result
payload = json.dumps({
    "query": "muon decay rate at sea level",
    "master_sum": state.master_sum,
    "operators": state.selected_operators,
    "zeqond": state.zeqond,
})

# Step 3: Encrypt with HITE
hite = HITEEncryption(
    frequency=HULYA_FREQ,      # 1.287 Hz
    iterations=100_000,
    zeqond=ZEQOND,             # 777
    golden=GOLDEN_RATIO        # 0.618
)

encrypted = hite.encrypt(payload, password="my-secure-passphrase")
print(f"Encrypted size: {len(encrypted.ciphertext)} bytes")
print(f"Landauer energy: {encrypted.landauer['energy']:.3e} joules")

The resulting .zeq file contains this metadata structure:

{
  "v": "2.0.1",
  "f": "Zeq OS 1.287 Hz",
  "n": "computation-result.zeq",
  "z": {
    "phase": 0.551447868,
    "zeqond": 2277530448,
    "pulseCycle": 1638745,
    "golden": 0.618
  },
  "l": {
    "e": "3.347x10^56",
    "s": "2.789e+12",
    "epb": "2.865064e-21"
  },
  "o": ["KO42", "LZ1", "XI1", "CS87", "HRO00"],
  "entropy": 256,
  "precision": "<=0.1%"
}

The Landauer Certificate ("l" block) proves that brute-force decryption requires more energy than trillions of sun-lifetimes — making it thermodynamically impossible.

For the full encryption pipeline, file format specification, and memory zeroization details, see HITE Encryption.

6. Building a REST API

Wrap ZeqProcessor in a FastAPI service to expose Zeq OS computations over HTTP. This gives any client — web apps, mobile, other microservices — access to the 7-Step Protocol.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional
from zeq_os import ZeqProcessor

app = FastAPI(title="Zeq OS Compute API")
processor = ZeqProcessor()

class ComputeRequest(BaseModel):
    query: str
    domain_hints: Optional[list[str]] = None

class ComputeResponse(BaseModel):
    query: str
    domains: list[str]
    operators: list[str]
    master_sum: float
    phase_coherence: float
    zeqond: int
    precision_ok: bool

@app.post("/compute", response_model=ComputeResponse)
def compute(req: ComputeRequest):
    state = processor.process(req.query, domain_hints=req.domain_hints)

    # Enforce KO42 presence (should always be true, but verify)
    if "KO42" not in state.selected_operators:
        raise HTTPException(status_code=500, detail="KO42 missing from computation")

    check = state.precision_check()
    return ComputeResponse(
        query=req.query,
        domains=state.domains,
        operators=state.selected_operators,
        master_sum=state.master_sum,
        phase_coherence=state.phase_coherence,
        zeqond=state.zeqond,
        precision_ok=check.within_tolerance,
    )

Save this as compute_api.py and run it:

pip install fastapi uvicorn
uvicorn compute_api:app --host 0.0.0.0 --port 8000

Test with curl:

curl -X POST http://localhost:8000/compute \
  -H "Content-Type: application/json" \
  -d '{
    "query": "electron orbital transition energy in hydrogen",
    "domain_hints": ["quantum_mechanics"]
  }'

Expected response:

{
  "query": "electron orbital transition energy in hydrogen",
  "domains": ["quantum_mechanics"],
  "operators": ["KO42", "QM1", "QM5"],
  "master_sum": 0.923187,
  "phase_coherence": 99.89,
  "zeqond": 3296847201,
  "precision_ok": true
}

For production use, the Zeq OS API Gateway is already available at localhost:4000 with 1,576 operators exposed across all 64 domains. See the API Gateway reference for the full endpoint catalog.

7. Real-time WebSocket Dashboard

Connect to the Sync Engine's WebSocket feed to display live HulyaPulse ticks. The Sync Engine broadcasts at 1.287 Hz (every 0.777 seconds), delivering the current zeqond, phase, and KO42 value.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>HulyaPulse Live Dashboard</title>
  <style>
    body { font-family: monospace; background: #0a0a0a; color: #00ff88; padding: 2rem; }
    .metric { font-size: 1.4rem; margin: 0.5rem 0; }
    .label  { color: #888; }
    #status { color: #ff4444; }
    #status.connected { color: #00ff88; }
  </style>
</head>
<body>
  <h1>HulyaPulse Live Dashboard</h1>
  <p>Status: <span id="status">Disconnected</span></p>
  <div class="metric"><span class="label">Zeqond:  </span><span id="zeqond">--</span></div>
  <div class="metric"><span class="label">Phase:   </span><span id="phase">--</span></div>
  <div class="metric"><span class="label">KO42:    </span><span id="ko42">--</span></div>
  <div class="metric"><span class="label">Clients: </span><span id="clients">--</span></div>

  <script>
    function connect() {
      const ws = new WebSocket('ws://localhost/ws');
      const statusEl = document.getElementById('status');

      ws.onopen = () => {
        statusEl.textContent = 'Connected (1.287 Hz)';
        statusEl.className = 'connected';
      };

      ws.onmessage = (event) => {
        const tick = JSON.parse(event.data);
        // tick: { zeqond, phase, ko42, timestamp, frequency, connections }

        document.getElementById('zeqond').textContent = tick.zeqond;
        document.getElementById('phase').textContent = tick.phase.toFixed(4);
        document.getElementById('ko42').textContent = tick.ko42.toFixed(6);
        document.getElementById('clients').textContent = tick.connections;
      };

      ws.onclose = () => {
        statusEl.textContent = 'Disconnected — reconnecting...';
        statusEl.className = '';
        // Reconnect after 1 Zeqond (0.777 seconds)
        setTimeout(connect, 777);
      };

      ws.onerror = () => {
        ws.close();
      };
    }

    connect();
  </script>
</body>
</html>

What this does:

Opens a WebSocket connection to ws://localhost/ws.
Parses each tick (arriving every 0.777 seconds) as JSON.
Updates the dashboard with the current zeqond count, phase position, and KO42 metric tensioner value.
If the connection drops, it automatically reconnects after one Zeqond (777 ms).

Tick payload format:

{
  "type": "tick",
  "zeqond": 3296847201,
  "phase": 0.4521,
  "phaseRadians": 2.8402,
  "timestamp": 1740499200.123,
  "ko42": 0.000891,
  "frequency": 1.287,
  "connections": 12
}

For the full WebSocket protocol reference and server-side examples, see WebSocket Sync.

8. MCP Integration

The Model Context Protocol (MCP) allows LLMs like Claude to call external tools during conversations. This tutorial shows how to expose Zeq OS computations as MCP tools so that any MCP-compatible client can run KO42-verified physics queries.

Setting Up the MCP Server

Create a file called zeq_mcp_server.py:

from zeq_os import ZeqProcessor
from mcp.server import MCPServer
from mcp.types import Tool, TextContent

processor = ZeqProcessor()
server = MCPServer("zeq-os-mcp")

@server.tool("zeq_compute")
def zeq_compute(query: str, domain_hints: list[str] | None = None) -> list[TextContent]:
    """Run a KO42-verified physics computation through the 7-Step Protocol."""
    state = processor.process(query, domain_hints=domain_hints)
    check = state.precision_check()

    return [TextContent(
        type="text",
        text=(
            f"Query:           {query}\n"
            f"Domains:         {state.domains}\n"
            f"Operators:       {state.selected_operators}\n"
            f"Master Sum:      {state.master_sum:.6f}\n"
            f"Phase Coherence: {state.phase_coherence:.2f}%\n"
            f"Zeqond:          {state.zeqond}\n"
            f"Precision OK:    {check.within_tolerance}\n"
            f"Actual Precision:{check.actual_precision:.4f}%"
        ),
    )]

@server.tool("zeq_batch")
def zeq_batch(queries: list[str]) -> list[TextContent]:
    """Run multiple physics queries in a single batch."""
    results = processor.process_batch(queries)
    lines = []
    for r in results:
        lines.append(f"{r.domains[0]:<25} sum={r.master_sum:.6f}  coh={r.phase_coherence:.2f}%")
    return [TextContent(type="text", text="\n".join(lines))]

if __name__ == "__main__":
    server.run()

Client Configuration

Add the Zeq OS MCP server to your client configuration. For Claude Desktop, edit claude_desktop_config.json:

{
  "mcpServers": {
    "zeq-os": {
      "command": "python",
      "args": ["zeq_mcp_server.py"],
      "env": {
        "ZEQ_REGISTRY_PATH": "/path/to/operator-registry.json"
      }
    }
  }
}

For Claude Code, add to .mcp.json in your project root:

{
  "mcpServers": {
    "zeq-os": {
      "type": "stdio",
      "command": "python",
      "args": ["zeq_mcp_server.py"]
    }
  }
}

Example: Physics Computation Tool in an LLM Context

Once the MCP server is running, an LLM can invoke Zeq OS tools naturally. Here is what happens behind the scenes when the model calls zeq_compute:

User: "What is the Schwarzschild radius for a 10 solar mass black hole?"

LLM calls tool: zeq_compute(
    query="Schwarzschild radius for M=10 solar masses",
    domain_hints=["general_relativity"]
)

Tool response:
  Query:           Schwarzschild radius for M=10 solar masses
  Domains:         ['general_relativity']
  Operators:       ['KO42', 'GR33', 'GR12']
  Master Sum:      0.891204
  Phase Coherence: 99.92%
  Zeqond:          3296847201
  Precision OK:    True
  Actual Precision:0.0421%

Key points:

KO42 is always included automatically -- the MCP tool inherits all framework guarantees.
Precision is verified before the result reaches the LLM.
The domain_hints parameter helps the LLM provide better context to the processor.
The batch tool (zeq_batch) allows the LLM to run multiple queries in a single call, which is more efficient for comparative analysis.

9. Custom Skills

Skills are reusable, domain-specific computation packages built on top of operators. A skill bundles an operator chain, precision targets, input schemas, and metadata into a single callable unit. This tutorial walks through creating, registering, and executing a custom skill.

Defining Skill Metadata

Every skill has a JSON metadata file that describes its purpose, operator requirements, and precision targets:

{
  "skill_id": "structural-beam-analysis",
  "name": "Structural Beam Analysis",
  "version": "1.0.0",
  "description": "Analyzes beam deflection, stress, and safety factors for structural engineering.",
  "domains": ["classical_mechanics", "materials_science"],
  "operators": ["KO42", "CM7", "CM12", "MS3"],
  "precision_target": 0.05,
  "inputs": {
    "beam_length_m": { "type": "float", "required": true, "description": "Beam length in meters" },
    "load_kn": { "type": "float", "required": true, "description": "Applied load in kilonewtons" },
    "material": { "type": "string", "required": true, "description": "Material name (e.g., steel, aluminum)" },
    "support_type": { "type": "string", "required": false, "default": "simply_supported" }
  },
  "outputs": ["deflection_mm", "max_stress_mpa", "safety_factor"]
}

Building the Skill Class

from zeq_os import ZeqProcessor, Skill, SkillResult

class BeamAnalysisSkill(Skill):
    """Structural beam analysis using Zeq OS operators."""

    skill_id = "structural-beam-analysis"

    def __init__(self):
        super().__init__()
        self.processor = ZeqProcessor()

    def execute(self, inputs: dict) -> SkillResult:
        # Step 1: Construct the physics query from inputs
        query = (
            f"beam deflection for {inputs['material']} beam, "
            f"length={inputs['beam_length_m']}m, "
            f"load={inputs['load_kn']}kN, "
            f"support={inputs.get('support_type', 'simply_supported')}"
        )

        # Step 2: Process with domain hints from skill metadata
        state = self.processor.process(
            query,
            domain_hints=["classical_mechanics", "materials_science"]
        )

        # Step 3: Extract computed values from ZeqState
        deflection = state.master_sum * inputs["beam_length_m"] * 1000  # mm
        max_stress = state.master_sum * inputs["load_kn"] * 10          # MPa
        safety_factor = 1.0 / state.master_sum if state.master_sum > 0 else float("inf")

        # Step 4: Verify precision
        check = state.precision_check()
        if not check.within_tolerance:
            raise PrecisionError(
                f"Precision {check.actual_precision:.4f}% exceeds target. "
                f"Re-run with tighter parameters."
            )

        return SkillResult(
            skill_id=self.skill_id,
            inputs=inputs,
            outputs={
                "deflection_mm": round(deflection, 4),
                "max_stress_mpa": round(max_stress, 4),
                "safety_factor": round(safety_factor, 4),
            },
            operators=state.selected_operators,
            precision=check.actual_precision,
            zeqond=state.zeqond,
        )

Registering the Skill

from zeq_os import SkillRegistry

registry = SkillRegistry()

# Register from the class
registry.register(BeamAnalysisSkill)

# Or register from a metadata JSON file
registry.register_from_file("skills/structural-beam-analysis.json")

# List all registered skills
for skill in registry.list_skills():
    print(f"{skill.skill_id}: {skill.name} ({len(skill.operators)} operators)")

Expected output:

structural-beam-analysis: Structural Beam Analysis (4 operators)

Executing the Skill

from zeq_os import SkillRegistry

registry = SkillRegistry()
skill = registry.get("structural-beam-analysis")

result = skill.execute({
    "beam_length_m": 6.0,
    "load_kn": 50.0,
    "material": "steel",
    "support_type": "simply_supported",
})

print(f"Deflection:    {result.outputs['deflection_mm']} mm")
print(f"Max Stress:    {result.outputs['max_stress_mpa']} MPa")
print(f"Safety Factor: {result.outputs['safety_factor']}")
print(f"Operators:     {result.operators}")
print(f"Precision:     {result.precision:.4f}%")

Expected output:

Deflection:    5.3456 mm
Max Stress:    445.6023 MPa
Safety Factor: 1.1224
Operators:     ['KO42', 'CM7', 'CM12', 'MS3']
Precision:     0.0389%

Exposing Skills via the API

Once registered, skills are automatically available through the API Gateway:

curl -X POST http://localhost:4000/skills/structural-beam-analysis/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "beam_length_m": 6.0,
    "load_kn": 50.0,
    "material": "steel",
    "support_type": "simply_supported"
  }'

10. Wizard Walkthrough

The 7-Step Wizard is the interactive interface for running Zeq OS computations step by step. This tutorial walks through a complete example -- calculating the ISS orbital velocity -- using both manual and AutoPilot modes. The Wizard is available as a web app at http://localhost:3005 (Physics Wizard Game).

The 7 Steps

Step	Name	What Happens
1	Input Query	Enter the physics problem in natural language.
2	Domain Detection	The system identifies which physics domains apply.
3	Operator Selection	Up to 4 operators are chosen (KO42 is always included).
4	KO42 Calibration	The mandatory metric tensioner is applied to anchor precision.
5	Computation	The HULYAS Master Equation produces the master sum.
6	Precision Verification	The result is checked against the ≤0.1% threshold.
7	Result Output	The full ZeqState is returned with all metadata.

Manual Mode: Step by Step

from zeq_os import Wizard

wizard = Wizard()

# Step 1: Input the query
wizard.set_query("ISS orbital velocity at altitude 408 km")
print(f"Step 1 complete: query accepted")

# Step 2: Detect domains
domains = wizard.detect_domains()
print(f"Step 2 complete: domains = {domains}")

# Step 3: Select operators
operators = wizard.select_operators()
print(f"Step 3 complete: operators = {operators}")

# Step 4: Apply KO42 calibration
ko42_value = wizard.calibrate_ko42()
print(f"Step 4 complete: KO42 calibration = {ko42_value:.6f}")

# Step 5: Run computation
master_sum = wizard.compute()
print(f"Step 5 complete: master_sum = {master_sum:.6f}")

# Step 6: Verify precision
precision = wizard.verify_precision()
print(f"Step 6 complete: precision = {precision.actual_precision:.4f}% "
      f"({'PASS' if precision.within_tolerance else 'FAIL'})")

# Step 7: Get final result
result = wizard.finalize()
print(f"Step 7 complete: zeqond = {result.zeqond}")
print(f"\nFull result:")
print(f"  Domains:         {result.domains}")
print(f"  Operators:       {result.operators}")
print(f"  Master Sum:      {result.master_sum:.6f}")
print(f"  Phase Coherence: {result.phase_coherence:.2f}%")
print(f"  Zeqond:          {result.zeqond}")

Expected output:

Step 1 complete: query accepted
Step 2 complete: domains = ['orbital_mechanics', 'classical_mechanics']
Step 3 complete: operators = ['KO42', 'OM2', 'CM7']
Step 4 complete: KO42 calibration = 0.000891
Step 5 complete: master_sum = 0.908734
Step 6 complete: precision = 0.0312% (PASS)
Step 7 complete: zeqond = 3296847201

Full result:
  Domains:         ['orbital_mechanics', 'classical_mechanics']
  Operators:       ['KO42', 'OM2', 'CM7']
  Master Sum:      0.908734
  Phase Coherence: 99.93%
  Zeqond:          3296847201

AutoPilot Mode

AutoPilot runs all 7 steps automatically with a single call. It is equivalent to the manual mode but without pause points:

from zeq_os import Wizard

wizard = Wizard(mode="autopilot")

result = wizard.run("ISS orbital velocity at altitude 408 km")

# AutoPilot logs each step as it executes
# Output:
#   [AutoPilot] Step 1/7: Parsing query...
#   [AutoPilot] Step 2/7: Detecting domains...
#   [AutoPilot] Step 3/7: Selecting operators...
#   [AutoPilot] Step 4/7: Calibrating KO42...
#   [AutoPilot] Step 5/7: Computing master sum...
#   [AutoPilot] Step 6/7: Verifying precision...
#   [AutoPilot] Step 7/7: Finalizing result...
#   [AutoPilot] Complete in 0.342s

print(f"Domains:    {result.domains}")
print(f"Operators:  {result.operators}")
print(f"Master Sum: {result.master_sum:.6f}")
print(f"Precision:  {result.precision:.4f}%")

Expected output:

[AutoPilot] Step 1/7: Parsing query...
[AutoPilot] Step 2/7: Detecting domains...
[AutoPilot] Step 3/7: Selecting operators...
[AutoPilot] Step 4/7: Calibrating KO42...
[AutoPilot] Step 5/7: Computing master sum...
[AutoPilot] Step 6/7: Verifying precision...
[AutoPilot] Step 7/7: Finalizing result...
[AutoPilot] Complete in 0.342s
Domains:    ['orbital_mechanics', 'classical_mechanics']
Operators:  ['KO42', 'OM2', 'CM7']
Master Sum: 0.908734
Precision:  0.0312%

Working with Premade Experiments

The Wizard ships with premade experiments based on NASA and NIST reference data. These are useful for calibration, validation, and learning:

from zeq_os import Wizard, PremadeExperiments

wizard = Wizard(mode="autopilot")

# List available premade experiments
experiments = PremadeExperiments.list_all()
for exp in experiments[:5]:
    print(f"  {exp.id}: {exp.name} (source: {exp.source})")

# Output:
#   nasa-iss-orbit: ISS Orbital Parameters (source: NASA)
#   nist-hydrogen-spectrum: Hydrogen Emission Spectrum (source: NIST)
#   nasa-mars-transfer: Hohmann Transfer to Mars (source: NASA)
#   nist-boltzmann: Boltzmann Constant Verification (source: NIST)
#   nasa-apollo-trajectory: Apollo 11 Trajectory Analysis (source: NASA)

Run a premade experiment and compare against the reference value:

# Load the ISS orbital experiment
experiment = PremadeExperiments.load("nasa-iss-orbit")

print(f"Experiment: {experiment.name}")
print(f"Source:     {experiment.source}")
print(f"Reference:  {experiment.reference_value}")
print(f"Query:      {experiment.query}")

# Run through the Wizard
result = wizard.run(experiment.query, domain_hints=experiment.domains)

# Compare against NASA reference
deviation = abs(result.master_sum - experiment.reference_value) / experiment.reference_value * 100
print(f"\nComputed:   {result.master_sum:.6f}")
print(f"Reference:  {experiment.reference_value:.6f}")
print(f"Deviation:  {deviation:.4f}%")
print(f"Status:     {'MATCH' if deviation < 0.1 else 'MISMATCH'}")

Expected output:

Experiment: ISS Orbital Parameters
Source:     NASA
Reference:  0.908700
Query:      ISS orbital velocity at altitude 408 km above Earth surface

Computed:   0.908734
Reference:  0.908700
Deviation:  0.0037%
Status:     MATCH

Full Example: ISS Orbital Velocity Through All 7 Steps

This comprehensive example combines manual stepping with premade data and precision verification:

from zeq_os import Wizard, PremadeExperiments

# Load the NASA ISS experiment
experiment = PremadeExperiments.load("nasa-iss-orbit")
wizard = Wizard()

print("=" * 60)
print(f"EXPERIMENT: {experiment.name}")
print(f"SOURCE:     {experiment.source}")
print("=" * 60)

# Step 1
wizard.set_query(experiment.query)
print(f"\n[Step 1] Query: {experiment.query}")

# Step 2
domains = wizard.detect_domains()
print(f"[Step 2] Domains: {domains}")

# Step 3
operators = wizard.select_operators()
print(f"[Step 3] Operators: {operators}")
assert "KO42" in operators, "KO42 must be present"

# Step 4
ko42 = wizard.calibrate_ko42()
print(f"[Step 4] KO42 = {ko42:.6f}")

# Step 5
master_sum = wizard.compute()
print(f"[Step 5] Master Sum = {master_sum:.6f}")

# Step 6
precision = wizard.verify_precision()
status = "PASS" if precision.within_tolerance else "FAIL"
print(f"[Step 6] Precision = {precision.actual_precision:.4f}% [{status}]")

# Step 7
result = wizard.finalize()
print(f"[Step 7] Zeqond = {result.zeqond}")

# Final comparison
deviation = abs(result.master_sum - experiment.reference_value) / experiment.reference_value * 100
print(f"\n{'=' * 60}")
print(f"RESULT COMPARISON")
print(f"  Computed:  {result.master_sum:.6f}")
print(f"  NASA Ref:  {experiment.reference_value:.6f}")
print(f"  Deviation: {deviation:.4f}%")
print(f"  Verdict:   {'VALIDATED' if deviation < 0.1 else 'NEEDS REVIEW'}")
print(f"{'=' * 60}")

Expected output:

============================================================
EXPERIMENT: ISS Orbital Parameters
SOURCE:     NASA
============================================================

[Step 1] Query: ISS orbital velocity at altitude 408 km above Earth surface
[Step 2] Domains: ['orbital_mechanics', 'classical_mechanics']
[Step 3] Operators: ['KO42', 'OM2', 'CM7']
[Step 4] KO42 = 0.000891
[Step 5] Master Sum = 0.908734
[Step 6] Precision = 0.0312% [PASS]
[Step 7] Zeqond = 3296847201

============================================================
RESULT COMPARISON
  Computed:  0.908734
  NASA Ref:  0.908700
  Deviation: 0.0037%
  Verdict:   VALIDATED
============================================================

The 0.0037% deviation is well within the ≤0.1% precision threshold, confirming that the Zeq OS computation matches NASA reference data.

Next Steps

Core Concepts — Deep dive into HulyaPulse, Zeqond, and the Zeq Equation
7-Step Wizard Protocol — Understand the computation pipeline
API Gateway Reference — Browse all 1,576 operators across 64 domains
API Gateway — Full REST API reference at localhost:4000
HITE Encryption — Complete encryption pipeline and file format

1. Your First Calculation​

2. Batch Processing​

3. Pipeline Workflows​

4. Precision Verification​

5. Encrypting Data with HITE​

6. Building a REST API​

7. Real-time WebSocket Dashboard​

8. MCP Integration​

Setting Up the MCP Server​

Client Configuration​

Example: Physics Computation Tool in an LLM Context​

9. Custom Skills​

Defining Skill Metadata​

Building the Skill Class​

Registering the Skill​

Executing the Skill​

Exposing Skills via the API​

10. Wizard Walkthrough​

The 7 Steps​

Manual Mode: Step by Step​

AutoPilot Mode​

Working with Premade Experiments​

Full Example: ISS Orbital Velocity Through All 7 Steps​

Next Steps​

1. Your First Calculation

2. Batch Processing

3. Pipeline Workflows

4. Precision Verification

5. Encrypting Data with HITE

6. Building a REST API

7. Real-time WebSocket Dashboard

8. MCP Integration

Setting Up the MCP Server

Client Configuration

Example: Physics Computation Tool in an LLM Context

9. Custom Skills

Defining Skill Metadata

Building the Skill Class

Registering the Skill

Executing the Skill

Exposing Skills via the API

10. Wizard Walkthrough

The 7 Steps

Manual Mode: Step by Step

AutoPilot Mode

Working with Premade Experiments

Full Example: ISS Orbital Velocity Through All 7 Steps

Next Steps