Passage Analysis — POST /v0/passage

/v0/passage is a stateless, single-author passage analyzer. Where /v0/ingest tracks the semantic telemetry of a conversation turn by turn, /v0/passage reads one passage by one author and returns the shape of the thinking inside it — the trajectory of ideas, the grammar and vocabulary, and a located "core vs noise" reading.

It is a mirror, not a grader. It emits measurements and located patterns, never a quality score or a letter grade. What counts as a "leap," and what to do about a pattern, is a downstream decision for the caller (for example, a teacher or curriculum policy). This is the engine behind Cognitive Leap / Plumb, a reflective-writing instrument for students.

When to use it

• A single reflective paragraph, journal entry, short essay, or memo (best at ~6–15 sentences).
• You want descriptive structure (trajectory, grammar, vocabulary) and/or a core-vs-noise reading.
• You do not want a quality grade — this tool deliberately does not produce one.

Layers

Request any subset via layers. divergence auto-includes the layers it depends on.

Layer	Embeddings	Returns
geometry	1 pass	sentence-to-sentence trajectory: raw angular steps, orbit, 2D path for display
grammar	none	deterministic syntactic structure (sentence types, parse depth, subordination)
lexical	breadth only	diversity (TTR / MTLD), density, frequency bands, concreteness
divergence	1 pass	the two-axis core detector → a located pattern

The two-axis core detector (divergence)

Two orthogonal, model-light axes, both computed from a single embedding pass:

• Content = concreteness (Brysbaert lexicon; model-independent). Does the language touch ground in specific, perceptible referents, or is it abstract fog? Low → hollow.
• Through-line = embedding dispersion. Do the sentences orbit a single context mass, or scatter across unrelated topics? High dispersion → scattered.

Located pattern (advisory; thresholds tunable per use case):

• concreteness < 2.40 → hollow — fluent but abstract / empty
• else clearly dispersed (with enough sentences) → scattered — concrete but no through-line
• else → grounded

The through-line verdict is conservative (high-precision) by design, and is suppressed on very short passages (< 6 sentences) where the signal is unreliable. It detects topical scatter — not logical organization (ordering, transitions, referents, contradictions), which is a separate concern.

Request

{
  "text": "the full passage...",
  "segmentation": "sentence",
  "backend": "nomic",
  "layers": ["geometry", "grammar", "lexical", "divergence"]
}

Response (abridged)

{
  "segments": ["sentence 1", "sentence 2", "..."],
  "geometry": {
    "trajectory_2d": [[0.0, 0.0], [0.12, -0.4]],
    "steps": [{ "seam_index": 1, "step_magnitude_deg": 22.4 }],
    "orbit": { "net_displacement": 0.21, "local_path_length": 1.84, "coneness_R": 0.78 },
    "notes": "geometry is descriptive only — no verdicts"
  },
  "grammar": { "sentence_count": 11, "subordination_ratio": 0.18, "mean_parse_depth": 3.4 },
  "lexical": {
    "type_token_ratio": 0.61, "mtld": 42.3, "lexical_density": 0.49,
    "concreteness": { "available": true, "mean": 2.94 }
  },
  "coherence": {
    "available": true,
    "dispersion": 0.31, "concentration": 0.85,
    "n_segments": 9, "reliable": true, "scattered": false,
    "disp_cut": 0.36, "disp_high": 0.45
  },
  "divergence": {
    "concreteness_mean": 2.94,
    "dispersion": 0.31, "concentration": 0.85,
    "through_line_reliable": true,
    "pattern": "grounded",
    "conc_cut": 2.40, "disp_cut": 0.36
  }
}

Notes

• Stateless. Nothing is stored. Persistence (rosters, history, submissions) is the caller's job.
• steps are raw and unjudged — one entry per sentence seam, no built-in "leap" threshold. Turning steps into leaps is a downstream policy.
• pattern is located, not graded — hollow / scattered / grounded are advisory readings a human interprets, never a mark.
• coherence (through-line) is computed only when divergence is requested, reusing the vectors embedded for geometry (no extra model call).

cURL

curl -X POST https://sdk.aicoevolution.com/v0/passage \
  -H "Content-Type: application/json" \
  -H "X-SDK-API-Key: $SDK_KEY" \
  -d '{"text":"...", "backend":"nomic", "segmentation":"sentence", "layers":["divergence"]}'