Cosinia JSON Protocol

This document defines the formal JSON contract for interacting with Cosinia. It is intended for advanced developers using the API directly.

Use this if you want full semantic control. For simpler usage, see the SDK.

← Back to Developers

Top-Level Contract

All requests must follow this structure.

{
  "mode": "observe" | "recall",
  "world_id": "string",
  "trace": {
    "client_trace_id": "string (optional)"
  },
  "events": [ ... ],        // required for observe
  "query": { ... },        // optional for recall
  "extensions": { ... }    // optional
}

Observe — Minimum

Simple ingestion of semantic events.

{
  "mode": "observe",
  "world_id": "worldX",
  "events": [
    {
      "process": "own",
      "participants": [
        { "entity": "Ray" },
        { "entity": "house" }
      ]
    }
  ]
}

Observe — Extended

Full semantic control including roles, conditions, and assertions.

{
  "mode": "observe",
  "world_id": "worldX",
  "trace": {
    "client_trace_id": "req-123"
  },
  "events": [
    {
      "event_ref": "optional-id",
      "process": "transformation",
      "process_family": "TRANSFORMATION",
      "participants": [
        { "entity": "water", "role": "reactant" },
        { "entity": "steam", "role": "product" }
      ],
      "conditions": [
        {
          "type": "quantitative",
          "subtype": "temperature",
          "operator": "at",
          "value": 100,
          "unit": "C",
          "anchor": "event"
        }
      ],
      "context": {
        "temperature": ["100 C"]
      },
      "assertion": {
        "mode": "assert",
        "polarity": "positive",
        "epistemic_weight": 1.0
      }
    }
  ]
}

Recall — Minimum

Basic recall by process.

{
  "mode": "recall",
  "world_id": "worldX",
  "query": {
    "process": "own"
  }
}

Recall — Extended

Advanced recall using roles, conditions, and target selection.

{
  "mode": "recall",
  "world_id": "worldX",
  "query": {
    "process": "transformation",
    "roles": {
      "reactant": ["water"]
    },
    "conditions": [
      {
        "type": "quantitative",
        "subtype": "temperature",
        "operator": "at",
        "value": 100,
        "unit": "C"
      }
    ],
    "target_role": "product"
  }
}

Validation Rules

Requests must satisfy the following constraints:

{
  "rules": [
    "mode must be 'observe' or 'recall'",
    "world_id is REQUIRED",
    "events REQUIRED for observe",
    "query is recommended for recall (empty query returns broad results)"
  ]
}

Forbidden Fields

These fields are reserved for the Cosinia engine and must NOT be provided by clients.

{
  "forbidden": [
    "context_fields",
    "canonical_hash",
    "trace_id",
    "sequence_index",
    "identity_candidates",
    "relational_candidates"
  ]
}

Response Format

Cosinia returns structured semantic results with computed belief.

{
  "relations": [
    {
      "subject": "ray",
      "relation": "own",
      "object": "house",
      "confidence": 0.99
    }
  ],
  "belief": {
    "value": true,
    "confidence": 0.99,
    "stability": 1
  }
}

Concept Model

Cosinia operates on structured semantic primitives.

{
  "process": "what happened",
  "participants": "entities involved",
  "conditions": "constraints of event",
  "belief": "computed truth from observations"
}

Unlike vector databases, Cosinia preserves meaning deterministically.