nat-engine 1__py3-none-any.whl

mannf/weights/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+# Backward-compatible shim — source of truth has moved to mannf.product.weights
+from mannf.product.weights import *  # noqa: F401, F403

mannf/weights/registry.py

@@ -0,0 +1,9 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+# Backward-compatible shim — source of truth has moved to mannf.product.weights.registry
+import sys
+import mannf.product.weights.registry as _real
+sys.modules[__name__] = _real

mannf/weights/store.py

@@ -0,0 +1,9 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+# Backward-compatible shim — source of truth has moved to mannf.product.weights.store
+import sys
+import mannf.product.weights.store as _real
+sys.modules[__name__] = _real

nat_engine-1.dist-info/METADATA

@@ -0,0 +1,555 @@
+Metadata-Version: 2.4
+Name: nat-engine
+Version: 1
+Summary: NeuroAgentTest (NAT) — AI-powered API testing with multi-agent neural networks, OWASP security scanning, and adaptive test allocation
+Author-email: NAT Contributors <licensing@nat-testing.io>
+License: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/bg-playground/MultiAgent-Neural-Network-Framework
+Project-URL: Documentation, https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/tree/main/docs
+Project-URL: Repository, https://github.com/bg-playground/MultiAgent-Neural-Network-Framework
+Project-URL: Issues, https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/issues
+Project-URL: Changelog, https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/blob/main/CHANGELOG.md
+Keywords: api-testing,security-scanning,owasp,neural-network,multi-agent,bdi,testing,quality-assurance,openapi,graphql
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Security
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy>=1.24
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.34
+Requires-Dist: python-multipart>=0.0.18
+Requires-Dist: opentelemetry-api>=1.20
+Requires-Dist: azure-monitor-opentelemetry>=1.6
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: alembic>=1.13
+Requires-Dist: defusedxml>=0.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-playwright>=0.4.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1; extra == "dev"
+Requires-Dist: respx>=0.22; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: stripe>=8.0; extra == "dev"
+Requires-Dist: Pillow>=11.0; extra == "dev"
+Requires-Dist: strawberry-graphql[fastapi]>=0.220; extra == "dev"
+Requires-Dist: PyJWT>=2.8; extra == "dev"
+Requires-Dist: slowapi>=0.1.9; extra == "dev"
+Requires-Dist: jinja2>=3.1; extra == "dev"
+Provides-Extra: billing
+Requires-Dist: stripe>=8.0; extra == "billing"
+Provides-Extra: azure-storage
+Requires-Dist: azure-storage-blob>=12.19; extra == "azure-storage"
+Provides-Extra: observability
+Requires-Dist: psutil>=5.9; extra == "observability"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40.0; extra == "browser"
+Requires-Dist: Pillow>=11.0; extra == "browser"
+Provides-Extra: grpc
+Requires-Dist: grpcio-tools>=1.60; extra == "grpc"
+Dynamic: license-file
+
+# NeuroAgentTest (NAT)
+
+> **AI-powered API testing that learns, adapts, and finds the vulnerabilities your static tools miss.**
+
+[![PyPI](https://img.shields.io/pypi/v/nat-engine)](https://pypi.org/project/nat-engine/)
+[![Python](https://img.shields.io/pypi/pyversions/nat-engine)](https://pypi.org/project/nat-engine/)
+[![CI](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/actions/workflows/e2e-regression.yml/badge.svg)](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/actions/workflows/e2e-regression.yml)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/blob/main/LICENSE)
+[![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?logo=docker)](https://github.com/bg-playground/MultiAgent-Neural-Network-Framework/pkgs/container/nat-engine)
+
+NAT is an open-source, **multi-agent neural network framework** for automated API testing and security scanning. Powered by BDI (Belief-Desire-Intention) agents and the Extended Contract Net Protocol (ECNP), NAT continuously learns from test results to focus coverage where risk is highest — so your team ships faster with fewer surprises.
+
+---
+
+## 🎯 Demo Mode
+
+See NAT in action with a single command:
+
+```bash
+nat demo
+# or with Docker:
+docker run -p 8080:8080 ghcr.io/bg-playground/nat-engine:demo
+```
+
+The dashboard opens automatically with live agent activity, risk heatmaps, security findings, and more. Works offline — perfect for sales demos and conferences.
+
+👉 [Full demo guide](docs/guides/demo-mode.md)
+
+---
+
+## 📸 Dashboard Preview
+
+NAT's web dashboard gives you full visibility into scan results, agent activity, and security findings.
+
+### Risk Overview & Anomaly Detection
+![Dashboard Overview](docs/assets/dashboard-overview-top.png)
+> The Overview tab shows total scans, endpoints discovered, pass/fail rates, health score, and a real-time anomaly feed — all at a glance.
+
+### Multi-Agent Activity
+![Agent Activity](docs/assets/dashboard-agents-dark.png)
+> Watch BDI agents (Planner, Executor, Analyzer, Coordinator) reason about uncertainty and update their beliefs as they learn from each test result.
+
+### OWASP Security Findings
+![Security Findings](docs/assets/dashboard-security.png)
+> Automated OWASP API Security Top 10 checks with severity breakdown, confidence scores, and actionable remediation guidance.
+
+### Security Finding Detail
+![Security Detail](docs/assets/dashboard-security-detail.png)
+> Drill into any finding to see evidence, CWE mapping, and specific remediation steps.
+
+---
+
+## 30-Second Quickstart
+
+```bash
+# 1. Install
+pip install nat-engine
+
+# 2. Scan an API
+nat scan \
+  --spec examples/petstore-openapi.yaml \
+  --base-url https://petstore3.swagger.io/api/v3
+
+# 3. Security audit
+nat security-scan \
+  --spec examples/petstore-openapi.yaml \
+  --base-url https://petstore3.swagger.io/api/v3
+```
+
+That's it — NAT parses your OpenAPI spec, distributes test tasks across its agent network, scores risk, and reports findings. Full docs at [`docs/`](docs/README.md).
+
+---
+
+## Feature Highlights
+
+| Feature | Description |
+|---|---|
+| 🤖 **BDI Multi-Agent Engine** | PlannerAgent, ExecutorAgent, AnalyzerAgent, and CoordinatorAgent collaborate via ECNP to maximize coverage |
+| 📐 **REST + GraphQL + gRPC Testing** | OpenAPI/Swagger, GraphQL introspection, and `.proto`-based gRPC scanning (unary, streaming, bidi) — no "coming soon" |
+| 🔒 **OWASP API Top 10** | 10 automated security checks (BOLA, Broken Auth, Mass Assignment, SSRF, and more) + 5 GraphQL-specific checks |
+| 🧠 **Belief-Driven Prioritization** | Neural networks predict which endpoints are highest risk and allocate test budget accordingly |
+| 📊 **Risk Scoring + Anomaly Detection** | Continuous scoring with latency spike, status-shift, and error-rate anomaly alerts |
+| 🎯 **Confidence Calibration** | Per-finding confidence scores with calibration tuning and statistical confidence intervals |
+| 🔑 **Flexible Auth** | No auth, API key, Bearer token, OAuth 2.0 (client credentials & password grant), SSO (OIDC/SAML) |
+| 🏢 **RBAC & Multi-Tenant** | Role-based access control (admin/operator/viewer), SSO, tenant isolation, and audit logging |
+| 👷 **Worker Pools** | Parallel distributed test execution via `nat worker launch` — scale across multiple agents |
+| 📤 **11 Exporters** | Push findings to Jira, Linear, GitHub Issues, GitLab, Azure DevOps, Shortcut, ServiceNow, PagerDuty, Webhook, Sentry, and Bugzilla |
+| 🕐 **Scheduled Scans** | Cron-based recurring scan schedules — backend implemented, API surface in Phase 9.4 |
+| 🌐 **Functional Testing** | Browser-based E2E test execution with DOM snapshots, screenshots, and interaction traces via Playwright |
+| 🖼️ **Visual Regression** | Pixel-diff analysis against stored baselines — catch unexpected UI changes automatically |
+| ♿ **Accessibility Scanning** | WCAG 2.1 compliance checks integrated into every browser-based scan |
+| ⚡ **Performance Testing** | Core Web Vitals measurement: LCP, FCP, TTI, CLS, TBT — every scan, every page |
+| 🐳 **Docker-Ready** | One-command server deployment; shared across the team |
+| ⚙️ **CI/CD Integration** | Native GitHub Actions support, Allure/CTRF export, PR annotations, and quality gates |
+| 🧙 **Setup Wizard** | `nat setup` interactive onboarding wizard and `nat doctor` pre-flight environment validation |
+| 🎬 **Demo Mode** | `nat demo` and `scripts/demo_orangehrm.py` for a live OrangeHRM E2E demo — no setup required |
+| 📈 **Web Dashboard** | Live risk heatmaps, belief visualization, anomaly timeline, and go-live status |
+| 🖥️ **REST API Server** | FastAPI server exposes all NAT capabilities as HTTP endpoints with RBAC and audit trail |
+
+---
+
+## Comparison vs. Competitors
+
+| Capability | NAT | Postman | SoapUI | Burp Suite |
+|---|---|---|---|---|
+| OpenAPI spec scanning | ✅ | ✅ | ✅ | ⚠️ limited |
+| GraphQL support | ✅ | ✅ | ❌ | ⚠️ limited |
+| gRPC support | ✅ | ❌ | ❌ | ❌ |
+| OWASP API Top 10 | ✅ | ❌ | ⚠️ | ✅ |
+| Adaptive AI prioritization | ✅ | ❌ | ❌ | ❌ |
+| Risk scoring + anomaly detection | ✅ | ❌ | ❌ | ❌ |
+| Confidence calibration | ✅ | ❌ | ❌ | ❌ |
+| Browser functional testing | ✅ | ❌ | ❌ | ❌ |
+| Visual regression testing | ✅ | ❌ | ❌ | ❌ |
+| Accessibility scanning (WCAG) | ✅ | ❌ | ❌ | ❌ |
+| Performance testing (Web Vitals) | ✅ | ❌ | ❌ | ❌ |
+| Worker pools (parallel execution) | ✅ | ❌ | ❌ | ❌ |
+| 11 issue-tracker exporters | ✅ | ❌ | ❌ | ⚠️ limited |
+| Scheduled / recurring scans | ✅ | ✅ | ❌ | ❌ |
+| RBAC + multi-tenant + SSO | ✅ | ✅ | ❌ | ❌ |
+| OAuth 2.0 auth | ✅ | ✅ | ✅ | ✅ |
+| CI/CD GitHub Action + quality gates | ✅ | ✅ | ❌ | ❌ |
+| Allure / CTRF report export | ✅ | ❌ | ❌ | ❌ |
+| Docker deployment | ✅ | ❌ | ⚠️ | ❌ |
+| Open source (AGPL) | ✅ | ❌ | ✅ | ❌ |
+| Programmatic Python API | ✅ | ❌ | ❌ | ❌ |
+
+---
+
+## Installation
+
+**pip (recommended):**
+```bash
+pip install nat-engine
+```
+
+**With optional extras:**
+```bash
+# Browser functional testing + visual regression + accessibility + performance
+pip install "nat-engine[browser]"
+
+# gRPC scanning support
+pip install "nat-engine[grpc]"
+
+# All optional extras
+pip install "nat-engine[browser,grpc,billing,observability]"
+```
+
+**Docker:**
+```bash
+docker run -p 8080:8080 ghcr.io/bg-playground/nat-engine:latest
+```
+
+**From source:**
+```bash
+git clone https://github.com/bg-playground/MultiAgent-Neural-Network-Framework.git
+cd MultiAgent-Neural-Network-Framework
+pip install -e ".[dev]"
+```
+
+See [`docs/getting-started/installation.md`](docs/getting-started/installation.md) for full details.
+
+### Configuration
+
+Copy the example environment file and customize it:
+
+```bash
+cp .env.example .env
+# Edit .env with your settings
+```
+
+See [`.env.example`](.env.example) for all available configuration options, including database, authentication, rate limiting, webhooks, LLM integration, and exporter settings.
+
+> **Note:** If `DATABASE_URL` is not set, NAT runs in in-memory mode and all scan data is lost on restart. Set `DATABASE_URL` to a PostgreSQL connection string for persistent storage.
+
+---
+
+## Usage Examples
+
+### REST API scan
+
+```bash
+nat scan \
+  --spec openapi.yaml \
+  --base-url https://api.example.com \
+  --auth-token $API_TOKEN \
+  --output json
+```
+
+### GraphQL scan
+
+```bash
+nat scan \
+  --type graphql \
+  --base-url https://api.example.com/graphql \
+  --graphql-introspection
+```
+
+### OWASP security audit
+
+```bash
+nat security-scan \
+  --spec openapi.yaml \
+  --base-url https://api.example.com \
+  --severity-threshold high \
+  --output markdown
+```
+
+### OAuth 2.0 authenticated scan
+
+```bash
+nat scan \
+  --spec openapi.yaml \
+  --base-url https://api.example.com \
+  --oauth2-token-url https://auth.example.com/oauth/token \
+  --oauth2-client-id $CLIENT_ID \
+  --oauth2-client-secret $CLIENT_SECRET
+```
+
+### GitHub Actions integration
+
+```yaml
+- uses: bg-playground/MultiAgent-Neural-Network-Framework@main
+  with:
+    spec: openapi.yaml
+    base-url: https://staging.example.com
+    security-scan: 'true'
+    fail-on-severity: high
+    output: allure           # also supports: ctrf, junit, html, json
+    fail-if: "critical > 0 OR risk_score > 0.8"  # quality gate expression
+```
+
+### gRPC scan
+
+```bash
+nat scan \
+  --proto services/auth.proto \
+  --grpc-endpoint grpc://localhost:50051 \
+  --output json
+```
+
+### Worker pool (parallel distributed execution)
+
+```bash
+# Launch a worker pool of 4 agents
+nat worker launch --concurrency 4
+
+# Check pool status
+nat worker status
+```
+
+### Export findings to an issue tracker
+
+```bash
+# List available exporters
+nat export list
+
+# Push findings to Jira
+nat security-scan \
+  --spec openapi.yaml \
+  --base-url https://api.example.com \
+  --export jira \
+  --export-config jira_url=https://myco.atlassian.net \
+  --export-config jira_project_key=SEC
+```
+
+### Setup wizard and environment validation
+
+```bash
+# Interactive first-time setup
+nat setup
+
+# Validate your environment before a scan
+nat doctor
+```
+
+### Programmatic Python API
+
+```python
+import asyncio
+from mannf.integrations.http_sut import HttpApiSUT
+from mannf.integrations.openapi_parser import OpenApiParser
+from mannf.integrations.auth import BearerTokenAuth
+from mannf.testing.models import TestSuite
+
+async def main():
+    auth = BearerTokenAuth("my-token")
+    sut = HttpApiSUT(base_url="https://api.example.com", auth=auth)
+    parser = OpenApiParser(spec_path="openapi.yaml", base_url="https://api.example.com",
+                           registry=sut.registry)
+    test_cases = parser.parse()
+
+    suite = TestSuite(name="My API")
+    for tc in test_cases:
+        suite.add_case(tc)
+        result = await sut.execute(tc)
+        suite.record_result(result)
+
+    s = suite.summary()
+    print(f"Passed: {s['passed']}/{s['total']} ({s['pass_rate']*100:.1f}%)")
+
+asyncio.run(main())
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        NATOrchestrator                          │
+│                                                                 │
+│  ┌───────────────┐  TASK_ANNOUNCEMENT  ┌──────────────────────┐│
+│  │ PlannerAgent  │────────────────────▶│ CoordinatorAgent     ││
+│  │               │                    │                      ││
+│  │ Predictor NN  │◀── CONTRACT_RESULT ─│ ECNP bid collection  ││
+│  │ BeliefState   │                    │ + award logic        ││
+│  └───────────────┘                    └──────────┬───────────┘│
+│                                                  │             │
+│                               CONTRACT_AWARD     │             │
+│                                                  ▼             │
+│                                     ┌─────────────────────┐   │
+│                                     │ ExecutorAgent (×N)  │   │
+│                                     │                     │   │
+│                                     │ Oracle NN + BDI     │   │
+│                                     │ Bids on tasks       │   │
+│                                     └──────────┬──────────┘   │
+│                                                │               │
+│                           TEST_RESULT /        │               │
+│                           CONTRACT_RESULT      │               │
+│                                                ▼               │
+│  ┌───────────────┐◀─ BELIEF_UPDATE ── ┌─────────────────────┐ │
+│  │ PlannerAgent  │                    │ AnalyzerAgent (×M)  │ │
+│  │ (belief sync) │                    │                     │ │
+│  └───────────────┘                    │ Autoencoder NN      │ │
+│                                       │ Anomaly detection   │ │
+│                                       │ BeliefState update  │ │
+│                                       └─────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+         │ async pub/sub Message Bus │
+         ▼                           ▼
+┌──────────────────┐    ┌──────────────────────────┐    ┌──────────────────┐
+│  HttpApiSUT      │    │  GraphQLSUT              │    │  GrpcSUT         │
+│  (REST / OpenAPI)│    │  (GraphQL / introspect)  │    │  (.proto / gRPC) │
+└──────────────────┘    └──────────────────────────┘    └──────────────────┘
+         │
+         ▼
+┌───────────────────────────────────┐   ┌──────────────────────────────────┐
+│  SecurityScanner                  │   │  FunctionalTestOrchestrator      │
+│  OWASP API1–API10 + GRAPHQL 1–5  │   │  Visual Regression + A11y + Perf │
+└───────────────────────────────────┘   └──────────────────────────────────┘
+```
+
+---
+
+## Documentation
+
+The full documentation lives in [`docs/`](docs/README.md):
+
+| Section | Contents |
+|---|---|
+| [Getting Started](docs/getting-started/quickstart.md) | Install and first scan |
+| [Guides](docs/guides/cli-reference.md) | CLI, REST API, Docker, CI/CD, Dashboard |
+| [API Reference](docs/api-reference/rest-api.md) | REST endpoints, Python API, GitHub Action |
+| [How-To](docs/how-to/run-security-audit.md) | Step-by-step task recipes |
+| [Concepts](docs/concepts/architecture.md) | Architecture, BDI agents, neural networks |
+| [Troubleshooting](docs/troubleshooting/common-issues.md) | Common problems and solutions |
+| [FAQ](docs/faq.md) | Frequently asked questions |
+| [Changelog](docs/changelog.md) | Release history |
+| [Contributing](docs/contributing.md) | How to contribute |
+
+---
+
+## Project Structure
+
+```
+src/mannf/
+├── core/
+│   ├── agents/          # BDI agent implementations (Planner, Executor, Analyzer, Coordinator)
+│   │   ├── worker_pool.py       # WorkerPool — parallel distributed test execution
+│   │   └── autonomous_loop_agent.py  # Autonomous multi-iteration test loop
+│   ├── anomaly/         # Enhanced anomaly detection (latency, status, payload, error rate)
+│   ├── browser/         # Playwright-based functional testing engine
+│   │   ├── functional_test_orchestrator.py  # Visual regression, accessibility, performance
+│   │   └── security_scenario_generator.py
+│   ├── prioritization/  # BeliefPrioritizer, RiskScorer, confidence calibration
+│   └── validation/      # Self-validation runner
+├── product/
+│   ├── cli.py           # nat CLI (scan, security-scan, worker, export, setup, doctor, demo, …)
+│   ├── server.py        # FastAPI REST API server with RBAC middleware
+│   ├── dashboard/       # Web dashboard (risk heatmaps, belief charts, go-live status)
+│   ├── exporters/       # 11 built-in exporters
+│   │   ├── jira_exporter.py
+│   │   ├── linear_exporter.py
+│   │   ├── github_exporter.py
+│   │   ├── gitlab_exporter.py
+│   │   ├── azuredevops_exporter.py
+│   │   ├── shortcut_exporter.py
+│   │   ├── servicenow_exporter.py
+│   │   ├── pagerduty_exporter.py
+│   │   ├── webhook_exporter.py
+│   │   ├── sentry_exporter.py
+│   │   └── bugzilla_exporter.py
+│   ├── ingestors/       # OpenAPI, GraphQL, gRPC (.proto), WebSocket, traffic (HAR/mitmproxy)
+│   ├── integrations/    # HttpApiSUT, GraphQLSUT, GrpcSUT, WebSocketSUT, auth providers
+│   ├── scheduling/      # Cron-based scheduled scans, JobQueue (in-memory/SQLite/Redis)
+│   ├── billing/         # Stripe integration, plan tiers, tenant manager
+│   ├── auth/            # OIDC/SAML SSO, RBAC middleware, audit logging
+│   ├── formatters/      # Allure, CTRF, JUnit, HTML report formatters
+│   └── middleware/      # Tenant isolation, audit middleware
+action/              # GitHub Action entrypoint and result parser (PR annotations, quality gates)
+action.yml           # Composite GitHub Action definition
+scripts/
+├── demo_orangehrm.py    # Live OrangeHRM E2E demo — login, CRUD, leave, recruitment
+└── demo.sh / demo.bat   # Quick-start demo launchers
+Dockerfile           # Multi-stage production image
+docker-compose.yml   # Local development Compose file
+examples/
+├── petstore-openapi.yaml     # Sample OpenAPI spec
+├── graphql-schema.graphql    # Sample GraphQL schema
+├── python/                   # Programmatic usage examples
+└── workflows/                # Example GitHub Actions workflows
+docs/                         # Full documentation
+├── guides/
+│   ├── grpc-scanning.md      # gRPC scanning guide (proto parsing, TLS, RPC types)
+│   └── demo-mode.md          # Demo mode walkthrough
+└── demos/
+    └── orangehrm.md          # OrangeHRM live demo guide
+```
+
+---
+
+## Requirements
+
+- Python ≥ 3.10
+- NumPy ≥ 1.24
+- No GPU, no PyTorch, no external ML dependencies
+
+**Optional extras:**
+- `[browser]` — Playwright ≥ 1.40, Pillow ≥ 11 (functional testing, visual regression, accessibility, performance)
+- `[grpc]` — grpcio-tools ≥ 1.60 (`.proto` file parsing for gRPC scanning)
+- `[billing]` — stripe ≥ 8.0 (usage-based billing)
+- `[observability]` — psutil ≥ 5.9 (system metrics)
+
+---
+
+## 🚀 Deployment
+
+NAT runs on Azure Container Apps with automatic scaling and managed TLS.
+
+- **Setup guide:** [`deploy/azure/README.md`](deploy/azure/README.md) — complete step-by-step instructions
+- **One-command setup:** `cd deploy/azure && ./setup.sh` — idempotent bootstrap script
+- **Custom domain:** `cd deploy/azure && ./custom-domain.sh` — configure `api.nat-testing.io`
+- **CI/CD pipeline:** Push to `main` → Docker build → GHCR push → ACA deploy → health check
+
+---
+
+## Thesis Reference
+
+> Guider, J. B. (1999). *A Multi-Agent Neural Network Framework for Adaptive
+> Testing of Large-Scale Distributed Software Systems*. Doctoral dissertation,
+> UCL / Florida State University Joint Programme.
+
+Key results from the original thesis (Chapter 6, Table 6.1):
+
+| Configuration | Coverage | Faults Found | Time |
+|---|---|---|---|
+| Scripted Regression | 68.4% | 71.2% | 112 min |
+| MAS (No Learning) | 74.1% | 78.5% | 94 min |
+| **NAT (Learning Enabled)** | **91.3%** | **93.0%** | **51 min** |
+
+---
+
+## License
+
+NeuroAgentTest (NAT) is dual-licensed:
+
+- **[AGPL-3.0-or-later](LICENSE)** — for open-source projects, academic research, and personal use.
+- **[Commercial License](COMMERCIAL_LICENSE.md)** — for proprietary products and SaaS deployments where AGPL-3.0 copyleft obligations are not acceptable.
+
+For commercial licensing inquiries, contact **licensing@nat-testing.io**.
+
+All contributors must agree to the [Contributor License Agreement (CLA)](CLA.md).
+
+See [docs/faq.md](docs/faq.md#licensing--community) for licensing FAQs, including information on internal use, CI/CD pipelines, and the CLA.
+
+A `NOTICE` file listing all third-party dependency licenses is included in the repository root ([NOTICE](NOTICE)).