🧠 ORTHOS

A Locally Sovereign, Replayable, Graph-Executed Cognitive System

Intelligence emerges from traceable structural constraints, not generation

Installation • Documentation • Contributing

---

📋 Overview

ORTHOS is a cognitive architecture that treats language models as fallible sensory organs rather than authorities. Intelligence emerges from traceable structural constraints that ensure every operation can be replayed, validated, and contradicted.

Core Principles

• Traceability: Nothing exists unless it can be traced and replayed
• Structural Intelligence: Intelligence emerges from constraints, not generation
• Deterministic Execution: Same inputs always produce same outputs
• Local Sovereignty: No external API dependencies for core functionality

🏗️ Architecture

ORTHOS is built in four progressive phases:

✅ Phase I: Deterministic Cognitive Kernel

• Typed node system with strict interfaces
• Topological execution with complete trace recording
• Zero external dependencies

✅ Phase II: Claim & Validation Layer

• Structured LLM outputs wrapped in Claim objects
• Structural validation (consistency, redundancy, contradiction)
• Confidence propagation without subjective scoring

✅ Phase III: Reorganization Engine

• Stress monitoring and dynamic graph mutation
• System complexity reduction under pressure
• Adaptive simplification when failing

✅ Phase IV: Persona as Constraint

• Personas define operational boundaries, not content generation
• Local inference enforcement with ethical constraints
• Dynamic persona switching capabilities

🚀 Quick Start

# Clone and setup
git clone <repository-url>
cd orthos

# Install dependencies
npm install

# Start backend development server
npm run dev

# In another terminal, start frontend
cd frontend && npm install && npm start

Visit http://localhost:3000 to access the web interface.

📦 Installation

Prerequisites

• Node.js ≥18.0.0
• npm or pnpm

Backend Setup

npm install
npm run build
npm run dev

Frontend Setup

cd frontend
npm install
npm start

Production Build

# Backend
npm run build

# Frontend
cd frontend && npm run build

💻 Usage

Web Interface

ORTHOS provides a comprehensive web interface with five main modules:

🕸️ Graph Editor

Create and visualize cognitive graphs with typed nodes and directed edges.

🎭 Persona Manager

Select from constraint-based personas that define system boundaries:

• Conservative Analyst: High evidence requirements, strict validation
• Creative Assistant: Moderate constraints for creative tasks
• Minimalist Processor: Resource-efficient with minimal complexity
• Educational Guide: Pedagogical constraints with safety checks

⚡ Execution Interface

Execute cognitive graphs with JSON inputs and view deterministic outputs with complete execution traces.

🔍 Trace Viewer

Explore Cognitive Trace Objects (CTOs) with timeline and graph visualization modes.

📊 Dashboard

Monitor system health, performance metrics, and stress indicators.

Programmatic Usage

import {
  CognitiveGraph,
  DeterministicExecutor,
  OrthosPersonaRegistry
} from 'orthos';

// Create a simple graph
const graph = new CognitiveGraph();
graph.addNode('input', new InputNode('input.v1'));
graph.addNode('process', new ArithmeticNode('add.v1', 'add'));
graph.addNode('output', new OutputNode('output.v1'));

// Execute with persona constraints
const registry = new OrthosPersonaRegistry();
registry.setActivePersona('conservative-analyst');

const executor = new DeterministicExecutor(graph);
const result = await executor.execute({ value: { a: 3, b: 2 } });

console.log(result.outputs); // { value: { a: 3, b: 2, result: 5 } }
console.log(result.trace);   // Complete execution trace

📚 API Reference

Core Classes

Class	Description
DeterministicExecutor	Executes cognitive graphs with full trace recording
CognitiveGraph	Typed directed graph of epistemic operators
OrthosPersonaRegistry	Manages persona constraints and validation
CognitiveTraceObject	Complete execution trace with inputs, outputs, confidence

Key Interfaces

interface CognitiveGraph {
  nodes: Map<string, Node>;
  edges: Edge[];
  entry_points: string[];
  exit_points: string[];
}

interface Persona {
  id: string;
  name: string;
  constraints: PersonaConstraints;
  local_inference_only: boolean;
}

interface CognitiveTraceObject {
  step: number;
  node: string;
  inputs: Record<string, any>;
  outputs: Record<string, any>;
  assumptions: string[];
  confidence: number;
  timestamp: string;
  parent_steps: number[];
}

🔧 Development

Project Structure

orthos/
├── src/
│   ├── kernel/          # Core execution engine
│   ├── nodes/           # Node implementations
│   ├── claims/          # Claim validation system
│   ├── personas/        # Persona constraint system
│   ├── trace/           # Trace recording & replay
│   └── types/           # TypeScript definitions
├── frontend/
│   ├── src/
│   │   ├── pages/       # React application pages
│   │   └── components/  # Reusable UI components
│   └── public/          # Static assets
├── tests/               # Comprehensive test suites
├── examples/            # Usage examples
├── docs/                # Detailed documentation
└── config/              # Configuration files

Development Commands

# Backend
npm run dev              # Development server with hot reload
npm run build           # Production build
npm run test            # Run test suites
npm run typecheck       # TypeScript validation

# Frontend
cd frontend
npm start               # React development server
npm run build          # Production build
npm test               # Component tests

Code Quality

• Zero warnings in static analysis
• 100% test coverage for kernel components
• Comprehensive type annotations
• Clear separation of concerns

🤝 Contributing

We welcome contributions that align with ORTHOS's architectural principles.

Development Guidelines

1. Follow the implementation roadmap - phases must be completed sequentially
2. Maintain determinism - all executions must be replayable
3. Zero external dependencies for core functionality
4. Comprehensive testing - every component needs full coverage
5. Type safety - all code must be fully typed

Quality Gates

• Each phase requires comprehensive testing before proceeding
• Performance benchmarks must be maintained
• Security audit required for production readiness

Prohibited Actions

• Adding autonomy or "cleverness"
• Breaking deterministic execution
• Introducing external API dependencies in core paths
• Adding subjective scoring or "reward models"

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

ORTHOS is built on principles of disciplined cognitive architecture, emphasizing epistemic rigor over computational power. The system survives pressure through simplification rather than complexity.

"Intelligence is not generation. Intelligence is constraint satisfaction under irreversible time."

---

Built with ❤️ for traceable, replayable cognition

📖 Documentation • 🧪 Examples • 🐛 Issues • 💬 Discussions