novalab-adk 1.4.0

NovaLab Agent Development Kit — Build, test, and deploy Nova AI agents with multi-agent orchestration

Nova ADK

The Agent Development Kit for governed AI

Nova ADK is the official SDK for the NovaLab AI orchestration platform. Build, deploy, and govern autonomous AI agents with enterprise-grade trust evaluation, confidence scoring, and full auditability.

Any LLM in. Governed agents out.

Every request flows through a 5-layer pipeline -- Intent, Risk, LLM, Trust, Confidence -- before an action is taken. The result is AI that explains itself, scores its own certainty, and stops when it is not sure.

Available in TypeScript (@novalabai/adk) and Python (novalab-adk).

---

Key Features

Core Pipeline

• LLM Semantic Routing -- classifies intent with an LLM and routes to the best model (Claude, Gemini, GPT), with keyword fallback
• Trust Evaluation -- cross-model evaluation scoring accuracy, safety, relevance, and completeness
• Confidence Scoring -- 0-100% score with four autonomy levels (autonomous, notify, approval required, blocked)
• Circuit Breaker -- trust evaluation includes a circuit breaker that degrades gracefully under failure

Agent Capabilities

• Agent Memory -- session, persistent, or shared context that carries across runs
• Learning Cache -- semantic similarity cache that skips the LLM when a similar question was already answered
• RAG (Retrieval Augmented Generation) -- ingest PDF, DOCX, CSV, or plain text; chunks are retrieved at query time
• BYOLLM (Bring Your Own LLM) -- register any OpenAI-compatible endpoint and run it through the full Nova pipeline
• SSE Streaming -- server-sent events endpoint for progressive, real-time output
• Training Data Collection -- opt-in with allow_training, submit feedback and corrections, export as OpenAI JSONL / Alpaca / pairs

Agent Tools & Communication

• Agent Tools & Function Calling -- register external APIs as tools; agents autonomously invoke them via a function-calling loop
• Agent-to-Agent Communication (A2A) -- agents discover and call other agents with capability cards, permission checks, and depth limits

Orchestration

• Multi-Agent Orchestration -- route, parallel, verify, and composable pipeline as first-class primitives
• Server-Side Orchestration -- single-call multi-agent decomposition with parallel sub-task execution

Evaluation & Ops

• Evaluation & Benchmarking -- create test suites, run agents against them, and get accuracy, confidence, latency, and cost metrics
• Persistent Storage -- force save/load, export/import full JSON backups, and monitor database status
• Rate Limiting & Cost Tracking -- per-model usage tracking, daily cost breakdown, configurable RPM and spend limits

Platform

• Workflow Studio -- multi-step pipelines with confidence gates at every step
• Signal Monitor -- real-time telemetry ingestion from IoT, vehicles, machines, and infrastructure
• Automations -- plain-English rule-based workflows with configurable confidence thresholds
• Webhooks -- 8+ event types with HMAC-SHA256 signed payloads
• Connections Hub -- Salesforce, Slack, GitHub, PostgreSQL, MQTT, and more
• Audit Trail -- every decision logged with filtering, pagination, replay, and full decision explanations
• GDPR-native, EU AI Act-ready compliance

---

Architecture

Every Nova request passes through five pipeline stages:

           +----------+     +------+     +-----+     +-------+     +------------+
 Request   |  Intent  | --> | Risk | --> | LLM | --> | Trust | --> | Confidence | --> Response
           +----------+     +------+     +-----+     +-------+     +------------+
                |                           |             |               |
           Classify task          Route to best      Cross-model     Score 0-100%
           + detect risk          model (Claude,     evaluation       + autonomy
             keywords             Gemini, GPT,       with circuit     level gate
                                  or BYOLLM)         breaker

