Tiger Clause

Django-based insurance policy clause management system with a CEL (Common Expression Language) rules engine for intelligent clause selection and policy document generation.

Overview

Tiger Clause enables insurance underwriters and product managers to:

• Manage a centralized clause library with version control and approval workflows
• Define business rules using CEL for intelligent clause selection based on quote/policy characteristics
• Generate policy documents from reusable templates with automatic clause assembly
• Maintain compliance through audit trails, regulatory reference tracking, and validation

Key Features

Clause Management

• Clause Library: Centralized repository of insurance policy text blocks (coverages, exclusions, conditions, definitions, warranties, endorsements, declarations)
• Version Control: Track all clause versions with only one active version per clause code at a time
• Status Workflow: Draft → Under Review → Approved → Active → Deprecated → Archived
• Hierarchical Categories: Organize clauses into nested categories for easy navigation
• Variable Placeholders: Dynamic {{variable_name}} syntax for policy-specific value substitution
• Dependency Management: Define REQUIRES, CONFLICTS, SUGGESTS, REPLACES, and RELATED relationships between clauses
• Regulatory References: Link clauses to ISO forms, ACORD forms, NCCI forms, state filings, and other regulatory documents
• Jurisdiction Support: Configure clauses for specific states/territories or mark as applicable to ALL

CEL Rules Engine

• Business Rule Definition: Create rules using Common Expression Language (CEL) for readable, maintainable logic
• Rule Types:
  • REQUIREMENT: Clause must be included when condition is met
  • SUGGESTION: Clause should be considered
  • EXCLUSION: Clause cannot be used
  • INCLUSION: Determines when to include a clause
  • VALIDATION: Post-selection validation checks
• Rule Sets: Group rules by line of business, product, or use case
• Priority System: Control rule evaluation order and conflict resolution
• Test Cases: Define test scenarios for each rule to ensure correctness
• Audit Trail: Full logging of rule evaluations for compliance and analytics

Example CEL Expressions:

# Limit-based requirements
limits.occurrence >= 1000000 && territory in ['CA', 'NY']

# Class code filtering
class_code.startsWith('915')

# Complex multi-condition rules
(product == 'GL' && limits.occurrence >= 1000000) || regulatory.state_filing == 'admitted'

Document Templates

• Template Builder: Create reusable document structures with sections that accept specific clause types
• Section-Based Organization: Define sections (Declarations, Coverages, Exclusions, Conditions) with automatic clause routing
• Content Blocks: Add static content (declaration pages, signature blocks, legal boilerplate) at specific positions
• Conditional Inclusion: Use CEL expressions to conditionally include sections or content blocks
• Category Filtering: Route clauses to sections based on both clause type and category

Document Generation

• Multiple Output Formats: Generate documents as PDF, DOCX, or HTML
• Variable Substitution: Automatically replace placeholders with policy-specific values
• Async Generation: Long-running generation tasks handled by Celery workers
• Generation Tracking: Monitor status (Pending, Generating, Completed, Failed) with error details
• Content Integrity: SHA-256 hash verification for generated documents

REST API

Full REST API with OpenAPI documentation:

• /api/docs/ - Interactive Swagger UI
• /api/schema/ - OpenAPI schema

Key Endpoints:

Endpoint	Description
/api/clauses/	Clause CRUD with search, filtering, versioning
/api/categories/	Hierarchical category management
/api/rules/	CEL rule management with test and evaluate actions
/api/rule-sets/	Rule set grouping and membership
/api/templates/	Document template management
/api/documents/	Generated document listing and status
/api/recommendations/	Get clause recommendations for a quote
/api/validations/	Validate clause selection against rules
/api/documents/generate/	Trigger document generation

Technology Stack

• Framework: Django 5.2 with Python 3.13
• Database: PostgreSQL with psycopg[c] driver
• API: Django REST Framework with drf-spectacular (OpenAPI/Swagger)
• Authentication: django-allauth with MFA support
• Task Queue: Celery with Redis broker and django-celery-beat
• Real-time: Django Channels with channels_redis
• Rules Engine: celparser (CEL implementation)
• Document Generation: python-docx, WeasyPrint, ReportLab
• Frontend: django-htmx, Tailwind CSS, crispy-forms
• AI/ML: pydantic-ai-slim[bedrock] for AI integrations

Getting Started

Prerequisites

• Docker and Docker Compose
• just command runner (optional, but recommended)

Quick Start

# Clone the repository
git clone https://github.com/tigerlab/tiger_clause.git
cd tiger_clause

# Build containers
just build
# OR: docker compose -f docker-compose.local.yml build

# Start all services
just up
# OR: docker compose -f docker-compose.local.yml up -d --remove-orphans

# Apply database migrations
just manage migrate

# Create a superuser
just manage createsuperuser

# Load sample data (optional)
just manage load_sample_clauses
just manage load_sample_rules
just manage load_sample_templates

Access the application:

• Web App: http://localhost:8000
• Admin: http://localhost:8000/admin/
• API Docs: http://localhost:8000/api/docs/
• Mailpit (email testing): http://localhost:8025
• Flower (Celery monitoring): http://localhost:5555

