Tractatus Framework

AI governance framework enforcing architectural safety constraints at runtime

📚 Full Documentation | 📋 Changelog | 🔒 Security Policy

---

Overview

The Tractatus Framework provides six core services that work together to prevent AI failures by:

• ✅ Enforcing architectural boundaries for human judgment
• ✅ Validating actions against explicit instructions
• ✅ Preventing cached patterns from overriding explicit rules
• ✅ Monitoring context pressure and triggering safety protocols
• ✅ Ensuring value pluralism in multi-stakeholder decisions

Current Release: v3.5.0 (Release Notes)

---

Quick Start

Using Docker (Recommended)

# Clone the repository
git clone https://github.com/AgenticGovernance/tractatus-framework.git
cd tractatus-framework

# Start with Docker Compose
cd deployment-quickstart
docker-compose up

# Access the API
curl http://localhost:9000/api

Manual Installation

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your MongoDB connection string

# Start the server
npm start

Run Tests

npm test

---

Core Services

The framework provides six governance services:

Service	Purpose	File
InstructionPersistenceClassifier	Classifies instructions by quadrant (STRATEGIC/OPERATIONAL/TACTICAL/SYSTEM/STORAGE) and time-persistence	src/services/InstructionPersistenceClassifier.service.js
CrossReferenceValidator	Validates actions against explicit instructions to prevent cached pattern overrides	src/services/CrossReferenceValidator.service.js
BoundaryEnforcer	Enforces Tractatus boundaries ensuring values decisions require human judgment	src/services/BoundaryEnforcer.service.js
ContextPressureMonitor	Monitors token usage and context pressure, triggering safety protocols at thresholds	src/services/ContextPressureMonitor.service.js
MetacognitiveVerifier	Verifies action reasoning and confidence, requiring confirmation for low-confidence actions	src/services/MetacognitiveVerifier.service.js
PluralisticDeliberationOrchestrator	Manages multi-stakeholder deliberation ensuring value pluralism in decisions	src/services/PluralisticDeliberationOrchestrator.service.js

Support Services

• AnthropicMemoryClient - Anthropic Memory API integration
• MemoryProxy - Hybrid MongoDB + Memory API storage
• RuleOptimizer - Rule conflict detection and optimization
• VariableSubstitution - Dynamic variable replacement

---

Basic Usage

1. Initialize Services

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

// Services initialize automatically
const classifier = new InstructionPersistenceClassifier();
const validator = new CrossReferenceValidator();
const enforcer = new BoundaryEnforcer();
const monitor = new ContextPressureMonitor();
const verifier = new MetacognitiveVerifier();

2. Classify Instructions

const classification = await 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({
  action: {
    type: 'database_config',
    proposedPort: 27017
  },
  instructions: [
    { text: "Always use MongoDB on port 27027", persistence: "HIGH" }
  ]
});

// Returns: { valid: false, conflicts: [...], ... }

4. Enforce Boundaries

const decision = {
  type: 'modify_values_content',
  description: 'Update ethical guidelines',
  context: { /* ... */ }
};

const result = await enforcer.enforce(decision);

// Returns: { allowed: false, requires_human: true, boundary: "12.3", ... }

5. Monitor Context Pressure

const pressure = await monitor.analyzePressure({
  currentTokens: 150000,
  maxTokens: 200000,
  messageCount: 45
});

// Returns: { level: "HIGH", score: 75, shouldReduce: true, ... }

---

API Documentation

The framework provides RESTful APIs for integration:

• Rules API - Governance rule management (CRUD, search)
• Projects API - Multi-project configuration
• OpenAPI Specification - Complete API spec (OpenAPI 3.0)

API Endpoints

/api/governance     - Framework operations (status, classify, validate, enforce)
/api/rules          - Governance rules CRUD operations
/api/projects       - Project configuration management
/api/audit          - System audit trail and statistics

Code Examples

• JavaScript Examples
• Python Examples

---

Deployment

Docker Deployment (Recommended)

The quickest way to deploy the framework:

cd deployment-quickstart
docker-compose up -d

See deployment-quickstart/README.md for details.

Troubleshooting: deployment-quickstart/TROUBLESHOOTING.md

Requirements

• Node.js: 18+ (20+ recommended)
• MongoDB: 7.0+
• Docker: 20+ (for containerized deployment)
• Memory: 2GB+ recommended

Environment Configuration

cp .env.example .env

Edit .env with your settings:

• MONGODB_URI - MongoDB connection string
• PORT - Server port (default: 9000)
• NODE_ENV - Environment (development/production)

---

Architecture

Diagrams

• Main Framework Flow - How services interact
• Decision Tree - Trigger conditions

Key Concepts

Governance Quadrants:

• STRATEGIC - Long-term vision and values
• OPERATIONAL - Day-to-day operations
• TACTICAL - Short-term decisions
• SYSTEM - Technical configuration
• STORAGE - Data persistence

Persistence Levels:

• HIGH - Permanent, overrides all
• MEDIUM - Session-scoped
• LOW - Temporary, can be superseded

Tractatus Boundaries (12.1-12.7):

• Prevent AI from making value-laden decisions
• Ensure human judgment for ethical choices
• Architectural constraints enforced at runtime

---

Testing

# Run all tests
npm test

# Run specific suites
npm test -- tests/unit/
npm test -- tests/integration/

# Watch mode (development)
npm test -- --watch

Test Coverage:

• 8 unit tests (all core services)
• 9 integration tests (full framework, APIs, MongoDB)
• Test helpers and fixtures included

---

Database Models

The framework uses MongoDB with 9 models:

Core Models:

• GovernanceRule - Governance instructions
• Project - Project configurations
• SessionState - Session tracking
• VariableValue - Dynamic variables

Logging Models:

• AuditLog - System audit trail
• GovernanceLog - Governance actions
• VerificationLog - Verification results

Deliberation Models:

• DeliberationSession - Multi-stakeholder sessions
• Precedent - Decision precedents

---

Security

Security Policy: See SECURITY.md for vulnerability reporting.

Built-in Security Features:

• Rate limiting (configurable per endpoint)
• Input validation middleware
• Security headers (Helmet + custom CSP)
• Error sanitization (no stack traces in production)
• CORS configuration
• MongoDB connection security

Report vulnerabilities to: security@agenticgovernance.digital

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Key areas for contribution:

• Testing framework components
• Expanding governance rule library
• Documentation improvements
• Bug fixes and performance optimizations
• Integration examples

Before contributing:

1. Read the Code of Conduct
2. Check existing issues
3. Review contributing guidelines

---

Changelog

See CHANGELOG.md for release history and upgrade notes.

Current Version: v3.5.0 (Initial Public Release - 2025-10-21)

---

Support

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

---

License

Apache License 2.0 - See LICENSE for details.

Copyright 2025 Agentic Governance Project

---

Citation

If you use this framework in your research or project, please cite:

@software{tractatus_framework,
  title = {Tractatus Framework: AI Governance Through Architectural Constraints},
  author = {Agentic Governance Project},
  year = {2025},
  version = {3.5.0},
  url = {https://github.com/AgenticGovernance/tractatus-framework},
  note = {Release v3.5.0}
}

---

Last Updated: 2025-10-21 | Status: ✅ Production Ready