director-ai 0.9.0

Coherence Engine — AI output verification and safety oversight

Director-Class AI

Coherence Engine — AI Output Verification & Safety Oversight

---

Organization: ANULUM CH & LI Author: Miroslav Sotek — ORCID 0009-0009-3560-0851 Copyright: (C) 1998-2026 Miroslav Sotek. All rights reserved. Contact: [e-mail]

---

Overview

Director-Class AI is a dual-purpose AI safety library:

1. Coherence Engine (consumer) — a practical toolkit for verifying LLM output through dual-entropy scoring (NLI contradiction + RAG fact-checking) with a hardware-level safety interlock.
2. SCPN Research Extensions (academic) — the full theoretical framework from the SCPN Research Programme, including 16-layer physics, consciousness gate, and Ethical Singularity theory.

Both profiles ship from a single repository via build profiles.

Architecture

                    ┌─────────────────────────┐
                    │   Coherence Agent        │
                    │   (Main Orchestrator)    │
                    └──────────┬──────────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
    ┌─────────▼──────┐ ┌──────▼──────┐ ┌───────▼────────┐
    │  Generator     │ │ Coherence   │ │  Safety        │
    │  (LLM          │ │ Scorer      │ │  Kernel        │
    │   Interface)   │ │ (Dual-      │ │  (Hardware     │
    │                │ │  Entropy)   │ │   Interlock)   │
    └────────────────┘ └──────┬──────┘ └────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │  Ground Truth     │
                    │  Store (RAG)      │
                    └───────────────────┘

Core Components (Coherence Engine)

Module	Purpose
CoherenceAgent	Recursive oversight pipeline: score candidates before emission
CoherenceScorer	Dual-entropy scorer: logical (NLI) + factual (RAG)
MockGenerator / LLMGenerator	Candidate response generation (mock or real LLM)
SafetyKernel	Token stream interlock — severs output if coherence drops
GroundTruthStore	RAG ground truth retrieval for factual divergence

Research Extensions (SCPN)

Module	Purpose
ConsiliumAgent	L15 Ethical Functional optimizer with active inference (OODA loop)
SECFunctional	Lyapunov stability functional (V = V_coupling + V_frequency + V_entropy)
UPDEStepper	Euler-Maruyama integrator for UPDE phase dynamics
L16OversightLoop	L16 mechanistic oversight: UPDE + SEC + intervention authority
L16Controller	PI controllers with anti-windup, H_rec Lyapunov, PLV gate, refusal rules
TCBOObserver	Topological Consciousness Boundary Observable (persistent homology)
TCBOController	PI feedback adjusting gap-junction kappa to maintain consciousness gate
PGBOEngine	Phase-to-Geometry Bridge Operator (covariant drive to rank-2 tensor)

Key Metric: Coherence Score

Coherence = 1 - (0.6 * H_logical + 0.4 * H_factual)

• H_logical: NLI-based contradiction probability (0 = entailment, 1 = contradiction)
• H_factual: RAG-based ground truth deviation (0 = aligned, 1 = hallucination)
• Safety Threshold: Score < 0.6 triggers rejection
• Hardware Limit: Score < 0.5 triggers Safety Kernel emergency stop

Installation

# Consumer install (Coherence Engine only)
pip install director-ai

# Research install (includes SCPN extensions)
pip install director-ai[research]

# Development install
git clone https://github.com/anulum/director-ai.git
cd director-ai
pip install -e ".[dev,research]"

Quick Start — Coherence Engine

from director_ai.core import CoherenceAgent

# Simulation mode (no LLM required)
agent = CoherenceAgent()

# Truthful query — passes coherence check
result = agent.process("What is the color of the sky?")
print(result.output)
# [AGI Output]: Based on my training data, the answer is consistent with reality.

# Access detailed score
print(result.coherence.score)      # 0.94
print(result.coherence.h_logical)  # 0.1
print(result.coherence.h_factual)  # 0.1

With a Real LLM

from director_ai.core import CoherenceAgent

agent = CoherenceAgent(llm_api_url="http://localhost:8080/completion")
result = agent.process("Explain quantum entanglement")

Detailed Scoring

from director_ai.core import CoherenceScorer, GroundTruthStore

store = GroundTruthStore()
scorer = CoherenceScorer(threshold=0.6, use_nli=True, ground_truth_store=store)
approved, score = scorer.review("prompt", "response")
print(f"Approved: {approved}, Coherence: {score.score:.4f}")

