npm package: @opennodex/opennodex
Description: Enterprise-grade AI Agent framework
Latest version: 0.1.0

# 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

```bash
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:

```bash
cp .env.example .env
```

```env
# Model Provider API Keys
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_AI_API_KEY=

# Database
DATABASE_URL=

# Redis
REDIS_URL=
```

### Development

```bash
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