Metadata-Version: 2.4
Name: nexus-sandbox
Version: 1.0.0
Summary: NEXUS multi-agent orchestration framework with a live Streamlit sandbox
Author: Manushri Bhuyan
License: MIT
Project-URL: Homepage, https://github.com/example/nexus-ai
Project-URL: Documentation, https://github.com/example/nexus-ai#readme
Project-URL: Repository, https://github.com/example/nexus-ai
Keywords: multi-agent,orchestration,llm,streamlit,nexus
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: tiktoken>=0.7
Requires-Dist: openai>=1.35
Requires-Dist: anthropic>=0.34
Requires-Dist: sentence-transformers>=3.0
Requires-Dist: chromadb>=0.5
Requires-Dist: opentelemetry-sdk>=1.25
Requires-Dist: opentelemetry-exporter-otlp>=1.25
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomli>=2.0
Requires-Dist: streamlit>=1.38
Requires-Dist: plotly>=5.24
Requires-Dist: pandas>=2.2
Requires-Dist: networkx>=3.3
Provides-Extra: google
Requires-Dist: google-generativeai>=0.7; extra == "google"
Provides-Extra: all
Requires-Dist: nexus-sandbox[google]; extra == "all"

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