Installation

Neugi requires Python 3.10+. Local Ollama is optional, not mandatory. The framework supports cloud and custom endpoints out of the box.

Prerequisites

One-Liner Install

macOS / Linux:

Windows (PowerShell):

Manual Install

Quickstart

Get from clean install to production-ready workflow with a provider-agnostic setup path.

Step 1: Install (One-Liner)

Step 2: Run the Wizard

The wizard walks you through provider selection, model choice, key setup, and connectivity verification. No manual config editing required.

Step 3: Run Readiness Smoke Check

Step 4: Run Shipping Gate (Strict)

Step 5: Start Runtime + Dashboard

Then open http://localhost:17901 for the web dashboard. The Setup tab can choose providers, search models, enter a key, test the connection, and save the AI config without using the terminal.

Step 6: Run Primary Workflow

Architecture

Neugi v2 isn't a chatbot loop. It's a deterministic multi-agent state machine with 29 subsystems designed for production-grade reliability at scale.

Core Subsystems

Agent Archetypes

Neugi uses six deterministic agent archetypes working in orchestrated harmony. Each is locked to a specific role, capable of routing to specialized sub-modules without human intervention.

Typed Agent LLM Wiring

Every agent is strongly typed with auto-generated tool schemas from Python type hints. The TypedAgent class injects tool definitions directly into the LLM prompt, enabling structured function calling across local, cloud, and custom compatible providers.

from neugi_swarm_v2.agents.typed import TypedAgent, agent_tool

class MyAgent(TypedAgent):
    @agent_tool(description="Search the web")
    def search(self, query: str, max_results: int = 5) -> dict:
        ...

Context Memory

Neugi utilizes a built-in hierarchical memory system bridging the gap between small context windows and massive operational history. It reads and writes deterministically without heavy dependencies.

Memory Scopes

Vector Memory (v2.1.1)

Neugi now includes vector embeddings with three-tier fallback:

1. sentence-transformers (all-MiniLM-L6-v2, 384-dim, ~80MB)
2. Ollama embeddings (nomic-embed-text via local API)
3. TF-IDF (pure Python, zero dependencies)

Hybrid recall blends TF-IDF scoring (0.7) with vector similarity (0.3) for maximum accuracy.

Dreaming

The Memory agent triggers sleep-cycle consolidation ("dreaming") during idle periods. This compresses ephemeral memories into semantic summaries and prunes stale entries automatically.

Skill System

Neugi's skill system is designed for production reliability. Skills are loaded in 6 tiers with automatic promotion/demotion based on usage frequency and relevance.

Skills are defined via SKILL.md v3 specification with gating, token budgets, and automatic schema validation.

CLI Reference

Neugi provides a robust CLI for full swarm management, interactive chat, diagnostics, and configuration. The table below highlights key commands; run neugi help for the complete live command tree.

REST API

The Neugi gateway exposes REST API endpoints on the configured dashboard port (default 17901).

Agent Operations

Provider & Runtime Setup

WebSocket Events

Connect to ws://localhost:17901/ws for real-time events:

• agent_status — Agent state changes
• memory_event — Memory writes/recalls
• tool_execution — Tool call results
• system_alert — Errors and warnings

Telegram Bot

Command your swarm remotely via a secure Telegram bridge. The bot provides full parity with the CLI interface and supports image uploads with vision model fallback.

Available Commands

Configuration

# In config.json or via neugi wizard
"channels": {
    "enabled": true,
    "telegram": {
        "token": "YOUR_BOT_TOKEN",
        "mode": "polling"
    }
}

Rescue & Wizard

Neugi v2.1.3 includes a comprehensive Rescue Wizard designed to help users when things go wrong — no terminal expertise required.

Setup Wizard

First-time users can run neugi wizard for guided setup:

1. Directory creation and permission checks
2. Provider selection from current multi-provider catalog (including NVIDIA NIM and compatible endpoints)
3. Model selection with compatibility hints
4. Feature enablement (memory, skills, channels, dashboard)
5. Connection test before finishing

Rescue Mode

When something breaks, run neugi rescue to auto-detect and fix:

Corruption Repair

neugi rescue --repair detects and fixes corrupted files:

• Invalid JSON configs are restored from defaults
• SQLite databases are integrity-checked and repaired
• Session files are validated and pruned if corrupted

Provider Switching

neugi rescue --switch-provider guides you through changing LLM providers without breaking existing configuration:

Enterprise Risk & Safety

This section is designed for due diligence, security review, and production governance. NEUGI is powerful agentic infrastructure; safe deployment requires explicit controls, human approval paths, and staged rollout discipline.

Risk Runbook

Use this runbook as the standard operational loop for all environments:

1. Scope and classify task risk (info / warn / critical) before execution.
2. Constrain capabilities: load only required tools, providers, and channels for the task.
3. Gate with approval policy: require explicit human approval for medium/high impact actions.
4. Execute in staged environment first with representative data and limited blast radius.
5. Observe and audit via governance logs, approval queue, and severity triage.
6. Promote to production only after repeatable pass criteria are met.

Approval Matrix by Risk Level

Environment Policy Baseline

Operational Checklist (Go / No-Go)

• Identity & Access: least-privilege keys, scoped credentials, rotation policy documented.
• Guardrails: approval queue active, high-risk tooling gated, sandbox boundaries validated.
• Observability: runtime logs, governance events, and alert routing verified.
• Resilience: fallback provider strategy tested, rescue workflow practiced.
• Compliance: data handling and retention aligned with internal/legal requirements.

Recommended Command Sequence

Compliance Artifact Mode

Generate an auditable due-diligence package (JSON + executive markdown) while enforcing a governance profile:

Artifacts are written to ~/.neugi/reports/ and include runtime fingerprint, gate results, governance stats, and active approval rules.

Ecosystem & Partnership

Neugi is designed as a Neural Bridge — a unifying layer that connects the reliability of local core engines with the raw reasoning power of frontier SOTA models.

Ecosystem Vision 2026

1. Provider-Agnostic Foundation — Cloud, local, and custom compatible endpoints within one unified runtime
2. Global Reach — Native integration for OpenAI, Anthropic, Gemini, Grok, and more
3. Cost Efficiency — Flexible scaling across DeepSeek, Qwen, NVIDIA NIM, and other optimized providers
4. Hardware Agnostic — Runs on CPU, GPU, or Apple Silicon with automatic backend selection

Collaboration & Grants

We are actively seeking partnerships with AI hardware and software providers to expand the boundaries of autonomous swarm intelligence. If you are a model provider or research organization, we invite you to connect for grants and integration opportunities.

Contact: atharia.agi@gmail.com • @Atharia_AGI