Skip to content

README.md

Latest commit

 

History

History
143 lines (105 loc) · 8.51 KB

README.md

File metadata and controls

143 lines (105 loc) · 8.51 KB
Raw

HumanityOS: Consensus Arena

A cinematic AI war room that orchestrates 12 specialist agents to debate, fetch live data, and map the cascading consequences of your most complex decisions.

License: MIT TypeScript React Node.js Tailwind CSS Prisma

HumanityOS Demo Video

1. Executive Summary & Abstract

In modern enterprise, governance, and daily life, complex decision-making scenarios—ranging from agricultural planning to global tech migrations—are often plagued by human bias, cognitive blind spots, and siloed data. While Artificial Intelligence offers powerful analytical capabilities, relying on a single Large Language Model (LLM) query often yields generalized, hallucinated, or overly agreeable advice without deep domain scrutiny.

HumanityOS is a full-stack Consequence Intelligence Platform designed to eliminate these blind spots. Operating as an interactive, cinematic "War Room," the system spins up 12 specialized AI agents to autonomously debate a user's decision, fetch live real-world data (such as weather forecasts or global public holidays), and synthesize the cascading consequences into a structured, interactive node graph and actionable 30-day timeline.

2. Introduction

2.1 The Crisis of Single-Agent AI

When individuals or organizations make critical decisions using standard chatbots, they fall victim to "sycophancy"—where the AI attempts to please the user rather than critically evaluate the risks. A single prompt lacks the adversarial scrutiny required to stress-test an idea. Furthermore, standard models lack immediate awareness of real-world, real-time constraints (e.g., "Is there a hurricane hitting the city I want to host my event in next week?").

2.2 The Solution: Multi-Agent Consensus

We were inspired to build a system that mirrors a real-world executive board meeting. Rather than one AI giving a unified answer, HumanityOS deploys a committee of agents that aggressively debate each other. By enforcing a strict "Zero-Mock Data Policy," we ensure the system relies entirely on live external APIs and real-time LLM inference to provide authentic, highly reliable decision frameworks.

3. System Architecture & Tech Stack

HumanityOS is engineered as a decoupled full-stack application, prioritizing high performance and real-time responsiveness during intense, parallel AI orchestration.

3.1 The Frontend UI

  • Core Framework: React 18, TypeScript, and Vite.
  • Aesthetic & Styling: Tailwind CSS was heavily utilized to create a "Cinematic Dark Mode" experience, relying on deep slate backgrounds, glowing neon accents, and glassmorphism.
  • Animations: Framer Motion powers the complex state-driven animations, specifically the mesmerizing "Arena" loading sequence.
  • Data Visualization: ReactFlow is used to render the highly complex, interactive Consequence Map, allowing users to drag, zoom, and explore 1st, 2nd, and 3rd-order consequences dynamically.

3.2 The Backend API

  • Server: Node.js running an Express.js REST API.
  • State Management: Prisma ORM connected to a local SQLite database, allowing for rapid iteration and persistent storage of previous decision sessions.

3.3 LLM Orchestration Layer

  • Inference Engine: The custom-built parallel pipeline utilizes the OpenAI Node.js SDK. To handle 12 simultaneous agents generating heavy JSON schemas without locking up, the primary inference is routed through Groq Cloud (Llama-3.1-8b-instant) for blazing-fast tokens-per-second.
  • Failover Mechanisms: If Groq's rate limits are exceeded, the pipeline dynamically falls back to OpenAI's GPT-4o-mini.

4. The 12-Agent "Consensus Arena"

At the core of the system is the custom AI orchestration pipeline. Rather than executing sequentially, the orchestrator fires parallel asynchronous requests in distinct phases.

Phase 1: Contextualization

  1. Decision Parser: Analyzes the raw string input, extracting the core title and description.
  2. Context Enricher: Adds domain-specific framing based on the user's category.

Phase 2: Opening Arguments

  1. Finance Controller: Analyzes budget, burn rate, and ROI.
  2. Geo-Logistics Expert: Evaluates physical space, supply chains, and travel.
  3. Ethics & Compliance: Ensures legal frameworks and moral standards are upheld.
  4. Agriculturalist / Domain Expert: Swaps in dynamically depending on the category.

Phase 3: Adversarial Rebuttals

The orchestrator aggregates all opening arguments and feeds the massive block of text back to the agents. The agents generate targeted rebuttals, actively hunting for logical fallacies in each other's statements.

Phase 4: Risk Inspection & Final Synthesis

  1. Assumption Hunter: Scans the debate for hidden assumptions.
  2. Risk Intelligence: Builds a probability × severity risk matrix.
  3. Blind Spot Detector: Actively seeks out overlooked considerations.
  4. Tradeoff Analyst: Compares immediate benefits against long-term costs.
  5. Executive Judge: The critical synthesizer. It reads the entire multi-turn debate transcript and generates a massive JSON payload mapping out the exact node-structure for the ReactFlow graph, the stakeholder matrices, and a final confidence score.
  6. Action Planner & Quality Reviewer: Extracts a concrete 30-day milestone timeline and validates the structural integrity of the output.

5. Live Data Grounding & API Integrations

To prevent the agents from debating in a vacuum, the orchestrator detects the category of the decision and fetches live external data:

5.1 OpenStreetMap Nominatim API

Geocodes physical location strings into precise latitude and longitude coordinates.

5.2 Open-Meteo API

Using the coordinates, the system fetches real-time meteorological data and 7-day weather forecasts to inject into the Agriculture and Logistics agents' prompts.

5.3 Nager.Date API

Cross-references proposed dates against real-world global public holidays to warn the user about travel restrictions or bank closures.

6. Technical Hurdles & The "Zero-Mock" Policy

The defining technical challenge was the strict enforcement of the "Zero-Mock Data Policy." During early alpha testing, if the backend hit an API rate limit, the system would silently fall back to "mock data." Purging these mocks forced us to engineer a highly resilient orchestration pipeline with a robust fail-fast tracking system (trackAgent). If an agent fails to connect, the frontend explicitly renders a red [Agent Disconnected] badge, guaranteeing absolute data integrity over silent hallucinations.

We also overcame severe JSON formatting issues with the high-speed Llama 3.1 model by strictly enforcing response_format: { type: 'json_object' } and optimizing the prompt engineering syntax.

7. Responsible AI Guardrails

7.1 Bias Mitigation

By forcing 12 distinct AI personas to aggressively debate and rebut each other's opening statements, we actively combat AI confirmation bias.

7.2 Human-in-the-Loop

HumanityOS does not autonomously execute decisions. The cascading consequences of high-stakes decisions carry severe real-world liabilities. The AI acts exclusively as a brilliant, data-driven advisory board, leaving ultimate authorization power to the human user.

8. Quick Start / Run Locally

  1. Clone the repository:

    git clone https://github.com/RunAzoth/HumanityOS.git
cd HumanityOS

  2. Backend Setup:

    cd backend
npm install
cp .env.example .env
# Add your GROQ_API_KEY and OPENAI_API_KEY to the .env file
npm run setup
npm run dev

  3. Frontend Setup:

    # Open a new terminal
cd app
npm install
npm run dev

  4. Access the application: Open http://localhost:3000 in your browser.

9. License & Copyright

Built by Muhammad Taha Nawab
© 2024 Muhammad Taha Nawab. All Rights Reserved.
Licensed under the MIT License.