Nexus: Orchestrator-Native AI Agentic Framework
Nexus is an autonomous AI agentic software engineering framework that turns requirements into runnable full-stack application scaffolds that you then review, test and harden. It provisions a full virtual IT department (BA, Solution Architect, Data Architect, UI Designer, Full-Stack Engineer, DevOps, and QA) and offers read only audit, blast radius, guardrail and ROI tools to Claude Code, Cursor, Codex, and Gemini via the Model Context Protocol (MCP).
- Platform Website & Docs: nexus.abburi.info
- Live Stage 1–3 Simulator: nexus.abburi.info/#simulator
- Brownfield AST Explorer: nexus.abburi.info/#brownfield
🚀 Installation & Quickstart
Python Framework (PyPI)
Install the core orchestrator and agent runtime:
pip install nexus-agent-framework
TypeScript / React Packages (npm)
Install individual enterprise contracts, UI components, and security middleware:
npm install @nexus-agent-framework/contracts
npm install @nexus-agent-framework/middleware
npm install @nexus-agent-framework/scraper
npm install @nexus-agent-framework/ui
🏛️ The Nexus Virtual IT Squad
Nexus simulates a real-world software engineering organization with 7 autonomous specialists working sequentially to deliver end-to-end applications:
flowchart TD
User["Creator with an Idea<br/>(Vague Requirements)"] --> BA["1. Business Analyst<br/>(User Stories & Interactive HTML Mockup)"]
BA --> SA["2. Solution Architect<br/>(System Topology & Cloud Choice)"]
SA --> DA["3. Data Architect<br/>(ERD & SQL DDL Schema)"]
DA --> Design["4. UI/UX Designer<br/>(Design Tokens & Component Specs)"]
Design & DA --> FS["5. Full-Stack Engineer<br/>(React UI + FastAPI Backend)"]
SA & DA --> DevOps["6. DevOps Engineer<br/>(Terraform IaC for target cloud)"]
FS & DevOps --> QA["7. QA & Security Engineer<br/>(Test Suite, run for real, & Security Review)"]
QA --> Repo["Delivered Application Workspace<br/>(Runnable Full-Stack Project on Disk)"]
Specialist Responsibilities
- Business Analyst (
BusinessAnalystAgent): Synthesizes ideas into a canonical slug, value proposition, user stories, and an interactive HTML wireframe preview (docs/preview_mockup.html). - Solution Architect (
SolutionArchitectAgent): Evaluates cloud runtime topology (Cloud Run serverless containers vs Always-Free VM), networking, and latency budgets. - Data Architect (
DataArchitectAgent): Normalizes relational schemas, foreign keys, indexes, and emits PostgreSQL SQL DDL (docs/DATA_ARCHITECTURE.md). - UI/UX Designer (
UiDesignerAgent): Produces responsive design tokens and Tailwind component structures utilizing@nexus-agent-framework/ui. - Full-Stack Engineer (
FullStackEngineerAgent): Implements clean FastAPI REST endpoints, Pydantic validation schemas, SQLAlchemy ORM entities, and React UI components. - DevOps Engineer (
DevopsEngineerAgent): Decides the app specific inputs (docker-compose.yml, whether the backend calls Vertex AI, which runtime secrets it reads). The files that encode platform policy are rendered from fixed templates, not written by the model: Terraform that calls thenexus_appandnexus_cloud_runmodules (scale to zero, max 2 instances, CPU billed per request, image tag required, Secret Manager access per secret, Vertex AI granted only when needed), abackend/Dockerfilethat runs as a non root user on port 8080, and a localscripts/deploy.shthat builds, tags the image with the git SHA and applies Terraform. No CI workflow is generated. - QA & Security Engineer (
QaEngineerAgent): Reviews the code for security issues and writes apytestsuite for the generated backend. When the workspace is written to disk, Nexus runs that suite for real (see Stage 1); the QA gate passes only if the tests pass and the review passes.
📦 Ecosystem Packages
Nexus is maintained as a unified monorepo providing full-stack libraries across PyPI and npm:
| Package | Registry | Version | Capabilities |
|---|---|---|---|
nexus-agent-framework |
PyPI | 0.4.0 in this repo (PyPI currently serves 0.1.1) |
Core orchestrator, 7 specialist agents, Stage 1–3 self-healing/brownfield/ROI, CLI (dream, mcp, ui, audit, refactor, metrics) |
@nexus-agent-framework/contracts |
npm | 1.0.3 |
Telemetry schemas, Stage 1–3 healing/AST/ROI contracts, agent audit chains |
@nexus-agent-framework/middleware |
npm | 1.0.2 |
Security headers, best effort credential sanitizer, correlation tracing |
@nexus-agent-framework/scraper |
npm | 1.0.2 |
Polite web scraping protocols, RSS feed ingestion, rate limits & backoff policies |
@nexus-agent-framework/ui |
tarball at tag ui-v1.0.0 (releases/); npm still serves 0.2.0 |
1.0.0: shared React kit for the platform apps (Button, form fields, Card, Table, Sheet, Dialog, Tabs, AppShell, Toast, SkeletonRows, EmptyState, ErrorState, Badge, Stat, LineChart); the showcase components moved to @nexus-agent-framework/ui/showcase |
|
@nexus-agent-framework/tokens |
tarball at tag ui-v1.0.0 (releases/) |
1.0.0: design tokens as CSS variables with light and dark themes per app, Tailwind 3 and 4 presets, AA tested |
🔌 Orchestrator-Native: Claude Code, Cursor & Gemini Integration
Nexus exposes a set of read only tools to AI code editors via the Model Context Protocol (MCP):
# Launch Nexus as an MCP server
nexus mcp
Editor Configuration (.cursor/mcp.json or claude_desktop_config.json)
{
"mcpServers": {
"nexus": {
"command": "nexus",
"args": ["mcp"],
"env": {
"GCP_PROJECT_ID": "your-gcp-project-id"
}
}
}
}
The server registers five tools, all read only:
| Tool | What it does |
|---|---|
nexus_check_ai |
Checks Vertex AI / Gemini connectivity (one small model call) |
nexus_audit |
Runs CodebaseAuditor on a directory |
nexus_blast_radius |
Static import graph and dependents of a module |
nexus_guardrail |
Prompt injection check and credential scrubbing for a piece of text |
nexus_roi |
The heuristic ROI estimate of nexus metrics |
The IT squad agents are not exposed over MCP; run them with nexus dream or NexusITTeam from Python.
⚡ Instant Application Generation: nexus dream
Generate complete, runnable applications from natural language:
nexus dream "I want an app that tracks second-hand luxury watches in Europe with price alerts"
Options: --output-dir, --max-budget-usd (spend cap for the whole run, default 1.00), --test-timeout
(seconds per generated test run, default 120) and --no-run-tests (skip executing the generated suite).
Example output:
--- Nexus Core IT Squad Activated ---
Goal: "I want an app that tracks second-hand luxury watches in Europe with price alerts"
Assignees: Business Analyst, Engineering Manager, UI/UX Designer, Backend Engineer, QA Engineer
=== Project Delivered! ===
App: WatchHub (watchhub)
Tagline: Verified European luxury watch index and real-time deal alerts
Output Directory: ./watchhub
Stories: 4 user stories defined
Cloud Target: GCP (Cloud Run Serverless)
Data Schema: PostgreSQL 16 (4 tables)
UI Component: WatchDashboard.tsx
QA Gate: PASS (generated tests passed (4 passed, 0 failed, 0 errors, exit 0))
Model spend: $0.0213 of $1.00 budget
🖥️ Local Observability Dashboard: nexus ui
Launch the real-time execution dashboard on http://localhost:8000:
nexus ui
- Visual Pipeline: Real-time status indicators across the 7 specialists.
- Server-Sent Telemetry: Live stream of agent thoughts, tool invocations, and model reasoning.
- Cost & Budget Meter: Live dollar spend calculation against Gemini 3.8 pricing models.
- Interactive Wireframe Viewer: Preview generated HTML mockups and explore generated FastAPI/React code.
🔄 Stage 1: Closed-Loop Self-Healing
When build_from_idea writes the workspace to disk (output_dir, which nexus dream always sets), Nexus runs the generated pytest suite for real: python -m pytest tests in the generated backend/ folder, in a subprocess with a timeout (default 120 s). A failing run triggers the healing loop, and the diagnosis is given the actual pytest output:
sequenceDiagram
participant QA as QA Engineer Agent
participant Runner as Pytest subprocess
participant Healer as Healer
participant FS as Full-Stack Engineer Agent
QA->>Runner: Write workspace, run generated suite
alt Tests pass and security review passes
Runner-->>QA: Gate passed, no healing
else Tests fail, time out or collect nothing
Runner-->>Healer: Real pytest output
Healer->>FS: Diagnosis from the failure
FS->>QA: Patched code
QA->>Runner: Regenerate suite, rewrite workspace, run again
Note over Runner: Up to max_healing_cycles (default 3), then FAIL_MAX_CYCLES_EXCEEDED
end
- The result is in
DeliveredProject.test_run,DeliveredProject.qa_passedandhealing_report(each attempt keeps its own test run). - Without an output directory, or with
run_generated_tests=False/--no-run-tests, nothing is executed and the gate is QA's self reportedpassed_preflightonly. - This executes model generated code on your machine. The subprocess gets a reduced environment (no cloud credentials or API keys from your shell) and a timeout, but it is not a sandbox. Turn execution off wherever someone else controls the idea or the model output; the public showcase does.
🔍 Stage 2: Brownfield Legacy Codebase Support
Nexus isn't just for greenfield scaffolding. It analyzes and safely refactors existing enterprise repositories:
1. Security & Architecture Audit: nexus audit
Scan your existing codebase for secret leaks, unvalidated AI client calls, prompt injection risks, and test coverage drift:
nexus audit ./existing-repo
2. AST Blast-Radius Mapping & Surgical Refactoring: nexus refactor
Before touching a line of code, Nexus builds an Abstract Syntax Tree (AST) import graph across Python files, classes, functions, and FastAPI routes to estimate the blast radius (static imports only: dynamic imports, reflection and non Python consumers are not seen):
nexus refactor "Migrate database pool to PostgreSQL asyncpg" --target src/db/session.py --apply
- Blast Radius Analysis: Identifies all direct dependents, indirect dependents, and affected REST endpoints.
- Surgical Patching: Emits targeted diffs that aim to preserve existing contracts; review every diff before applying it.
📊 Stage 3: Team Telemetry & Enterprise ROI: nexus metrics
Estimate return on investment (ROI) and DORA style velocity figures for a workspace. Every figure is a heuristic estimate: hours saved, token spend, the DORA values (deployment frequency, lead time, change failure rate, MTTR) and the security counts are derived from file counts, lines of code, an hourly rate you supply and fixed multipliers. Nothing is measured from your deployments, incidents or model bills, so treat the output as illustrative:
nexus metrics ./my-project --hourly-rate 95
================================================================================
NEXUS ENTERPRISE TELEMETRY & ROI SCORECARD: my-project
================================================================================
Target Path : /workspace/my-project
Files / LOC Analyzed : 116 files | 5,608 lines of code
--------------------------------------------------------------------------------
FINANCIAL ROI & EFFICIENCY:
* Human Hours Saved : 117.6 engineering hours
* Human Cost Benchmark : $95/hour (Senior Full-Stack benchmark)
* Gross Value Generated: $11,172.00 USD
* Total LLM Spend : $0.0493 USD (415,912 tokens)
* Net Financial Savings: $11,171.95 USD
* NET ROI MULTIPLIER : 226612.0x Return On Investment
--------------------------------------------------------------------------------
DORA VELOCITY ACCELERATION:
* Deployment Frequency : 12.0x faster release cadence
* Lead Time Reduction : 85.0% decrease from idea to working code
* Change Failure Rate : 2.4% (defects intercepted by closed-loop tests)
* Mean Time to Restore : 3.8 minutes MTTR (automated self-healing loop)
--------------------------------------------------------------------------------
SECURITY & STABILITY IMPACT:
* Vulnerabilities Prevented: 17 security defects / secret leaks avoided
* Closed-Loop Healing Cycles: 9 automated QA repair loops
================================================================================
🛡️ Built-in Cost & Security Guardrails
- Budget Caps:
max_budget_usdceilings per execution context. A whole squad run is capped too:NexusITTeam(max_budget_usd=1.00)(default) ornexus dream --max-budget-usd; the run stops withBudgetExceededErrorafter the call that crosses the cap. Calls count when the provider reports usage (VertexAIProviderdoes;MockProviderreports $0). - Cost-Optimized Model Tiering: Economical token profile with Gemini 3.8 Flash.
- Prompt Injection Filter (best effort):
check_prompt_injectionmatches a short list of known jailbreak phrasings. Paraphrases, other languages, encodings and indirect injection (through documents or tool output) get through, so it is a first filter, not a defence on its own. Treat model input and output as untrusted and keep critical tools behind approval (GuardrailManager). - Secret Scrubbing (best effort):
sanitize_textredacts known credential formats before text reaches a model or a log: OpenAI stylesk-..., Anthropicsk-ant-..., AWS access key ids (AKIA...,ASIA...), Google API keys (AIza...), Google OAuth client secrets (GOCSPX-...), Slack tokens (xoxb-,xoxp-, ...), GitHub tokens, Google OAuth bearer tokens, PEM private key blocks, and email addresses. Unknown formats, passwords and encoded secrets are not detected. - Closed CORS by default:
create_nexus_app()and thenexus uidashboard send no CORS headers unless you pass explicitcors_origins; credentials are only allowed with explicit origins, never with"*". - Security headers (opt in):
create_nexus_app(security_headers=True)adds a Content Security Policy, HSTS,X-Content-Type-Options: nosniff,X-Frame-Options: DENY,Referrer-Policy: same-originand a restrictivePermissions-Policy. Pass aSecurityHeadersConfigto adjust the policy per path or to cache hashed static assets as immutable while serving HTML withno-cache. The showcase uses it. - Backend adoption kit:
nexus.apialso ships a sliding window rate limiter (rate_limit,RateLimitMiddleware), a safe SPA mount (mount_spa), a Google OIDC verifier for Cloud Scheduler and service account callers (GoogleOidcVerifier, extra[oidc]), andnexus.ai.spenda persistent monthly AI spend ledger with a fail closed budget gate. Moving an existing app over: docs/ADOPTING.md. - No implicit cloud project:
GeminiClientusesGCP_PROJECT_ID,GOOGLE_CLOUD_PROJECTor your gcloud default, and raisesNexusConfigurationErrorwhen Vertex AI is needed and none is set. API keys go in thex-goog-api-keyheader, never in URLs. - Deterministic Mock Engine: Run the entire IT pack and test suite locally for $0.00 using
MockProvider.
🧪 Verification & Testing
Nexus has unit tests for the agents, security helpers, API factory, telemetry contracts and CLI. There is no hosted CI at the moment, so the test badge links here: run the suites yourself.
git clone https://github.com/sabburi1994/nexus.git
cd nexus
pip install -e ".[dev]"
python -m pytest -o pythonpath=src tests/
python -m ruff check src tests
python -m mypy src
The showcase API has its own suite: cd apps/showcase/backend && python -m pytest tests/.
Local hooks
Commits are checked locally with pre-commit: gitleaks on staged changes, ruff (lint and format) and mypy.
pip install pre-commit
pre-commit install
pre-commit run --all-files
Releases
.github/workflows/release.yml publishes to PyPI and npm with OIDC trusted publishing (no long lived tokens). GitHub Actions is currently disabled for this repository, so nothing publishes automatically.
Showcase deployment
The nexus.abburi.info showcase runs on Cloud Run with its own runtime service account (no project roles), build service account and Artifact Registry repository. The project is a Terraform variable: a dedicated project is preferred, and hosting it in an existing project is supported because every grant is scoped to the showcase's own resources. Runtime and build service accounts, the registry, the Cloud Run service and the domain mapping are all Terraform managed. See apps/showcase/ROLLOUT.md. Reusable platform modules live in infra/terraform/modules.
🤝 Governance & Feature Requests
Nexus is free for everyone to use, run, and explore. To preserve strict architectural consistency, contracts, and quality gates:
- Nexus is maintained exclusively by the author. External pull requests are disabled and will not be accepted.
- Have an idea or need a feature? We warmly welcome your feedback! Please submit feature requests, questions, or bug reports via GitHub Issues.
📄 License
Nexus is licensed under the Apache 2.0 License.
Copyright © 2026 Sai Nikhil Abburi. All rights reserved.
Metadata
Release files for nexus-agent-framework 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nexus_agent_framework-0.4.0.tar.gz | 3.3 MB | Without provenance | Details for nexus_agent_framework-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nexus_agent_framework-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for nexus_agent_framework-0.4.0-py3-none-any.whl |
Total release size: 3.4 MB
Release files / nexus_agent_framework-0.4.0.tar.gz
| Download URL | nexus_agent_framework-0.4.0.tar.gz |
|---|---|
| Size | 3.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fcbf57e6b14ee991ac48345623ebdcf60b6fb20056d8d1f3f442befed0375dce
|
|
BLAKE2b-256 checksum How to use checksums |
7520fb6f61a8a9c5750131784e95109d5a308a5f635d086b85921fe583a95044
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / nexus_agent_framework-0.4.0-py3-none-any.whl
| Download URL | nexus_agent_framework-0.4.0-py3-none-any.whl |
|---|---|
| Size | 116.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c136442b1a30228a3b518b39309b80005a2517b83c41155cc9209cde3ab809f1
|
|
BLAKE2b-256 checksum How to use checksums |
911b693e0b4dde2db5b2220ea5f2dbe11eea99efb584fc105bee7147edc1e593
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for nexus-agent-framework 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.