Reasoning

Reasoning in Pimsy is a loop, not a single forward pass. The reasoning layer decides what is being asked, what is missing, what approach fits, and whether the result it produced actually satisfies the objective.

The reasoning loop#

  objective
     │
     ▼
  ┌──────────────┐   restate the goal, extract constraints,
  │ COMPREHEND   │   surface ambiguity, define done
  └──────┬───────┘
         ▼
  ┌──────────────┐   split into sub-problems, identify
  │ DECOMPOSE    │   dependencies and unknowns
  └──────┬───────┘
         ▼
  ┌──────────────┐   pick method: derive, retrieve, compute,
  │ SELECT       │   execute, delegate, ask
  └──────┬───────┘
         ▼
  ┌──────────────┐
  │ EXECUTE      │──▶ observation
  └──────┬───────┘
         ▼
  ┌──────────────┐   does the result satisfy the criteria?
  │ INSPECT      │   is the evidence sufficient?
  └──────┬───────┘
         │ no ──────────────▶ revise (back to DECOMPOSE)
         │ yes
         ▼
      result

Deliberation modes#

Not every request deserves the same amount of thinking. The runtime selects a deliberation mode from task complexity, risk class and budget, and callers may pin it explicitly.

await pimsy.tasks.create({
  objective: class="tok-str">"Assess whether this migration plan can run with zero downtime.",
  reasoning: { mode: class="tok-str">"adversarial", maxBranches: class="tok-num">3 },
  capabilities: [class="tok-str">"research.web", class="tok-str">"files.read"]
});

Handling ambiguity#

Silently guessing an interpretation is the most common failure mode of agent systems. Pimsy scores interpretation ambiguity during comprehension and branches on the result.

1. 1Ambiguity below threshold: proceed, and record the chosen interpretation in the trace.
2. 2Ambiguity above threshold with a cheap probe available: resolve it by investigation — read the repository, check the schema, sample the data.
3. 3Ambiguity above threshold with no cheap probe: emit a clarification.requested event and pause. See Human-in-the-Loop.

Long-context work#

Long inputs are treated as a retrieval problem rather than a context-window problem. Large corpora are segmented, indexed into working memory, and pulled in per step with provenance, so a 400-document review does not degrade into a lossy summary of summaries.

Related#