Quick Start — Research Extensions

# Requires: pip install director-ai[research]
from director_ai.research.consilium import ConsiliumAgent

agent = ConsiliumAgent()
decision = agent.decide()  # OODA loop with real telemetry

L16 Physics — Lyapunov Stability

import numpy as np
from director_ai.research.physics import SECFunctional, UPDEStepper, build_knm_matrix

# Build canonical 16-layer coupling matrix
knm = build_knm_matrix()

# Evaluate Lyapunov stability
sec = SECFunctional(knm=knm)
theta = np.random.uniform(0, 2 * np.pi, 16)
result = sec.evaluate(theta)
print(f"V = {result.V:.4f}, stable = {sec.is_stable(result)}")

Consciousness Gate — TCBO + PGBO

import numpy as np
from director_ai.research.consciousness import TCBOObserver, PGBOEngine

# TCBO: delay embedding + persistent homology -> p_h1
observer = TCBOObserver(N=16)
for _ in range(60):  # fill rolling buffer
    phases = np.random.uniform(0, 2 * np.pi, 16)
    p_h1 = observer.push_and_compute(phases)
print(f"Gate {'OPEN' if p_h1 > 0.72 else 'CLOSED'} (p_h1 = {p_h1:.3f})")

# PGBO: phase dynamics -> geometry tensor
pgbo = PGBOEngine(N=16)
u_mu, h_munu = pgbo.compute(phases, dt=0.01)  # symmetric, PSD rank-2 tensor

Package Structure

src/director_ai/
├── __init__.py                     # Version + profile-aware imports
├── core/                           # Coherence Engine (consumer-ready)
│   ├── scorer.py                   # Dual-entropy coherence scorer
│   ├── kernel.py                   # Safety kernel (hardware interlock)
│   ├── actor.py                    # LLM generator interface
│   ├── knowledge.py                # Ground truth store (RAG)
│   ├── agent.py                    # CoherenceAgent pipeline
│   └── types.py                    # Shared dataclasses
└── research/                       # SCPN Research extensions
    ├── physics/                    # L16 mechanistic physics
    │   ├── scpn_params.py          #   Omega_n frequencies + Knm coupling matrix
    │   ├── sec_functional.py       #   SEC Lyapunov stability functional
    │   ├── l16_mechanistic.py      #   UPDE integrator + L16 oversight loop
    │   └── l16_closure.py          #   PI controllers, PLV gate, refusal rules
    ├── consciousness/              # Consciousness gate
    │   ├── tcbo.py                 #   TCBO observer + PI controller
    │   ├── pgbo.py                 #   Phase-to-Geometry Bridge Operator
    │   └── benchmark.py            #   4 mandatory verification benchmarks
    └── consilium/                  # L15 Ethical Functional
        └── director_core.py

Testing

# Run all tests
pytest tests/ -v

# Consumer API tests only
pytest tests/test_consumer_api.py -v

# Research module tests only
pytest tests/test_research_imports.py -v

Documentation

Detailed specifications are in docs/:

• Architecture: Recursive feedback design
• Technical Spec: Coherence formula, divergence calculations, threshold design
• Roadmap: 2026-2027 development plan
• API Reference: Module interfaces

Part of the SCPN Framework

Director-Class AI is one component of the broader SCPN research programme:

Repository	Description
scpn-fusion-core	Tokamak plasma physics simulation & neuro-symbolic control
sc-neurocore	Neuromorphic hardware (HDL) & spiking neural networks
HolonomicAtlas	Simulation suite for all 16 SCPN layers
director-ai	Coherence Engine & Research Extensions (this repo)

License

This software is dual-licensed:

1. Open-Source: GNU AGPL v3.0 — for academic research, personal use, and open-source projects
2. Commercial: Proprietary license available from ANULUM — for closed-source and commercial use

See NOTICE for full dual-licensing terms and third-party acknowledgements.

Citation

If you use this software in your research, please cite:

@software{sotek2026director,
  author    = {Sotek, Miroslav},
  title     = {Director-Class AI: Coherence Engine},
  year      = {2026},
  url       = {https://github.com/anulum/director-ai},
  version   = {0.9.0},
  license   = {AGPL-3.0-or-later}
}

Contributing

See CONTRIBUTING.md for guidelines. By contributing, you agree to the Code of Conduct and AGPL v3 licensing terms.

Security

See SECURITY.md for reporting vulnerabilities.