Discovery examples

Create, inspect, and query Transition, Structure, Sequential, and mixed Discovery Domains through the production API.

These examples cover numeric and categorical Transition Discovery, Structure Discovery, Sequential Discovery, and mixed causal-binding discovery.

Run one complete Discovery tutorial

Create a fresh Domain, submit the included observations, inspect before/after responses, and query retained state from one Python file.

Choose a declaration below, then use the shared create → ingest → inspect → query loop. These payloads extend the complete tutorial; HTTP and contracts describes schema coverage.

All examples use:

https://rei-neuroadapt-api.reilabs.org/api/v1

Export a bearer token before running them:

export ADAPT1_API_KEY="YOUR_SECRET_TOKEN"

The hosted API derives tenant ownership and effective session identity from the bearer token. Request examples use session_id: ignored for compatibility.

Choose a declaration

Numeric

This Domain declares the numeric target and lets Adapt-1 discover the stable input projection.

{
  "domain_id": "process-output-demo",
  "session_id": "ignored",
  "description": "Predict an observed process output from available measurements.",
  "schema": {
    "event_types": ["observation"]
  },
  "learning": {
    "enabled": true,
    "transition": {
      "enabled": true,
      "event_types": ["observation"],
      "targets": [
        {
          "path": "values.process.output",
          "type": "number"
        }
      ],
      "required_support": 3,
      "numeric_model": "auto",
      "autonomous_projection": {
        "enabled": true,
        "minimum_observations": 3,
        "minimum_availability": 0.8,
        "maximum_input_paths": 8
      }
    }
  }
}

Send complete observations in order. The first events can return projection_accumulating. Continue while storage succeeds and inspect the projection until it becomes ready.

At query time, omit the target:

{
  "session_id": "ignored",
  "question": "Predict the process output.",
  "context": {
    "values": {
      "process": {
        "temperature": 30,
        "pressure": 1.2
      }
    }
  },
  "return_fields": ["transition_prediction", "learning_state"],
  "update_memory_state": false,
  "allow_exploration": false
}

Verify:

learning_state.subsystems.structured_transition.autonomous_projection.status == "ready"
learning_state.subsystems.structured_transition.autonomous_projection.input_source == "discovered"
transition_prediction.status == "predicted"
transition_prediction.support_count >= required_support

Categorical

Use a categorical target when labels have no numeric geometry.

{
  "domain_id": "case-disposition-demo",
  "session_id": "ignored",
  "description": "Predict case disposition from stable observed fields.",
  "schema": {
    "event_types": ["resolved_case"]
  },
  "learning": {
    "enabled": true,
    "transition": {
      "enabled": true,
      "event_types": ["resolved_case"],
      "targets": [
        {
          "path": "values.case.disposition",
          "type": "categorical"
        }
      ],
      "required_support": 3,
      "discrete_model": "auto",
      "autonomous_projection": {
        "enabled": true,
        "minimum_observations": 4,
        "minimum_availability": 0.9,
        "maximum_input_paths": 12
      }
    }
  }
}

Eligible event:

{
  "session_id": "ignored",
  "event_type": "resolved_case",
  "values": {
    "case": {
      "severity": "high",
      "repeat_count": 3,
      "verified": true,
      "disposition": "review"
    }
  },
  "metadata": {
    "episode_id": "cases-001"
  }
}

Query context omits disposition.

Structure

This Domain lets Adapt-1 inspect eligible scalar fields, evaluate useful combinations and lags, and induce typed target rules.

{
  "domain_id": "case-structure-demo",
  "session_id": "ignored",
  "description": "Discover observable structure associated with case outcomes.",
  "schema": {
    "event_types": ["resolved_case"]
  },
  "learning": {
    "enabled": true,
    "structure": {
      "enabled": true,
      "event_types": ["resolved_case"],
      "feature_paths": [],
      "targets": [
        {
          "path": "values.outcome",
          "type": "categorical"
        }
      ],
      "representation": {
        "enabled": true,
        "maximum_order": 2,
        "maximum_lag": 3,
        "minimum_support": 12,
        "episode_path": "metadata.episode_id"
      }
    }
  }
}

Inspect:

learning_state.subsystems.autonomous_structure.status
learning_state.subsystems.autonomous_structure.representation.selected_paths
learning_state.subsystems.autonomous_structure.representation.active_representations
induced_structure.hypotheses[].conditions
induced_structure.hypotheses[].supporting_memory_ids
induced_structure.hypotheses[].counterevidence_memory_ids

Reviewed fields

A reviewed base surface can remain explicit while representation discovery continues over combinations and lags derived from it.

