OmniIntelligence

Intelligence, pattern learning, and code quality analysis as first-class ONEX nodes.

Table of Contents

• Overview
• Prerequisites
• Installation
• Architecture
• Project Structure
• Development
• Testing

Overview

OmniIntelligence is the intelligence platform for the ONEX ecosystem. It provides code quality analysis, ML-based pattern learning, semantic analysis, and Claude Code hook processing — all implemented as declarative ONEX nodes following the thin-shell pattern.

The system is registered as a domain plugin (PluginIntelligence) and discovered at runtime by RuntimeHostProcess from omnibase_infra. Nodes declare their Kafka subscriptions and handler routing in contract.yaml; the runtime wires everything automatically.

For architecture details, invariants, and handler patterns, see CLAUDE.md.

Prerequisites

• Python 3.12+
• uv for dependency management (required — do not use pip or Poetry directly)

Installation

# Core node system + all infrastructure dependencies
uv sync --group core

# Development tools (ruff, mypy, pytest)
uv sync --group dev

# Everything (core + dev)
uv sync --group all

# Install pre-commit hooks
pre-commit install

ONEX ecosystem dependencies (NOT on public PyPI — installed via editable installs from sibling repos or private registry):

Package	Version	Purpose
omnibase-core	>=0.18.0,<0.19.0	Node base classes, protocols, validation
omnibase-spi	>=0.10.0,<0.11.0	Service Provider Interface protocols
omnibase-infra	>=0.8.0,<0.9.0	Kafka, PostgreSQL, runtime infrastructure

Architecture

The system decomposes intelligence operations into 21 specialized ONEX nodes across four types.

Node Inventory

Orchestrators — coordinate multi-step workflows

Node	Purpose
NodeIntelligenceOrchestrator	Main workflow coordination (contract-driven)
NodePatternAssemblerOrchestrator	Pattern assembly from execution traces

Reducer — FSM state management

Node	Purpose
NodeIntelligenceReducer	Unified FSM handler for ingestion, pattern learning, and quality assessment

Compute nodes — pure data processing, no side effects

Node	Purpose
NodeQualityScoringCompute	Code quality scoring with ONEX compliance
NodeSemanticAnalysisCompute	Semantic code analysis
NodePatternExtractionCompute	Extract patterns from code
NodePatternLearningCompute	ML pattern learning pipeline
NodePatternMatchingCompute	Match patterns against code
NodeIntentClassifierCompute	User prompt intent classification
NodeExecutionTraceParserCompute	Parse execution traces
NodeSuccessCriteriaMatcherCompute	Match success criteria against outcomes

Effect nodes — external I/O (Kafka, PostgreSQL)

Node	Purpose
NodeClaudeHookEventEffect	Process Claude Code hook events; emit classified intents to Kafka
NodePatternStorageEffect	Persist patterns to PostgreSQL
NodePatternPromotionEffect	Promote patterns (provisional → validated)
NodePatternDemotionEffect	Demote patterns (validated → deprecated)
NodePatternFeedbackEffect	Record session outcomes and metrics
NodePatternLifecycleEffect	Atomic lifecycle transitions with audit trail
NodePatternLearningEffect	Pattern learning effect (contract-only)
NodeComplianceEvaluateEffect	Evaluate compliance rules against patterns
NodeEnforcementFeedbackEffect	Record enforcement feedback and confidence adjustments
NodePatternComplianceEffect	Pattern compliance assessment pipeline

Runtime Plugin

PluginIntelligence (omniintelligence.runtime.plugin) is the domain plugin entry point registered under onex.domain_plugins. It is discovered by RuntimeHostProcess, which manages the process lifecycle. PluginIntelligence itself scans contract.yaml files (via collect_subscribe_topics_from_contracts()) to wire Kafka subscriptions and handler routing.

API Module

omniintelligence.api exposes HTTP endpoints (FastAPI/uvicorn) for intelligence operations.

Project Structure

src/omniintelligence/
├── nodes/                              # 21 ONEX nodes
│   ├── node_claude_hook_event_effect/
│   ├── node_compliance_evaluate_effect/
│   ├── node_enforcement_feedback_effect/
│   ├── node_execution_trace_parser_compute/
│   ├── node_intelligence_orchestrator/
│   ├── node_intelligence_reducer/
│   ├── node_intent_classifier_compute/
│   ├── node_pattern_assembler_orchestrator/
│   ├── node_pattern_compliance_effect/
│   ├── node_pattern_demotion_effect/
│   ├── node_pattern_extraction_compute/
│   ├── node_pattern_feedback_effect/
│   ├── node_pattern_learning_compute/
│   ├── node_pattern_learning_effect/
│   ├── node_pattern_lifecycle_effect/
│   ├── node_pattern_matching_compute/
│   ├── node_pattern_promotion_effect/
│   ├── node_pattern_storage_effect/
│   ├── node_quality_scoring_compute/
│   ├── node_semantic_analysis_compute/
│   └── node_success_criteria_matcher_compute/
├── runtime/                            # PluginIntelligence, MessageDispatchEngine wiring
├── api/                                # FastAPI HTTP endpoints
├── repositories/                       # Database access layer
├── handlers/                           # Shared handler functions
├── models/                             # Shared Pydantic models
├── enums/                              # Domain enumerations
├── protocols/                          # Protocol interfaces
├── utils/                              # Utilities
├── testing/                            # Shared test helpers and fixtures
├── tools/                              # Internal tooling and scripts
├── audit/                              # Audit and compliance utilities
├── _legacy/                            # Legacy code (do not import)
└── constants.py                        # Module-level constants

tests/
├── audit/                              # I/O purity enforcement (AST analysis)
├── unit/                               # Unit tests (no infrastructure)
│   └── nodes/                          # Primary location for node-specific unit tests (10+ node subdirectories)
├── integration/                        # Integration tests
├── nodes/                              # Legacy/transitional node tests (limited coverage, single entry)
└── fixtures/                           # Shared test data

Each node directory contains:

node_example_compute/
├── contract.yaml        # Declarative: I/O models, handler routing, event bus topics
├── node.py              # Thin shell (~20-50 lines), delegates to handler
├── models/              # Input/output Pydantic models
└── handlers/            # All business logic, error handling, logging

Development

# Lint (includes import sorting)
uv run ruff check src tests

# Auto-fix lint issues
uv run ruff check --fix src tests

# Format
uv run ruff format src tests

# Type check
uv run mypy src

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/omniintelligence --cov-report=html

Testing

uv run pytest tests/unit          # Unit tests (no infrastructure required)
uv run pytest tests/integration   # Integration tests (requires Kafka + PostgreSQL)
uv run pytest -m unit             # Only @pytest.mark.unit tests
uv run pytest -m audit            # I/O purity enforcement
uv run pytest -m "not slow"       # Exclude slow tests
uv run pytest -k "test_name"      # Single test by name

pytest Markers

Marker	Purpose
unit	Fast, isolated unit tests
integration	Tests requiring live infrastructure
slow	Long-running tests
audit	AST-based I/O purity enforcement (network client imports, env var access, file I/O in nodes)
performance	Performance benchmarks

For infrastructure configuration (Kafka, PostgreSQL, remote server topology), see ~/.claude/CLAUDE.md.

---

Copyright © 2024 OmniNode Team