ARCHITECTURE.md

# Nuclear Intelligence Project Architecture Design

## 1. Introduction

This document outlines the detailed architecture for the **Nuclear Intelligence** project, aiming to autonomously expand and tokenize nuclear energy knowledge. The system will leverage advanced AI techniques, including Retrieval Augmented Generation (RAG), a dynamic Knowledge Graph, and a simulated Virtual Blockchain, to convert novel scientific insights into a stablecoin (NES).

## 2. Core Ideology

The central tenet of Nuclear Intelligence is to rapidly, deeply, and autonomously disseminate nuclear energy knowledge as the foundation for a prosperous, clean, secure, and digital 21st-century civilization. By directly converting genuine scientific advancements (complex questions + accurate, novel answers) into NES tokens, the project transforms knowledge into sustainable economic value, providing real scientific backing for the NES stablecoin.

## 3. System Components and Enhancements

The Nuclear Intelligence system is composed of several interconnected modules, each designed for specific functionalities and integrated to achieve the overarching goal. The existing codebase provides a foundational structure, which will be enhanced and expanded upon.

### 3.1. Nuclear Intelligence Core (NI Core)

**Current State:** The `core/nuclear_intelligence.py` file contains a basic `NuclearIntelligenceCore` class with methods for generating questions, conducting research, evaluating answers, and adding to a knowledge base. It uses `ChatOpenAI` for LLM interactions and `HuggingFaceEmbeddings`.

**Proposed Enhancements:**
*   **Base Model:** Utilize the strongest available LLM (e.g., Llama-3.1-70B, Qwen2.5-72B, or Mixtral Large) with intelligent quantization for optimal performance. The current `ChatOpenAI` will be configured to use the specified model via API calls.
*   **Advanced RAG:**
    *   **Vector Database:** Implement a robust vector database using `FAISS` (as indicated by `faiss-cpu` in `requirements.txt`) or `pgvector` for efficient similarity search. The `vector_db` attribute in `NuclearIntelligenceCore` will be properly initialized and managed.
    *   **Hybrid Search:** Combine keyword-based search (e.g., BM25) with vector similarity search for comprehensive retrieval.
    *   **Reranking:** Integrate a reranking mechanism (e.g., using `sentence-transformers` or a dedicated reranker model) to improve the relevance of retrieved documents before feeding them to the LLM.
*   **Knowledge Graph Integration:** The existing `KnowledgeGraph` class will be deeply integrated. Instead of a simple dictionary, the `knowledge_base` will primarily interact with the `KnowledgeGraph` for structured knowledge representation and retrieval. This will involve: 
    *   Storing entities and relationships extracted from research answers.
    *   Using graph traversal for contextual retrieval during RAG.
    *   Potentially simulating a graph database (like Neo4j) within JSON structures for persistence and queryability.
*   **Persistent Memory:** Ensure all cycles, ledger states, and datasets are persistently stored. This will involve saving the Knowledge Graph, vector database index, and research history to disk or cloud storage (e.g., Hugging Face Datasets Repository, Git LFS, or mounted volumes).

### 3.2. Virtual Blockchain (Virtual Ledger)

**Current State:** The `blockchain/virtual_ledger.py` file contains a `VirtualLedger` class that simulates a blockchain with blocks, transactions, and NES token minting. It includes basic functionalities like adding transactions, mining blocks, and exporting the ledger state.

**Proposed Enhancements:**
*   **Full Blockchain Features:** Enhance the virtual blockchain to include all realistic blockchain features such as immutability, transparency, and auditability. This involves robust hashing, timestamping, and cryptographic signatures (already partially implemented with `hmac`).
*   **NES Token Minting:** The `mint_nes_token` function will be refined to ensure that exactly 1 NES token is minted for each validated scientific advancement, with comprehensive metadata including the question, answer, evaluation scores, cryptographic hash, model version, and Hugging Face link.
*   **Mirroring and Sync:** Implement continuous synchronization mechanisms to mirror the NES value and ledger state between the internal virtual blockchain and the external dedicated project network (Custom App-chain/Rollup). This will involve secure webhook/relayer/script mechanisms for external minting commands.

### 3.3. Operation Loop

**Current State:** The `core/operation_loop.py` defines the `OperationLoop` class, which orchestrates the main AI cycle: question generation, research, evaluation, and token minting. It includes configuration for thresholds and question generation.