{
  "domain_id": "reviewed-structure-demo",
  "schema": {
    "event_types": ["resolved_case"]
  },
  "learning": {
    "enabled": true,
    "structure": {
      "enabled": true,
      "event_types": ["resolved_case"],
      "feature_paths": [
        "values.signal_a",
        "values.signal_b"
      ],
      "targets": [
        {
          "path": "values.outcome",
          "type": "categorical"
        }
      ],
      "representation": {
        "enabled": true,
        "maximum_order": 2,
        "maximum_lag": 2,
        "minimum_support": 12,
        "episode_path": "metadata.episode_id"
      }
    }
  }
}

The explicit base paths stay authoritative. Active rules can still update from evidence.

Causal bindings

This pattern keeps the pre-outcome transition inputs explicit while allowing Adapt-1 to discover compatible before/after causal bindings.

{
  "domain_id": "intervention-effect-demo",
  "session_id": "ignored",
  "description": "Learn observable intervention effects from before and after measurements.",
  "schema": {
    "event_types": ["intervention_result"]
  },
  "learning": {
    "enabled": true,
    "transition": {
      "enabled": true,
      "event_types": ["intervention_result"],
      "input_paths": [
        "values.before.temperature",
        "values.before.pressure",
        "values.intervention"
      ],
      "action_path": "values.intervention",
      "targets": [
        {
          "path": "values.after.output",
          "type": "number"
        }
      ],
      "required_support": 3,
      "autonomous_projection": {
        "enabled": true,
        "minimum_observations": 4,
        "discover_causal_bindings": true,
        "minimum_causal_variables": 2
      },
      "causal_graph": {
        "enabled": true,
        "event_types": ["intervention_result"]
      }
    }
  }
}

Each event contains repeated numeric variable names under before and after, plus an intervention string matching one of those variable names. Inspect causal_binding_source, causal_intervention_path, causal_variables, and causal_graph before using the result.

Sequential Discovery

Use Sequential Discovery when actions change later states and later rewards should revise earlier choices.

An opaque-action loop can expose public observation fields and legal actions while leaving their useful action values and action-effect structure for Adapt-1 to form:

1. query current public state
2. execute the selected legal action
3. observe the public next state and native reward
4. return episode ID, step, next state, reward, and terminal status
5. query again from retained Discovery state

Configure learning.sequential.enabled: true with real episode, step, next-state, reward, and terminal paths. Preserve the selected policy and decision_id through execution. Inspect sequential sample counts and selection attribution before claiming that retained state influenced a later action.

See Sequential Discovery for the starting declaration and Sequential learning, advanced for the full policy, reward, training, and evaluation contract.

Executable runner pattern

The following is a zero-start online pattern shared by the Discovery paths. For separate acquisition, run the evidence-formation steps before the declared new-run boundary, then freeze the resulting state or continue adapting according to the protocol:

1. create a unique Domain
2. send eligible events or feedback
3. inspect path-specific admission on every write
4. wait for usable discovered state
5. query, select, or predict
6. return the observable consequence when applicable
7. verify that a later result uses the intended retained state

Use a fresh unique domain_id for an independent rerun. When one reported run starts empty and retains state across its own episodes, later episodes show within-run retention rather than separate acquisition. For held-out frozen evaluation, split entities or episodes before ingestion, form state only on the acquisition partition, record the final learner state and version, stop event and feedback writes, and verify state identity remains unchanged through scoring.

Common setup failures

Symptom	Cause	Correction
Domain creation returns 422	Unknown field, missing target, or transition enabled without inputs or projection	Validate the declaration against the current Domain schema
Events store but learner count stays at zero	Projection is still accumulating or the event is missing a target	Inspect learner_eligibility.rejection_reason and missing_paths
Projection stays empty	Too few complete events or candidate fields do not meet availability	Send representative complete events and review observation and availability settings
Query abstains after projection is ready	Query context is missing a discovered path or lacks compatible support	Read input_paths, then send the same pre-target structure in context
Structural learner has samples but no active rule	The current evidence is still insufficient for a supported rule	Inspect representation and induced-structure diagnostics; do not force selection
Sequential feedback stores but no sequential sample appears	Episode, step, next state, reward, terminal status, or policy binding is missing or invalid	Inspect feedback admission and preserve the full sequential tuple
Temporal candidates cross unrelated records	Episode identity is absent or reused across independent sequences	Set metadata.episode_id consistently and start a new episode at each reset
A suspicious field dominates	Identifier, post-outcome value, or target-derived field entered the learner view	Remove it, create a clean Domain, and rerun Discovery and holdout evaluation

Discovery

Understand the Discovery boundary and lifecycle.

Transition Discovery

Review projection fields, revisions, and causal bindings.

Structure Discovery

Review discovered fields, combinations, temporal relationships, and induced rules.

Sequential Discovery

Review ordered feedback, delayed credit, readiness, and action attribution.