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):

Architecture

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

Node Inventory

Orchestrators — coordinate multi-step workflows

Reducer — FSM state management

Compute nodes — pure data processing, no side effects

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

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

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

Copyright © 2024 OmniNode Team