Nexus Agent

A local-first reference architecture for building practical AI agents.
🧠 Intelligence • 🛠️ Tools • 🛡️ Verification

---

Technical Demonstration

📹 Watch or Download Full 1080p HD Demo Video with Audio (MP4)

---

Why I Built This

Most agent frameworks today start with a fundamental compromise: they send your private code, files, and prompts to closed-source cloud APIs, while giving the LLM unconstrained or poorly-bounded tool access to the host machine.

When building autonomous software, generative text alone is rarely enough. Practical agents must:

1. Decompose complex objectives into discrete, trackable milestones.
2. Route model requests locally across hardware-accelerated runners without cloud lock-in.
3. Execute tools inside strict sandboxes where path traversal and destructive commands are physically intercepted.
4. Empirically verify results before reporting completion.

I built Nexus Agent as a clean, minimal reference architecture to explore this exact pipeline: Goal ──► Plan ──► Route ──► Tool ──► Verify.

---

What Problem It Solves

1. Cloud Lock-in & Privacy: Decouples agent reasoning from proprietary remote APIs by running natively against local models (Ollama, LM Studio, vLLM, or offline mock engines).
2. Uncontrolled Tool Execution: Enforces strict workspace containment and command sanitization to prevent accidental system corruption or path escapes.
3. State & Memory Loss: Maintains a deterministic two-tier memory model combining active conversational context with indexed episodic memory for factual recall.

---

Architecture

  User Goal ──► Agent ──► Planner ──► Model Router ──► Tools ──► Execution ──► Verification ──► Memory

Key Subsystems & Layers

Layer	Implementation File	Purpose & Guarantees
Model Router	core/router.py	Dispatches prompts across Ollama, local OpenAI-compatible endpoints (vLLM / LM Studio), and deterministic offline Mock engines.
Task Planner	core/planner.py	Decomposes high-level user objectives into ordered milestone steps (PENDING ──► IN_PROGRESS ──► COMPLETED).
Memory Subsystem	core/memory.py	Two-tier architecture: sliding context window for active turns + indexed episodic key-value store for tool observations.
Sandboxed Tools	tools/workspace.py	JSON Schema-validated tools strictly confined within target workspace_root (parent directory traversal ../ is blocked).
Safety Policy	safety/policy.py	Multi-tier security engine (STRICT, BALANCED, PERMISSIVE) with regex pattern filters for destructive shell commands.

---

Quick Start (Under 60 Seconds)

1. Installation

# Clone repository
git clone https://github.com/dax0056/nexus-agent.git
cd nexus-agent

# Install dependencies in editable mode
pip install -e .[dev]

2. Option A: Instant 0-Setup Run (Offline Mock Backend)

No external model server, API keys, or internet connection required:

from pathlib import Path
from nexus_agent import NexusAgent, InferenceBackend, SecurityLevel

# Initialize agent inside a sandboxed workspace
agent = NexusAgent(
    workspace_dir=Path("./workspace"),
    backend=InferenceBackend.MOCK,
    security_level=SecurityLevel.BALANCED
)

# Run autonomous task
result = agent.run("Analyze workspace structure and save executive summary")
print(f"Execution Status: {result.status}")
print(f"Steps executed   : {len(result.executed_steps)}")

3. Option B: Local LLM Runner (Ollama)

If you have Ollama installed locally:

# Pull your preferred local model
ollama run llama3:8b

from pathlib import Path
from nexus_agent import NexusAgent, InferenceBackend, SecurityLevel

agent = NexusAgent(
    workspace_dir=Path("./workspace"),
    backend=InferenceBackend.OLLAMA,
    model_name="llama3:8b",
    security_level=SecurityLevel.BALANCED
)

result = agent.run("Inspect workspace and generate structured summary")
print(f"Status: {result.status}")

---

Live Execution Trace

Here is the actual execution trace produced by the agent run harness:

[NexusAgent] Initialized with backend: MOCK | Workspace: ./workspace
[Planner] Decomposed goal into 3 steps:
  1. [inspect_workspace] List directory structure
  2. [extract_data] Read key documentation files
  3. [write_summary] Generate analysis report
[Router] Generating step execution for step 1 via MOCK backend...
[Tools] Executing 'list_files' inside workspace -> 8 files found.
[Safety] Action permitted by BALANCED security policy.
[Memory] Stored 8 items in episodic memory buffer.
[Router] Generating step execution for step 3 via MOCK backend...
[Tools] Executing 'write_file' -> 'workspace_summary.txt' (248 bytes written).
[Agent] Task completed successfully with status: SUCCESS

---

Test Report

Nexus Agent is covered by 7 automated unit tests validating all core subsystems:

============================= test session starts =============================
tests/test_agent_flow.py::test_nexus_agent_execution_flow PASSED         [ 14%]
tests/test_router_memory.py::test_model_router_mock PASSED               [ 28%]
tests/test_router_memory.py::test_agent_memory_buffer PASSED             [ 42%]
tests/test_router_memory.py::test_agent_memory_retrieval PASSED          [ 57%]
tests/test_tools_safety.py::test_safety_policy_blocking PASSED           [ 71%]
tests/test_tools_safety.py::test_sandboxed_workspace_tools PASSED        [ 85%]
tests/test_tools_safety.py::test_browser_mock_tool PASSED                [100%]
============================== 7 passed in 0.06s ==============================

• Passed: 7 / 7 (100%)
• Test Command: pytest -v

---

Security & Sandbox Positioning

• Strict Root Boundary: Path resolution enforces relative workspace containment. Any attempt to access /etc, C:\Windows, or parent directories (../) raises an immediate security violation.
• Command Sanitization: Destructive system patterns (format, del, rmdir, shutdown, powershell -enc) are blocked prior to tool invocation.
• For vulnerability reporting, see SECURITY.md.

---

Roadmap & Changelog

• Milestone development plan: ROADMAP.md
• Release notes and version history: CHANGELOG.md
• Contribution guidelines: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md

---

Part of the DAX Agent Engineering Series

Nexus Agent serves as the Intelligence flagship of the series:

• 🧠 nexus-agent — Intelligence & Local Agent Core
• 💻 micro-coding-agent — Deterministic Code AST & Patch Engine
• 🖥️ desktop-action-agent — Safe Sandboxed Desktop Automation

---

License

Distributed under the MIT License. See LICENSE for details.