tractatus/README.md

Tractatus Framework

AI governance framework enforcing architectural safety constraints at runtime

For background, research, and detailed documentation, see https://agenticgovernance.digital

---

Quick Start

Prerequisites

• Node.js 18+
• MongoDB 7+
• npm or yarn

Installation

git clone https://github.com/AgenticGovernance/tractatus-framework.git
cd tractatus-framework
npm install

Configuration

cp .env.example .env
# Edit .env with your MongoDB connection details

Initialize Database

npm run init:db

Run Tests

npm test

Start Development Server

npm run dev
# Server runs on port 9000

---

Core Services

The framework provides six governance services:

Service	Purpose
InstructionPersistenceClassifier	Categorizes instructions by persistence level (HIGH/MEDIUM/LOW) and quadrant (STRATEGIC/OPERATIONAL/TACTICAL/SYSTEM/STOCHASTIC)
CrossReferenceValidator	Validates AI actions against stored instruction history to prevent override
BoundaryEnforcer	Blocks AI from making decisions requiring human judgment
ContextPressureMonitor	Tracks context window usage and triggers pressure management
MetacognitiveVerifier	Validates AI reasoning against governance rules
PluralisticDeliberationOrchestrator	Manages multi-stakeholder deliberation processes

---

Basic Usage

1. Initialize Services

const {
  InstructionPersistenceClassifier,
  CrossReferenceValidator,
  BoundaryEnforcer,
  ContextPressureMonitor
} = require('./src/services');

const classifier = new InstructionPersistenceClassifier();
const validator = new CrossReferenceValidator();
const enforcer = new BoundaryEnforcer();
const monitor = new ContextPressureMonitor();

2. Classify Instructions

const classification = classifier.classify({
  text: "Always use MongoDB on port 27027",
  source: "user",
  context: "explicit_configuration"
});

// Returns: { quadrant: "SYSTEM", persistence: "HIGH", ... }

3. Validate Actions

const validation = await validator.validate({
  type: 'database_config',
  proposedPort: 27017,
  storedInstruction: { port: 27027 }
});

// Returns: REJECTED if action conflicts with instructions

4. Enforce Boundaries

const decision = {
  type: 'modify_values_content',
  description: 'Update ethical guidelines'
};

const result = enforcer.enforce(decision);

// Returns: { allowed: false, requires_human: true, ... }

---

API Documentation

Full API reference: docs/api/

• Rules API - Governance rule management
• Projects API - Project configuration
• OpenAPI Specification - Complete API spec

---

Deployment

Quick Deployment

See deployment-quickstart/ for Docker-based deployment.

cd deployment-quickstart
docker-compose up -d

Production Deployment

• systemd service configuration: systemd/
• Environment configuration: .env.example
• Troubleshooting: deployment-quickstart/TROUBLESHOOTING.md

---

Architecture

Architecture decision records: docs/architecture/

• ADR-001: Dual Governance Architecture

Diagrams:

• docs/diagrams/architecture-main-flow.svg
• docs/diagrams/trigger-decision-tree.svg

---

Testing

# Run all tests
npm test

# Run specific suites
npm run test:unit
npm run test:integration
npm run test:security

# Watch mode
npm run test:watch

Test Coverage: 625 passing tests, 108 known failures under investigation

---

Contributing

See CONTRIBUTING.md for contribution guidelines.

Key areas:

• Testing framework components across different LLMs
• Expanding governance rule library
• Improving boundary detection algorithms
• Documentation improvements

---

License

Apache License 2.0 - See LICENSE

---

Contact

• Email: research@agenticgovernance.digital
• Issues: GitHub Issues
• Website: https://agenticgovernance.digital

---

Last Updated: 2025-10-21