Get Started with R-Think

1. What You Will Build

By the end of this guide, you will have a running mission that observes input, validates claims, registers artifacts, creates evidence, and stores the complete trace for replay. You do not need prior experience with runtime frameworks.

2. Requirements

• Node.js 18.0 or higher
• npm 9.0 or higher
• TypeScript 5.0 or higher (recommended)

3. Installation

Install the R-Think runtime package. The package includes the core engine, protocol definitions, state machine, and validation rules.

npm install @r-think/core

4. Project Setup

Create a new project directory and initialize it.

mkdir my-rthink-mission
cd my-rthink-mission
npm init -y
npm install @r-think/core

5. First Mission Contract

A mission contract defines the mission identifier, the protocol steps, and the validation rules. Create mission-contract.ts:

import { Runtime, Protocol, Rule } from '@r-think/core';

const mission = Runtime.create({
  id: 'hello-reasoning',
  protocol: Protocol.sequential,
  rules: [
    Rule.required('observation'),
    Rule.type('observation', 'string'),
    Rule.minLength('observation', 1)
  ]
});

Expected output: A configured runtime instance with id, protocol, and rules. No execution has occurred yet.

6. Run the Cognitive State Machine

Execute the mission with input. The runtime moves the mission through the cognitive cycle, applies rules, and returns a structured result.

const result = await mission.execute({
  observation: 'Service latency increased by 300ms after deployment'
});

console.log(result.output);      // Final cognitive output
console.log(result.validated);    // true
console.log(result.trace.id);     // trace identifier
console.log(result.trace.steps);  // Array of step objects

// Error handling: missing required field
try {
  await mission.execute({});
} catch (error) {
  console.log(error.code);        // 'RuleViolation'
  console.log(error.field);       // 'observation'
  console.log(error.message);     // 'observation is required'
}

7. Register an Artifact

Artifacts are persistent records produced by reasoning execution. Configure artifact capture in the runtime so every step produces traceable output.

import { Runtime, Protocol, Rule, Artifact } from '@r-think/core';

const mission = Runtime.create({
  id: 'artifact-mission',
  protocol: Protocol.sequential,
  rules: [Rule.required('observation')],
  artifacts: [
    Artifact.trace({ includeInput: true, includeOutput: true }),
    Artifact.evidence({ store: 'local' }),
    Artifact.metrics({ includeTiming: true })
  ]
});

const result = await mission.execute({ observation: 'Latency spike detected' });

console.log(result.trace.steps.length); // step count
console.log(result.trace.steps[0].name); // first step name

Expected output: result.trace.steps includes the full execution record. Evidence and metrics are attached to each step.

8. Create Evidence

Evidence links claims to their supporting data. Build an evidence graph during the mission to keep reasoning auditable.

import { EvidenceGraph, Artifact } from '@r-think/core';

const evidence = new EvidenceGraph();

evidence.addSource({ id: 'src-1', type: 'sensor', reference: 'sensor-latency-01' });
evidence.addObservation({ id: 'obs-1', sourceId: 'src-1', claim: 'Latency exceeded threshold' });
evidence.addEvidence({ id: 'ev-1', observationId: 'obs-1', artifact: 'trace-001', confidence: 'high' });
evidence.addDecision({ id: 'dec-1', evidenceIds: ['ev-1'], authority: 'mission-operator', result: 'rollback-triggered' });

console.log(evidence.toGraph());
// { nodes: [...], edges: [...] }

Expected output: A graph object with nodes for source, observation, evidence, and decision. Contradictions are surfaced as explicit nodes that can trigger Challenge, Retry, or Evolution.

9. Inspect the Mission

Use the Inspector to review mission timeline, evidence graph, artifacts, authority records, and replay data. The Inspector is read-only and never mutates runtime state.

import { Inspector } from '@r-think/inspector';

const inspector = new Inspector({ source: 'local' });

const missionView = await inspector.inspect(result.trace.id);
console.log(missionView.timeline);
// [ { step: 1, state: 'OBSERVE', durationMs: 12 }, ... ]

console.log(missionView.evidenceGraph.nodes);
// source, observation, claim, evidence, decision nodes

await inspector.replay(result.trace.id);
// Replays the mission step-by-step from persisted history

Expected output: A structured view of the mission timeline and evidence graph. Replay executes the mission history without side effects.

10. Next Steps

You have installed R-Think, created a mission contract, executed a cognitive process, registered artifacts, built an evidence graph, and inspected the mission. To go deeper:

• Explore the Concepts page for the canonical algorithm and cognitive states.
• Read the Runtime documentation for state machine and transition rules.
• Review Examples for L0 through L3 missions and advanced patterns.
• Visit API Reference for complete interface definitions.