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)
[![Tests](https://img.shields.io/badge/Tests-625%20passing-green.svg)](tests/)

For background, research, and detailed documentation, see **[https://agenticgovernance.digital](https://agenticgovernance.digital)**

---

## Quick Start

### Prerequisites

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

### Installation

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

### Configuration

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

### Initialize Database

```bash
npm run init:db
```

### Run Tests

```bash
npm test
```

### Start Development Server

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

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

```javascript
const classification = 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({
  type: 'database_config',
  proposedPort: 27017,
  storedInstruction: { port: 27027 }
});

// Returns: REJECTED if action conflicts with instructions
```

### 4. Enforce Boundaries

```javascript
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/](docs/api/)

- [Rules API](docs/api/RULES_API.md) - Governance rule management
- [Projects API](docs/api/PROJECTS_API.md) - Project configuration
- [OpenAPI Specification](docs/api/openapi.yaml) - Complete API spec

---

## Deployment

### Quick Deployment

See [deployment-quickstart/](deployment-quickstart/) for Docker-based deployment.

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

### Production Deployment

- systemd service configuration: [systemd/](systemd/)
- Environment configuration: [.env.example](.env.example)
- Troubleshooting: [deployment-quickstart/TROUBLESHOOTING.md](deployment-quickstart/TROUBLESHOOTING.md)

---

## Architecture

Architecture decision records: [docs/architecture/](docs/architecture/)

- [ADR-001: Dual Governance Architecture](docs/architecture/ADR-001-dual-governance-architecture.md)

Diagrams:
- [docs/diagrams/architecture-main-flow.svg](docs/diagrams/architecture-main-flow.svg)
- [docs/diagrams/trigger-decision-tree.svg](docs/diagrams/trigger-decision-tree.svg)

---

## Testing

```bash
# 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](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](LICENSE)

---

## Contact

- **Email:** research@agenticgovernance.digital
- **Issues:** [GitHub Issues](https://github.com/AgenticGovernance/tractatus-framework/issues)
- **Website:** [https://agenticgovernance.digital](https://agenticgovernance.digital)

---

**Last Updated:** 2025-10-21