Project

# Project
Hivemind-python is a python package implementing the Hivemind Protocol, a Condorcet-style Ranked Choice Voting System that stores all data on IPFS and uses Bitcoin-signed messages for verification.

# Requirements
ipfs-dict-chain >= 1.0.9
pytest >= 7.0.0
pytest-cov >= 4.0.0

# development_rules:
  - All tests must pass before pushing changes
  - Use package-relative imports
  - Maintain Python 3.10 compatibility
  - Follow existing code style and patterns (PEP 8)
  - Use type hints and annotations
  - Use Sphinx for documentation
  - Update README.md as needed
  - Use a testdriven development (TDD) approach, only add one test at a time and ask to commit after every successful test
  - Use the following command to run tests: python -m pytest
  - Always use 'python -m' versions of commands where possible
  - Use PowerShell syntax for your commands, like using ; instead of &&
  - VERY IMPORTANT: if a test fails, DO NOT CHANGE THE CORE CODE!! If you believe it is a bug you must first explain why to me!
  - Always run all tests with 'python -m pytest', don't waste my credits by doing single tests
  - When I tell you to do a diff to see the changes, do it with 'git diff', don't start analyzing things.

# Project Structure
/
├── LICENSE                 # Software license terms and conditions
├── README.md              # Project overview, installation and usage instructions
├── pytest.ini            # Configuration file for pytest testing framework
├── requirements.txt      # List of Python package dependencies
├── setup.py              # Package installation and distribution configuration
│
├── diagrams/             # System architecture and design diagrams
│   ├── class_diagram.md      # UML class diagram showing system architecture
│   ├── component_diagram.md  # System component relationships and interactions
│   ├── state_diagram.md      # State transitions in the voting system
│   └── voting_sequence.md    # Sequence diagram of the voting process
│
├── docs/                 # Documentation directory
│   └── source/          # Sphinx documentation source files
│       ├── conf.py           # Sphinx documentation configuration
│       ├── index.rst         # Main documentation landing page
│       └── modules/          # Module-specific documentation
│           ├── issue.rst         # Documentation for voting issues module
│           ├── opinion.rst       # Documentation for voter opinions module
│           ├── option.rst        # Documentation for voting options module
│           ├── ranking.rst       # Documentation for ranking algorithms
│           ├── state.rst         # Documentation for system state management
│           └── validators.rst    # Documentation for input validation utilities
│
├── examples/            # Example implementations and usage
│   ├── README.md           # Examples documentation and usage guide
│   ├── basic_voting.py     # Basic voting system example
│   ├── advanced_features.py # Advanced usage examples
│   └── protocol_upgrade.py # Protocol upgrade demonstration
│
├── hivemind/            # Main package + Web Application
│   ├── app.py              # Main web application
│   ├── requirements.txt    # Web app specific dependencies
│   ├── static/            # Static files (CSS, JS, images)
│   ├── templates/         # HTML templates
│   └── logs/              # Application logs
│
├── src/hivemind/        # Core package source code
│   ├── __init__.py          # Package initialization and public API exports
│   ├── issue.py            # Implementation of voting issues and questions
│   ├── opinion.py          # Handling of voter opinions and preferences
│   ├── option.py           # Management of voting options and choices
│   ├── ranking.py          # Condorcet-style ranking algorithm implementation
│   ├── state.py            # IPFS-based state management system
│   └── validators.py       # Input validation and data verification
│
└── tests/               # Test suite directory
    ├── conftest.py         # Pytest fixtures and shared test configurations
    ├── test_ipfs.py        # Tests for IPFS integration functionality
    ├── test_issue.py       # Tests for voting issues implementation
    ├── test_opinion.py     # Tests for opinion handling
    ├── test_option.py      # Tests for voting options management
    ├── test_ranking.py     # Tests for ranking algorithm
    ├── test_integration.py # Integration tests
    └── test_state.py       # Tests for state management system

# Tech Stack
- Python 3.10
- Pytest
- Sphinx
- FastAPI
- uvicorn
- Jinja2
- IPFS
- ipfs-dict-chain
- python-bitcoinlib
- pytest-cov

# Ipfs-dict-chain
This package provides a Python interface to the ipfs-dict-chain library, which allows for easy management of key-value pairs on IPFS.
It provides 2 main classes: 
- IPFSDict: A Dict object with additional methods for working with IPFS, like .load(cid) and .save()
- IPFSDictChain : Same as IPFSDict, but also tracks changes by storing the previous CID.