> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reilabs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Run the examples

> Exercise forecast revision, numeric transport, and one- and two-step planning with Python 3.

Set the API base to your authorized UAT deployment and supply its key. The base must include `/api/v1`.

```bash theme={null}
export ADAPT_API_BASE='https://YOUR-UAT-HOST/api/v1'
read -rsp 'UAT API key: ' ADAPT_API_KEY
export ADAPT_API_KEY
```

Save the Python code below as `uat_futures.py`. It uses the standard library. Choose a case and run it from a writable directory.

```bash theme={null}
python3 uat_futures.py --case forecast
python3 uat_futures.py --case numeric
python3 uat_futures.py --case planning
python3 uat_futures.py --case multistep
# Or run all four:
python3 uat_futures.py --case all
```

Each case creates a fresh Domain, sends synthetic observations and prints a `PASS` line for each successful check. The multi-step case sends 72 transitions and queries between observations. Requests, responses and checks are saved under `uat-futures-...` in the working directory. The trace excludes authentication headers.

```python theme={null}
import argparse
import json
import os
import time
import uuid
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen


def run(case):
    base = os.environ["ADAPT_API_BASE"].rstrip("/")
    key = os.environ["ADAPT_API_KEY"]
    session = "futures-" + uuid.uuid4().hex
    out = Path("uat-" + session)
    out.mkdir(exist_ok=False)

    def api(method, path, body=None):
        headers = {"Authorization": "Bearer " + key}
        data = None
        if body is not None:
            headers["Content-Type"] = "application/json"
            data = json.dumps(body, allow_nan=False).encode()
        request = Request(base + path, data=data, headers=headers, method=method)
        started = time.monotonic()
        try:
            with urlopen(request, timeout=180) as response:
                status, raw = response.status, response.read().decode()
        except HTTPError as exc:
            status, raw = exc.code, exc.read().decode()
        try:
            result = json.loads(raw)
        except json.JSONDecodeError:
            result = {"raw_response": raw}
        record = {"method": method, "path": path, "request": body,
                  "status": status, "seconds": time.monotonic() - started,
                  "response": result}
        with (out / "requests.jsonl").open("a") as handle:
            handle.write(json.dumps(record) + "\n")
        if status >= 400:
            raise RuntimeError(f"{method} {path}: HTTP {status}: {raw}")
        return result

    def create(name, signals, transition):
        domain = session + "-" + name
        body = {"domain_id": domain, "session_id": session,
                "schema": {"signals": signals, "event_types": ["outcome"]},
                "learning": {"transition": transition}}
        (out / (name + "-domain.json")).write_text(json.dumps(body, indent=2))
        api("POST", "/domains", body)
        return domain

    def query(domain, values, future=None):
        context = {"values": values}
        if future is not None:
            context["metadata"] = {"future_id": future}
        return api("POST", f"/domains/{domain}/query", {
            "session_id": session, "question": "Forecast and plan",
            "context": context,
            "return_fields": ["decision_id", "transition_prediction", "transition_plan"],
        })

    def observe(domain, values, decision=None, future=None):
        metadata = {}
        if decision is not None:
            metadata["decision_id"] = decision
        if future is not None:
            metadata["future_id"] = future
        return api("POST", f"/domains/{domain}/events", {
            "session_id": session, "event_type": "outcome",
            "values": values, "metadata": metadata,
        })

    def state(domain):
        result = api("POST", f"/domains/{domain}/explain", {
            "session_id": session, "question": "Inspect learning state",
            "context": {"values": {}}, "update_memory_state": False,
        })
        return result["learning_state"]["subsystems"]["structured_transition"]

    def check(name, condition, detail):
        if not condition:
            raise AssertionError(name + ": " + json.dumps(detail))
        print("PASS", name)
        with (out / "checks.jsonl").open("a") as handle:
            handle.write(json.dumps({"check": name, "passed": True, "detail": detail}) + "\n")

    def distribution(reply):
        return reply["transition_prediction"]["futures"]

    def basic_transition():
        return {"enabled": True, "event_types": ["outcome"],
                "input_paths": ["values.cue"],
                "targets": [{"path": "values.result", "type": "boolean"}],
                "required_support": 4, "max_samples": 512,
                "futures": {"enabled": True}}

    if case in ("forecast", "all"):
        domain = create("forecast", ["cue", "result"], basic_transition())
        cold = distribution(query(domain, {"cue": 1}))
        check("empty Domain abstains", cold["status"] == "abstained", cold)
        for i in range(12):
            observe(domain, {"cue": i % 2, "result": bool(i % 2)})
        for i in range(24):
            cue = i % 2
            future = "calibration-" + str(i)
            issued = query(domain, {"cue": cue}, future)
            completed = observe(domain, {"cue": cue, "result": bool(cue)},
                                issued["decision_id"], future)
            update = completed["learner_eligibility"]["futures_update"]
            if not update["accepted"]:
                raise AssertionError(update)
        early_reply = query(domain, {}, "revised-target")
        late_reply = query(domain, {"cue": 1}, "revised-target")
        early, late = distribution(early_reply), distribution(late_reply)
        early_p = early["marginals"]["values.result"]["probabilities"]["true"]
        late_p = late["marginals"]["values.result"]["probabilities"]["true"]
        check("new evidence changes probabilities", late_p > early_p,
              {"before_evidence": early_p, "after_evidence": late_p})
        completed = observe(domain, {"cue": 1, "result": True},
                            late_reply["decision_id"], "revised-target")
        update = completed["learner_eligibility"]["futures_update"]
        check("one outcome resolves both revisions",
              update["accepted"] and update["resolved_revisions"] == 2, update)
        learning = state(domain)["futures"]
        check("issued forecasts outperform their prior on this mock stream",
              learning["mean_energy_score"] < learning["mean_prior_energy_score"], learning)
        check("all predicted receipts resolved", learning["pending_forecasts"] == 0, learning)

    if case in ("numeric", "all"):
        cfg = basic_transition()
        cfg["targets"] = [{"path": "values.result", "type": "number"}]
        cfg["numeric_min_skill"] = 0.0
        cfg["futures"]["numeric_transport"] = "linear_residual"
        domain = create("numeric", ["cue", "result"], cfg)
        for i in range(80):
            cue = ((i * 17) % 80) / 80
            observed = 10 * cue + (0.1 if i % 2 else -0.1)
            observe(domain, {"cue": cue, "result": observed})
        issued = query(domain, {"cue": 0.55}, "numeric-target")
        forecast = distribution(issued)
        check("numeric transport is active",
              forecast["numeric_transport"]["status"] == "active", forecast)
        mean = forecast["marginals"]["values.result"]["mean"]
        check("numeric center follows this mock relationship", abs(mean - 5.5) < 0.3,
              forecast["marginals"])
        observe(domain, {"cue": 0.55, "result": 5.6}, issued["decision_id"], "numeric-target")

    if case in ("planning", "all"):
        cfg = {"enabled": True, "event_types": ["outcome"],
               "input_paths": ["values.x", "values.action"], "action_path": "values.action",
               "targets": [{"path": "values.next_x", "type": "number"}],
               "required_support": 4, "max_samples": 512,
               "futures": {"enabled": True},
               "planning": {"enabled": True, "probabilistic": True,
                   "actions": ["wide", "steady"], "horizon": 1,
                   "state_bindings": [{"target_path": "values.next_x", "state_path": "values.x"}],
                   "goals": [{"path": "values.x", "operator": "between", "value": [0.8, 1.2]}],
                   "objectives": [{"path": "values.x", "direction": "target", "target": 1.0}],
                   "constraints": [{"path": "values.x", "operator": "lte", "value": 1.2}],
                   "risk_weight": 0.25, "tail_probability": 0.1,
                   "max_failure_probability": 0.0, "max_unresolved_probability": 0.05}}
        domain = create("planning", ["x", "action", "next_x"], cfg)
        for i in range(12):
            action = "wide" if i < 6 else "steady"
            next_x = (2.0 if i % 2 else 0.0) if action == "wide" else 0.9
            observe(domain, {"x": 0.0, "action": action, "next_x": next_x})
        issued = query(domain, {"x": 0.0}, "planned-execution")
        plan = issued["transition_plan"]
        check("planner selects the observed lower-risk action",
              plan["status"] == "planned" and plan["selected_action"] == "steady", plan)
        completed = observe(domain, {"x": 0.0, "action": plan["selected_action"], "next_x": 0.9},
                            issued["decision_id"], "planned-execution")
        update = completed["learner_eligibility"]["futures_update"]
        check("execution resolves the selected action's forecast", update["accepted"], update)

    if case in ("multistep", "all"):
        cfg = {"enabled": True, "event_types": ["outcome"],
               "input_paths": ["values.phase", "values.action"], "action_path": "values.action",
               "targets": [{"path": "values.after", "type": "categorical"}],
               "required_support": 2, "max_samples": 512, "max_distance": 1.0,
               "futures": {"enabled": True, "prior_strength": 0.1},
               "planning": {"enabled": True, "probabilistic": True,
                   "actions": ["move", "finish"], "horizon": 2, "beam_width": 8,
                   "state_bindings": [{"target_path": "values.after", "state_path": "values.phase"}],
                   "goals": [{"path": "values.phase", "value": "done"}],
                   "max_unresolved_probability": 0.1}}
        domain = create("multistep", ["phase", "action", "after"], cfg)
        executions = [("start", "move", "middle"), ("start", "finish", "dead"),
                      ("middle", "finish", "done"), ("middle", "move", "dead"),
                      ("dead", "move", "dead"), ("dead", "finish", "dead")]
        for i in range(72):
            phase, action, after = executions[i % len(executions)]
            future = "step-" + str(i)
            issued = query(domain, {"phase": phase, "action": action}, future)
            predicted = distribution(issued)["status"] == "predicted"
            observe(domain, {"phase": phase, "action": action, "after": after},
                    issued["decision_id"] if predicted else None, future if predicted else None)
        issued = query(domain, {"phase": "start"}, "two-step-plan")
        plan = issued["transition_plan"]
        check("two-step route learned from transitions",
              plan["status"] == "planned" and plan["action_sequence"] == ["move", "finish"], plan)
        # Execute only the first action and report its real result; replan afterwards.
        observe(domain, {"phase": "start", "action": plan["selected_action"], "after": "middle"},
                issued["decision_id"], "two-step-plan")

    print("Session:", session)
    print("Evidence directory:", out.resolve())
    return out


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--case", choices=["forecast", "numeric", "planning", "multistep", "all"],
                        default="forecast")
    run(parser.parse_args().case)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.