firecloud-devnet 0.1.0__tar.gz

firecloud_devnet-0.1.0/.dockerignore

@@ -0,0 +1,12 @@
+__pycache__
+.pytest_cache
+*.pyc
+*.pyo
+.env
+venv
+.venv
+.git
+*.egg-info
+dist
+build
+.ruff_cache

firecloud_devnet-0.1.0/.env.example

@@ -0,0 +1,3 @@
+FIRECLOUD_PASSPHRASE=change-this-before-use
+FIRECLOUD_MAX_STORAGE_GB=10
+FIRECLOUD_DATA_DIR=/data

firecloud_devnet-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Lint with ruff
+        run: |
+          dirs=""
+          for d in firecloud fc_rag fc_mlops; do
+            if [ -d "$d" ]; then
+              dirs="$dirs $d"
+            fi
+          done
+          if [ -n "$dirs" ]; then
+            ruff check $dirs
+          else
+            echo "No directories to lint."
+          fi
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+      - name: Upload test results on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-${{ matrix.python-version }}
+          path: |
+            .pytest_cache/
+            tests/
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build Docker image (latest)
+        run: docker build -t firecloud:latest .
+
+      - name: Build Docker image (SHA tag)
+        run: docker build -t firecloud:${{ github.sha }} .

firecloud_devnet-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

firecloud_devnet-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Linting
+.ruff_cache/
+
+# Environment
+.env
+
+# OS
+.DS_Store
+Thumbs.db
+
+# AI tool metadata — do not commit
+.antigravitycli/
+
+# Qdrant local data (created by fc-rag)
+~/.fc_rag/

firecloud_devnet-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to FireCloud will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - 2025-06-01
+
+### Added
+- XChaCha20-Poly1305 chunk encryption with HMAC-SHA-256 keyed addressing
+- FastCDC content-defined chunking
+- zfec erasure coding (configurable k/n)
+- mDNS peer discovery via zeroconf with config file fallback
+- TLS binary RPC transport with handshake and heartbeat
+- Manifest with Lamport timestamps and tombstone support
+- Watchdog-based folder sync (outbound upload, inbound download)
+- Click CLI (`firecloud` entry point) — init, start, upload, download, status, peers
+- Docker Compose multi-node setup with health checks
+- GitHub Actions CI (lint → test → build)
+- `fc-rag`: local RAG pipeline (fastembed + Qdrant + Ollama)
+- `fc-ml`: ML artifact versioning, telemetry server, anomaly detection

firecloud_devnet-0.1.0/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies and upgrade pip
+RUN pip install --no-cache-dir --upgrade pip
+
+# Copy the full project into the container
+COPY . .
+
+# Install FireCloud using hatchling build system (pyproject.toml)
+RUN pip install --no-cache-dir .
+
+# Expose the default FireCloud node port
+EXPOSE 7474
+
+# Entrypoint: start the FireCloud node
+ENTRYPOINT ["firecloud", "start"]

firecloud_devnet-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Rajashekhar Sunkara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