1. Intent -- Semantic classification determines the task category and the best-fit model. 2. Risk -- Keyword and pattern analysis flags high-risk operations (delete, deploy, payment). 3. LLM -- The selected model generates the response. Learning cache and RAG context are injected here. 4. Trust -- A separate evaluator model scores the output on accuracy, safety, relevance, and completeness. 5. Confidence -- A composite score determines whether the agent acts autonomously, notifies, waits for approval, or blocks.

---

Quick Start

Installation

TypeScript

npm install @novalabai/adk

Python

pip install novalab-adk

Environment Variables

export NOVA_API_KEY="nv-your-key"

# If self-hosting the server:
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="AIza..."
export OPENAI_API_KEY="sk-..."       # optional, enables GPT routing

---

Code Examples

Basic Agent Run

TypeScript

import { NovaClient } from "@novalabai/adk";

const nova = new NovaClient({
  apiKey: process.env.NOVA_API_KEY!,
  region: "eu-west-1",
});

const agent = await nova.agents.create({
  name: "Risk Analyser",
  description: "Analyses portfolio risk using financial data",
  model: "claude",
  confidenceThresholds: {
    autonomous: 90,
    notify: 70,
    approvalRequired: 50,
  },
});

await nova.agents.deploy(agent.id);

const result = await nova.agents.run(agent.id, {
  input: "Analyse portfolio risk for Q1 2026",
  memory: true,
  learning: true,
});

console.log(`Output:     ${result.output}`);
console.log(`Confidence: ${result.confidence}%`);
console.log(`Model:      ${result.modelUsed}`);
console.log(`Autonomy:   ${result.autonomyLevel}`);
console.log(`Cache Hit:  ${result.cacheHit}`);
console.log(`Audit ID:   ${result.auditId}`);

Python

import asyncio
from novalab_adk import NovaClient

async def main():
    async with NovaClient(api_key="nv-...", region="eu-west-1") as nova:
        agent = await nova.agents.create(
            name="Risk Analyser",
            description="Analyses portfolio risk using financial data",
            model="claude",
            confidence_thresholds={
                "autonomous": 90,
                "notify": 70,
                "approval_required": 50,
            },
        )
        await nova.agents.deploy(agent.id)

        result = await nova.agents.run(
            agent.id,
            input="Analyse portfolio risk for Q1 2026",
            memory=True,
            learning=True,
        )
        print(f"Output:     {result.output}")
        print(f"Confidence: {result.confidence}%")
        print(f"Autonomy:   {result.autonomy_level}")

asyncio.run(main())

---

Multi-Agent Orchestration

// Route to the best agent based on intent
const routed = await nova.orchestrate.route({
  input: "Analyse customer churn for Q4",
  targets: [
    { agentId: "data-agent",    intents: ["analyse", "data", "metrics"] },
    { agentId: "support-agent", intents: ["support", "help", "ticket"] },
    { agentId: "crm-agent",     intents: ["customer", "crm", "lead"] },
  ],
});

// Fan out to multiple agents in parallel
const results = await nova.orchestrate.parallel({
  tasks: [
    { agentId: "data-agent",    input: "Analyse churn rate trends",    label: "trends" },
    { agentId: "crm-agent",     input: "Identify at-risk customers",   label: "at-risk" },
  ],
  merge: "best",
  timeout: 30_000,
  confidenceFloor: 50,
});

// Verify any output through the trust layer
const verified = await nova.orchestrate.verify({
  input: "Summarise Q4 revenue",
  output: results.merged?.result?.output ?? "",
  threshold: 80,
});

// Or compose everything into a single pipeline
const pipeline = await nova.orchestrate.pipeline({
  input: "Analyse customer churn and prepare a retention plan",
  steps: [
    { kind: "route",    params: { input: "", targets: [/* ... */] } },
    { kind: "parallel", params: { tasks: [/* ... */], merge: "best" } },
    { kind: "verify",   params: { input: "", output: "", threshold: 80 } },
  ],
});

---

BYOLLM (Bring Your Own LLM)

Register any OpenAI-compatible endpoint and run it through the full Nova pipeline -- intent classification, risk analysis, trust evaluation, and confidence scoring all still apply.

