OpenNodeX

An enterprise-grade AI Agent framework built with TypeScript, designed for production-ready multi-agent orchestration with multi-model routing.

Features

• Multi-Model Routing — Automatically selects the best model based on task type, quality requirements, latency, and cost. Supports rule-based, tiered, capability-based, parallel voting, pipeline, and score-based routing strategies.
• Multi-Agent Collaboration — Supports single agent execution and multi-agent workflows with planner, executor, researcher, reviewer, and specialized agent roles.
• Tool Execution — Secure, permission-controlled tool calling with sandboxed execution for high-risk operations.
• Workflow Orchestration — DAG-based workflow engine supporting sequential, parallel, conditional, and review nodes.
• Memory Management — Three-tier memory system: short-term (session), working (task), and long-term (persistent) with scoped isolation.
• Governance & Security — Built-in permission control, quota management, rate limiting, audit logging, and prompt version management.
• Observability — Full-chain tracing from request to response, metrics collection, cost analysis, and quality analysis.
• Fallback & Recovery — Automatic retry, model switching, model escalation, and task decomposition on failure.

Architecture

┌─────────────────────────────────────────────────┐
│                 Interface Layer                  │
│          (API / Chat / Event Gateway)            │
├─────────────────────────────────────────────────┤
│              Task Management Layer               │
│     (Task Manager / Scheduler / State Machine)   │
├─────────────────────────────────────────────────┤
│              Agent Runtime Layer                 │
│  (Registry / Factory / Executor / Collaboration) │
├──────────┬──────────┬──────────┬────────────────┤
│  Model   │   Tool   │ Workflow │    Memory &    │
│ Mgmt     │   Exec   │  Orch    │   Knowledge    │
│ Layer    │  Layer   │  Layer   │    Layer       │
├──────────┴──────────┴──────────┴────────────────┤
│           Governance & Security Layer            │
├─────────────────────────────────────────────────┤
│             Observability Layer                  │
└─────────────────────────────────────────────────┘

Quick Start

Prerequisites

• Node.js >= 20
• npm >= 10

Installation

git clone https://github.com/opennodex-wq/opennodex.git
cd opennodex
npm install

Configuration

Copy the example environment file and fill in your API keys:

cp .env.example .env

# Model Provider API Keys
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_AI_API_KEY=

# Database
DATABASE_URL=

# Redis
REDIS_URL=

Development

npm run dev       # Start development server
npm run build     # Build for production
npm run test      # Run tests
npm run lint      # Run linter

Project Structure

src/
├── interface/       # API/Chat/Event gateways, request parsing
├── task/            # Task lifecycle, state machine, scheduling
├── agent/           # Agent base, registry, factory, executor, collaboration
│   └── types/       # Planner, Executor, Researcher, Reviewer, etc.
├── model/           # Model adapters, registry, router, fallback, evaluator
│   └── adapters/    # OpenAI, Anthropic, Gemini, Qwen, DeepSeek, etc.
├── tool/            # Tool registry, executor, auth, sandbox
├── workflow/        # Workflow engine, DAG graph, node execution
├── memory/          # Session/working/long-term memory, context builder
├── governance/      # Policy, permissions, quota, rate limiting, audit
├── observability/   # Tracing, metrics, logging, cost/quality analysis
├── core/            # Config, constants, exceptions, utilities
└── storage/         # Database, Redis, vector DB, object store adapters

Multi-Model Routing

OpenNodeX routes tasks to the optimal model using capability tags rather than hardcoded model names:

| Task Type | Recommended Strategy | Model Capabilities | | ------------------ | -------------------------- | -------------------------------------- | | Simple Q&A | Rule / Tiered | fast, cheap | | Summarization | Rule-based | fast, cheap, long_context | | RAG Q&A | Capability-based | long_context, factual, tool_call | | Complex Reasoning | Capability / Escalation | reasoning, stable | | Code Generation | Capability-based | code, structured | | Structured Extract | Capability-based | json_output, stable | | Multi-step Workflow| Pipeline | mixed | | Critical Review | Parallel Voting / Reviewer | high_quality, stable |

Routing Flow

Request → Feature Extraction → Policy Engine → Hard Constraint Filter
→ Candidate Ranking → Primary Model + Fallback Chain → Model Invocation
→ Response Evaluation → Return Result (or Fallback/Escalate)

Roadmap

Phase 1: Minimum Viable Product

• Interface Layer, Task Management, BaseAgent + Executor
• Model Adapter + Router, Tool Registry + Executor
• Session Memory, basic logging and tracing

Phase 2: Collaboration

• Workflow Engine, Planner/Executor/Reviewer agents
• Working Memory, Fallback/Recovery
• Permission control, enhanced observability

Phase 3: Enterprise Governance

• Long-term Memory, Quota/Budget management
• Audit system, Prompt version management
• Policy configuration center, dynamic routing optimization

Contributing

1. Do not push directly to main
2. Create a feature branch: feature/<description>
3. Keep PRs small and focused (one purpose per PR)
4. Write descriptive commit messages
5. All PRs require review before merging

License

MIT