KnightsORT - Role Routing System

    ## Project overview
    
    KnightsORT is a **role routing system** for the Solutions Brewer stack.
    
    It provides executive role definitions (CEO, CFO, CMO, COO), intelligent
    task routing via MindOT (OWL, METROLOGIC, ADVANCED, ENSEMBLE strategies),
    delegation hierarchy, audit logging, and role switching for testing.
    
    ## Overview
    
    KnightsORT is a **role routing system** that provides:
    - Executive role definitions (CEO, CFO, CMO, COO)
    - Intelligent task routing via MindOT (OWL, METROLOGIC, ADVANCED, ENSEMBLE strategies)
    - Delegation hierarchy and audit logging
    - Role switching for testing
    
    ## Features
    
    - **Role Definitions** - Comprehensive role system with permissions, capabilities, and hierarchy
    - **Smart Routing** - Multiple routing strategies (OWL, Metrologic, Advanced, Ensemble)
    - **MindOT Integration** - Data-driven and trend-based decision making
    - **Audit Logging** - Complete task lifecycle tracking
    - **Delegation** - Role-to-role delegation with hierarchy enforcement
    - **CLI Interface** - Command-line tool for managing groups and roles
    
    ## Quick start
    
    ```python
    import kahndor
    from knightsort import Instruct, Logma
    from knightsort.utilities.schema import RoutingStrategy, RoutingDecision
    
    # 1. Load a role decision directly
    role_cfg = kahndor.Instruct("path/to/roles.yaml").select("executives").dikt
    
    # 2. Construct a routing decision
    decision = RoutingDecision(
        role="ceo",
        strategy=RoutingStrategy.ADVANCED,
        score=0.92,
        confidence=0.88,
        rationale="strategic alignment + budget authority",
    )
    
    print(decision.summary())
    # -> Role: ceo (score: 0.92, confidence: 0.88)
    #    Strategy: advanced
    #    Rationale: strategic alignment + budget authority
    ```
    
    ## Installation
    
    ```bash
    # Clone the repository
    git clone https://github.com/solubrew/knightsort.git
    cd knightsort
    
    # Install dependencies
    pip install -e .
    ```
    # Install optional MindOT for advanced routing
    pip install mindot
    ```
    
    ## Architecture
    
    ```
    KnightsORT (Roles & Routing)
    ├── roles/
    │   ├── base.py      # BaseRole abstract class
    │   ├── ceo.py       # CEO role
    │   ├── cfo.py       # CFO role
    │   ├── cmo.py       # CMO role
    │   └── coo.py       # COO role
    ├── router.py        # RoleRouter with MindOT strategies
    ├── switcher.py      # Role switching for testing
    ├── hierarchy.py     # Role hierarchy definitions
    └── audit.py         # Audit logging
    ```
    
    ## ⚠️ IMPORTANT: Scope Limitation
    
    KnightsORT is ONLY responsible for:
    1. **Role definitions** - What each role is, their permissions, capabilities
    2. **Role routing** - Which role should handle a given task
    3. **Delegation** - Can one role delegate to another?
    4. **Metrics** - Track role performance
    
    KnightsORT does NOT handle:
    - ❌ System prompt assembly
    - ❌ Context injection
    - ❌ Memory management
    - ❌ Skills loading
    - ❌ Identity management
    
    Those are LadyOL's responsibilities.
    
    ## Integration with LadyOL
    
    Use `KnightsORTIntegration` from LadyOL to combine role routing with prompt assembly:
    
    ```python
    from ladyol.integration.knightsort import KnightsORTIntegration, create_knightsort_integration
    
    # Create integration
    rt = create_knightsort_integration(
        config_path="../../knightsort/config/routing.yaml",
        mindot_enabled=True
    )
    
    # Route a task
    decision = rt.route_task(
        task_data={"type": "financial_analysis", "priority": "high"},
        context={"user": "alice"}
    )
    print(f"Routed to: {decision.role}")
    
    # Build role-aware prompt
    full_prompt = rt.build_role_aware_prompt(
        base_prompt=ladyol_system_prompt,
        task_context={"type": "budget_approval"}
    )
    ```
    
    ## Available Roles
    
    | Role | Title | Description |
    |------|-------|-------------|
    | CEO | Chief Executive Officer | Strategic vision, final decisions |
    | CFO | Chief Financial Officer | Financial planning, budget |
    | CMO | Chief Marketing Officer | Marketing, communications |
    | COO | Chief Operating Officer | Operations, logistics |
    
    ## Routing Strategies
    
    1. **OWL** - Data-driven suitability scoring
    2. **METROLOGIC** - Trend-based analysis
    3. **ADVANCED** - Combined OWL + Metrologic (default)
    4. **ENSEMBLE** - Voting across all strategies
    
    ## Usage
    
    ```python
    from knightsort import RoleRouter, RoutingStrategy
    from knightsort.knights.knights import get_role, get_all_roles
    
    # Get a specific role
    ceo = get_role("ceo")
    print(ceo.title)  # Chief Executive Officer
    
    # Route a task
    router = RoleRouter(config={"knights": {...}})
    decision = router.route_task(
        task_data={"type": "strategic_decision", "priority": "critical"}
    )
    print(decision.role)  # "ceo"
    print(decision.rationale)
    ```
    
    ## Dependencies
    
    - `mindot` - For intelligent routing (OWL + Metrologic)
    - `pyyaml` - For config files
    
    ## Notes
    
    - KnightsORT roles are designed to work with MindOT for intelligent routing
    - Without MindOT, it falls back to priority-based or round-robin routing
    - Audit logging is optional (enable with `audit_enabled=True`)
    
    ## Development
    
    To set up a development environment and run the test suite locally:
    
    ```bash
    git clone https://github.com/solubrew/knightsort.git
    cd knightsort
    python -m pip install --upgrade pip
    pip install -e ".[dev]"
    pip install pytest
    
    # Run the test suite
    pytest tests/ -v
    
    # Lint (matches CI)
    ruff check knightsort/
    
    # Confirm the package imports cleanly
    python -c "import knightsort; print(knightsort.__version__)"
    
    # Run the CLI
    knightsort status
    ```
    
    Before opening a pull request:
    
    ```bash
    pytest tests/ -v              # all tests pass
    ruff check knightsort/        # no lint errors
    sasquatch analyze -p . --skip-pii-secrets    # audit score >= 90%
    ```
    
    ## License
    
    KnightsORT is licensed under the MIT License. See the [LICENSE](LICENSE.md)
    file for more details.