TypeScript

// Register your custom LLM
const llm = await nova.byollm.register({
  name: "Local Llama",
  api_url: "http://localhost:11434/v1/chat/completions",
  model_name: "llama3",
  format: "openai",
  description: "Self-hosted Llama 3 via Ollama",
});

// Test the connection
const test = await nova.byollm.test(llm.id);
console.log(`Status: ${test.status}, Latency: ${test.latency_ms}ms`);

// Run through the full Nova pipeline
const result = await nova.byollm.run(llm.id, {
  input: "Explain the CAP theorem in distributed systems",
  memory: true,
  allow_training: true,
});

Python

llm = await nova.byollm.register(
    name="Local Llama",
    api_url="http://localhost:11434/v1/chat/completions",
    model_name="llama3",
    format="openai",
)

result = await nova.byollm.run(llm.id, input="Explain the CAP theorem")
print(f"Output: {result.output}")
print(f"Trust:  {result.confidence}%")

---

Training Data Collection

Opt in to training data collection on any agent run with allow_training: true. Review, correct, and export data for fine-tuning.

// 1. Run an agent with training collection enabled
const result = await nova.agents.run(agent.id, {
  input: "Summarise the quarterly earnings report",
  allowTraining: true,
});

// 2. Submit human feedback and corrections
await nova.training.feedback({
  training_id: result.training!.trainingId!,
  audit_id: result.auditId,
  rating: 5,
  feedback: "Accurate and well-structured summary",
  approved: true,
});

// 3. Export approved data for fine-tuning
const exported = await nova.training.export({
  format: "openai_jsonl",    // also: "alpaca", "pairs"
  only_approved: true,
  min_quality: 80,
});

console.log(`Exported ${exported.count} entries`);

---

RAG (Retrieval Augmented Generation)

Ingest documents and have their content automatically retrieved during agent runs.

// Ingest a document (supports plain text; parse PDF/DOCX/CSV before ingesting)
const doc = await nova.rag.ingest({
  title: "Q4 Earnings Report",
  content: documentText,
  chunkSize: 500,
  chunkOverlap: 50,
});

// Query the knowledge base directly
const results = await nova.rag.query({
  query: "What was the revenue growth in Q4?",
  topK: 5,
  similarityThreshold: 0.7,
});

// Or enable RAG on an agent run -- context is injected automatically
const answer = await nova.agents.run(agent.id, {
  input: "Summarise the Q4 earnings highlights",
  rag: true,
  ragDocumentIds: [doc.documentId],
});

---

Agent Tools & Function Calling

Register external APIs as tools and let agents call them autonomously during a run.

TypeScript

// Register a tool
const tool = await nova.tools.create({
  name: "crm-lookup",
  description: "Look up customer details by email",
  endpoint: "https://crm.example.com/api/customers",
  method: "GET",
  parametersSchema: {
    type: "object",
    properties: { email: { type: "string" } },
    required: ["email"],
  },
  authType: "header",
  authValue: "crm_key_123",
  timeout: 5000,
});

// Run an agent with tools -- the LLM decides when to call the tool
const result = await nova.agents.run(agent.id, {
  input: "Get the account status for [e-mail]",
  tools: [tool.id],
});

Python

tool = await nova.tools.create(
    name="crm-lookup",
    description="Look up customer details by email",
    endpoint="https://crm.example.com/api/customers",
    method="GET",
    parameters_schema={"type": "object", "properties": {"email": {"type": "string"}}, "required": ["email"]},
    auth_type="header",
    auth_value="crm_key_123",
)

result = await nova.agents.run(agent.id, input="Get the account status for [e-mail]", tools=[tool.id])

---

Evaluation & Benchmarking

Create test suites to measure agent accuracy, confidence, latency, and cost.

