nexus-agent-framework 0.1.0__tar.gz

nexus_agent_framework-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,78 @@
+name: Nexus CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test-python:
+    name: Python Test Suite & Wheel Build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev] build pytest-cov
+
+      - name: Run Ruff Lint & Format Check
+        run: |
+          ruff check src/ tests/
+          ruff format --check src/ tests/
+
+      - name: Run Mypy Type Check
+        run: |
+          mypy src/ tests/
+
+      - name: Run Pytest Suite with Coverage
+        run: |
+          pytest --cov=src -o pythonpath=src tests/
+
+      - name: Run Showcase App Tests
+        run: |
+          cd apps/showcase/backend && pytest tests/
+
+      - name: Validate Package Build (sdist & wheel)
+        run: |
+          python -m build
+
+  build-packages:
+    name: Monorepo TypeScript Packages Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install TypeScript & React Types
+        run: |
+          npm install --no-save typescript @types/react @types/react-dom
+
+      - name: Compile @nexus/contracts
+        run: npx tsc -p packages/contracts
+
+      - name: Compile @nexus/middleware
+        run: npx tsc -p packages/middleware
+
+      - name: Compile @nexus/scraper
+        run: npx tsc -p packages/scraper
+
+      - name: Compile @nexus/ui
+        run: npx tsc -p packages/ui

