@adverant-nexus/cli 2.0.0

package/docs/graphrag-commands.md

@@ -0,0 +1,387 @@
+# GraphRAG CLI Commands
+
+Enhanced GraphRAG commands for the Nexus CLI with support for memory management, enhanced search, and RAG Triad evaluation.
+
+## Overview
+
+The GraphRAG CLI commands provide access to both the standard GraphRAG service and the GraphRAG Enhanced service with advanced RAG patterns.
+
+## Configuration
+
+### Tenant Context
+
+All GraphRAG commands require tenant context headers. Configure these in your Nexus CLI config:
+
+```json
+{
+  "companyId": "adverant",
+  "appId": "nexus-cli",
+  "userId": "your-user-id"
+}
+```
+
+### Service Discovery
+
+The CLI automatically detects available services:
+- `graphrag` - Standard GraphRAG (Port 8090)
+- `graphrag-enhanced` - Enhanced GraphRAG with Modular RAG patterns (Port 9051)
+
+Commands that support enhanced features will automatically use `graphrag-enhanced` if available, falling back to standard `graphrag`.
+
+## Commands
+
+### Document Management
+
+#### `store-document`
+Store a document in GraphRAG for indexing and retrieval.
+
+**Usage:**
+```bash
+nexus graphrag store-document --file <path> [--title <title>]
+```
+
+**Examples:**
+```bash
+nexus graphrag store-document --file report.pdf --title "Q4 Report"
+nexus graphrag store-document --file docs/api-spec.md
+```
+
+#### `query`
+Query documents using standard search.
+
+**Usage:**
+```bash
+nexus graphrag query --text <query> [--limit N]
+```
+
+**Examples:**
+```bash
+nexus graphrag query --text "user authentication" --limit 10
+nexus graphrag query --text "deployment instructions"
+```
+
+### Memory Management
+
+#### `store-memory`
+Store a memory (code snippet, note, documentation) in GraphRAG.
+
+**Usage:**
+```bash
+nexus graphrag store-memory --content <text> [--tags <tags>]
+```
+
+**Examples:**
+```bash
+nexus graphrag store-memory --content "User auth uses JWT tokens with bcrypt hashing" --tags "auth,jwt,security"
+
+nexus graphrag store-memory --content "API endpoint: POST /api/users/register" --tags "api,users"
+```
+
+#### `recall`
+Recall memories using semantic search.
+
+**Usage:**
+```bash
+nexus graphrag recall --query <text> [--limit N]
+```
+
+**Examples:**
+```bash
+nexus graphrag recall --query "How does authentication work?" --limit 3
+
+nexus graphrag recall --query "user registration endpoint"
+```
+
+**Output:**
+```json
+{
+  "memories": [
+    {
+      "content": "User auth uses JWT tokens...",
+      "score": 0.73,
+      "timestamp": "2025-12-26T14:26:16.601Z",
+      "tags": ["auth", "jwt"]
+    }
+  ],
+  "count": 1
+}
+```
+
+#### `list-memories`
+List all stored memories with pagination.
+
+**Usage:**
+```bash
+nexus graphrag list-memories [--limit N] [--offset N]
+```
+
+**Examples:**
+```bash
+nexus graphrag list-memories --limit 10
+
+nexus graphrag list-memories --limit 20 --offset 20
+```
+
+### Enhanced Search (GraphRAG Enhanced)
+
+#### `enhanced-search`
+Perform enhanced search with query rewriting, HyDE, and self-correction.
+
+**Usage:**
+```bash
+nexus graphrag enhanced-search --query <text> [options]
+```
+
+**Options:**
+- `--enable-enhancement` - Enable query enhancement (default: true)
+- `--enable-correction` - Enable self-correction (default: true)
+- `--enable-eval` - Enable RAG Triad evaluation (default: true)
+- `--top-k` - Number of results (default: 10)
+
+**Examples:**
+```bash
+# Full enhanced search
+nexus graphrag enhanced-search --query "JWT authentication implementation"
+
+# Disable self-correction for faster results
+nexus graphrag enhanced-search --query "How to deploy to K8s?" --enable-correction false
+
+# Custom result count
+nexus graphrag enhanced-search --query "API documentation" --top-k 5
+```
+
+**Output:**
+```json
+{
+  "results": [...],
+  "enhancement": {
+    "originalQuery": "JWT auth",
+    "enhancedQuery": "JWT token-based authentication implementation with Express.js",
+    "routingDecision": {
+      "route": "full_pipeline",
+      "confidence": 0.9
+    }
+  },
+  "quality": {
+    "contextRelevance": 0.88,
+    "groundedness": 0.92,
+    "answerRelevance": 0.85,
+    "overall": 0.88
+  },
+  "iterations": [...]
+}
+```
+
+#### `analyze`
+Analyze query complexity and routing decision without performing search.
+
+**Usage:**
+```bash
+nexus graphrag analyze --query <text>
+```
+
+**Examples:**
+```bash
+nexus graphrag analyze --query "What is the refund policy?"
+
+nexus graphrag analyze --query "Compare PostgreSQL vs MongoDB for high-volume transactions"
+```
+
+**Output:**
+```json
+{
+  "analysis": {
+    "intent": "exploratory",
+    "complexity": "complex",
+    "keywords": ["postgresql", "mongodb", "high-volume", "transactions"]
+  },
+  "routingDecision": {
+    "route": "full_pipeline",
+    "reason": "Complex query requiring full enhancement",
+    "confidence": 0.9,
+    "estimatedLatencyMs": 2000
+  }
+}
+```
+
+#### `evaluate`
+Evaluate RAG quality using RAG Triad metrics (Context Relevance, Groundedness, Answer Relevance).
+
+**Usage:**
+```bash
+nexus graphrag evaluate --query <text> --context <text> --answer <text>
+```
+
+**Note:** Separate multiple context chunks with `|||`
+
+**Examples:**
+```bash
+nexus graphrag evaluate \
+  --query "What is JWT?" \
+  --context "JWT is a token standard|||Used for authentication" \
+  --answer "JWT is a token standard used for authentication"
+```
+
+**Output:**
+```json
+{
+  "scores": {
+    "contextRelevance": 0.95,
+    "groundedness": 0.92,
+    "answerRelevance": 0.88,
+    "overall": 0.92
+  },
+  "diagnostics": {
+    "irrelevantChunks": [],
+    "unsupportedClaims": [],
+    "unansweredAspects": [],
+    "suggestions": ["Quality is excellent - no immediate improvements needed"]
+  }
+}
+```
+
+## Routing Decision Types
+
+The `enhanced-search` and `analyze` commands use adaptive routing:
+
+| Route | Trigger | Latency | Use Case |
+|-------|---------|---------|----------|
+| `direct_llm` | Greetings, simple chat | ~500ms | "Hello", "Thanks" |
+| `keyword_only` | Error codes, IDs, exact matches | ~300ms | "ERROR_401", "user-123" |
+| `semantic_only` | Conceptual, explanatory queries | ~600ms | "How does X work?" |
+| `full_pipeline` | Complex, multi-part queries | ~2000ms | "Compare A vs B for use case C" |
+
+## Quality Metrics
+
+### RAG Triad Scores
+
+The `enhanced-search` and `evaluate` commands provide RAG Triad quality metrics:
+
+| Metric | Description | Weight |
+|--------|-------------|--------|
+| **Context Relevance** | Is retrieved context relevant to query? | 0.35 |
+| **Groundedness** | Is answer supported by context? | 0.35 |
+| **Answer Relevance** | Does answer address the query? | 0.30 |
+
+**Quality Thresholds:**
+- `>= 0.80` - Excellent quality
+- `0.70 - 0.79` - Good quality
+- `0.60 - 0.69` - Acceptable quality
+- `< 0.60` - Poor quality (triggers self-correction)
+
+## Performance
+
+### Typical Latencies
+
+| Operation | Latency |
+|-----------|---------|
+| `store-memory` | ~100-200ms |
+| `recall` | ~400-600ms |
+| `query` | ~200-500ms |
+| `enhanced-search` (no correction) | ~400-800ms |
+| `enhanced-search` (with correction) | ~800-1500ms |
+| `analyze` | ~45ms |
+| `evaluate` | ~200-400ms |
+
+### Caching
+
+Enhanced search commands benefit from caching:
+- Query enhancements cached for 1 hour
+- Routing decisions cached for 30 minutes
+- Search results cached for 15 minutes
+
+## Integration with GraphRAG Enhanced
+
+### Query Enhancement Flow
+
+1. **Original Query**: "how does auth work?"
+2. **Enhanced Query**: "Explain JWT token-based authentication implementation with Express.js including bcrypt password hashing and validation"
+3. **HyDE Document**: Hypothetical answer generated for better similarity matching
+4. **Multi-Query**: 3 query variations created to increase recall
+5. **Results**: 30-50% more relevant context retrieved
+
+### Self-Correction Flow
+
+1. Initial retrieval → Quality score: 0.65
+2. Identify quality issues → "Context lacks code examples"
+3. Refine query → "Show TypeScript code for JWT authentication"
+4. Re-retrieve → Quality score: 0.88
+5. Return best results
+
+## Examples
+
+### Store and Recall Code Snippets
+
+```bash
+# Store a code snippet
+nexus graphrag store-memory \
+  --content "Express registration endpoint uses bcrypt.hash(password, 10) for password hashing" \
+  --tags "express,security,bcrypt,authentication"
+
+# Recall similar code
+nexus graphrag recall --query "How to hash passwords in Node.js?" --limit 3
+```
+
+### Enhanced Search with Quality Evaluation
+
+```bash
+# Search with full enhancement
+nexus graphrag enhanced-search \
+  --query "PostgreSQL connection pooling best practices" \
+  --top-k 5
+```
+
+### Quality Evaluation Workflow
+
+```bash
+# Analyze query first
+nexus graphrag analyze --query "What is the deployment process?"
+
+# Perform search
+nexus graphrag enhanced-search --query "What is the deployment process?"
+
+# Evaluate quality
+nexus graphrag evaluate \
+  --query "What is the deployment process?" \
+  --context "Deployment uses Kubernetes|||Docker containers are built first|||CI/CD pipeline automates deployment" \
+  --answer "The deployment process uses Kubernetes with Docker containers. The CI/CD pipeline automates the deployment workflow."
+```
+
+## Troubleshooting
+
+### Service Not Found
+
+If you see "GraphRAG service not found":
+1. Ensure GraphRAG service is running
+2. Check service discovery configuration
+3. Verify service is registered in Nexus CLI
+
+### Authentication Errors
+
+If you see "Unauthorized" or "Missing tenant context":
+1. Configure tenant context in CLI config
+2. Ensure `companyId`, `appId`, and `userId` are set
+3. Verify API key is valid
+
+### Low Quality Scores
+
+If enhanced search returns low quality scores:
+1. Try enabling self-correction (if disabled)
+2. Use more specific queries
+3. Check if relevant content exists in knowledge base
+
+## API Integration
+
+For programmatic access, use the Nexus API directly:
+
+**Endpoint**: `https://api.adverant.ai`
+
+**Required Headers**:
+```
+Authorization: Bearer <api-key>
+X-Company-ID: <company-id>
+X-App-ID: <app-id>
+X-User-ID: <user-id>
+```
+
+See [GraphRAG API Documentation](../../services/nexus-graphrag/README.md) for details.

