README.md

metadata

title: Nuclear Intelligence
emoji: ⚛️
colorFrom: yellow
colorTo: red
sdk: gradio
sdk_version: 4.36.0
python_version: 3.11
app_file: app.py
pinned: false

⚛️ Nuclear Intelligence v4.0

Autonomous nuclear-energy research pipeline that turns validated Q&A into on-chain NES tokens.

Nuclear Intelligence is a 24/7 autonomous system that:

1. Generates cutting-edge research questions about nuclear energy (fusion, SMR, Gen IV, waste, materials, safety, AI-assisted design, etc.)
2. Researches each question using a chain of free LLM providers (HF Router, Groq, DeepSeek, Gemini, Together, Fireworks, AIMLAPI) with automatic fallback.
3. Evaluates every answer with an independent LLM call (multi-layer: accuracy, novelty, usefulness, completeness, self-consistency).
4. Mints a NES token on a real SHA-3 Proof-of-Work blockchain for every answer that passes the thresholds.
5. Syncs all minted records to a public HuggingFace Dataset and the GitHub repo, so the corpus is openly readable.

🛡️ v4.0 Highlights (June 2026)

• Safety & Ethics Guardrails — hard pre-LLM + post-generation filter; refuses weapons / proliferation / RDD / cyber-proliferation prompts and redirects to legitimate peaceful-use topics.
• Enhanced Evaluation — multi-pass self-consistency, citation-quality scoring, novelty vs Knowledge Graph, and a Tokenization-Readiness composite (Accuracy ≥ 93 %, Novelty ≥ 75 %, Usefulness ≥ 80 %, Overall ≥ 85 %).
• Enhanced RAG — domain weighting (IAEA 2.5×, NRC 2.5×, peer-reviewed 1.7–1.8×), recency boost, diversity round-robin.
• Multilingual — automatic Persian / English detection + localized UI labels.
• Security — hardcoded API keys removed from app.py and LLM engines; all keys now flow through .env only.
• Health Check — python scripts/health_check.py runs 9 smoke tests; available in the Gradio UI under 🛡️ Safety & Health.

See CHANGELOG_V4.md for the full release notes.

---

🏗️ Architecture

                    ┌──────────────────────────────┐
                    │  GitHub Actions (every 25m)  │
                    │  • run_operation_cycle.py    │
                    │  • sync_huggingface.py       │
                    └──────────────┬───────────────┘
                                   │
                                   ▼
            ┌──────────────────────────────────────────┐
            │  NuclearIntelligenceCore (core/)         │
            │  ┌────────┐  ┌────────┐  ┌────────────┐  │
            │  │ LLM    │  │ RAG    │  │ Knowledge  │  │
            │  │ Engine │  │ FAISS  │  │ Graph      │  │
            │  └────┬───┘  └────────┘  └────────────┘  │
            │       │ multi-provider fallback         │
            └───────┼──────────────────────────────────┘
                    ▼
            ┌──────────────────┐    ┌──────────────────┐
            │ VirtualLedger    │    │ HF Dataset       │
            │ SHA-3 PoW chain  │◄──►│ (public)         │
            │ NES tokens       │    │ + GitHub repo    │
            └──────────────────┘    └──────────────────┘

Two deployment modes:

• GitHub Actions (.github/workflows/operation-loop.yml) — runs the full pipeline every 25 min.
• HuggingFace Space (hf_deploy/app.py) — Gradio UI + the same pipeline, runs 24/7 if upgraded to a paid tier, otherwise kept alive by keep_alive.yml.

---

🚀 Quick Start

HuggingFace Space (easiest)

1. Visit https://huggingface.co/spaces/Qalam/Nuclear-Intelligence
2. Click Run Research Cycle to mint a token.
3. Browse the Blockchain and Knowledge Graph tabs.

GitHub Actions (production)

1. Fork this repo.
2. Add secrets in Settings → Secrets and variables → Actions:
   • HF_TOKEN (required)
   • GITHUB_TOKEN (auto-provided, but secrets.GITHUB_TOKEN is read-only for PRs — use a PAT if you need to push from PRs)
   • GROQ_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, etc. (optional, for more LLM providers)
3. The workflow runs every 25 minutes automatically.

Local development

git clone https://github.com/QalamHipHop/nuclear-intelligence.git
cd nuclear-intelligence
pip install -r requirements.txt
cp .env.template .env  # fill in API keys
python scripts/run_operation_cycle.py  # one cycle
python -m uvicorn api.health:app --reload  # API on :8000

---

🔑 Required Secrets

Secret	Required?	Used by
HF_TOKEN	✅	LLM provider, dataset sync, space deploy
GITHUB_TOKEN	optional	report commit, ledger push
GROQ_API_KEY	optional	LLM provider (fastest)
DEEPSEEK_API_KEY	optional	LLM provider (best free)
GEMINI_API_KEY	optional	LLM provider
TOGETHER_API_KEY	optional	LLM provider
FIREWORKS_API_KEY	optional	LLM provider
AIMLAPI_API_KEY	optional	LLM provider
BLOCKCHAIN_SECRET	optional	HMAC for tx signing

