tractatus/README.md

# Tractatus Framework

**AI governance framework enforcing architectural safety constraints at runtime**

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Release](https://img.shields.io/github/v/release/AgenticGovernance/tractatus-framework)](https://github.com/AgenticGovernance/tractatus-framework/releases)
[![Tests](https://img.shields.io/badge/Tests-17%20passing-green.svg)](tests/)
[![Node](https://img.shields.io/badge/Node.js-18%2B-brightgreen.svg)](https://nodejs.org)
[![MongoDB](https://img.shields.io/badge/MongoDB-7.0%2B-green.svg)](https://www.mongodb.com)

📚 **[Full Documentation](https://agenticgovernance.digital)** | 📋 **[Changelog](CHANGELOG.md)** | 🔒 **[Security Policy](SECURITY.md)**

---

## 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](https://github.com/AgenticGovernance/tractatus-framework/releases/tag/v3.5.0))

---

## Quick Start

### Using Docker (Recommended)

```bash
# 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

```bash
# Install dependencies
npm install

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

# Start the server
npm start
```

### Run Tests

```bash
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](src/services/InstructionPersistenceClassifier.service.js) |
| **CrossReferenceValidator** | Validates actions against explicit instructions to prevent cached pattern overrides | [src/services/CrossReferenceValidator.service.js](src/services/CrossReferenceValidator.service.js) |
| **BoundaryEnforcer** | Enforces Tractatus boundaries ensuring values decisions require human judgment | [src/services/BoundaryEnforcer.service.js](src/services/BoundaryEnforcer.service.js) |
| **ContextPressureMonitor** | Monitors token usage and context pressure, triggering safety protocols at thresholds | [src/services/ContextPressureMonitor.service.js](src/services/ContextPressureMonitor.service.js) |
| **MetacognitiveVerifier** | Verifies action reasoning and confidence, requiring confirmation for low-confidence actions | [src/services/MetacognitiveVerifier.service.js](src/services/MetacognitiveVerifier.service.js) |
| **PluralisticDeliberationOrchestrator** | Manages multi-stakeholder deliberation ensuring value pluralism in decisions | [src/services/PluralisticDeliberationOrchestrator.service.js](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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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](docs/api/RULES_API.md)** - Governance rule management (CRUD, search)
- **[Projects API](docs/api/PROJECTS_API.md)** - Multi-project configuration
- **[OpenAPI Specification](docs/api/openapi.yaml)** - 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](docs/api/examples-javascript.md)
- [Python Examples](docs/api/examples-python.md)

---

## Deployment

### Docker Deployment (Recommended)

The quickest way to deploy the framework:

```bash
cd deployment-quickstart
docker-compose up -d
```

See [deployment-quickstart/README.md](deployment-quickstart/README.md) for details.

**Troubleshooting:** [deployment-quickstart/TROUBLESHOOTING.md](deployment-quickstart/TROUBLESHOOTING.md)

### Requirements

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

### Environment Configuration

```bash
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](docs/diagrams/architecture-main-flow.svg) - How services interact
- [Decision Tree](docs/diagrams/trigger-decision-tree.svg) - 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

```bash
# 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](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](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](CODE_OF_CONDUCT.md)
2. Check existing [issues](https://github.com/AgenticGovernance/tractatus-framework/issues)
3. Review [contributing guidelines](CONTRIBUTING.md)

---

## Changelog

See [CHANGELOG.md](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](https://github.com/AgenticGovernance/tractatus-framework/issues)
- **Discussions:** [GitHub Discussions](https://github.com/AgenticGovernance/tractatus-framework/discussions)
- **Email:** research@agenticgovernance.digital

---

## License

Apache License 2.0 - See [LICENSE](LICENSE) for details.

Copyright 2025 Agentic Governance Project

---

## Citation

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

```bibtex
@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