firecloud_devnet-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: firecloud-devnet
+Version: 0.1.0
+Summary: Private, encrypted, distributed storage across your own machines
+Project-URL: Homepage, https://github.com/rajashekharsunkara/firecloud
+Project-URL: Repository, https://github.com/rajashekharsunkara/firecloud
+Project-URL: Issues, https://github.com/rajashekharsunkara/firecloud/issues
+Project-URL: Changelog, https://github.com/rajashekharsunkara/firecloud/blob/main/CHANGELOG.md
+Author: Rajashekhar Sunkara
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chunking,distributed,encryption,p2p,storage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: fastcdc>=1.5.0
+Requires-Dist: pycryptodome>=3.20.0
+Requires-Dist: watchdog>=3.0.0
+Requires-Dist: zeroconf>=0.80.0
+Requires-Dist: zfec>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: mlops
+Requires-Dist: fastapi>=0.100.0; extra == 'mlops'
+Requires-Dist: numpy>=1.24.0; extra == 'mlops'
+Requires-Dist: psutil>=5.9.0; extra == 'mlops'
+Requires-Dist: pydantic>=2.0; extra == 'mlops'
+Requires-Dist: rich>=13.0.0; extra == 'mlops'
+Requires-Dist: scikit-learn>=1.3.0; extra == 'mlops'
+Requires-Dist: uvicorn>=0.20.0; extra == 'mlops'
+Provides-Extra: rag
+Requires-Dist: fastembed>=0.2.0; extra == 'rag'
+Requires-Dist: ollama>=0.1.0; extra == 'rag'
+Requires-Dist: pydantic>=2.0; extra == 'rag'
+Requires-Dist: qdrant-client>=1.8.0; extra == 'rag'
+Requires-Dist: rich>=13.0.0; extra == 'rag'
+Description-Content-Type: text/markdown
+
+![CI](https://github.com/rajashekharsunkara/firecloud/actions/workflows/ci.yml/badge.svg)
+
+# FireCloud
+
+Private, encrypted, distributed storage across machines you own.
+
+Unlike S3 (vendor lock-in), Syncthing (no erasure coding), or IPFS (public DHT), FireCloud gives you zero-knowledge peer-to-peer storage where data is encrypted locally before it leaves your machine. Every chunk stored on the network is ciphertext — nodes can't read it.
+
+---
+
+## Install
+
+```bash
+# from GitHub (recommended for now)
+pip install git+https://github.com/rajashekharsunkara/firecloud.git
+
+# with RAG extensions
+pip install "firecloud-devnet[rag]"
+
+# with MLOps extensions
+pip install "firecloud-devnet[mlops]"
+```
+
+## Quickstart
+
+```bash
+# 1. Start a 4-node network via Docker Compose
+git clone https://github.com/rajashekharsunkara/firecloud.git
+cd firecloud
+cp .env.example .env          # set FIRECLOUD_PASSPHRASE in .env
+docker compose up -d           # starts bootstrap + 3 storage nodes
+
+# 2. Upload a file
+docker exec firecloud-bootstrap firecloud upload /data/my-file.zip
+
+# 3. Download from any node
+docker exec firecloud-node-1 firecloud download <file_id> /data/restored.zip
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│  fc-rag (Private RAG — opt-in)          │  LLMOps
+│  fc-mlops (Artifact Store — opt-in)     │  MLOps
+│  Docker + GitHub Actions                │  DevOps
+│  FireCloud Core (storage, crypto, P2P)  │  Distributed Systems
+└─────────────────────────────────────────┘
+```
+
+**Distributed Systems** — XChaCha20-Poly1305 encryption, FastCDC content-defined chunking, zfec erasure coding, mDNS peer discovery. Manifest consistency uses Lamport timestamps with last-writer-wins semantics. Node communication runs over TLS-protected binary RPC.
+
+**DevOps** — Multi-node Docker Compose setup with health checks. GitHub Actions CI pipeline (lint → test → build) gates every merge.
+
+**MLOps** — `fc-mlops` provides version-tracked ML artifact storage via FireCloud's `Node` API, a FastAPI telemetry endpoint with psutil system metrics, and IsolationForest-based anomaly detection on telemetry readings.
+
+**LLMOps** — `fc-rag` is a fully local RAG pipeline using fastembed for embeddings, Qdrant (embedded mode) for vector search, and Ollama for local LLM inference — no text ever leaves your machine.
+
+---
+
+## Security
+
+FireCloud uses **HMAC-SHA-256 with a network-derived key** for chunk addressing instead of plain SHA-256. This raises the cost of confirmation-of-file attacks — an attacker who suspects a specific file is stored cannot verify its presence by computing chunk hashes from the plaintext, because valid chunk IDs require the network key. This protection holds as long as the network key remains confidential.
+
+---
+
+## AI/ML Extensions
+
+FireCloud stores and retrieves encrypted content. The RAG and artifact layers run entirely on the client — nothing in plaintext crosses the server boundary.
+
+### Private RAG (`fc-rag`)
+
+Index your docs locally and query with a private LLM — no data leaves your machine.
+
+```bash
+pip install "firecloud-devnet[rag]"
+fc-rag index ./docs
+fc-rag query "How does FireCloud handle node departure?"
+```
+
+### MLOps Artifact Store (`fc-mlops`)
+
+Version-track ML models, datasets, and checkpoints using FireCloud as the storage backend.
+
+```bash
+pip install "firecloud-devnet[mlops]"
+fc-ml save ./model.pt --name resnet --version 1.0.0 --type model --metric accuracy=0.94
+fc-ml simulate-failure
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/rajashekharsunkara/firecloud.git
+cd firecloud
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

firecloud_devnet-0.1.0/README.md

@@ -0,0 +1,106 @@
+![CI](https://github.com/rajashekharsunkara/firecloud/actions/workflows/ci.yml/badge.svg)
+
+# FireCloud
+
+Private, encrypted, distributed storage across machines you own.
+
+Unlike S3 (vendor lock-in), Syncthing (no erasure coding), or IPFS (public DHT), FireCloud gives you zero-knowledge peer-to-peer storage where data is encrypted locally before it leaves your machine. Every chunk stored on the network is ciphertext — nodes can't read it.
+
+---
+
+## Install
+
+```bash
+# from GitHub (recommended for now)
+pip install git+https://github.com/rajashekharsunkara/firecloud.git
+
+# with RAG extensions
+pip install "firecloud-devnet[rag]"
+
+# with MLOps extensions
+pip install "firecloud-devnet[mlops]"
+```
+
+## Quickstart
+
+```bash
+# 1. Start a 4-node network via Docker Compose
+git clone https://github.com/rajashekharsunkara/firecloud.git
+cd firecloud
+cp .env.example .env          # set FIRECLOUD_PASSPHRASE in .env
+docker compose up -d           # starts bootstrap + 3 storage nodes
+
+# 2. Upload a file
+docker exec firecloud-bootstrap firecloud upload /data/my-file.zip
+
+# 3. Download from any node
+docker exec firecloud-node-1 firecloud download <file_id> /data/restored.zip
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│  fc-rag (Private RAG — opt-in)          │  LLMOps
+│  fc-mlops (Artifact Store — opt-in)     │  MLOps
+│  Docker + GitHub Actions                │  DevOps
+│  FireCloud Core (storage, crypto, P2P)  │  Distributed Systems
+└─────────────────────────────────────────┘
+```
+
+**Distributed Systems** — XChaCha20-Poly1305 encryption, FastCDC content-defined chunking, zfec erasure coding, mDNS peer discovery. Manifest consistency uses Lamport timestamps with last-writer-wins semantics. Node communication runs over TLS-protected binary RPC.
+
+**DevOps** — Multi-node Docker Compose setup with health checks. GitHub Actions CI pipeline (lint → test → build) gates every merge.
+
+**MLOps** — `fc-mlops` provides version-tracked ML artifact storage via FireCloud's `Node` API, a FastAPI telemetry endpoint with psutil system metrics, and IsolationForest-based anomaly detection on telemetry readings.
+
+**LLMOps** — `fc-rag` is a fully local RAG pipeline using fastembed for embeddings, Qdrant (embedded mode) for vector search, and Ollama for local LLM inference — no text ever leaves your machine.
+
+---
+
+## Security
+
+FireCloud uses **HMAC-SHA-256 with a network-derived key** for chunk addressing instead of plain SHA-256. This raises the cost of confirmation-of-file attacks — an attacker who suspects a specific file is stored cannot verify its presence by computing chunk hashes from the plaintext, because valid chunk IDs require the network key. This protection holds as long as the network key remains confidential.
+
+---
+
+## AI/ML Extensions
+
+FireCloud stores and retrieves encrypted content. The RAG and artifact layers run entirely on the client — nothing in plaintext crosses the server boundary.
+
+### Private RAG (`fc-rag`)
+
+Index your docs locally and query with a private LLM — no data leaves your machine.
+
+```bash
+pip install "firecloud-devnet[rag]"
+fc-rag index ./docs
+fc-rag query "How does FireCloud handle node departure?"
+```
+
+### MLOps Artifact Store (`fc-mlops`)
+
+Version-track ML models, datasets, and checkpoints using FireCloud as the storage backend.
+
+```bash
+pip install "firecloud-devnet[mlops]"
+fc-ml save ./model.pt --name resnet --version 1.0.0 --type model --metric accuracy=0.94
+fc-ml simulate-failure
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/rajashekharsunkara/firecloud.git
+cd firecloud
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

firecloud_devnet-0.1.0/docker-compose.yml

@@ -0,0 +1,103 @@
+services:
+  bootstrap-node:
+    build: .
+    container_name: firecloud-bootstrap
+    ports:
+      - "7474:7474"
+    volumes:
+      - fc-bootstrap-data:/data
+    environment:
+      - FIRECLOUD_PASSPHRASE=${FIRECLOUD_PASSPHRASE}
+      - FIRECLOUD_MAX_STORAGE_GB=${FIRECLOUD_MAX_STORAGE_GB:-10}
+      - FIRECLOUD_DATA_DIR=/data
+    command: ["start", "--passphrase", "${FIRECLOUD_PASSPHRASE}", "--port", "7474", "--storage", "/data"]
+    healthcheck:
+      test: ["CMD", "firecloud", "status", "--passphrase", "${FIRECLOUD_PASSPHRASE}", "--storage", "/data"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    restart: unless-stopped
+    networks:
+      - firecloud-net
+
+  storage-node-1:
+    build: .
+    container_name: firecloud-node-1
+    ports:
+      - "7475:7475"
+    volumes:
+      - fc-node1-data:/data
+    environment:
+      - FIRECLOUD_PASSPHRASE=${FIRECLOUD_PASSPHRASE}
+      - FIRECLOUD_BOOTSTRAP=bootstrap-node:7474
+      - FIRECLOUD_MAX_STORAGE_GB=${FIRECLOUD_MAX_STORAGE_GB:-10}
+      - FIRECLOUD_DATA_DIR=/data
+    command: ["start", "--passphrase", "${FIRECLOUD_PASSPHRASE}", "--port", "7475", "--storage", "/data"]
+    healthcheck:
+      test: ["CMD", "firecloud", "status", "--passphrase", "${FIRECLOUD_PASSPHRASE}", "--port", "7475", "--storage", "/data"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    restart: unless-stopped
+    depends_on:
+      - bootstrap-node
+    networks:
+      - firecloud-net
+
+  storage-node-2:
+    build: .
+    container_name: firecloud-node-2
+    ports:
+      - "7476:7476"
+    volumes:
+      - fc-node2-data:/data
+    environment:
+      - FIRECLOUD_PASSPHRASE=${FIRECLOUD_PASSPHRASE}
+      - FIRECLOUD_BOOTSTRAP=bootstrap-node:7474
+      - FIRECLOUD_MAX_STORAGE_GB=${FIRECLOUD_MAX_STORAGE_GB:-10}
+      - FIRECLOUD_DATA_DIR=/data
+    command: ["start", "--passphrase", "${FIRECLOUD_PASSPHRASE}", "--port", "7476", "--storage", "/data"]
+    healthcheck:
+      test: ["CMD", "firecloud", "status", "--passphrase", "${FIRECLOUD_PASSPHRASE}", "--port", "7476", "--storage", "/data"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    restart: unless-stopped
+    depends_on:
+      - bootstrap-node
+    networks:
+      - firecloud-net
+
+  storage-node-3:
+    build: .
+    container_name: firecloud-node-3
+    ports:
+      - "7477:7477"
+    volumes:
+      - fc-node3-data:/data
+    environment:
+      - FIRECLOUD_PASSPHRASE=${FIRECLOUD_PASSPHRASE}
+      - FIRECLOUD_BOOTSTRAP=bootstrap-node:7474
+      - FIRECLOUD_MAX_STORAGE_GB=${FIRECLOUD_MAX_STORAGE_GB:-10}
+      - FIRECLOUD_DATA_DIR=/data
+    command: ["start", "--passphrase", "${FIRECLOUD_PASSPHRASE}", "--port", "7477", "--storage", "/data"]
+    healthcheck:
+      test: ["CMD", "firecloud", "status", "--passphrase", "${FIRECLOUD_PASSPHRASE}", "--port", "7477", "--storage", "/data"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    restart: unless-stopped
+    depends_on:
+      - bootstrap-node
+    networks:
+      - firecloud-net
+
+volumes:
+  fc-bootstrap-data:
+  fc-node1-data:
+  fc-node2-data:
+  fc-node3-data:
+
+networks:
+  firecloud-net:
+    driver: bridge

firecloud_devnet-0.1.0/fc_mlops/__init__.py

@@ -0,0 +1,3 @@
+"""MLOps extensions for FireCloud."""
+
+__version__ = "0.1.0"

firecloud_devnet-0.1.0/fc_mlops/__main__.py

@@ -0,0 +1,5 @@
+"""fc_mlops __main__ — allows ``python -m fc_mlops.simulate_failure``."""
+
+from fc_mlops.simulate_failure import main
+
+main()