phantom-neural-cortex

Phantom Neural Cortex (PNC) is a unified AI employee system that orchestrates planning, security, tool execution, and team communication in one deployable package. It combines the PhantomAgent runtime, the HRM Controller for planning, NSS security layers, the echo_log tool execution environment, and a Mattermost bridge for team messaging. When started in gateway mode, the system exposes an API for task submission, routes tasks through NSS and planners, executes steps via local or cloud LLMs, and provides real-time updates to your Mattermost channel. This makes it suitable for automating complex workflows, risk-scored task execution, and collaborative task management with built-in kill-switch capabilities for safety.

To use it, start the agent with a configured AGENT.yaml, which defines the agent’s role, language models, and security posture. The gateway coordinates orchestration, while the agent handles task execution and reporting. You can submit tasks via the REST endpoint at the gateway (for example, http://localhost:18789/agent/<agent-name>/task) and monitor progress and results through Mattermost or the local TUI if you enable the Kommandozentrale component. The system also supports a docker-compose setup for full-stack deployment, including NSS services, databases, and the messaging bridge, so you can run a complete, production-like environment with a single command.

Prerequisites:

• Git
• Python 3.8+ and pip
• Optional: Docker and Docker Compose for full-stack deployment
• Access to a compatible LLM (cloud or Ollama local) as configured in AGENT.yaml

Step 1: Clone the repository

git clone https://github.com/LEEI1337/phantom-neural-cortex
cd phantom-neural-cortex

Step 2: Create a virtual environment and install dependencies

python -m venv venv
source venv/bin/activate  # on Unix/macOS
venv\Scripts\activate     # on Windows
pip install -r requirements.txt

Step 3: Prepare an agent configuration

• Use the provided template in config/templates (e.g., lisa01.yaml) or create your own AGENT.yaml
• Ensure the AGENT.yaml defines:
  • agent.name
  • agent.role
  • llm.planner / llm.executor
  • security.nss_enabled and related settings

Step 4: Run the gateway with an agent configuration

# Example (adjust paths to your environment)
python run_agent.py --config agents/lisa01/AGENT.yaml --gateway

Step 5: (Optional) Deploy the full stack with Docker Compose

docker compose up -d

Step 6: Verify operation

• Access the gateway REST API at http://localhost:18789
• Connect Mattermost bridges if configured and monitor agent activity

Notes:

• If you need to customize environment, edit the AGENT.yaml and the gateway config to match your deployment.
• For local testing, you can run a single agent in gateway mode with a sample AGENT.yaml path that you provide.

Tips and common considerations:

• NSS layers (Sentinel, Mars, Vigil, Shield) provide defense-in-depth. If NSS is offline, the system can degrade safely to SAFE mode but with reduced protections.
• The 3-way killswitch can be triggered via terminal, Mattermost command, or REST API. Ensure proper ownership and access controls for your environment.
• The 42 tools exposed through echo_log enable a wide range of actions; ensure you review and approve tool usage in your organization, especially for sensitive operations.
• When using the full Docker Compose stack, ensure your environment has sufficient resources (CPU, RAM, and database storage) to support the gateway, NSS services, and memory backends.
• The AGENT.yaml schema is validated; use config/templates as reference and validate your own configs against the schema to avoid deployment errors.
• Environment variables like MM_GATEWAY_HOST and MM_GATEWAY_PORT should reflect your actual gateway address when running in non-local environments.