Without any LLM key, the system falls back to demo mode (no real research, no minting).

---

📁 Project Structure

nuclear-intelligence/
├── core/                         # Main pipeline (LLM + RAG + KG)
│   ├── llm_engine_v4.py         # Multi-provider LLM engine
│   ├── nuclear_intelligence_v4.py  # Research-to-token pipeline
│   ├── operation_loop_v4.py     # Autonomous loop
│   ├── knowledge_graph.py       # KG
│   ├── embeddings.py            # Sentence-transformers wrapper
│   └── web_search.py            # arXiv / web research
├── blockchain/
│   └── virtual_ledger.py        # SHA-3 PoW blockchain
├── api/
│   ├── health.py                # Health check + cycle trigger API
│   ├── main.py                  # Legacy FastAPI
│   └── enhanced_api.py          # Full FastAPI
├── hf_deploy/                    # Self-contained for HF Space
│   ├── app.py                   # Gradio UI + inline pipeline
│   ├── requirements.txt
│   └── Dockerfile
├── scripts/
│   ├── run_operation_cycle.py   # One cycle entrypoint
│   ├── sync_huggingface.py      # Push to HF dataset + GH
│   ├── initialize_knowledge_base.py
│   └── keep_alive.py
├── knowledge_base/              # Persisted state (gitignored)
├── reports/                     # Cycle reports (gitignored)
├── logs/                        # Runtime logs (gitignored)
├── .github/workflows/
│   ├── operation-loop.yml       # Every 25 min
│   ├── keep_alive.yml           # Every 20 min (ping HF Space)
│   ├── deploy-hf.yml            # Push hf_deploy → Space
│   └── ci-cd.yml                # Lint + smoke tests
├── requirements.txt
├── requirements_enhanced.txt
├── requirements_hf.txt
└── docker-compose.yml

---

⚙️ Configuration

Edit .env (or set GitHub Actions secrets):

# Mint thresholds
MIN_ACCURACY=70
MIN_NOVELTY=60
MIN_USEFULNESS=60
MIN_OVERALL=65

# Mining
POW_DIFFICULTY=3        # 3 ≈ a few seconds; 4 ≈ a minute; 5+ = slow

# Loop
OPERATION_LOOP_INTERVAL_MINUTES=25

# LLM
DEFAULT_TEMPERATURE=0.7
MAX_TOKENS=4096

---

📊 API

Run locally: uvicorn api.health:app --port 8000

Method	Endpoint	Description
GET	/health	Liveness probe
GET	/ready	Readiness probe (checks LLM configured)
GET	/stats	Full system stats
GET	/chain	Blockchain stats
GET	/recent?limit=20	Recent cycles
GET	/search?q=...	Search knowledge graph
POST	/cycle	Trigger a research cycle
POST	/cycle with {"question": "..."}	Direct Q&A

Full docs at /docs (Swagger UI).

---

🪙 NES Tokenomics

• Symbol: NES (Nuclear Energy Science)
• Mint rate: 1 NES per validated research cycle (when all 4 thresholds + consistency pass)
• Supply: unbounded but rate-limited by the 25-min loop
• Ledger: /knowledge_base/virtual_ledger.json (full chain with PoW)
• Public mirror: https://huggingface.co/datasets/Qalam/nuclear-intelligence-dataset

The chain is a real blockchain:

• SHA-3-256 block hashes
• Real Proof-of-Work (configurable difficulty)
• Adaptive difficulty (raises if blocks mined too fast, lowers if too slow)
• Merkle-tree transaction verification
• HMAC-signed transactions

---

🧪 Testing

# Quick import + smoke test
python -c "from core.nuclear_intelligence import NuclearIntelligenceCore; print('OK')"

# Full ledger test
python -c "
from blockchain.virtual_ledger import VirtualLedger
import tempfile, os
with tempfile.TemporaryDirectory() as tmp:
    ledger = VirtualLedger(ledger_file=os.path.join(tmp, 'l.json'), difficulty=1)
    assert ledger.is_valid()
    ledger.mint({'test': True})
    assert ledger.is_valid()
    assert ledger.nes_supply == 1.0
    print('✅ ledger OK')
"

# GitHub Actions also runs these in .github/workflows/ci-cd.yml

---

🤝 Contributing

1. Fork the repo.
2. Create a feature branch.
3. Run python -m pytest tests/ (if you add tests).
4. Open a pull request.

The CI will run lint + smoke tests automatically.

---

📜 License

MIT

---

🔗 Links

• GitHub: https://github.com/QalamHipHop/nuclear-intelligence
• HuggingFace Space: https://huggingface.co/spaces/Qalam/Nuclear-Intelligence
• HuggingFace Dataset: https://huggingface.co/datasets/Qalam/nuclear-intelligence-dataset
• Architecture docs: ARCHITECTURE.md