Docker Services

Service	Port	Description
django	8000	Main web application
postgres	5432	PostgreSQL database
redis	6379	Cache and Celery broker
celeryworker	-	Async task worker
celerybeat	-	Periodic task scheduler
flower	5555	Celery monitoring UI
mailpit	8025	Local email testing

Development

Common Commands

# Run tests
docker compose -f docker-compose.local.yml run --rm django pytest

# Run tests with coverage
docker compose -f docker-compose.local.yml run --rm django coverage run -m pytest
docker compose -f docker-compose.local.yml run --rm django coverage html

# Type checking
docker compose -f docker-compose.local.yml run --rm django mypy tiger_clause

# Django shell
just manage shell

# View logs
just logs [service]

Code Quality

# Lint and auto-fix with Ruff
uvx ruff check --fix tiger_clause

# Format with Ruff
uvx ruff format tiger_clause

# Lint Django templates
uvx djlint tiger_clause/templates --reformat

# Run pre-commit hooks
uvx pre-commit run --all-files

Creating New Django Apps

just manage startapp app_name
# Then register in LOCAL_APPS in config/settings/base.py

Project Structure

tiger_clause/
├── config/                     # Project configuration
│   ├── settings/              # Environment-specific settings
│   ├── api_router.py          # REST API endpoint registration
│   ├── celery_app.py          # Celery configuration
│   └── urls.py                # Main URL routing
├── tiger_clause/
│   ├── clauses/               # Clause management app
│   │   ├── api/              # REST API views and serializers
│   │   ├── models.py         # Clause, Rule, RuleSet models
│   │   ├── services.py       # CEL rule engine service
│   │   └── management/       # Django management commands
│   ├── documents/             # Document generation app
│   │   ├── api/              # REST API views and serializers
│   │   ├── models.py         # Template, Document models
│   │   ├── services.py       # Document generation service
│   │   └── generation/       # PDF, DOCX, HTML generators
│   ├── users/                 # User authentication
│   ├── templates/             # Django templates
│   └── static/                # Static assets
├── .envs/                     # Environment variable files
├── compose/                   # Docker configuration
└── requirements/              # Python dependencies

API Usage Examples

Get Clause Recommendations

curl -X POST http://localhost:8000/api/recommendations/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "quote-123",
    "line_of_business": "GL",
    "context": {
      "territory": "CA",
      "limits": {"occurrence": 2000000, "aggregate": 4000000},
      "class_code": "91580"
    }
  }'

Validate Clause Selection

curl -X POST http://localhost:8000/api/validations/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "quote-123",
    "line_of_business": "GL",
    "context": {"territory": "CA"},
    "selected_clauses": ["CGL-001", "CGL-002", "CGL-003"]
  }'

Generate Document

curl -X POST http://localhost:8000/api/documents/generate/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "policy-456",
    "template_code": "POLICY-STD",
    "selected_clauses": ["CGL-001", "CGL-002"],
    "variable_context": {
      "insured_name": "Acme Corp",
      "policy_number": "GL-2024-001",
      "effective_date": "2024-01-01"
    },
    "output_formats": ["PDF", "DOCX"]
  }'

Roadmap

Completed

• Phase 1: Core clause management with versioning, categories, and dependencies
• Phase 2: CEL rules engine with rule sets, priority, and audit trails
• Phase 3: Document template builder with sections and content blocks
• Phase 4: Document generation (PDF, DOCX, HTML) with async processing

Planned

• Phase 5: Enhanced AI-powered clause suggestions and conflict detection
• Phase 6: Workflow automation with approval chains and notifications
• Phase 7: Analytics dashboard for rule effectiveness and clause usage
• Phase 8: External system integrations (policy admin, rating engines)
• Phase 9: Multi-tenant support for managing multiple carrier programs
• Phase 10: Advanced document comparison and diff visualization

Configuration

Environment Variables

Environment files are stored in .envs/:

• .envs/.local/.django - Local Django settings
• .envs/.local/.postgres - Local database credentials
• .envs/.production/.django - Production Django settings
• .envs/.production/.postgres - Production database credentials

Key settings:

• DJANGO_SECRET_KEY - Secret key for cryptographic signing
• DJANGO_ALLOWED_HOSTS - Allowed host headers
• DATABASE_URL - PostgreSQL connection string
• REDIS_URL - Redis connection for caching and Celery
• SENTRY_DSN - Sentry error tracking (production)

Deployment

Production Setup

• ASGI Server: uvicorn with gunicorn
• Static Files: WhiteNoise middleware
• Media Storage: django-storages with S3 support
• Email: django-anymail with Amazon SES
• Monitoring: Sentry SDK integration
• Security: Argon2 password hashing, secure headers

See Cookiecutter Django Docker documentation for detailed deployment instructions.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (pytest, ruff check, ruff format)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

Proprietary - All rights reserved.

Support

For issues and feature requests, please use the GitHub Issues page.