NEXUS v3 — Fractal Engineering Mind

Version: 3.0.0
Runtime: Python 3.11+
LLM: Groq (LLaMA 3.3 70B), extensible via ProviderType

NEXUS v3 is a fractal decomposition engine that transforms a problem statement into verified, production-aware component implementations using an LLM. It uses a multi-phase pipeline: fractal decomposition → token-compiled context → LLM execution → composition verification → production intuition scoring.

---

Quick Start

# 1. Install
pip install -e .

# 2. Set your API key
set GROQ_API_KEY=gsk_your_key

# 3. Run the pipeline
nexus run "build a task management API" --report

This single command decomposes the problem into components, implements each via LLM, verifies interface contracts, and scores production readiness.

---

Pipeline Architecture

Problem Statement
       │
       ▼
┌─────────────────┐
│  FractalDecomposer │  4 depth levels (Pattern Match → Research)
│  Depth 1-4       │  LLM-guided decomposition into ComponentNodes
│                  │  with InterfaceContracts (provides/requires/pre/post)
└────────┬────────┘
         │ CompositionTree
         ▼
┌─────────────────┐
│ TCAContextManager │  3-tier context: manifest (150t) + contracts (50t) + impl cache
│                  │  Token-budget-aware, prerequisite-aware
└────────┬────────┘
         │ context string
         ▼
┌─────────────────┐
│ ComponentExecutor│  Iterates execution_order, calls LLM per component
│                  │  crash-safe checkpoint/resume via StateStore
└────────┬────────┘
         │ raw outputs
         ▼
┌─────────────────┐
│CompositionVerifier│  LLM-as-judge for interface contract verification
│                  │  preconditions, postconditions, invariants, integration
└────────┬────────┘
         │ verified outputs
         ▼
┌─────────────────┐
│  Production     │  10 structural rules + LLM semantic analysis
│ IntuitionEngine │  Score 0.0–1.0, categories: ERROR/WARN/INFO
└────────┬────────┘
         │
         ▼
   Pipeline Report

---

CLI Commands

Command	Description
nexus run "<problem>" --report	Full pipeline: decompose → execute → verify
nexus decomposer "<problem>" --depth 2 --output tree.json	Phase 1 only: decompose into components
nexus execute "<problem>"	Phase 2: execute components (resumes from checkpoint)
nexus verify "<problem>"	Phase 3: full composition verification report

Options:

• --depth 1-4 — Force decomposition depth (Pattern Match=1, Standard=2, Deep=3, Research=4)
• --context "..." — Additional context for decomposition
• --report — Print detailed full report
• --output file.json — Save tree to JSON file

---

Depth Levels

Level	Value	Behavior
Pattern Match	1	Direct implementation, minimal decomposition
Standard	2	LLM-guided decomposition with interface contracts
Deep	3	Deeper nesting, more granular components
Research	4	Exhaustive decomposition, external context

---

Core Modules

Module	File	Coverage	Lines
FractalDecomposer	core/decomposer.py	80%	148
TCAContextManager	core/context.py	89%	88
ComponentExecutor	core/executor.py	96%	97
CompositionVerifier	core/verifier.py	95%	146
ProductionIntuitionEngine	core/pie.py	96%	123
FractalOrchestrator	orchestration/fractal_orchestrator.py	100%	74
StateStore	state/store.py	67%	181
LLMClient	llm/client.py	28%	317

---

PIE Rules

Production Intuition Engine checks each component implementation for:

Rule	ID	Severity	Check
Hardcoded secrets	SECRETS-001	ERROR	API keys, passwords, tokens
SQL injection	SEC-002	ERROR	f-string/concat in execute()
Bare excepts	ERR-001	ERROR	except: without type
Missing error handling	ERR-002	WARN	open/json/subprocess without try
Hardcoded URLs	CONFIG-001	INFO	localhost/127.0.0.1 strings
Print statements	LOGGING-001	INFO	print() instead of logger
TODO/FIXME	QUALITY-001	INFO	Unresolved comments
Large functions	DESIGN-001	WARN	Functions >50 lines
Semantic analysis	PIE-SEMANTIC	varies	LLM-guided review (optional)

---

Configuration

Set environment variables:

GROQ_API_KEY=gsk_...        # Required for LLM calls
NEXUS_API_KEY=...           # Fallback if GROQ_API_KEY not set

Copy .env.example to .env as a reference.

---

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests (115+ tests)
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=core --cov=orchestration --cov=state --cov-report=term

# Lint
ruff check .

---

Project Structure

.agent/
├── cli.py                    # CLI entry point (nexus command)
├── pyproject.toml            # Package config + entry point
├── .env.example              # Environment variable reference
├── core/
│   ├── decomposer.py         # Fractal decomposition with LLM
│   ├── context.py            # Token-compiled context (3-tier)
│   ├── executor.py           # Component executor with checkpoint
│   ├── verifier.py           # LLM-as-judge composition verifier
│   ├── pie.py                # Production Intuition Engine
│   └── __init__.py           # Public API exports
├── orchestration/
│   └── fractal_orchestrator.py  # Full pipeline orchestrator
├── llm/
│   └── client.py             # Provider-agnostic LLM client
├── state/
│   └── store.py              # Crash-safe atomic state store
├── tests/
│   ├── test_core.py          # 42 core tests
│   ├── test_edge_cases.py    # 25 edge-case tests
│   ├── test_coverage.py      # ~50 coverage tests
│   └── test_state.py         # State store edge-case tests
└── .github/workflows/ci.yml # GitHub Actions CI

---

Stats

Metric	Value
Total tests	115+
Core module coverage	80-96%
Pipeline modules	6
PIE rules	10 (structural) + LLM semantic
Decomposition depths	4
Crash recovery	Checkpoint/resume per component
CLI commands	4

---

License

Built with NEXUS v3.