NOVA is Fractics' secure, multi-tenant platform for building, deploying, and operating grounded AI agents across web, Hybrid RAG, commerce, Shopify, and support workflows.
The repository name remains agentbuilder for engineering purposes, but the product name is NOVA - Agent Builder Platform.
NOVA is a context-aware conversational agent platform by Fractics. It helps teams build grounded AI assistants with hybrid search, evidence-aware answers, structured knowledge bases, memory, product catalogs, embeddable web chat, human takeover, and responsible AI observability.
| Area | Current capability |
|---|---|
| Hybrid RAG | Brand-scoped MongoDB Atlas or Qdrant retrieval, BM25, RRF fusion, reranking, evidence/citation contracts, and explicit no-evidence behavior. |
| Commerce and Shopify | A canonical catalog contract, product/inventory visibility rules, Admin GraphQL catalogue sync, durable webhook processing, reconciliation, and Shopify MCP actions. |
| Vertical agents | Controlled capability boundaries for generic, ecommerce, Shopify, and Lal Kitab agents; Lal Kitab connectors abstain deterministically when validated chart/source data is unavailable. |
| Multi-tenancy | Tenant and brand authorization at API, retrieval, widget-session, WebSocket, and job boundaries. |
| Knowledge lifecycle | Encrypted durable ingestion with leases, retries, idempotency, cancellation, deletion, re-indexing, upload limits, and archive-bomb controls. |
| Operations | Rate-limit and takeover failure safety, non-root service images, security CI gates, SBOM/provenance controls, release documentation, and protected evaluation contracts. |
NOVA's P0–P6 application controls are implemented in this repository. A broad external multi-tenant launch still requires the deployment owner to complete the environment-specific proof in the operations documentation: private Qdrant network placement, cloud workload identity and secret mounting, malware-scanner operation, real deployment smoke tests and recovery drills, the remote Strapi privacy-deletion contract, and staged human or pinned-model quality review.
See the GA Release and Operations Contract and Privacy Lifecycle before deploying outside a controlled environment.
NOVA helps teams create reliable AI agents with:
- Multi-agent architecture for brand-specific and task-specific agents
- Hybrid retrieval using MongoDB Atlas Vector Search or local Qdrant, BM25, RRF fusion, and reranking
- Evidence-aware responses with versioned citations and explicit retrieval-degradation/no-evidence semantics
- Session continuity and memory across conversations
- Structured knowledge bases for products, dealers, FAQs, guides, and documents
- Durable ingestion lifecycle with encryption, idempotency, leases/retries, cancellation, deletion, and re-index support
- Embeddable web widget for deploying agents on external websites
- Shopify Admin GraphQL and MCP bridge for catalog lifecycle and live commerce workflows
- Tenant-bound human takeover for live conversations with signed widget and authenticated admin sessions
- Lal Kitab safety controls with validated-source requirements and deterministic abstention
- Responsible AI observability for rate limits, guardrails, fallbacks, hallucination signals, Strapi sync health, and latency
- Secure data handling with JWT auth, admin API protection, rate limiting, PII handling, and production CORS controls
Website visitor -> apps/widget -> apps/api
Admin user -> apps/admin -> apps/api
Shopify tools -> apps/shopify-mcp -> apps/api / Shopify
apps/api -> MongoDB # documents, agents, memory, knowledge source of truth
apps/api -> Qdrant # local/self-hosted vector search when VECTOR_BACKEND=qdrant
apps/api -> Redis # cache, rate limits, jobs, pub/sub, live handoff
apps/api -> LLM providers # OpenAI, Azure OpenAI, Qwen
apps/api -> Voyage AI # embeddings
apps/api -> Strapi # conversation/session sync, when configured
Core services:
| Service | Path | Default URL | Role |
|---|---|---|---|
| API | apps/api |
http://localhost:8000 | FastAPI backend, chat runtime, retrieval, observability |
| Admin | apps/admin |
http://localhost:3000 | NOVA dashboard for brands, agents, settings, KB, observability |
| Widget | apps/widget |
http://localhost:5174 | Embeddable chat widget |
| Shopify MCP | apps/shopify-mcp |
http://localhost:3005 | Shopify OAuth and MCP bridge |
| Ingestion worker | apps/api image |
internal | Mongo-leased encrypted knowledge ingestion, retry, cancellation, deletion, and re-index jobs |
| Catalog sync worker | apps/api/app/workers/catalog_sync_worker.py |
internal | Mongo-leased Shopify full sync, delete, and uninstall lifecycle work |
| Privacy retention worker | apps/api image |
internal | Enforces first-party retention policies across brand data |
| Strapi privacy worker | apps/api image |
internal | Processes the separately deployed, signed Strapi privacy-deletion contract when enabled |
| MongoDB | Compose service | internal | Agent data, knowledge, memory, source of truth |
| Qdrant | Compose-only internal service | not host-published | Local/self-hosted vector search; requires an API key |
| Redis | Compose service | internal | Rate limits, jobs, pub/sub, session state |
The API image is built from the repository root so it installs the same canonical
packages/ source used in development and CI. There is no API-local copy of
these packages; changes belong in the root tree. The admin, widget, and Shopify
MCP services retain independent build contexts.
agentbuilder/
├── apps/
│ ├── api/ # FastAPI backend and agent runtime service
│ ├── admin/ # React admin dashboard
│ ├── widget/ # React embeddable web widget
│ └── shopify-mcp/ # Shopify MCP bridge
├── packages/
│ ├── agent_runtime/ # Agent orchestration
│ ├── commons/ # Shared types/utilities
│ ├── llm/ # LLM provider adapters
│ ├── memory/ # Memory managers and processors
│ ├── retrieval/ # Hybrid retrieval pipeline
│ └── tools/ # Tool registry and built-in tools
├── scripts/ # Operational setup/verification scripts
├── docs/ # Current architecture and production guides
├── docker-compose.yml # Local full-stack runtime
├── AGENTS.md # Coding-agent instructions
└── README.md # This file
packages/ is the single source of truth for shared Python packages. The legacy
apps/api/packages/ copies are excluded from image builds and must not be used
for runtime changes.
Create .env.docker in the repository root.
Minimum local values:
# Configure one supported inference provider (OpenAI or Azure OpenAI).
OPENAI_API_KEY=sk-...
VOYAGE_API_KEY=pa-...
VOYAGE_BASE_URL=https://api.voyageai.com/v1
SECRET_KEY=<openssl rand -hex 32>
PII_ENCRYPTION_KEY=<openssl rand -hex 32>
SETTINGS_ENCRYPTION_KEY=<openssl rand -hex 32>
ADMIN_API_KEY=<openssl rand -hex 32>
SESSION_SECRET=<openssl rand -hex 32>
MCP_SERVICE_AUTH_TOKEN=<openssl rand -hex 32>
STRAPI_PRIVACY_SUBJECT_HMAC_KEY=<openssl rand -hex 32>
MONGODB_URI=mongodb://mongodb:27017
REDIS_URL=redis://redis:6379
VECTOR_BACKEND=qdrant
QDRANT_URL=http://qdrant:6333
QDRANT_API_KEY=<openssl rand -hex 32>
CORS_ALLOW_ORIGINS=http://localhost:3000,http://localhost:5174
# Local Compose only. Production requires the environment-specific controls
# described in docs/operations/GA_RELEASE_OPERATIONS.md.
ENVIRONMENT=development
DEBUG=false
USE_AZURE_KEYVAULT=false
MALWARE_SCAN_MODE=disabled
STRAPI_PRIVACY_MODE=contract_pending
ALLOW_ADMIN_KEY_BYPASS=falseUse VOYAGE_BASE_URL=https://ai.mongodb.com/v1 when the key is a MongoDB Atlas Model API key.
Optional integrations:
STRAPI_URL=http://host.docker.internal:1337
STRAPI_API_TOKEN=...
SHOPIFY_CLIENT_ID=...
SHOPIFY_CLIENT_SECRET=...
SHOPIFY_WEBHOOK_SECRET=...
FIRECRAWL_API_KEY=...docker compose --env-file .env.docker up -d --buildcurl http://localhost:8000/live
curl http://localhost:8000/health
curl http://localhost:8000/ready
curl http://localhost:3005/healthOpen:
- Admin dashboard: http://localhost:3000
- Widget: http://localhost:5174
- API docs: http://localhost:8000/docs
- Shopify MCP service info: http://localhost:3005
--env-file .env.docker is required because Compose uses the Qdrant API key during service interpolation. The file is local-only and must never be committed. See .env.docker.example for the complete supported configuration.
Run each service directly when you want fast iteration:
cd apps/api && python run.py
cd apps/admin && npm start
cd apps/widget && npm run dev
cd apps/shopify-mcp && npm startWidget runs on port 5174.
For Docker deployments, admin and widget runtime URLs are injected through generated runtime-config.js files at container startup. This keeps browser-safe runtime config separate from secrets and avoids rebuilding frontend images just to change API origins.
The widget can be embedded on an external website with the generated agent snippet from the NOVA admin dashboard.
Typical shape:
<script
src="https://your-widget-domain/embed.js"
data-agent-id="your-agent-id"
data-api-url="https://your-api-domain"
async
></script>For local testing, use the widget service at http://localhost:5174.
NOVA supports structured and unstructured knowledge sources:
- Products
- Dealers
- FAQs
- Office locations
- Categories
- Guides and documents
Retrieval combines:
- MongoDB Atlas Vector Search
- BM25 keyword search
- Reciprocal Rank Fusion
- Reranking
- Content-type and brand-aware boosts
- Groundedness and source-validation checks
For MongoDB Atlas Vector Search, create a vector index on the knowledge_base collection with:
- index name:
vector_index - vector field:
embeddings - dimensions:
1024 - similarity:
cosine - useful filters:
agent_id,brand_id,brand_slug,doc_id,content_type
NOVA includes operational controls for enterprise-grade agents:
- Rate limiting by policy, brand, agent, IP/user, and conversation
- Guardrail tracking by action and reason
- Fallback tracking by stage and reason
- Hallucination-management signals such as groundedness and low-confidence responses
- Strapi sync health by operation and status
- Message latency by mode and status
- Low-cardinality Prometheus metrics
- Dashboard-level observability in the admin app
Run service-specific tests from each app/package.
API:
cd apps/api
pytest tests/Admin:
cd apps/admin
npm testWidget:
cd apps/widget
npm testFull container build:
docker compose --env-file .env.docker build api admin widget shopify catalog-sync-workerRecommended Azure layout:
- API: Azure Container Apps or App Service for Containers
- Admin: Azure Static Web Apps, App Service, or containerized nginx
- Widget: Azure Static Web Apps, Storage Static Website + CDN, or containerized nginx
- Shopify MCP: separate Azure Container App or App Service for Containers
- MongoDB: MongoDB Atlas
- Local/self-hosted vector search: Qdrant
- Redis: Azure Cache for Redis
- Secrets: Azure Key Vault
- Edge/TLS: Azure Front Door or Application Gateway
For independent Azure container deployments, configure each service through Azure Container Apps/App Service environment variables or Key Vault references. Root .env.docker is only for local Docker Compose and should not be required by deployed service containers.
Keep Strapi deployed separately from this repository. Strapi is expected to run from the agentbuilder-strapi repository.
Current docs:
- Server Startup Guide
- Database Setup
- Production Readiness Guide
- Vector Database Architecture
- Hybrid RAG Workflow
- API Documentation
- Generated OpenAPI 3.1 Contract
- Generated Postman Collection
- Canonical Source and API Contract
- GA Release and Operations Contract
- Agent/Coding Contracts
NOVA is built and owned by Fractics (fractics.com).
The code is released under the GNU Affero General Public License v3.0 or later. You can self-deploy, use, study, modify, and share NOVA under the terms of the AGPL.
The NOVA and Fractics names, logos, product identity, and brand assets remain owned by Fractics. The AGPL covers the code; it does not grant trademark rights or permission to present a hosted, managed, white-label, or commercial resale offering as the official NOVA product.
For commercial hosting, managed services, white-label use, resale, or brand permissions, contact Fractics. See TRADEMARKS.md.
Public product name:
NOVA - Agent Builder Platform
Internal engineering name:
agentbuilder
Suggested short description:
NOVA is a context-aware conversational agent platform that helps brands deploy grounded AI assistants with hybrid search, memory, product catalogs, human takeover, and responsible AI observability.
Built by Fractics for reliable, grounded, context-aware AI agents.
