NEXUS AI

NEXUS (Neural Execution with Unified Cross-Adaptive State) is a Python multi-agent orchestration framework with a live Streamlit sandbox.

This repository includes:

• A production-oriented NEXUS runtime and modular architecture
• Local-provider-first Streamlit sandbox with two-pane UI
• Incremental visual telemetry while workflows run

Author: Manushri Bhuyan

Sandbox Overview

The sandbox is designed as a ChatGPT-like interface with a split screen:

• Left pane: agent chat
• Right pane: live visualization dashboard

The sandbox runs an end-to-end NEXUS workflow for each query and incrementally updates:

• Dynamic graph progression (plan -> research -> synthesize)
• Token economy metrics
• Fluid state mesh indicators
• Tool usage timeline
• Multiple unique plots

Local LLM Requirement

The sandbox is configured for local llama-server usage on localhost:8080.

Example server command:

D:\llama_bin\llama-server.exe \
  -m D:\models\qwen2.5-3b\qwen2.5-3b-instruct-q4_k_m.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  -c 8192 \
  -n 2048 \
  -t 4

The sandbox expects OpenAI-compatible endpoints and supports:

• /chat/completions and /v1/chat/completions
• /models and /v1/models

Install

pip install -e .

or for distribution build:

python -m build

Run Sandbox

After install, launch with:

nexus-sandbox

This command opens the Streamlit sandbox app.

Visualizations Included

The right pane updates incrementally with:

• Main live evolution plot (cumulative/hot tokens over workflow steps)
• Runtime radar profile
• State/economy heatmap
• Node duration timeline
• Execution graph view
• Token/workload sunburst

End-to-End Workflow in Sandbox

Each query executes through NEXUS components:

1. Budget allocation
2. Dynamic graph construction
3. Agent role assignment setup
4. Tool-assisted research (web search + URL fetch)
5. LLM planning, research synthesis, final synthesis
6. Token accounting
7. Fluid mesh writes + eviction cycle
8. Deduplication check
9. Checkpoint writing
10. Audit/tracing updates

Packaging Notes

• Project metadata is configured in pyproject.toml
• Console script entrypoint: nexus-sandbox
• Package discovery includes nexus* modules
• README is set as long description source

Important

This sandbox is local-first and intended to use your local Qwen model via llama-server. If the local server is unavailable, requests will fail fast with provider connection errors.