Metadata-Version: 2.4
Name: polymath-nodeos
Version: 1.0.5
Summary: A zero-dependency Autonomous Agentic Swarm Operating System.
Author: Polymath Void
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 🧠 Polymath-NodeOS: The Autonomous Swarm Operating System

[![Zero Dependency](https://img.shields.io/badge/Dependencies-Zero-brightgreen.svg?style=for-the-badge)](#) [![Agent Compatible](https://img.shields.io/badge/Agent-Native-purple.svg?style=for-the-badge)](#) [![Platform](https://img.shields.io/badge/Platform-Cross--Platform-blue.svg?style=for-the-badge)](#) [![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue.svg?style=for-the-badge)](#) [![License](https://img.shields.io/badge/License-MIT-gray.svg?style=for-the-badge)](#)

**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 `grep`ing 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:
```bash
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`.

After pip installing, you must run the Antigravity integration setup once:
```bash
nodeos --install
```
This automatically maps NodeOS directly into your AI Agent's global memory (`~/.gemini/config/`), granting them the `nodeos_standard.md` rule and `agy-nodeos-installer` injection protocols.

---

## 📖 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:
```bash
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`:
```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:**
> [^1]: Barnes, J., & Hut, P. (1986). A hierarchical O(N log N) force-calculation algorithm (QuadTree application for NodeOS physics).
> [^2]: SQLite Consortium (2024). ACID-compliant transactional guarantees for embedded graphs.

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