novalab-adk 2.12.0

NovaLab Agent Development Kit — Multi-provider AI with Ollama, Bedrock, Claude, GPT, Gemini + multimodal + training

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

Safety & Governance

• Guardrails & Content Filters -- PII detection and redaction, blocked topic filtering, prompt injection detection, and output safety checks
• Agent Versioning -- immutable version snapshots, one-click deploy and rollback, cross-version performance comparison

Templates & Real-Time

• Prompt Templates & Chains -- reusable prompt templates with {{variable}} placeholders, template chaining for multi-step workflows, variable validation
• Real-Time WebSocket -- full-duplex WebSocket connections for live agent interaction, streaming responses, real-time pipeline step updates

Marketplace

• Agent Marketplace -- pre-built agent templates (8 included), clone-to-deploy, community ratings, category browsing, submit your own templates

Evaluation & Ops

• Evaluation & Benchmarking -- create test suites, run agents against them, and get accuracy, confidence, latency, and cost metrics
• Observability & Tracing -- OpenTelemetry-compatible distributed tracing, per-step span tracking, metrics with p50/p95/p99 percentiles, OTLP/JSON/CSV export
• 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
• Cost Optimization -- model efficiency comparison, optimization suggestions, cost projection, and detailed spending history
• Async Jobs -- background job execution with webhook notifications, queue stats, and full lifecycle management
• Multi-Modal -- image and text analysis with automatic model routing (Gemini for images, Claude for documents)

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}`);

---

Guardrails & Content Filters

Scan inputs for PII and prompt injection, auto-redact sensitive data, and configure per-agent content policies.

TypeScript

// Scan text for PII and prompt injection
const scan = await nova.guardrails.scan({
  text: "My SSN is 123-45-6789",
  checks: ["pii", "injection", "topics"],
});

// Auto-redact PII
const redacted = await nova.guardrails.redact({
  text: "Email me at [e-mail]",
});
console.log(redacted.redacted); // "Email me at [EMAIL_REDACTED]"

// Set per-agent guardrails
await nova.guardrails.setConfig("agent-123", {
  pii_detection: true,
  pii_redaction: true,
  blocked_topics: ["violence"],
  prompt_injection: true,
  content_safety: true,
});

Python

scan = await nova.guardrails.scan(
    text="My SSN is 123-45-6789",
    checks=["pii", "injection", "topics"],
)

redacted = await nova.guardrails.redact(text="Email me at [e-mail]")

await nova.guardrails.set_config("agent-123", {
    "pii_detection": True,
    "blocked_topics": ["violence"],
    "content_safety": True,
})

---

Prompt Templates & Chains

Create reusable prompt templates with variable placeholders and chain them into multi-step workflows.

TypeScript

// Create a template with validated variables
const template = await nova.templates.create({
  name: "greeting", template: "Hello {{name}}, welcome to {{company}}!",
  variables: [{ name: "name", type: "string", required: true }]
});
await nova.templates.run(template.id, { variables: { name: "Alice", company: "Nova" } });

Python

template = nova.templates.create(name="greeting", template="Hello {{name}}!")
nova.templates.run(template["id"], variables={"name": "Alice"})

---

Real-Time WebSocket

Open a full-duplex WebSocket connection for live agent interaction with streaming responses and real-time pipeline step updates.

TypeScript

const session = nova.websocket.connect("agent-id", {
  onMessage: (msg) => console.log(msg),
  onStep: (step) => console.log(step),
});
session.send("Hello!");

---

Agent Marketplace

Browse, clone, and deploy pre-built agent templates. Submit your own templates for the community.

TypeScript

const templates = await nova.marketplace.list({ category: "code" });
await nova.marketplace.clone(templates[0].id);

Python

templates = nova.marketplace.list(category="code")
nova.marketplace.clone(templates[0]["id"])

---

Observability & Tracing

OpenTelemetry-compatible distributed tracing with per-step span tracking and latency percentiles.

TypeScript

const traces = await nova.observability.listTraces({ agent_id: "agent-id" });
const metrics = await nova.observability.getMetrics({ window: "24h" });

Python

traces = nova.observability.list_traces(agent_id="agent-id")
metrics = nova.observability.get_metrics(window="24h")

---

Agent Versioning

Create immutable snapshots of agent configuration, deploy any version, and compare performance across versions.

TypeScript

// Create a version snapshot
const v3 = await nova.agents.createVersion("agent-123", {
  description: "Tuned confidence thresholds",
});

// Deploy a specific version
await nova.agents.deployVersion("agent-123", 2);

// Rollback to previous
await nova.agents.rollback("agent-123");

// Compare performance
const diff = await nova.agents.compareVersions("agent-123", 1, 2);
console.log(`Accuracy delta: ${diff.delta.accuracy}`);

Python

v3 = await nova.agents.create_version("agent-123", description="Tuned thresholds")
await nova.agents.deploy_version("agent-123", 2)
await nova.agents.rollback("agent-123")
diff = await nova.agents.compare_versions("agent-123", 1, 2)

---

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);

Prompt Templates & Chains

Define reusable prompt templates with {{variable}} placeholders and optional validation rules. Chain multiple templates together for multi-step workflows where the output of one step feeds into the next.

• Variable types: string, number, boolean, enum
• Required/optional variable validation
• Template chaining with automatic output-to-input mapping

Real-Time WebSocket

Open a persistent, full-duplex WebSocket connection to interact with agents in real time. Unlike SSE streaming (which is unidirectional), WebSocket sessions allow you to send follow-up messages mid-stream and receive pipeline step updates as they happen.

Agent Marketplace

A library of pre-built agent templates covering common use cases (code review, customer support, data analysis, and more). Clone any template to your account with a single call, customise it, and deploy. Community ratings and category browsing help you find the right starting point. You can also submit your own templates.

Observability & Tracing

OpenTelemetry-compatible distributed tracing for every agent run. Each pipeline step (intent, risk, LLM, trust, confidence) produces a span with timing data. Aggregated metrics include p50, p95, and p99 latency percentiles. Export traces in OTLP, JSON, or CSV format for integration with Grafana, Datadog, or any OpenTelemetry-compatible backend.

---

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

Guardrails & Content Filters

Method	Endpoint	Description
POST	/v1/guardrails/scan	Scan for PII, injection, blocked topics
POST	/v1/guardrails/redact	Auto-redact PII from text
PUT	/v1/guardrails/config/{agent_id}	Set per-agent guardrails
GET	/v1/guardrails/config/{agent_id}	Get agent guardrails
DELETE	/v1/guardrails/config/{agent_id}	Remove custom guardrails
GET	/v1/guardrails/defaults	Get default guardrail settings

Agent Versioning

Method	Endpoint	Description
GET	/v1/agents/{id}/versions	List all versions
POST	/v1/agents/{id}/versions	Create a version snapshot
GET	/v1/agents/{id}/versions/{v}	Get a specific version
POST	/v1/agents/{id}/versions/{v}/deploy	Deploy a version
POST	/v1/agents/{id}/rollback	Rollback to previous version
GET	/v1/agents/{id}/versions/compare	Compare version performance

Async Jobs

Method	Endpoint	Description
POST	/v1/jobs	Submit an async job
GET	/v1/jobs	List jobs (filter by status, type)
GET	/v1/jobs/{id}	Get job status and result
POST	/v1/jobs/{id}/cancel	Cancel a running job
DELETE	/v1/jobs/{id}	Delete a job
GET	/v1/jobs/stats	Queue statistics

Multi-Modal

Method	Endpoint	Description
POST	/v1/multimodal/analyze	Analyze image and text together
POST	/v1/multimodal/upload	Upload file for analysis
GET	/v1/multimodal/supported	List supported formats

Cost Optimization

Method	Endpoint	Description
GET	/v1/costs	Cost summary by period
GET	/v1/costs/optimize	Optimization suggestions
GET	/v1/costs/compare	Model cost efficiency comparison
GET	/v1/costs/projection	Future cost projection
GET	/v1/costs/history	Detailed cost records

Prompt Templates

Method	Endpoint	Description
POST	/v1/templates	Create a prompt template
GET	/v1/templates	List all templates
GET	/v1/templates/{id}	Get a template
PATCH	/v1/templates/{id}	Update a template
DELETE	/v1/templates/{id}	Delete a template
POST	/v1/templates/{id}/run	Execute a template with variables
POST	/v1/templates/chain	Run a template chain

WebSocket

Method	Endpoint	Description
GET	/v1/ws/agents/{id}	Open WebSocket connection for live agent interaction
GET	/v1/ws/sessions	List active WebSocket sessions
DELETE	/v1/ws/sessions/{id}	Close a WebSocket session

Agent Marketplace

Method	Endpoint	Description
GET	/v1/marketplace/templates	Browse marketplace templates
GET	/v1/marketplace/templates/{id}	Get template details
POST	/v1/marketplace/templates/{id}/clone	Clone a template to your account
POST	/v1/marketplace/templates	Submit a template
GET	/v1/marketplace/categories	List categories
POST	/v1/marketplace/templates/{id}/rate	Rate a template

Observability & Tracing

Method	Endpoint	Description
GET	/v1/observability/traces	List distributed traces
GET	/v1/observability/traces/{id}	Get trace with spans
GET	/v1/observability/traces/{id}/spans	List spans for a trace
GET	/v1/observability/metrics	Get aggregated metrics (p50/p95/p99)
POST	/v1/observability/export	Export traces (OTLP/JSON/CSV)

---

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
nova.guardrails    -- PII scanning, redaction, and per-agent content filters
nova.jobs          -- Async job submission, tracking, and queue management
nova.multimodal    -- Image and text analysis with automatic model routing
nova.costs         -- Cost summaries, optimization suggestions, and projections
nova.templates     -- Prompt templates with variable placeholders and chaining
nova.websocket     -- Full-duplex WebSocket connections for live agent interaction
nova.marketplace   -- Browse, clone, and deploy pre-built agent templates
nova.observability -- Distributed tracing, span tracking, and latency metrics

---

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