**Proposed Enhancements:**
*   **Automated, Precise, and Creative Execution:** The loop will run every 30-60 minutes, focusing on:
    *   **Step 1: Question Generation:** Generate 1-3 highly complex, multidimensional, and cutting-edge questions combining physics, engineering, economics, safety, novel applications, and AI integration.
    *   **Step 2: Deep Research:** Conduct thorough research using enhanced RAG, search tools (e.g., web search, arXiv API), and a citation generator to produce long, accurate scientific answers with equations, practical examples, and citations.
    *   **Step 3: Multi-layer Professional Evaluation:** Implement stringent evaluation criteria:
        *   Scientific Accuracy ≥ 93%
        *   Novelty Score (semantic comparison with Knowledge Base)
        *   Usefulness for NES project (valuation, risk, innovation)
        *   Self-consistency check (multiple tests)
    *   **Step 4: Token Minting (if approved):** If the answer is validated, a new block will be created in the Virtual Blockchain, and exactly 1 NES token will be minted with full metadata. An external minting command will be issued via a secure mechanism.
    *   **Step 5: Knowledge Integration:** Add new knowledge to the Knowledge Graph and vector database. If resources allow, perform or queue small LoRA fine-tuning. Upload new datasets to Hugging Face.
*   **Error Recovery:** Implement intelligent error recovery mechanisms to handle failures gracefully and log them comprehensively.

### 3.4. Scheduling and Persistence

**Current State:** The `app.py` and `api/main.py` suggest a FastAPI backend and Gradio frontend. The `scripts` directory contains `run_operation_cycle.py` and `sync_huggingface.py`, indicating some scheduling and synchronization capabilities.

**Proposed Enhancements:**
*   **Always Online and Persistent System:**
    *   **GitHub Actions Workflow:** Implement a GitHub Actions workflow to ping the Hugging Face Space every 25 minutes to prevent sleep mode.
    *   **External Scheduler Fallback:** Integrate an external scheduler (e.g., a simple cron job on a separate VM or a cloud function) as a fallback for internal cron-like mechanisms.
    *   **Persistent Storage:** Utilize Hugging Face Datasets Repository, Git LFS, and potentially mounted volumes for persistent storage of the Knowledge Graph, vector database, research history, and blockchain state.
    *   **Auto-restart Mechanism:** Implement a robust auto-restart mechanism in case of sleep or errors, possibly using Docker health checks and restart policies.
*   **Hugging Face Space Deployment:** The project will be deployed on a Hugging Face Space, configured for 
Always-On status and auto-restart capabilities.

### 3.5. Human-in-the-Loop and Guardrails

**Proposed Enhancements:**
*   **Human-in-the-Loop:** Implement an initial human-in-the-loop mechanism for the primary developer (Qalam) to review and log high-novelty findings.
*   **Nuclear Guardrails:** Develop strong guardrails to prevent misinformation and ensure the scientific integrity of generated content, especially concerning sensitive nuclear topics.

### 3.6. NES Token Integration and Governance

**Proposed Enhancements:**
*   **Full Integration:** Ensure complete integration with the external NES stablecoin, where validated knowledge acts as an oracle to back the token's value.
*   **Governance:** Prepare the system for future governance by NES token holders, allowing community input on project direction and parameters.

### 3.7. Auto-Documentation and Visualization

**Proposed Enhancements:**
*   **Auto-Documentation:** Implement automatic documentation generation for code, architecture, and operational logs.
*   **Visualization:** Develop tools for visualizing progress, Knowledge Graph evolution, and blockchain activity.

## 4. Execution Style

The project will be executed with a highly professional, precise, developer-first, creative, and automated approach. Every cycle will be logged with full details, and intelligent recovery mechanisms will be in place for error handling.

## 5. Initial Setup and Continuous Operation

Upon initiation, the system will:
1.  Validate all credentials (Hugging Face Token, GitHub Personal Access Token).
2.  Create a new Hugging Face Space (e.g., `nuclear-intelligence` or `nuclear-intelligence-core`) using the `smolagents` or `Gradio + LangGraph` template.
3.  Create a new GitHub Repository named `nuclear-intelligence`.
4.  Link the Hugging Face Space to the GitHub Repository with a complete workflow.
5.  Commit and push all initial project files (main code, `requirements.txt`, `.env` with keys, scheduler, Knowledge Base initializer, Virtual Ledger engine).
6.  Deploy the Space and activate Always-On settings.
7.  Provide a comprehensive report on the setup status (Space link, GitHub link, deployment status).

Following the initial setup, the main Nuclear Intelligence loop will commence, executing its first full cycle with detailed output and logging.