# 🛡️ Ontology Firewall for AI Agents

[![CI](https://github.com/cloudbadal007/ontology-firewall/workflows/CI/badge.svg)](https://github.com/cloudbadal007/ontology-firewall/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

Production-ready implementation of ontology-grounded AI agent architecture that prevents hallucinations in enterprise systems by adding deterministic validation layers.

📄 **Read the full article:** [The Ontology Firewall on Medium](https://medium.com/@cloudbadal007/the-ontology-firewall-why-enterprise-ai-agents-are-failing-in-production)

## 🎯 Problem Statement

Enterprise AI agents fail in production because LLMs are probabilistic—they predict what's *likely*, not what's *correct*. In high-stakes environments (finance, legal, healthcare), "probably correct" is catastrophic.

**Common Failure Modes:**
- Confusing "Gross Margin" with "Operating Margin" (different formulas)
- Using "Subsidiary" and "Affiliate" interchangeably (legal distinction matters)
- Violating referential integrity in database operations
- Ignoring business rule constraints (negative quantities, invalid dates)

## 💡 Solution

This project implements an **Ontology Firewall**—a semantic validation layer that sits between your AI agent and execution:

```
User Request → Ontology Validator → LLM + Constraints → Verified Action → Execution
```

**Key Benefits:**
- ✅ Prevents category errors (confusing entity types)
- ✅ Enforces business rules (constraints, relationships)
- ✅ Provides audit trails (why was action allowed/denied)
- ✅ Self-healing (adapts when schemas change)
- ✅ Production-ready (typed, tested, documented)

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/cloudbadal007/ontology-firewall.git
cd ontology-firewall

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .
```

### Basic Usage

```python
from ontology_firewall import OntologyValidator, BusinessRules
from ontology_firewall.core.validator import CommonValidators

# Load your ontology
validator = OntologyValidator("ontologies/sales_domain.owl")

# Define business rules
rules = BusinessRules()
rules.add_constraint("Order", "quantity", CommonValidators.positive, "Quantity must be positive")
rules.add_constraint("Order", "discount", CommonValidators.percentage, "Discount must be 0-100%")

# Validate an action
action = {
    "entity_type": "Order",
    "operation": "create",
    "data": {"quantity": 5, "discount": 0.1, "customer_id": "C123"}
}

result = validator.validate(action)
if result.is_valid:
    print("✅ Action allowed:", result.message)
else:
    print("❌ Action denied:", result.violations)
```

## 📚 Examples

### 1. Basic Ontology Creation and Validation
```bash
python examples/01_basic_ontology.py
```
Creates a simple sales ontology and validates basic operations.

### 2. Extract Ontology from Database Schema
```bash
python examples/02_database_schema_extraction.py
```
Automatically generates OWL ontology from existing SQL schema.

### 3. Validation Firewall Pattern
```bash
python examples/03_validation_firewall.py
```
Demonstrates the complete validation pipeline for AI actions.

### 4. MCP Server Setup
```bash
python examples/04_mcp_server_setup.py
```
Exposes ontology to AI agents via Model Context Protocol.

### 5. Complete Workflow
```bash
python examples/05_complete_workflow.py
```
End-to-end example: schema extraction → ontology → MCP → validated agent.

## 🏗️ Architecture

### Three Core Patterns

**1. Validation Firewall**
```python
# Prevents invalid actions before execution
validator.validate(action) → Allow | Deny + Reason
```

**2. Semantic Router**
```python
# Routes requests to appropriate handlers based on ontology
router.route(intent, ontology) → Handler + Context
```

**3. Self-Healing Schema**
```python
# Adapts when database schemas change
schema_monitor.detect_change() → Update Ontology → Notify Agents
```

See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed diagrams and patterns.

## 🧪 Testing

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=src/ontology_firewall --cov-report=html

# Run specific test suite
pytest tests/unit/test_validator.py

# Run integration tests
pytest tests/integration/
```

## 📦 Docker Deployment

```bash
# Build image
docker build -t ontology-firewall .

# Run MCP server
docker run -p 8000:8000 ontology-firewall

# Or use docker-compose
docker-compose up
```

## 🔧 Configuration

Configuration via environment variables:

```bash
export ONTOLOGY_PATH="ontologies/sales_domain.owl"
export MCP_PORT="8000"
export LOG_LEVEL="INFO"
export ENABLE_CACHING="true"
```

Or use `.env` file (see `.env.example`).

## 📖 Documentation

- [Getting Started Guide](docs/GETTING_STARTED.md)
- [Architecture Deep Dive](docs/ARCHITECTURE.md)
- [API Reference](docs/API_REFERENCE.md)
- [Deployment Guide](docs/DEPLOYMENT.md)
- [Examples & Tutorials](docs/EXAMPLES.md)

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

**Ways to contribute:**
- 🐛 Report bugs via [GitHub Issues](https://github.com/cloudbadal007/ontology-firewall/issues)
- 💡 Suggest features or improvements
- 📝 Improve documentation
- 🔧 Submit pull requests

## 🔐 Security

Found a security issue? Please see [SECURITY.md](SECURITY.md) for responsible disclosure.

## 📄 License

This project is licensed under the MIT License - see [LICENSE](LICENSE) file.

## 🙏 Acknowledgments

- Built on [owlready2](https://github.com/pebbie/owlready2) for ontology management
- Inspired by Palantir's AIP ontology-first architecture
- MCP server implementation based on [Model Context Protocol](https://modelcontextprotocol.io/)

## 📚 Related Work

- **Article:** [The Ontology Firewall on Medium](https://medium.com/@cloudbadal007/the-ontology-firewall-why-enterprise-ai-agents-are-failing-in-production)
- **Tutorial:** Power BI to AI Agent in 30 Minutes
- **Analysis:** Microsoft vs Palantir: Two Paths to Enterprise Ontology

## 📊 Benchmarks

| Operation | Without Ontology | With Ontology | Improvement |
|-----------|-----------------|---------------|-------------|
| Error Detection | 45% | 98% | +118% |
| Invalid Actions | 12% | <1% | -92% |
| Debugging Time | 2.5h | 15min | -83% |

See [benchmarks/](benchmarks/) for methodology.

## 🗺️ Roadmap

- [x] Core ontology validation
- [x] MCP server implementation
- [x] Database schema extraction
- [ ] GraphRAG integration
- [ ] Web UI for ontology visualization
- [ ] Pre-built domain ontologies (healthcare, finance, legal)
- [ ] LangChain/LlamaIndex adapters

## 💬 Community

- **Questions?** [Open an issue](https://github.com/cloudbadal007/ontology-firewall/issues)
- **LinkedIn:** [Connect with Pankaj](https://www.linkedin.com/in/pankaj-kumar-551b52a/)
- **Twitter/X:** [@CloudyPankaj](https://x.com/CloudyPankaj)

---

**Built with ❤️ by [Pankaj Kumar](https://github.com/cloudbadal007)**

⭐ Star this repo if you find it useful!