# 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:

```powershell
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

```bash
pip install -e .
```

or for distribution build:

```bash
python -m build
```

## Run Sandbox

After install, launch with:

```bash
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.
