POST /learn/{pid} — submit semantic label corrections - NSP

The /learn endpoint lets you feed corrections back into the NSP semantic engine. When the engine mislabels a state key — or surfaces it as an opaque unknown_0x... identifier — you can submit the correct label, type, and an optional note explaining the mapping. The daemon stores each correction in the per-application schema registry and applies it starting with the next probe cycle. Over time, a well-corrected schema reaches near-perfect confidence and produces cleaner, more predictable state maps for your agents.

Endpoint

POST /substrate/v1/learn/{pid}
X-Substrate-Key: <key>
Content-Type: application/json

Rate limit: 10 requests per second.

Parameters

pid

integer

required

The OS process ID of the application whose schema you are correcting. Obtain this from GET /apps.

Request Fields

capture_id

string

required

The capture_id of the state snapshot on which you observed the keys you are correcting. This ties each correction to a specific point in time, which helps the semantic engine understand the runtime context of the correction.

corrections

array

required

Array of label correction objects. Each object describes one key mapping to fix.

Show Correction object fields

corrections[].observed_key

string

required

The key as it currently appears in the objects map — this may be an opaque identifier like "unknown_0x4a2f", a misnamed label like "mail.count_b", or a correctly named but wrongly typed key.

corrections[].correct_label

string

required

The correct dot-notation label you want this key to have in future snapshots, e.g. "inbox.unread_count". Use the same naming conventions as the existing keys in the objects map.

corrections[].correct_type

string

required

The correct JSON type for this field. One of: "number", "string", "boolean", "object", or "array".

corrections[].confidence

float

Your confidence that this correction is accurate, from 0.0 to 1.0. The semantic engine weights corrections by this value when merging them with its internal model. Defaults to 1.0 if omitted.

corrections[].notes

string

Optional free-text description of why this correction is correct, e.g. "This field always matches the unread badge count visible in the browser tab title". Notes are stored in the schema registry and visible in the developer console.

feedback_type

string

default:"label_correction"

Category of feedback being submitted. One of:

Value	Meaning
`label_correction`	Relabeling an existing or unknown key
`type_correction`	Fixing the inferred type of a correctly labeled key
`action_correction`	Correcting the mapping of an action to its underlying runtime method

schema_version

string

required

The schema_version value from the SubstrateState that contained the keys you are correcting. This prevents stale corrections from being applied on top of a newer schema version.

Response Fields

accepted

integer

required

Number of corrections successfully applied to the schema registry.

rejected

integer

required

Number of corrections rejected. Corrections are rejected when the observed_key no longer exists in the current schema, the schema_version does not match the current version, or the correct_label conflicts with an already-confirmed key.

new_schema_version

string

required

The schema version after applying all accepted corrections. If any corrections were accepted, this will be higher than the version you submitted.

message

string

required

Human-readable summary of the result, e.g. "2 corrections applied. Schema updated to 1.4.4.".

Examples

curl -X POST http://127.0.0.1:7842/substrate/v1/learn/12847 \
  -H "X-Substrate-Key: sk_nsp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "capture_id": "0196f4a2-3b5c-7d00-8e1f-9a0b2c3d4e5f",
    "schema_version": "1.4.2",
    "feedback_type": "label_correction",
    "corrections": [
      {
        "observed_key": "unknown_0x4a2f",
        "correct_label": "inbox.unread_count",
        "correct_type": "number",
        "confidence": 0.95,
        "notes": "This field always matches the unread badge count in the tab title"
      },
      {
        "observed_key": "mail.count_b",
        "correct_label": "inbox.total_count",
        "correct_type": "number",
        "confidence": 0.90
      }
    ]
  }'

from nelieo import NspClient

client = NspClient(api_key="sk_nsp_...", base_url="http://127.0.0.1:7842")
session = await client.attach("Gmail")

state = await session.refresh()

result = await client.learn(
    pid=session.pid,
    capture_id=state.capture_id,
    schema_version=state.schema_version,
    feedback_type="label_correction",
    corrections=[
        {
            "observed_key": "unknown_0x4a2f",
            "correct_label": "inbox.unread_count",
            "correct_type": "number",
            "confidence": 0.95,
            "notes": "Matches the unread badge count visible in the tab title",
        },
    ],
)

print(f"Accepted: {result.accepted}")
print(f"New schema version: {result.new_schema_version}")

Example Response

{
  "accepted": 2,
  "rejected": 0,
  "new_schema_version": "1.4.4",
  "message": "2 corrections applied. Schema updated to 1.4.4."
}

When to Use This Endpoint

Unknown keys — The semantic engine surfaces opaque identifiers like unknown_0x4a2f when it cannot confidently label a heap object. If you can identify what the field represents by correlating it with visible application data, submit a correction to name it permanently. Type mismatches — If a field you expect to be a number is typed as a string (or vice versa), submit a type_correction. Wrong types break numeric comparison expressions in /verify and /action. Action mapping errors — If an action in the schema is triggering the wrong runtime method, submit an action_correction with the correct method binding. Improving confidence — A confidence score below 0.85 on GET /apps indicates the semantic engine is uncertain about some labels. Submitting corrections for the uncertain keys is the fastest way to raise confidence to >0.95.

Corrections take effect on the next probe cycle, which runs within 2 seconds by default. The schema version is bumped on every accepted correction — update any cached schema references in your agent after calling /learn.

Endpoints

Data Models

POST /learn/{pid} — submit semantic label corrections

Endpoint

Parameters

Request Fields

Response Fields

Examples

Example Response

When to Use This Endpoint

​Endpoint

​Parameters

​Request Fields

​Response Fields

​Examples

​Example Response

​When to Use This Endpoint

Endpoint

Parameters

Request Fields

Response Fields

Examples

Example Response

When to Use This Endpoint