package/package.json

@@ -0,0 +1,154 @@
+{
+  "name": "@adverant-nexus/cli",
+  "version": "2.0.0",
+  "description": "World-class CLI for Adverant-Nexus - Surpassing Claude Code and Gemini CLI",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "nexus": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "dev:build": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "clean": "rm -rf dist",
+    "docs:dev": "cd docs-site && npm run docs:dev",
+    "docs:build": "cd docs-site && npm run docs:build",
+    "docs:preview": "cd docs-site && npm run docs:preview",
+    "docs:install": "cd docs-site && npm install",
+    "prepublishOnly": "npm run validate && npm run clean && npm run build",
+    "prepack": "npm run build",
+    "postpack": "echo '✓ Package created successfully'",
+    "validate": "node scripts/prepublish.js",
+    "verify": "node scripts/verify-package.js",
+    "link:global": "npm run build && npm link",
+    "unlink:global": "npm unlink -g @adverant-nexus/cli",
+    "publish:dry": "npm publish --dry-run",
+    "publish:test": "npm run verify",
+    "completions:install": "bash scripts/install-completions.sh",
+    "completions:install:bash": "bash scripts/install-completions.sh --shell bash",
+    "completions:install:zsh": "bash scripts/install-completions.sh --shell zsh",
+    "completions:install:fish": "bash scripts/install-completions.sh --shell fish",
+    "postinstall": "echo '\nℹ️  To install shell completions, run: npm run completions:install\n'"
+  },
+  "keywords": [
+    "nexus",
+    "nexus",
+    "cli",
+    "ai",
+    "mcp",
+    "model-context-protocol",
+    "autonomous-agents",
+    "multi-agent",
+    "graphrag",
+    "microservices",
+    "devtools"
+  ],
+  "author": "Adverant AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adverant-ai/adverant-nexus.git",
+    "directory": "packages/nexus-cli"
+  },
+  "homepage": "https://adverant-nexus.dev",
+  "bugs": {
+    "url": "https://github.com/adverant-ai/adverant-nexus/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@adverant-nexus/sdk": "file:../nexus-sdk",
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "ansi-escapes": "^6.2.0",
+    "axios": "^1.6.2",
+    "boxen": "^7.1.1",
+    "chalk": "^5.3.0",
+    "chokidar": "^3.6.0",
+    "cli-cursor": "^4.0.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^12.0.0",
+    "conf": "^12.0.0",
+    "configstore": "^7.0.0",
+    "cosmiconfig": "^9.0.0",
+    "date-fns": "^3.0.6",
+    "dayjs": "^1.11.10",
+    "debug": "^4.3.4",
+    "dotenv": "^16.6.1",
+    "eventemitter3": "^5.0.1",
+    "execa": "^8.0.1",
+    "fast-glob": "^3.3.2",
+    "figures": "^6.0.1",
+    "fs-extra": "^11.2.0",
+    "glob": "^10.3.10",
+    "inquirer": "^9.2.12",
+    "js-yaml": "^4.1.0",
+    "listr2": "^8.0.1",
+    "lodash-es": "^4.17.21",
+    "log-symbols": "^6.0.0",
+    "nanospinner": "^1.1.0",
+    "node-fetch": "^3.3.2",
+    "open": "^10.0.3",
+    "ora": "^8.0.1",
+    "p-queue": "^8.0.1",
+    "parse-duration": "^1.1.0",
+    "pretty-bytes": "^6.1.1",
+    "pretty-ms": "^9.0.0",
+    "prompts": "^2.4.2",
+    "semver": "^7.5.4",
+    "socket.io-client": "^4.7.2",
+    "string-width": "^7.0.0",
+    "strip-ansi": "^7.1.0",
+    "terminal-link": "^3.0.0",
+    "update-notifier": "^7.0.0",
+    "wrap-ansi": "^9.0.0",
+    "ws": "^8.16.0",
+    "yaml": "^2.3.4",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "@types/fs-extra": "^11.0.4",
+    "@types/iarna__toml": "^2.0.5",
+    "@types/inquirer": "^9.0.7",
+    "@types/jest": "^29.5.11",
+    "@types/js-yaml": "^4.0.9",
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^20.10.5",
+    "@types/prompts": "^2.4.9",
+    "@types/uuid": "^10.0.0",
+    "@types/ws": "^8.5.10",
+    "@typescript-eslint/eslint-plugin": "^6.15.0",
+    "@typescript-eslint/parser": "^6.15.0",
+    "eslint": "^8.56.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "jest": "^29.7.0",
+    "prettier": "^3.1.1",
+    "ts-jest": "^29.1.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.0"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "completions",
+    "scripts",
+    "docs",
+    "README.md",
+    "ARCHITECTURE.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}