const suite = await nova.eval.createSuite({
  name: "Support Quality",
  testCases: [
    { input: "How do I reset my password?", expectedOutput: "Navigate to Settings > Security > Reset Password", category: "account" },
    { input: "What is your refund policy?", expectedOutput: "Full refund within 30 days of purchase", category: "billing" },
  ],
});

const run = await nova.eval.run(suite.id, { agentId: agent.id, maxConcurrent: 5 });
const results = await nova.eval.getRun(run.runId);
console.log(`Accuracy:   ${results.metrics.accuracy}`);
console.log(`Avg Conf:   ${results.metrics.avg_confidence}%`);
console.log(`Avg Latency: ${results.metrics.avg_latency_ms}ms`);
console.log(`Total Cost: $${results.metrics.total_cost}`);

---

Feature Reference

LLM Semantic Routing

Nova uses an LLM to classify task intent and route to the best model, with keyword-based fallback when the routing LLM is unavailable.

Model	Routed For	Examples
Claude	Reasoning, analysis, code, security, logic	"Analyse security risks", "Debug this function"
Gemini	Creative writing, summarisation, general knowledge	"Write a blog post", "Summarise this article"
GPT	Conversational, casual, quick explanations	"Explain like I'm five", "What is X?"
BYOLLM	Any task when a custom LLM is specified	Overrides routing with your registered endpoint

Confidence Scoring and Autonomy Levels

Score	Level	Behaviour
90-100%	AUTONOMOUS	Executes without intervention
70-89%	NOTIFY	Executes and notifies stakeholders
50-69%	APPROVAL_REQUIRED	Blocked until human approves
0-49%	BLOCKED	Escalated to human, cannot proceed

Thresholds are configurable per agent, per workflow, and per organisation.

Trust Evaluation

Every response is evaluated across four dimensions by a separate model:

Dimension	Weight	Description
Accuracy	30%	Is the output factually correct?
Safety	25%	Does it avoid harmful content?
Relevance	25%	Does it address the original task?
Completeness	20%	Is the response thorough?

The trust evaluator includes a circuit breaker -- if the evaluation model fails repeatedly, the system degrades gracefully (skipping trust scoring and lowering confidence) rather than blocking all requests.

Agent Memory

Agents support three memory scopes:

Scope	Behaviour
session	Context persists within a single session
persistent	Context persists across sessions for the same agent
shared	Context is shared across multiple agents

Enable memory on any run with memory: true. Retrieve or clear memory via nova.agents.getMemory(id) and nova.agents.clearMemory(id).

Learning Cache (Semantic Cache)

When learning: true is set, Nova computes a semantic similarity score against previous Q&A pairs. If a cached answer exceeds the similarity threshold, it is returned instantly -- no LLM call required. This reduces latency and cost for repeated or similar queries.

RAG (Retrieval Augmented Generation)

Ingest documents into Nova's vector store. At query time, the most relevant chunks are retrieved by semantic similarity and injected into the LLM prompt as grounding context.

• Configurable chunk size and overlap
• Top-K retrieval with similarity threshold
• Filter by specific document IDs
• Full document lifecycle (ingest, list, get, delete)

BYOLLM (Bring Your Own LLM)

Register any OpenAI-compatible API endpoint. Nova runs your model through the same 5-layer pipeline (intent, risk, LLM call, trust, confidence) that built-in models use. Supports:

• OpenAI-compatible and raw HTTP formats
• Custom headers and API keys
• Connection testing
• Full pipeline integration (memory, learning cache, RAG, training data)

Training Data Collection

Every agent run can optionally collect training data for fine-tuning:

1. Set allow_training: true on any run
2. Nova records the input/output pair with quality metrics
3. Humans review, rate, correct, and approve entries
4. Export in OpenAI JSONL, Alpaca, or raw pairs format

SSE Streaming

The /v1/agents/{id}/stream endpoint returns server-sent events as each pipeline stage executes. The TypeScript SDK exposes this via nova.agents.stream():

const stream = await nova.agents.stream(agent.id, {
  input: "Analyse the market trends for Q1",
});

