nexus-ai-pro 0.6.0 → 0.8.0

package/EXPLANATION.md

@@ -17,15 +17,15 @@ Most AI apps begin with one provider call. Then the app grows:
 - documents need RAG
 - production needs metrics, retries, health checks, and test fixtures
 
-`nexus-ai-pro` puts those pieces behind one main class: `NexusAI`.
+`nexus-ai-pro` puts those pieces behind one main class: `NexusAI`, plus a small `createNexus()` helper for beginner setups.
 
 You can use it lightly:
 
 ```ts
-const ai = new NexusAI({
-  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
-  routing: { mode: 'direct' },
-  defaultModel: 'openai/fast',
+const ai = createNexus({
+  provider: 'openai',
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'openai/fast',
   security: 'off',
   tokenOptimizer: { enabled: false },
 });
@@ -91,9 +91,38 @@ Supported adapters:
 - Groq
 - Mistral
 - Cohere
+- DeepSeek
+- Azure OpenAI
+- LM Studio
+- llama.cpp
+- custom OpenAI- or Anthropic-compatible endpoints
 
 Provider SDKs are optional peer dependencies. Install only the SDKs your app uses.
 
+For typed setup without a large config object, use the builder:
+
+```ts
+const ai = createNexusConfig()
+  .openai(process.env.OPENAI_API_KEY!)
+  .deepseek(process.env.DEEPSEEK_API_KEY!)
+  .auto('quality')
+  .security('standard')
+  .create();
+```
+
+## CLI
+
+The package also installs `nexus`:
+
+```bash
+nexus scan src --json
+nexus models --provider openai
+nexus optimize prompt.txt --max-input-tokens 4000
+nexus eval examples/cli-eval.json
+```
+
+The CLI is intentionally small. It calls the same scanner, model registry, eval runner, and token optimizer that library users can import directly.
+
 ### Routing
 
 Routing chooses a model and provider.
@@ -269,6 +298,7 @@ Evals:
 - operational metrics
 - RAG metrics
 - safety heuristics
+- optional LLM-as-judge scoring with rubrics and thresholds
 
 ## Voice Integrations
 
@@ -285,6 +315,7 @@ The basic operations are:
 - `ai.transcribe(...)` for speech-to-text
 - `ai.speak(...)` for text-to-speech
 - `ai.voice(...)` for the full voice pipeline
+- `ai.createVoiceSession(...)` for multi-turn call sessions with tools
 - `registerVoiceProvider(...)` for private, local, or hosted services
 
 The full voice turn is:
@@ -299,7 +330,17 @@ audio/transcript
 
 Because the completion step calls `ai.complete(...)`, it reuses routing, security, context-window compaction, token optimization, cache, retries, metrics, and tracing.
 
-Realtime sessions are still future work. That should be added as a separate `VoiceSession` abstraction instead of forcing realtime state into normal completion streams.
+`VoiceSession` adds state across caller turns. It accepts transcript or audio, builds prompts from any combination of `prompt`, `instructions`, and conditional `taskPrompts`, executes registered tools when the model requests app data, and can synthesize the final answer.
+
+Low-level realtime transport is still future work. That should be added as a bridge from telephony/WebSocket/SIP media events into `VoiceSession` instead of forcing socket state into normal completion streams.
+
+Phone-number telephony is a separate optional layer:
+
+- `nexus-ai-pro/telephony` provides provider-neutral call, webhook, and media-stream types.
+- `nexus-ai-pro/telephony/twilio` provides a Twilio adapter without adding the Twilio SDK as a required dependency.
+- `NexusAI` exposes helper methods for outbound calls, TwiML webhook responses, webhook validation, and media event normalization.
+
+This keeps a small transcription/TTS app small, while larger phone-agent apps can add Twilio or another carrier as needed.
 
 ## Choosing a Setup
 
@@ -351,12 +392,16 @@ const ai = new NexusAI({
   retry: { enabled: true, maxRetries: 2 },
   health: { enabled: true },
   metrics: { enabled: true },
+  logger: { console: false, sink: (event) => console.log(JSON.stringify(event)) },
 });
 ```
 
 ## Important Files
 
 - `src/core/nexus.ts` - main runtime