nexus_agent_framework-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,98 @@
+name: Release & Package Distribution
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
+jobs:
+  build-and-publish-python:
+    name: Build & Publish Python Wheel (nexus-framework)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install build tools & twine
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build sdist and wheel
+        run: |
+          python -m build
+
+      - name: Verify package distributions
+        run: |
+          twine check dist/*
+
+      - name: Upload artifacts to GitHub Release
+        uses: softprops/action-gh-release@v2
+        if: startsWith(github.ref, 'refs/tags/v')
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        if: startsWith(github.ref, 'refs/tags/v') && env.HAVE_PYPI_TOKEN == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true
+        env:
+          HAVE_PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN != '' }}
+
+  build-and-publish-npm:
+    name: Build & Publish TypeScript Packages (@nexus/*)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install TypeScript and type definitions
+        run: |
+          npm install --no-save typescript @types/react @types/react-dom
+
+      - name: Compile all monorepo packages
+        run: |
+          npx tsc -p packages/contracts
+          npx tsc -p packages/middleware
+          npx tsc -p packages/scraper
+          npx tsc -p packages/ui
+
+      - name: Publish @nexus/* to NPM Registry
+        if: startsWith(github.ref, 'refs/tags/v') && env.HAVE_NPM_TOKEN == 'true'
+        run: |
+          for pkg in contracts middleware scraper ui; do
+            echo "Publishing packages/$pkg..."
+            cd packages/$pkg
+            npm publish --access public || echo "Skipping $pkg or already published"
+            cd ../..
+          done
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          HAVE_NPM_TOKEN: ${{ secrets.NPM_TOKEN != '' }}

nexus_agent_framework-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv/
+venv/
+ENV/
+
+# Testing & Coverage
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node / Frontend
+node_modules/
+dist/
+.turbo/
+
+# Environment & Secrets
+.env
+*.env.local
+secrets/
+*.pem
+*.key
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Terraform
+.terraform/
+*.tfstate
+*.tfstate.backup
+.terraform.lock.hcl

nexus_agent_framework-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: nexus-agent-framework
+Version: 0.1.0
+Summary: Autonomous Application & Platform Framework for Google Cloud and Gemini 3.8
+Author-email: Sai Nikhil Abburi <sai.nikhil@abburi.info>
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.2.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.30
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Nexus: Orchestrator-Native AI Agentic Framework
+
+> The **AI Agentic Framework** that equips non-technical creators with a full virtual IT department while interfacing natively with **Claude Code, Cursor, Codex, and Gemini** via the Model Context Protocol (MCP).
+
+Nexus bridges the gap between raw ideas and production code. It serves two distinct developer cohorts:
+1. **Beginners with Ideas**: Run `nexus dream "<vague idea>"` and the **Core IT Pack** (BA, Solution Architect, Data Architect, UI/UX Designer, Full-Stack Engineer, DevOps Engineer, and QA) takes the idea, designs the UI mockup, normalizes the relational schema, writes the full-stack code, generates Terraform IaC, and runs automated tests.
+2. **AI Orchestrator Users (Claude Code, Cursor, Codex, Gemini)**: Run `nexus mcp` to expose your agents, tools, databases, and guardrails to any modern AI IDE as first-class, equal participants.
+
+---
+
+## 🚀 Quickstart & Installation
+
+```bash
+pip install nexus-agent-framework
+```
+
+---
+
+## 🏛️ The Nexus Core IT Pack
+
+Nexus comes pre-packaged with an autonomous IT squad that simulates a real-world software engineering organization:
+
+```mermaid
+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/>(Preflight Guardrails & Test Suite)"]
+    QA --> Repo["Delivered Application Workspace<br/>(Runnable Full-Stack Project on Disk)"]
+```
+
+### 1. Business Analyst (`BusinessAnalystAgent`)
+Takes conversational, incomplete user thoughts and formats them into a crisp **Product Proposal**:
+- Canonical app slug & value proposition tagline.
+- User stories (`As a [user], I want to [action] so that [benefit]`).
+- Core features specification & interactive HTML wireframe preview (`docs/preview_mockup.html`).
+
+### 2. Solution Architect (`SolutionArchitectAgent`)
+Evaluates holistic system design, integration boundaries, and non-functional requirements:
+- Selects the cloud runtime strategy (GCP, AWS, or Local).
+- Defines compute model (Cloud Run serverless container vs Always-Free VM).
+- Details service communication topology and latency budgets.
+
+### 3. Data Architect (`DataArchitectAgent`)
+Designs the relational and persistence architecture:
+- Normalizes tables, foreign keys, and indexes.
+- Emits clean, production-ready PostgreSQL SQL DDL schemas (`docs/DATA_ARCHITECTURE.md`).
+
+### 4. UI/UX Designer (`UiDesignerAgent`)
+Focuses on user journey, design tokens, and interactive mockups styled with Tailwind CSS and `@nexus/ui`.
+
+### 5. Full-Stack Engineer (`FullStackEngineerAgent`)
+Implements the unified end-to-end codebase:
+- Production-grade FastAPI microservice with Gemini 3.8 client (`backend/src/main.py`).
+- Pydantic models & SQLAlchemy entity definitions (`backend/src/models.py`).
+- React frontend consuming the API endpoints (`frontend/src/App.tsx`).
+
+### 6. DevOps Engineer (`DevopsEngineerAgent`)
+Generates real Infrastructure as Code (IaC) tailored to the architectural need and selected cloud:
+- Complete Terraform `main.tf` and `variables.tf` (e.g. Cloud Run, IAM `roles/aiplatform.user`, Secret Manager).
+- Multi-container `docker-compose.yml` for local development.
+- GitHub Actions CI/CD deployment pipeline (`.github/workflows/deploy.yml`).
+
+### 7. QA & Security Engineer (`QaEngineerAgent`)
+Inspects implemented backend routes, runs pre-flight security checks (injection shields, permission levels), and produces an executable `pytest` test suite (`backend/tests/test_api.py`) with 100% pre-flight clearance.
+
+---
+
+## 📦 Shared Monorepo Packages (`packages/`)
+
+Nexus is structured as a monorepo with universal, reusable packages:
+
+| Package | Purpose | Exports / Capabilities |
+| :--- | :--- | :--- |
+| **`@nexus/ui`** | Shared React UI & Design System | `StatCard`, `AiBadge`, `MetricTrend`, `NexusHeader`, `TraceViewer`, `SecurityShieldBadge` |
+| **`@nexus/contracts`** | Universal Spec & Telemetry Contracts | `AgentTelemetryEvent`, `ProductProposalContract`, `SolutionBlueprintContract`, `DataArchitectureContract`, `DevopsSpecificationContract`, `QaSpecificationContract`, `AuditChainEntryContract` |
+| **`@nexus/middleware`** | Security & Scrubbing Middleware | `NEXUS_SECURITY_HEADERS`, `scrubSensitiveData` (zero credential leaks), `generateCorrelationId` |
+| **`@nexus/scraper`** | Ethical & Resilient Scraping | `ScrapedItem`, `DEFAULT_NEXUS_SCRAPING_POLICY`, rate-limit & backoff policy contracts |
+
+### Centralized Terraform Modules (`infra/terraform/modules/`)
+- **`nexus_app`**: Baseline GCP APIs (`aiplatform.googleapis.com`, `secretmanager.googleapis.com`), service accounts, and IAM roles (`roles/aiplatform.user`).
+- **`nexus_cloud_run`**: Auto-scaling serverless Cloud Run container module with HTTPS termination and VPC access.
+- **`nexus_vm`**: Cost-optimized Always-Free Compute Engine VM module with custom VPC, firewall, IAP SSH, and Docker setup.
+
+---
+
+## 🔌 Orchestrator-Native: Claude Code & Cursor Integration
+
+Nexus is designed to work as an equal peer alongside **Claude Code, Cursor, Codex, and Gemini CLI**:
+
+```bash
+# Start the Nexus Model Context Protocol (MCP) server
+nexus mcp
+```
+
+### Connecting from Cursor / Claude Code
+Add Nexus to your `.cursor/mcp.json` or `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "python",
+      "args": ["-m", "nexus.cli.main", "mcp"],
+      "env": {
+        "GCP_PROJECT_ID": "finhub-510316"
+      }
+    }
+  }
+}
+```
+Instantly, Claude Code or Cursor gains access to all Nexus tools, allowing you to trigger IT squad workflows, check AI connections, or diagnose errors right inside your editor prompt.
+
+---
+
+## 🖥️ Localhost Visualizer & Agent Observability (`nexus ui`)
+
+Nexus provides a built-in interactive web visualizer to track your agent squad and execution telemetry in real time:
+
+```bash
+# Launch localhost progress visualizer on http://localhost:8000
+nexus ui
+```
+
+### Features:
+- **Visual Squad Pipeline**: Live status indicators for each agent (`Idle`, `Active`, `Done ✓`) as tasks move through the 7 specialists.
+- **Real-Time Telemetry Stream**: Server-Sent Events (SSE) feed displaying thoughts, tool calls, and model reasoning.
+- **Cost & Budget Meter**: Live dollar spend tracking (`total_cost_usd`) updated after every inference turn against official Gemini 3.8 pricing.
+- **Live Artifact Inspector**: Read generated Product Proposals, preview interactive HTML wireframes, and inspect React/FastAPI code directly in your browser.
+- **Interactive Launcher**: Trigger new squad builds directly from the web interface.
+
+---
+
+## ⚡ Instant Application Creation: `nexus dream`
+
+```bash
+nexus dream "I want an app that tracks second-hand luxury watches in Europe with price alerts"
+```
+
+Output:
+```text
+--- 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 Preflight: PASS (Test suite generated with 100% pre-flight clearance)
+```
+
+---
+
+## 🛡️ Built-in Cost & Security Guardrails
+
+- **Zero Runaway Bills**: `max_budget_usd` spend ceilings on every agent execution context.
+- **Gemini 3.8 Flash Cost Profile**: \$0.075 / \$0.30 per million tokens (cents per month for active squads).
+- **Prompt Injection Defense**: Intercepts jailbreaks (`"ignore all prior instructions"`) before hitting the LLM.
+- **PII & Secret Scrubber**: Redacts API keys (`sk-...`, `ghp-...`) and credentials automatically.
+- **Zero-Cost Mock Engine**: Run the entire IT pack and test suite locally for \$0.00 using `MockProvider`.
+
+---
+
+## 🧪 Verification
+
+```bash
+git clone https://github.com/sabburi1994/nexus.git
+cd nexus
+pytest -o pythonpath=src tests/
+```
+All 20 unit tests pass cleanly out of the box.

nexus_agent_framework-0.1.0/README.md

@@ -0,0 +1,178 @@
+# Nexus: Orchestrator-Native AI Agentic Framework
+
+> The **AI Agentic Framework** that equips non-technical creators with a full virtual IT department while interfacing natively with **Claude Code, Cursor, Codex, and Gemini** via the Model Context Protocol (MCP).
+
+Nexus bridges the gap between raw ideas and production code. It serves two distinct developer cohorts:
+1. **Beginners with Ideas**: Run `nexus dream "<vague idea>"` and the **Core IT Pack** (BA, Solution Architect, Data Architect, UI/UX Designer, Full-Stack Engineer, DevOps Engineer, and QA) takes the idea, designs the UI mockup, normalizes the relational schema, writes the full-stack code, generates Terraform IaC, and runs automated tests.
+2. **AI Orchestrator Users (Claude Code, Cursor, Codex, Gemini)**: Run `nexus mcp` to expose your agents, tools, databases, and guardrails to any modern AI IDE as first-class, equal participants.
+
+---
+
+## 🚀 Quickstart & Installation
+
+```bash
+pip install nexus-agent-framework
+```
+
+---
+
+## 🏛️ The Nexus Core IT Pack
+
+Nexus comes pre-packaged with an autonomous IT squad that simulates a real-world software engineering organization:
+
+```mermaid
+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/>(Preflight Guardrails & Test Suite)"]
+    QA --> Repo["Delivered Application Workspace<br/>(Runnable Full-Stack Project on Disk)"]
+```
+
+### 1. Business Analyst (`BusinessAnalystAgent`)
+Takes conversational, incomplete user thoughts and formats them into a crisp **Product Proposal**:
+- Canonical app slug & value proposition tagline.
+- User stories (`As a [user], I want to [action] so that [benefit]`).
+- Core features specification & interactive HTML wireframe preview (`docs/preview_mockup.html`).
+
+### 2. Solution Architect (`SolutionArchitectAgent`)
+Evaluates holistic system design, integration boundaries, and non-functional requirements:
+- Selects the cloud runtime strategy (GCP, AWS, or Local).
+- Defines compute model (Cloud Run serverless container vs Always-Free VM).
+- Details service communication topology and latency budgets.
+
+### 3. Data Architect (`DataArchitectAgent`)
+Designs the relational and persistence architecture:
+- Normalizes tables, foreign keys, and indexes.
+- Emits clean, production-ready PostgreSQL SQL DDL schemas (`docs/DATA_ARCHITECTURE.md`).
+
+### 4. UI/UX Designer (`UiDesignerAgent`)
+Focuses on user journey, design tokens, and interactive mockups styled with Tailwind CSS and `@nexus/ui`.
+
+### 5. Full-Stack Engineer (`FullStackEngineerAgent`)
+Implements the unified end-to-end codebase:
+- Production-grade FastAPI microservice with Gemini 3.8 client (`backend/src/main.py`).
+- Pydantic models & SQLAlchemy entity definitions (`backend/src/models.py`).
+- React frontend consuming the API endpoints (`frontend/src/App.tsx`).
+
+### 6. DevOps Engineer (`DevopsEngineerAgent`)
+Generates real Infrastructure as Code (IaC) tailored to the architectural need and selected cloud:
+- Complete Terraform `main.tf` and `variables.tf` (e.g. Cloud Run, IAM `roles/aiplatform.user`, Secret Manager).
+- Multi-container `docker-compose.yml` for local development.
+- GitHub Actions CI/CD deployment pipeline (`.github/workflows/deploy.yml`).
+
+### 7. QA & Security Engineer (`QaEngineerAgent`)
+Inspects implemented backend routes, runs pre-flight security checks (injection shields, permission levels), and produces an executable `pytest` test suite (`backend/tests/test_api.py`) with 100% pre-flight clearance.
+
+---
+
+## 📦 Shared Monorepo Packages (`packages/`)
+
+Nexus is structured as a monorepo with universal, reusable packages:
+
+| Package | Purpose | Exports / Capabilities |
+| :--- | :--- | :--- |
+| **`@nexus/ui`** | Shared React UI & Design System | `StatCard`, `AiBadge`, `MetricTrend`, `NexusHeader`, `TraceViewer`, `SecurityShieldBadge` |
+| **`@nexus/contracts`** | Universal Spec & Telemetry Contracts | `AgentTelemetryEvent`, `ProductProposalContract`, `SolutionBlueprintContract`, `DataArchitectureContract`, `DevopsSpecificationContract`, `QaSpecificationContract`, `AuditChainEntryContract` |
+| **`@nexus/middleware`** | Security & Scrubbing Middleware | `NEXUS_SECURITY_HEADERS`, `scrubSensitiveData` (zero credential leaks), `generateCorrelationId` |
+| **`@nexus/scraper`** | Ethical & Resilient Scraping | `ScrapedItem`, `DEFAULT_NEXUS_SCRAPING_POLICY`, rate-limit & backoff policy contracts |
+
+### Centralized Terraform Modules (`infra/terraform/modules/`)
+- **`nexus_app`**: Baseline GCP APIs (`aiplatform.googleapis.com`, `secretmanager.googleapis.com`), service accounts, and IAM roles (`roles/aiplatform.user`).
+- **`nexus_cloud_run`**: Auto-scaling serverless Cloud Run container module with HTTPS termination and VPC access.
+- **`nexus_vm`**: Cost-optimized Always-Free Compute Engine VM module with custom VPC, firewall, IAP SSH, and Docker setup.
+
+---
+
+## 🔌 Orchestrator-Native: Claude Code & Cursor Integration
+
+Nexus is designed to work as an equal peer alongside **Claude Code, Cursor, Codex, and Gemini CLI**:
+
+```bash
+# Start the Nexus Model Context Protocol (MCP) server
+nexus mcp
+```
+
+### Connecting from Cursor / Claude Code
+Add Nexus to your `.cursor/mcp.json` or `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "python",
+      "args": ["-m", "nexus.cli.main", "mcp"],
+      "env": {
+        "GCP_PROJECT_ID": "finhub-510316"
+      }
+    }
+  }
+}
+```
+Instantly, Claude Code or Cursor gains access to all Nexus tools, allowing you to trigger IT squad workflows, check AI connections, or diagnose errors right inside your editor prompt.
+
+---
+
+## 🖥️ Localhost Visualizer & Agent Observability (`nexus ui`)
+
+Nexus provides a built-in interactive web visualizer to track your agent squad and execution telemetry in real time:
+
+```bash
+# Launch localhost progress visualizer on http://localhost:8000
+nexus ui
+```
+
+### Features:
+- **Visual Squad Pipeline**: Live status indicators for each agent (`Idle`, `Active`, `Done ✓`) as tasks move through the 7 specialists.
+- **Real-Time Telemetry Stream**: Server-Sent Events (SSE) feed displaying thoughts, tool calls, and model reasoning.
+- **Cost & Budget Meter**: Live dollar spend tracking (`total_cost_usd`) updated after every inference turn against official Gemini 3.8 pricing.
+- **Live Artifact Inspector**: Read generated Product Proposals, preview interactive HTML wireframes, and inspect React/FastAPI code directly in your browser.
+- **Interactive Launcher**: Trigger new squad builds directly from the web interface.
+
+---
+
+## ⚡ Instant Application Creation: `nexus dream`
+
+```bash
+nexus dream "I want an app that tracks second-hand luxury watches in Europe with price alerts"
+```
+
+Output:
+```text
+--- 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 Preflight: PASS (Test suite generated with 100% pre-flight clearance)
+```
+
+---
+
+## 🛡️ Built-in Cost & Security Guardrails
+
+- **Zero Runaway Bills**: `max_budget_usd` spend ceilings on every agent execution context.
+- **Gemini 3.8 Flash Cost Profile**: \$0.075 / \$0.30 per million tokens (cents per month for active squads).
+- **Prompt Injection Defense**: Intercepts jailbreaks (`"ignore all prior instructions"`) before hitting the LLM.
+- **PII & Secret Scrubber**: Redacts API keys (`sk-...`, `ghp-...`) and credentials automatically.
+- **Zero-Cost Mock Engine**: Run the entire IT pack and test suite locally for \$0.00 using `MockProvider`.
+
+---
+
+## 🧪 Verification
+
+```bash
+git clone https://github.com/sabburi1994/nexus.git
+cd nexus
+pytest -o pythonpath=src tests/
+```
+All 20 unit tests pass cleanly out of the box.

nexus_agent_framework-0.1.0/apps/showcase/backend/.gcloudignore

@@ -0,0 +1,7 @@
+.git
+.gitignore
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+tests/

nexus_agent_framework-0.1.0/apps/showcase/backend/Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PORT=8080
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy local wheel and install dependencies
+COPY wheels/ /app/wheels/
+RUN pip install --no-cache-dir /app/wheels/*.whl uvicorn fastapi httpx pydantic sqlalchemy asyncpg
+
+# Copy application source code
+COPY src/ /app/src/
+
+EXPOSE 8080
+
+CMD ["sh", "-c", "uvicorn main:app --app-dir src --host 0.0.0.0 --port ${PORT:-8080}"]

nexus_agent_framework-0.1.0/apps/showcase/backend/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "nexus-showcase"
+version = "0.1.0"
+description = "Reference Showcase Application demonstrating Nexus Monorepo Packages and Framework"
+requires-python = ">=3.11"
+dependencies = [
+    "nexus-framework>=0.1.0",
+    "uvicorn>=0.30.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "httpx>=0.27.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+asyncio_mode = "auto"

nexus_agent_framework-0.1.0/apps/showcase/backend/src/__init__.py

@@ -0,0 +1 @@
+"""Nexus Showcase Backend Package."""

nexus_agent_framework-0.1.0/apps/showcase/backend/src/backend_models.py

@@ -0,0 +1,2 @@
+"""Alias for models.py."""
+from .models import *  # noqa: F403