for await (const event of stream) {
  console.log(event);
}

Audit Trail

Every decision is logged with full pipeline details. Query the history with filtering and pagination:

const entries = await nova.history.list({
  agentId: "agent-123",
  status: "completed",
  minConfidence: 70,
  startDate: "2026-01-01",
  limit: 50,
  offset: 0,
});

// Get a full decision explanation
const explanation = await nova.history.explain(entries[0].id);

// Replay a previous run
const replayed = await nova.history.replay(entries[0].id);

Webhooks

Subscribe to platform events with HMAC-SHA256 signed payloads:

import { verifyWebhookSignature } from "@novalabai/adk";

// Events: approval.needed | anomaly.detected | agent.run.completed
//         agent.run.failed | workflow.completed | signal.alert
//         automation.triggered | confidence.low

const isValid = verifyWebhookSignature(payload, signature, secret);

---

API Endpoints

Agents

Method	Endpoint	Description
POST	/v1/agents	Create an agent
GET	/v1/agents	List all agents
GET	/v1/agents/{id}	Get an agent
PATCH	/v1/agents/{id}	Update an agent
DELETE	/v1/agents/{id}	Delete an agent
POST	/v1/agents/{id}/deploy	Deploy an agent
POST	/v1/agents/{id}/run	Run an agent
POST	/v1/agents/{id}/stream	Run with SSE streaming
POST	/v1/agents/{id}/pause	Pause a running agent
POST	/v1/agents/{id}/resume	Resume a paused agent
GET	/v1/agents/{id}/memory	Get agent memory
DELETE	/v1/agents/{id}/memory	Clear agent memory

Orchestration

Method	Endpoint	Description
POST	/v1/orchestrate	Server-side multi-agent orchestration

BYOLLM

Method	Endpoint	Description
POST	/v1/llms	Register a custom LLM
GET	/v1/llms	List registered LLMs
GET	/v1/llms/{id}	Get LLM details
DELETE	/v1/llms/{id}	Remove a registered LLM
POST	/v1/llms/{id}/test	Test LLM connectivity
POST	/v1/llms/{id}/run	Run full pipeline with custom LLM

RAG

Method	Endpoint	Description
POST	/v1/rag/documents	Ingest a document
GET	/v1/rag/documents	List all documents
GET	/v1/rag/documents/{id}	Get document with chunks
DELETE	/v1/rag/documents/{id}	Delete a document
POST	/v1/rag/query	Query for relevant chunks
GET	/v1/rag/stats	RAG system statistics

Learning Cache

Method	Endpoint	Description
GET	/v1/learning/cache	View cached entries
GET	/v1/learning/stats	Cache statistics
POST	/v1/learning/query	Query the cache
DELETE	/v1/learning/cache	Clear the cache

Training Data

Method	Endpoint	Description
GET	/v1/training/data	List entries (with filters and pagination)
GET	/v1/training/data/{id}	Get a single entry
DELETE	/v1/training/data/{id}	Delete an entry
DELETE	/v1/training/data	Clear all entries
GET	/v1/training/stats	Training statistics
POST	/v1/training/feedback	Submit feedback/correction
POST	/v1/training/export	Export for fine-tuning

Trust

Method	Endpoint	Description
POST	/v1/trust/evaluate	Evaluate any AI output

History / Audit Trail

Method	Endpoint	Description
GET	/v1/history	List entries (filter by agent, date, status, confidence)
GET	/v1/history/{id}	Get a single entry
GET	/v1/history/{id}/explain	Full decision explanation
POST	/v1/history/{id}/replay	Replay a previous run

Webhooks

Method	Endpoint	Description
POST	/v1/webhooks	Create a webhook
GET	/v1/webhooks	List webhooks
PATCH	/v1/webhooks/{id}	Update a webhook
DELETE	/v1/webhooks/{id}	Delete a webhook

Agent Tools

