Causal Reasoning
causal

Validate Edge

Validate a causal edge based on observed outcomes.

When a prediction is made and later verified/falsified, update edge strength:

  • Success: Increase strength (edge was correct)
  • Failure: Decrease strength (edge was wrong)

Uses Bayesian averaging to accumulate evidence:

new_strength = (old_strength * count + adjustment) / (count + 1)

Also tracks validation_count and invalidation_count for meta-analysis:

  • Edges with many validations are reliable
  • Edges with mixed validation are uncertain
  • Completely invalidated edges can be removed

Why This Matters

Causal edges are hypotheses. This endpoint turns them into tested knowledge:

  • Observing outcomes validates predictions
  • Strength gradually approaches ground truth
  • Enables continuous improvement via experience

This is how Ninai learns from the world: discover → predict → observe → validate.

Args: request: Edge ID, success flag, and strength adjustment current_user: Authenticated user db: Database session

Returns: Updated edge with new strength and validation counts

Example: ``` Edge: "user_context → model_accuracy" (strength 0.6) Observed: Accuracy improved 23% when context increased

Request:
{
    "edge_id": "edge_123",
    "success": true,
    "strength_adjustment": 0.25
}

Returns:
{
    "id": "edge_123",
    "strength": 0.725,
    "validation_count": 5,
    "invalidation_count": 1,
    "last_validated_at": "2026-03-02T10:30:00Z"
}
```
post/api/v1/causal/validate

Request

  • The document declares no server URL.
  • Auth: HTTP bearer

Headers

X-API-Keystring nullable

Request body

edge_idstring required
successboolean required

Did the causal prediction hold?

strength_adjustmentnumber

How much to adjust strength

Response

Successful Response

idstring required
strengthnumber required
validation_countinteger required
invalidation_countinteger required
last_validated_atstring date-time required

Changes

No recorded changes to this operation across all 2 revisions of this API.