🧠 Polymath-NodeOS: The Autonomous Swarm Operating System

Polymath-NodeOS is a zero-dependency Autonomous Agentic Operating System designed specifically to run natively alongside the Antigravity (AGY) CLI environment. By intercepting OS events and using advanced mathematical physics—specifically modeling code components using a Native QuadTree matrix, Hooke's Law, and Coulomb Repulsion—Polymath-NodeOS creates a physical environment for LLM swarms to natively understand code structure, dependencies, and blast radiuses instantly.

This project is 100% cross-platform and runs flawlessly on Windows, macOS, Linux, and Android (Termux).

🚀 Key Features & Real-World Use Cases

The true value of Polymath-NodeOS is curing the "blind spot" problem that plagues traditional AI coding agents. Instead of blindly modifying files and breaking downstream dependencies, NodeOS mathematically calculates the structural layout of your codebase into a native SQLite database (agy_nodeos.db).

1. Real-Time Blast Radius Warnings 💥

• The Problem: An agent changes a core utility function without realizing it breaks 14 deeply nested components.
• The NodeOS Solution: The zero-dependency watchdog detects the file save. It instantly runs a recursive SQLite CTE to calculate the transitive dependents. If the "blast radius" is high, it automatically drops an ephemeral warning directly into the agent's memory stream, preventing catastrophic commits.

2. Spatial Context Ghost Writer 👻

• The Problem: AI agents waste massive amounts of tokens and time greping or opening multiple files to memorize function signatures when building new APIs.
• The NodeOS Solution: When a new file is created, NodeOS calculates its QuadTree spatial centroid, locates the 10 closest physical neighbors in the AST matrix, and seamlessly injects their exact code signatures into the agent's context payload. The agent writes flawless code on the first try without a single research tool.

3. The Domino Refactor Engine 🎲

• The Problem: Standard refactoring using Regex search-and-replace accidentally corrupts identically named variables or comments across massive projects.
• The NodeOS Solution: NodeOS uses pure Graph Theory (Inner Joins on AST Edges) to locate the precise structural files invoking a specific function hash. It then dynamically dispatches a massive parallel array of Antigravity Swarm agents to deterministically refactor the files.

4. Semantic Dead Code Eradication ☠️

• The Problem: Unused code accumulates, polluting the LLM's context window.
• The NodeOS Solution: A native engine queries the graph for orphaned nodes (nodes with 0 incoming AST dependencies) and automatically orchestrates the safe deletion of dead code.

🛠 Installation Guide (For Users)

Polymath-NodeOS is designed for frictionless installation.

Method 1: The One-Click Auto-Install (Recommended)

If you are using the Antigravity IDE, simply cloning this repository and opening the workspace will automatically trigger the .agents/hooks.json script. The system will seamlessly install itself into your global environment.

Method 2: Manual Installation

Install the package globally via pip:

pip install polymath-nodeos

What this does:

1. Installs the nodeos CLI globally.
2. Allows you to instantly boot the Swarm OS in any folder.
3. Automatically triggers your swarm agents to read workflow.json.

📖 Usage Guide

Polymath-NodeOS works silently in the background to empower your AI agents.

Starting the OS

To initialize NodeOS in a project directory, you or your agent can start the background daemon:

nodeos -d

Note: In properly configured workspaces, the daemon automatically boots when the agent initializes thanks to the AGY Customization Engine (PreInvocation hook).

Dispatching Swarm Tasks

Instead of manually typing prompts, you can add task drops to workflow.json:

{
  "type": "JSON_Task",
  "status": "pending",
  "action": "execute_agents",
  "agents": ["architect_designer"]
}

The daemon detects the pending state and automatically alerts your agent swarm via lifecycle hooks.

🤖 Agent Protocol (For AI Agents)

If you are an autonomous AI Agent interacting with this workspace, adhere to the Native Interaction Paradigm:

1. File Operations: Use your built-in editing tools (e.g., view_file, replace_file_content).
2. Spatial Queries: Use standard SQL queries against agy_nodeos.db to trace dependencies.
3. Task Orchestration: Update the status field in workflow.json to manage sub-agent queues.
4. Feature Modules: Do NOT execute standard searches for refactoring. Utilize the pre-built mathematical engines located in the scripts/ directory.

🧬 Architectural Workflow & Citations

The underlying architecture relies on several foundational concepts adapted for LLM systems:

1. Auto-Boot: hooks.json intercepts PreInvocation events, booting the Python daemon daemon.py silently in the background.
2. Deep Ingestion: The daemon scans the project using jage_engine.py, mapping semantic ast.Call edges natively.
3. Kinetic Simulation: nodes_engine.py hydrates the QuadTree and applies spatial algorithms to physically pull dependent AST blocks into clustered coordinates.
4. Intent Emission: When a workflow intent is detected, it is logged to workflow.json.
5. Telemetry Tracking: scripts/telemetry.py natively tracks Swarm execution intents and state transitions (Pending -> Running -> Completed).

Citations:

Built natively for the Antigravity Agent Swarm Ecosystem. Optimized for speed, context, and zero-dependency portability.