Method	Endpoint	Description
POST	/v1/tools	Register a tool
GET	/v1/tools	List tools
GET	/v1/tools/{id}	Get a tool
DELETE	/v1/tools/{id}	Delete a tool
POST	/v1/tools/{id}/test	Test tool connectivity

A2A (Agent-to-Agent)

Method	Endpoint	Description
GET	/v1/agents/{id}/card	Get agent capability card
POST	/v1/agents/{id}/call	Call another agent
GET	/v1/a2a/discover	Discover agents by capability
GET	/v1/a2a/messages	A2A message log

Evaluation & Benchmarking

Method	Endpoint	Description
POST	/v1/eval/suites	Create a test suite
GET	/v1/eval/suites	List test suites
GET	/v1/eval/suites/{id}	Get a test suite
PUT	/v1/eval/suites/{id}	Update a test suite
DELETE	/v1/eval/suites/{id}	Delete a test suite
POST	/v1/eval/suites/{id}/run	Run evaluation
GET	/v1/eval/runs	List evaluation runs
GET	/v1/eval/runs/{id}	Get evaluation results

Persistent Storage

Method	Endpoint	Description
POST	/v1/persistence/save	Force save to database
POST	/v1/persistence/load	Force load from database
GET	/v1/persistence/status	Database status and stats
POST	/v1/persistence/export	Export full JSON backup
POST	/v1/persistence/import	Import from backup

Usage & Rate Limiting

Method	Endpoint	Description
GET	/v1/usage	Current usage stats
GET	/v1/usage/costs	Cost breakdown by model
GET	/v1/usage/history	Daily usage history
PUT	/v1/usage/limits	Set rate limits
POST	/v1/usage/reset	Reset usage counters

---

SDK Resources

Both SDKs expose the same resource structure:

nova.agents        -- Create, deploy, run, stream, and manage agents + memory
nova.orchestrate   -- Multi-agent orchestration (route, parallel, verify, pipeline)
nova.multiAgent    -- Server-side orchestration (single-call decomposition)
nova.tools         -- Register, test, and manage agent tools for function calling
nova.a2a           -- Agent-to-agent communication, discovery, and message log
nova.eval          -- Evaluation suites, benchmark runs, and metrics
nova.persistence   -- Force save/load, export/import, and storage status
nova.usage         -- Usage tracking, cost breakdown, rate limits
nova.byollm        -- Register and run custom LLMs through the Nova pipeline
nova.learning      -- Semantic learning cache management
nova.rag           -- Document ingestion and retrieval
nova.training      -- Training data collection, feedback, and export
nova.trust         -- Trust evaluation on any AI output
nova.history       -- Audit trail with filtering, pagination, and replay
nova.workflows     -- Multi-step pipelines with confidence gates
nova.signals       -- Real-time telemetry ingestion and streaming
nova.automations   -- Rule-based automation workflows
nova.connections   -- Third-party integration management
nova.data          -- Dataset upload and natural language querying
nova.webhooks      -- Event subscriptions with HMAC verification

---

Running the Server Locally

Nova includes a full-featured local server for development:

cd Nova
python3 playground/real_server.py

The server starts at http://localhost:4300/v1 with interactive API docs at http://localhost:4300/docs.

A mock server is also available for testing without API keys:

python3 playground/mock_server.py    # port 4200

---

Running Tests

# Python
cd Nova/python && pip install -e ".[dev]" && pytest tests/

# TypeScript
cd Nova/typescript && npm install && npm test

---

Documentation

Full API documentation with request/response examples for every endpoint is available in API_DOCUMENTATION.md.

---

Compliance

• GDPR-native -- data residency in EU, no cross-border transfers without consent
• EU AI Act-ready -- risk classification, transparency obligations, human oversight
• Full audit trail -- every decision logged with timestamp, confidence, reasoning, and trust scores
• Role-based access control -- granular permissions per user, team, and agent
• Signed webhooks -- HMAC-SHA256 payload verification

---

License

MIT

---

NovaLab -- Build AI Workflows You Can Trust