Skip to content

README.md

Latest commit

 

History

History
207 lines (161 loc) · 6.21 KB

README.md

File metadata and controls

207 lines (161 loc) · 6.21 KB

ConsensusMind

Autonomous AI researcher for blockchain consensus mechanisms.

Overview

ConsensusMind is a local-first autonomous research toolchain for blockchain consensus protocols. It performs literature review, generates hypotheses, runs simulations/experiments, and produces publication-ready outputs (LaTeX paper + Markdown whitepaper).

Status

Current Version: 0.10.0

Project Status: Complete (Milestones 1–10 delivered)

Completed Milestones

Milestone 1: Foundation & Infrastructure

  • Project initialization and structure
  • Configuration system with TOML and environment variable support
  • Logging infrastructure (file + console)
  • LLM client with exponential backoff retry logic
  • Integration tests
  • Production-ready code quality (zero warnings)

Milestone 2: Knowledge Ingestion

  • arXiv API integration with HTTPS
  • PDF download and local storage
  • JSON-based metadata tracking
  • PDF text extraction and analysis
  • Rate limiting and error handling
  • Search and store workflow

Milestone 3: Knowledge Base

  • Local embedding index build/update
  • Semantic search over indexed papers

Milestone 4: Agent Core

  • Agent runner with step tracking and persisted run memory
  • Report generation

Milestone 5: Consensus Simulator

  • Deterministic simulators with CLI entrypoints

Milestone 6: Hypothesis Generation

  • LLM-driven hypothesis generation with novelty scoring
  • Hypotheses persistence and reporting

Milestone 7: Automated Experimentation

  • Experiment runner tied to hypothesis IDs
  • Results saved under data/experiments and summarized into output reports

Milestone 8: Paper Generation

  • LaTeX paper generation from hypotheses and experiment results

Milestone 9: Integration & Polish

  • Unified CLI entrypoints (help/version and command usage)
  • Repo structure improvements for outputs and data directories

Milestone 10: Whitepaper & Research Paper

  • Whitepaper (Markdown) and research paper (LaTeX) generation from hypotheses and experiment results

Features

Current (v0.10.0)

  • Configuration management from TOML files
  • Environment variable overrides for sensitive data
  • Structured logging to file and console
  • HTTP client for vLLM/RunPod inference endpoints
  • Automatic retry with exponential backoff
  • Comprehensive error handling
  • arXiv paper search and retrieval
  • PDF download with duplicate detection
  • Metadata persistence in JSON
  • PDF text extraction for analysis
  • Local embedding index + semantic search
  • Agent run pipeline (search, download, index, retrieve, summarize, report)
  • Hypothesis generation and persistence
  • Consensus simulation and experimentation
  • LaTeX paper generation from experiment outputs
  • CLI help/version and stable command interface
  • Whitepaper + research paper publishing commands

Architecture

Built in Rust for production reliability and performance.

Core Components:

  • Agent executor with planning and memory
  • Knowledge base with vector search
  • Consensus protocol simulator
  • LLM client for reasoning tasks
  • LaTeX/Markdown output generation
  • arXiv integration for paper retrieval
  • PDF parsing and text extraction

Tech Stack:

  • Language: Rust 2021 edition
  • Async Runtime: Tokio
  • HTTP Client: Reqwest with rustls
  • Logging: Tracing
  • Config: TOML
  • LLM: Self-hosted vLLM (DeepSeek/Qwen)
  • PDF Processing: pdf-extract
  • Data Storage: JSON metadata + local files

Requirements

  • Rust 1.70+
  • GPU inference server (RunPod, self-hosted vLLM, or compatible endpoint)
  • Storage for paper corpus

Installation

git clone https://github.com/ChronoCoders/consensusmind.git
cd consensusmind
cargo build --release

Configuration

Create config.toml in the project root with LLM endpoint, model settings, paths, agent parameters, and logging configuration.

For secrets (like API keys), use either:

  • Environment variables (recommended), or
  • config.local.toml (kept out of git via .gitignore)

Environment variable overrides available:

  • LLM_ENDPOINT
  • LLM_API_KEY
  • LLM_MODEL
  • CONFIG_PATH

Additional settings:

  • knowledge.max_pdf_bytes controls the maximum allowed PDF download size.

Usage

consensusmind run "<query>"
consensusmind hypothesize "<query>"
consensusmind experiment <hypothesis-id> [--seeds N] [--ticks T] [--nodes N]
consensusmind paper <hypothesis-id>
consensusmind whitepaper <hypothesis-id>
consensusmind publish <hypothesis-id>
consensusmind index
consensusmind semantic-search "<query>" [top_k]
consensusmind simulate [rounds] [leader_failure_prob] [seed]
consensusmind raft-simulate [nodes] [ticks] [seed]
consensusmind help
consensusmind --version

Supports end-to-end research runs, hypothesis generation, experiments, and paper/whitepaper generation.

Outputs

Artifacts are written to disk so runs are reproducible and auditable:

  • data/metadata.json: paper metadata store
  • data/embeddings/index.json: local embedding index
  • data/hypotheses.json: generated hypotheses
  • data/experiments/<hypothesis-id>/results.json: experiment results
  • output/reports/*.json: run/hypothesis/experiment reports
  • output/papers/*.tex: generated LaTeX papers
  • output/papers/*.md: generated Markdown whitepapers

Development

cargo build          # Build debug
cargo test           # Run tests
cargo fmt            # Format code
cargo clippy         # Lint
cargo build --release # Build optimized

This repository does not ship GitHub Actions workflows. Run the commands above locally for formatting, linting, and tests.

Roadmap

  • Milestone 1: Foundation & Infrastructure
  • Milestone 2: Knowledge Ingestion
  • Milestone 3: Knowledge Base
  • Milestone 4: Agent Core
  • Milestone 5: Consensus Simulator
  • Milestone 6: Hypothesis Generation
  • Milestone 7: Automated Experimentation
  • Milestone 8: Paper Generation
  • Milestone 9: Integration & Polish
  • Milestone 10: Whitepaper & Research Paper

License

Apache 2.0 - See LICENSE file

Contact

Distributed Systems Labs, LLC

Contributing

This project maintains strict code quality standards:

  • Zero compiler warnings
  • Zero dead code
  • Zero unused imports
  • Production-ready quality required

Contributions welcome via pull requests.