+- `src/core/create-nexus.ts` - beginner factory
+- `src/core/config-builder.ts` - fluent typed config builder
+- `src/cli.ts` - `nexus` command implementation
 - `src/providers/*` - provider adapters
 - `src/router/*` - routing and failover
 - `src/security/*` - guardrails
@@ -373,7 +418,7 @@ const ai = new NexusAI({
 
 ## Known Limitations
 
-- Voice is documented as a roadmap, not a finished runtime.
+- Voice, telephony, local models, and custom providers are optional layers; apps should enable only the pieces they use.
 - Audio/video preprocessing is limited.
 - Provider modality support differs and may require preprocessing.
 - Built-in model metadata is a routing convenience, not a pricing contract.

package/NEXUS.md

@@ -49,6 +49,8 @@ Core runtime:
 - `ai.plan(...)`
 - `ai.batchComplete(...)`
 - `ai.createQueue(...)`
+- `createNexus(...)`
+- `createNexusConfig(...)`
 
 Provider adapters:
 
@@ -60,7 +62,18 @@ Provider adapters:
 - Groq
 - Mistral
 - Cohere
-- custom providers through `registerProvider(...)`
+- DeepSeek
+- Azure OpenAI
+- LM Studio
+- llama.cpp
+- custom providers through `providers.custom` or `registerProvider(...)`
+
+CLI:
+
+- `nexus scan`
+- `nexus models`
+- `nexus eval`
+- `nexus optimize`
 
 Pipeline layers:
 
@@ -74,6 +87,7 @@ Pipeline layers:
 - metrics and provider health
 - audit logs and rate limits
 - pipeline hooks and custom steps
+- structured logger hooks
 
 Supporting modules:
 
@@ -83,6 +97,7 @@ Supporting modules:
 - Chain of Verification
 - self-consistency sampling
 - eval runner and metrics
+- optional LLM-as-judge eval scoring
 - workflow templates
 - web/search connector tools
 - provider conformance fixtures
@@ -95,6 +110,8 @@ Voice is implemented as an optional layer. Import size is controlled through sub
 
 - `nexus-ai-pro/voice` for provider-neutral types, errors, and `VoiceManager`
 - `nexus-ai-pro/voice/openai` for the OpenAI voice adapter
+- `nexus-ai-pro/telephony` for provider-neutral phone-call types and `TelephonyManager`
+- `nexus-ai-pro/telephony/twilio` for the Twilio phone-number adapter
 
 Current support:
 
@@ -102,21 +119,30 @@ Current support:
 - `ai.speak(...)`
 - `ai.voice(...)`
 - `ai.voiceTurn(...)`
+- `ai.createVoiceSession(...)`
 - `registerVoiceProvider(...)`
 - configurable `voice.providers`
 - custom voice providers
 - OpenAI voice provider adapter
 - full completion pipeline reuse after transcription
+- stateful `VoiceSession` turns with prompts, task prompts, tool calls, history, and optional speech
+- optional telephony providers for calls, webhook responses, webhook validation, and media-stream event parsing
 
 Useful test cases:
 
 - registered voice provider can transcribe
 - registered voice provider can synthesize speech
 - `ai.voice(...)` transcribes, appends transcript, calls `ai.complete(...)`, and optionally speaks
+- `VoiceSession` can accept transcript or audio, select matching task prompts, execute tools, and speak
 - `nexus-ai-pro/voice` imports without provider adapters
 - `nexus-ai-pro/voice/openai` imports separately
+- `nexus-ai-pro/voice/session` imports separately
 - type consumer can configure `VoiceConfig`
 - missing voice provider errors clearly
+- registered telephony provider can create calls
+- Twilio adapter can create inline-TwiML/media-stream calls
+- Twilio webhook signatures can be validated
+- Twilio media-stream messages can be normalized
 
 Example:
 
@@ -144,9 +170,16 @@ const result = await ai.voice({
 
 Still future work:
 
-- realtime `VoiceSession`
 - audio chunks in `NexusStream`
-- WebRTC/WebSocket/SIP session helpers
+- WebRTC/SIP session helpers
+- fully managed Twilio/OpenAI realtime bridge
+
+Telephony is intentionally separate from voice:
+
+- `voice` handles file/buffer/stream audio turns.
+- `VoiceSession` handles multi-turn call state and app/tool requests during a conversation.
+- `telephony` handles phone numbers, TwiML, provider webhooks, and media-stream protocol messages.
+- apps can use one, both, or neither.
 
 ## Context Window Testing
 
@@ -200,6 +233,14 @@ npm install
 npm run build
 ```
 
+Quick CLI checks after build:
+
+```bash
+node dist/cli.js models --provider deepseek
+node dist/cli.js scan src --no-fail
+node dist/cli.js optimize README.md --model gpt-5.4-mini
+```
+
 Main test suite:
 
 ```bash

package/README.md

@@ -14,7 +14,7 @@ Use the whole pipeline for production AI features, or turn pieces off when you o
 npm install nexus-ai-pro
 ```
 
-Install only the provider SDKs your app uses:
+Install only the provider SDKs your app uses. The OpenAI SDK also powers OpenAI-compatible adapters such as OpenRouter, Groq, Mistral, DeepSeek, Azure OpenAI, LM Studio, and llama.cpp.
 
 ```bash
 npm install openai @anthropic-ai/sdk ollama
@@ -25,33 +25,13 @@ The Google Gemini provider uses Node.js `fetch`, so it does not need an extra SD
 ## Quick Start
 
 ```ts
-import { NexusAI } from 'nexus-ai-pro';
+import { createNexus } from 'nexus-ai-pro';
 
-const ai = new NexusAI({
-  providers: {
-    openai: { apiKey: process.env.OPENAI_API_KEY! },
-    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },
-    google: { apiKey: process.env.GOOGLE_API_KEY! },
-    ollama: { baseUrl: 'http://localhost:11434' },
-  },
-  routing: {
-    mode: 'auto',
-    strategy: 'quality',
-  },
+const ai = createNexus({
+  provider: 'openai',
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-5.4-mini',
   security: 'standard',
-  contextWindow: {
-    strategy: 'last-messages-with-summary',
-    lastMessages: 10,
-    summary: { model: 'openai/fast', maxTokens: 600 },
-  },
-  tokenOptimizer: {
-    densification: { enabled: true },
-    budget: {
-      enabled: true,
-      maxInputTokens: 8000,
-      onExceeded: 'densify',
-    },
-  },
 });
 
 const response = await ai.complete({
@@ -64,6 +44,24 @@ console.log(response.meta.providerUsed);
 console.log(response.meta.modelUsed);
 ```
 
+For a fuller typed config, use the builder:
+
+```ts
+import { createNexusConfig } from 'nexus-ai-pro';
+
+const ai = createNexusConfig()
+  .openai(process.env.OPENAI_API_KEY!)
+  .anthropic(process.env.ANTHROPIC_API_KEY!)
+  .deepseek(process.env.DEEPSEEK_API_KEY!)
+  .lmstudio({ baseUrl: 'http://localhost:1234/v1' })
+  .auto('quality')
+  .security('standard')
+  .retry({ enabled: true, maxRetries: 2 })
+  .create();
+```
+
+You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want full object-literal control.
+
 ## Why Use It
 
 `nexus-ai-pro` is useful when an app needs more than a direct SDK call:
@@ -78,6 +76,24 @@ console.log(response.meta.modelUsed);
 - add tools, agents, RAG context, evals, batch jobs, and queues
 - keep TypeScript types around every request and response
 
+## CLI
+
+The package installs a `nexus` command:
+
+```bash
+nexus scan src --json
+nexus models --provider deepseek
+nexus optimize prompt.txt --model gpt-5.4-mini --max-input-tokens 4000
+nexus eval examples/cli-eval.json
+```
+
+CLI commands are intentionally thin wrappers around library modules:
+
+- `nexus scan` checks files for secrets, PII, and prompt-injection patterns.
+- `nexus models` lists the bundled model registry.
+- `nexus eval` runs JSON or JS eval cases.
+- `nexus optimize` previews token optimization for a request or prompt file.
+
 ## Core Concepts
 
 ### Providers and Routing
@@ -88,7 +104,10 @@ const ai = new NexusAI({
     openai: { apiKey: process.env.OPENAI_API_KEY! },
     anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },
     groq: { apiKey: process.env.GROQ_API_KEY! },
+    deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! },
+    openrouter: { apiKey: process.env.OPENROUTER_API_KEY! },
     ollama: { baseUrl: 'http://localhost:11434' },
+    lmstudio: { baseUrl: 'http://localhost:1234/v1' },
   },
   routing: {
     mode: 'auto',
@@ -101,6 +120,22 @@ const ai = new NexusAI({
 });
 ```
 
+First-class provider adapters:
+
+- OpenAI
+- Anthropic
+- Google Gemini
+- Ollama
+- OpenRouter
+- Groq
+- Mistral
+- Cohere
+- DeepSeek
+- Azure OpenAI
+- LM Studio
+- llama.cpp
+- custom OpenAI- or Anthropic-compatible endpoints through `providers.custom` or `registerProvider(...)`
+
 Routing modes:
 
 - `direct` - always use the requested model or `defaultModel`
@@ -343,6 +378,62 @@ console.log(result.response.content);
 console.log(result.speech?.audio.data);
 ```
 
+### Voice Session With App Requests
+
+Use `VoiceSession` when a call has multiple turns, should keep history, and may need to call your app while talking.
+
+The prompt setup is flexible:
+
+- `prompt` describes the assistant or business role.
+- `instructions` describe behavior.
+- `taskPrompts` add conditional instructions when the caller asks about something specific.
+- `tools` let the model call your app, such as booking, CRM, billing, or inventory APIs.
+
+```ts
+import { tool } from 'nexus-ai-pro';
+
+const session = ai.createVoiceSession({
+  model: 'auto',
+  prompt: 'You are a phone booking assistant for a small clinic.',
+  instructions: [
+    'Keep answers short and natural for a phone call.',
+    'Ask one follow-up question at a time.',
+  ],
+  taskPrompts: [
+    {
+      name: 'booking',
+      when: ['book', 'appointment', 'free slot'],
+      instructions: 'When the caller asks about availability, call check_free_slots before offering times.',
+      tools: ['check_free_slots'],
+    },
+  ],
+  tools: [
+    tool({
+      name: 'check_free_slots',
+      description: 'Check available booking slots for a date.',
+      parameters: {
+        type: 'object',
+        properties: { date: { type: 'string' } },
+        required: ['date'],
+      },
+      execute: async ({ date }) => bookingApi.freeSlots(String(date)),
+    }),
+  ],
+  toolSelection: 'task',
+  speech: { provider: 'openai', voice: 'alloy', format: 'mp3' },
+});
+
+const turn = await session.handleTurn({
+  transcript: 'Do you have any free slots tomorrow?',
+});
+
+console.log(turn.response.content);
+console.log(turn.toolSteps);
+console.log(turn.speech?.audio.data);
+```
+
+You can use only `prompt`, only `instructions`, only `taskPrompts`, or all of them together. For phone calls through Twilio media streams, parse incoming audio/media events in `telephony`, feed complete caller turns into `session.handleTurn(...)`, then send the returned speech audio back through your call transport.
+
 ### Custom Voice Provider
 
 Bring any private, local, or hosted voice service:
@@ -369,7 +460,62 @@ ai.registerVoiceProvider('private-voice', {
 });
 ```
 
-Realtime voice sessions and audio chunks inside `NexusStream` are still future work; the current voice layer covers transcription, speech generation, and full request/response voice turns.
+Low-level realtime transport adapters are still future work; the current voice layer covers transcription, speech generation, full request/response voice turns, and stateful voice sessions with tool calls.
+
+## Phone Number Telephony
+
+Phone-number support is optional and separate from the voice layer. Use `voice` for audio transcription/TTS, and use `telephony` when calls, webhooks, TwiML, or media-stream events are involved.
+
+```ts
+import { TelephonyManager } from 'nexus-ai-pro/telephony';
+import { TwilioTelephonyProvider } from 'nexus-ai-pro/telephony/twilio';
+```
+
+Configure only the provider you need:
+
+```ts
+const ai = new NexusAI({
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+  telephony: {
+    defaultProvider: 'twilio',
+    providers: {
+      twilio: new TwilioTelephonyProvider({
+        accountSid: process.env.TWILIO_ACCOUNT_SID!,
+        authToken: process.env.TWILIO_AUTH_TOKEN!,
+      }),
+    },
+  },
+});
+```
+
+Generate a Twilio webhook response for an inbound phone number:
+
+```ts
+const response = await ai.createTelephonyResponse({
+  say: 'Thanks for calling. Connecting you now.',
+  stream: {
+    url: 'wss://voice.example.com/twilio',
+    mode: 'bidirectional',
+    parameters: { tenant: 'acme' },
+  },
+});
+
+return new Response(response.body, {
+  headers: { 'content-type': response.contentType },
+});
+```
+
+Start an outbound call with either a webhook, inline TwiML, an application SID, or a media-stream URL:
+
+```ts
+const call = await ai.createCall({
+  to: '+15551230000',
+  from: '+15557650000',
+  mediaStreamUrl: 'wss://voice.example.com/twilio',
+});
+```
+
+For smaller apps, skip Twilio entirely and register your own `TelephonyProvider`.
 
 ## Security
 
@@ -435,9 +581,35 @@ Available runtime helpers:
 - batch completion with concurrency control
 - in-memory job queue
 - Redis and BullMQ queue adapters
-- eval runner with quality, operations, RAG, and safety metrics
+- eval runner with quality, operations, RAG, safety metrics, and optional LLM-as-judge scoring
+- voice sessions for multi-turn calls with conditional task prompts and app tools
 - workflow templates for RAG answers, extraction, classification, comparison, support, sales, legal review, and code review
 
+Use a plain assertion for small evals, or add an LLM judge when a rubric is more useful than exact matching:
+
+```ts
+import { LLMJudge } from 'nexus-ai-pro/evals';
+
+const judge = new LLMJudge({
+  client: ai,
+  model: 'openai/gpt-4.1-mini',
+  rubric: 'Score whether the answer is correct, concise, and grounded in the supplied context.',
+  passThreshold: 0.7,
+});
+
+const run = await ai.runEvals([
+  {
+    name: 'support answer quality',
+    request: {
+      model: 'auto',
+      messages: [{ role: 'user', content: 'Explain our refund policy.' }],
+    },
+    expected: 'Refunds are available within 30 days.',
+    judge: judge.asEvalJudge(),
+  },
+]);
+```
+
 ## Observability and Reliability
 
 ```ts
@@ -452,6 +624,19 @@ console.log(ai.getPrometheusMetrics());
 console.log(await ai.checkProviders());
 ```
 
+Structured logging can be injected without replacing audit logs or metrics:
+
+```ts
+const ai = createNexusConfig()
+  .openai(process.env.OPENAI_API_KEY!)
+  .direct('gpt-5.4-mini')
+  .logger({
+    console: false,
+    sink: (event) => myLogger.info(event),
+  })
+  .create();
+```
+
 Production controls include:
 
 - request timeouts
@@ -462,6 +647,7 @@ Production controls include:
 - Prometheus metrics
 - OpenTelemetry metrics and trace export helpers
 - audit log sink
+- structured logger sink
 - rate limiting
 
 ## Import Surface
@@ -469,17 +655,19 @@ Production controls include:
 The root import is convenient:
 
 ```ts
-import { NexusAI } from 'nexus-ai-pro';
+import { NexusAI, createNexus, createNexusConfig } from 'nexus-ai-pro';
 ```
 
 Focused subpaths are available for smaller imports:
 
 ```ts
 import { NexusAI } from 'nexus-ai-pro/core';
+import { createNexusConfig } from 'nexus-ai-pro/config';
 import { TokenOptimizer } from 'nexus-ai-pro/optimizer';
 import { ContextWindowManager } from 'nexus-ai-pro/context';
 import { guardrailPolicy } from 'nexus-ai-pro/security';
 import { RedisCacheAdapter } from 'nexus-ai-pro/cache';
+import { DeepSeekProvider } from 'nexus-ai-pro/providers/deepseek';
 ```
 
 Provider SDKs are optional peer dependencies. The package is ESM-first and marked with `sideEffects: false`.
@@ -488,6 +676,9 @@ Provider SDKs are optional peer dependencies. The package is ESM-first and marke
 
 ```bash
 npm run example:minimal
+npm run example:create-nexus
+npm run example:config-builder
+npm run example:custom-provider
 npm run example:feature-flags
 npm run example:basic
 npm run example:security
@@ -503,6 +694,8 @@ Included example files cover:
 - persisted vector stores
 - classifier calibration
 - domain workflows
+- custom providers
+- import examples under `examples/exports`
 
 ## Test Commands
 

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};