Operate stateful and adaptive workflows

Keep ordered, stateful Adapt-1 workflows isolated, retryable, and auditable.

Stateful integrations need explicit isolation, ordering, stable identifiers, and careful retry behavior.

Recommended metadata

Use stable identifiers on event and feedback writes when the request schema accepts metadata:

{
  "metadata": {
    "run_id": "run1",
    "trial_id": "run1-trial-001",
    "event_id": "run1-event-001",
    "relation": "in_front_of",
    "policy": "footprint_edge_projection"
  }
}

run_id isolates a workflow, trial_id identifies one outcome unit, and event_id identifies one logical write. Relation and policy fields keep feedback scoped when that workflow uses them.

Online-policy ordering

For Adaptive Policies:

one writer
fresh domain_id
POST /api/v1/domains/{domain_id}/adapt/reset before replay
ordered observations
checkpointed responses

Concurrent workers against the same domain/session can interleave observations and change the result.

Do not reset state between interactions that share learning. Reset policy state only for a new state history or a rebuild from a known record. Record each reset in the application log.

Retryable failures

Handle 429, 502, 503, and 504 as transient. Use exponential backoff with jitter and a bounded retry count.

0.5s -> 1s -> 2s -> 4s -> 8s maximum

Do not automatically retry 400, 401, 403, 404, or 422; correct the request first.

Ambiguous writes

A gateway failure can occur after an upstream write was accepted. Until a route explicitly documents idempotency, treat failed event and feedback writes as ambiguous:

1. Send stable run_id and event/trial identifiers.
2. Check the available state or audit response before resubmitting when a duplicate would affect the result.
3. Checkpoint the last confirmed identifier.
4. Resume from the last confirmed write.

POST /api/v1/domains/{domain_id}/adapt/predict reads current adaptive state without adding an observation and can be repeated safely according to its documented contract.

Read-only state inspection

A route name does not specify if the route changes state. Use the documented state-change contract for the selected endpoint.

If the route supports allow_exploration and update_memory_state, set both fields to false. Record the learner-state hash and applicable versions before the calls. Compare the values after the calls. The values must not change.

The two fields control different functions. allow_exploration: false does not prevent state updates.

Store the complete response and the required query context. If a query changes a learner version, stop the inspection. Identify the endpoint or process that changed the version.

Reset and clear

Operation	Evidence	Policy/context	Transition	Structural	Adaptive interval	Definition
POST https://rei-neuroadapt-api.reilabs.org/api/v1/memory/clear	clears caller memory and memory indexes	retained	retained	retained	retained	retained
POST https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}/clear	clears that Domain’s evidence	retained	retained	retained	retained	retained
POST https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}/policy/reset	retained	cleared	retained	retained	retained	retained
POST https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}/adapt/reset	retained	retained	retained	retained	configurable	retained
DELETE https://rei-neuroadapt-api.reilabs.org/api/v1/domains/{domain_id}	clears Domain evidence	cleared	cleared	cleared	cleared	deleted

Choose the route that owns the intended state boundary. For a completely cold Domain evaluation, delete and recreate the Domain; also clear memory if the same identity holds unrelated test memories.

Production integration checklist

• Keep API keys server-side and use canonical /api/v1 routes.
• Persist memory IDs and sealed Domain decision IDs when later correction, deletion, feedback, or historical explanation is required.
• Set update_memory_state: false for read-only evaluation and replay.
• Check learner eligibility and abstention fields instead of assuming every stored event trained a learner.
• Use the dedicated adaptive routes for adaptive output and validate Vision grounding before acting on a point.
• Record every reset boundary and choose its scope deliberately.