firecloud-devnet 0.1.0__py3-none-any.whl

fc_mlops/__init__.py

@@ -0,0 +1,3 @@
+"""MLOps extensions for FireCloud."""
+
+__version__ = "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()

fc_mlops/anomaly.py

@@ -0,0 +1,112 @@
+"""IsolationForest-based anomaly scoring on telemetry readings."""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+from pydantic import BaseModel, ConfigDict
+from sklearn.ensemble import IsolationForest
+
+_LOG_PATH = Path.home() / ".fc_mlops" / "telemetry_log.jsonl"
+_ALERTS_PATH = Path.home() / ".fc_mlops" / "alerts.jsonl"
+
+# columns pulled from each telemetry reading
+_FEATURES = [
+    "disk_io_read_mbps",
+    "chunk_upload_latency_ms",
+    "cpu_percent",
+    "memory_percent",
+]
+
+
+class AnomalyReport(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    timestamp: datetime
+    is_anomaly: bool
+    anomaly_score: float
+    flagged_metrics: list[str]
+    recommendation: str
+
+
+def _append_alert(report: AnomalyReport) -> None:
+    _ALERTS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with open(_ALERTS_PATH, "a", encoding="utf-8") as f:
+        f.write(json.dumps(report.model_dump(), default=str) + "\n")
+
+
+def _load_readings(log_path: Path | None = None, max_lines: int = 200) -> list[dict]:
+    path = log_path or _LOG_PATH
+    if not path.exists():
+        return []
+
+    lines = path.read_text(encoding="utf-8").strip().splitlines()
+    tail = lines[-max_lines:] if len(lines) > max_lines else lines
+
+    readings = []
+    for line in tail:
+        try:
+            readings.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return readings
+
+
+def check_anomaly(log_path: Path | None = None) -> AnomalyReport | dict:
+    """Run anomaly detection against the latest telemetry data.
+
+    Pass *log_path* to override the default telemetry log location
+    (used by the simulation script and tests).
+    """
+    readings = _load_readings(log_path)
+
+    if len(readings) < 50:
+        return {"status": "insufficient_data", "readings": len(readings)}
+
+    # build feature matrix
+    data = []
+    for r in readings:
+        row = [float(r.get(f, 0.0)) for f in _FEATURES]
+        data.append(row)
+    X = np.array(data)
+
+    clf = IsolationForest(contamination=0.05, random_state=42)
+    clf.fit(X)
+
+    latest = X[-1].reshape(1, -1)
+    prediction = clf.predict(latest)[0]   # -1 = anomaly, 1 = normal
+    score = clf.decision_function(latest)[0]
+    is_anomaly = prediction == -1
+
+    # flag anything > 2 stddev from mean
+    means = X.mean(axis=0)
+    stds = X.std(axis=0)
+    flagged: list[str] = []
+    for i, feat in enumerate(_FEATURES):
+        if stds[i] > 0 and abs(X[-1, i] - means[i]) > 2 * stds[i]:
+            flagged.append(feat)
+
+    if not is_anomaly:
+        rec = "Node healthy"
+    elif "chunk_upload_latency_ms" in flagged:
+        rec = "High latency — check network"
+    elif "cpu_percent" in flagged:
+        rec = "CPU spike — check running processes"
+    elif "disk_io_read_mbps" in flagged:
+        rec = "Disk I/O degraded — check storage health"
+    else:
+        rec = "Anomalous reading — investigate node"
+
+    report = AnomalyReport(
+        timestamp=datetime.now(timezone.utc),
+        is_anomaly=is_anomaly,
+        anomaly_score=round(float(score), 4),
+        flagged_metrics=flagged,
+        recommendation=rec,
+    )
+
+    if is_anomaly:
+        _append_alert(report)
+
+    return report

fc_mlops/artifact_store.py

@@ -0,0 +1,111 @@
+"""Version-tracked ML artifact storage backed by FireCloud's Node API."""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+_MANIFEST_PATH = Path.home() / ".fc_mlops" / "artifacts.json"
+
+
+class ArtifactMetadata(BaseModel):
+    """Immutable metadata record for a stored ML artifact."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    version: str
+    artifact_type: Literal["model", "dataset", "checkpoint"]
+    saved_at: datetime
+    file_size_bytes: int
+    metrics: dict[str, float]
+    tags: list[str]
+    firecloud_file_id: str
+
+
+def _load_manifest() -> list[dict]:
+    if not _MANIFEST_PATH.exists():
+        return []
+    try:
+        return json.loads(_MANIFEST_PATH.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return []
+
+
+def _save_manifest(entries: list[dict]) -> None:
+    _MANIFEST_PATH.parent.mkdir(parents=True, exist_ok=True)
+    _MANIFEST_PATH.write_text(
+        json.dumps(entries, indent=2, default=str),
+        encoding="utf-8",
+    )
+
+
+async def save_artifact(
+    node,
+    local_path: Path,
+    name: str,
+    version: str,
+    artifact_type: str,
+    metrics: dict[str, float] | None = None,
+    tags: list[str] | None = None,
+) -> ArtifactMetadata:
+    """Upload *local_path* to FireCloud and record metadata in the manifest.
+
+    Returns the :class:`ArtifactMetadata` for the saved artifact.
+    """
+    local_path = Path(local_path)
+    file_id = await node.upload(local_path)
+
+    metadata = ArtifactMetadata(
+        name=name,
+        version=version,
+        artifact_type=artifact_type,
+        saved_at=datetime.now(timezone.utc),
+        file_size_bytes=local_path.stat().st_size,
+        metrics=metrics or {},
+        tags=tags or [],
+        firecloud_file_id=file_id,
+    )
+
+    entries = _load_manifest()
+    entries.append(metadata.model_dump())
+    _save_manifest(entries)
+    return metadata
+
+
+async def load_artifact(
+    node,
+    name: str,
+    version: str,
+    destination: Path,
+) -> Path:
+    """Download an artifact by name+version from the manifest."""
+    entries = _load_manifest()
+
+    match = None
+    for entry in entries:
+        if entry["name"] == name and entry["version"] == version:
+            match = entry
+            break
+
+    if match is None:
+        raise ValueError(
+            f"Artifact '{name}' version '{version}' not found in manifest"
+        )
+
+    destination = Path(destination)
+    await node.download(match["firecloud_file_id"], destination)
+    return destination.resolve()
+
+
+def list_artifacts(artifact_type: str | None = None) -> list[ArtifactMetadata]:
+    """Return tracked artifacts, optionally filtered by *artifact_type*."""
+    entries = _load_manifest()
+    results = []
+    for entry in entries:
+        if artifact_type and entry.get("artifact_type") != artifact_type:
+            continue
+        results.append(ArtifactMetadata(**entry))
+    return results

fc_mlops/cli.py

@@ -0,0 +1,190 @@
+"""fc-ml CLI — artifact management, telemetry, and anomaly detection."""
+
+from pathlib import Path
+
+import click
+
+
+@click.group()
+def cli():
+    """fc-ml — MLOps extensions for FireCloud."""
+    pass
+
+
+# --- Artifact commands ---
+
+@cli.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--name", "-n", required=True, help="Artifact name.")
+@click.option("--version", "-v", required=True, help="Artifact version.")
+@click.option(
+    "--type", "artifact_type",
+    type=click.Choice(["model", "dataset", "checkpoint"]),
+    required=True,
+    help="Artifact type.",
+)
+@click.option(
+    "--metric", "-m",
+    multiple=True,
+    help="Metric in key=value format (repeatable).",
+)
+@click.option("--passphrase", prompt=True, hide_input=True, help="Network passphrase.")
+@click.option("--port", default=7474, type=int)
+@click.option("--storage", default=None, type=click.Path())
+def save(
+    path: str,
+    name: str,
+    version: str,
+    artifact_type: str,
+    metric: tuple[str, ...],
+    passphrase: str,
+    port: int,
+    storage: str | None,
+):
+    """Save an artifact to the FireCloud network."""
+    import asyncio
+    from firecloud import Network, Node
+    from fc_mlops.artifact_store import save_artifact
+
+    metrics = {}
+    for m in metric:
+        if "=" in m:
+            k, v = m.split("=", 1)
+            metrics[k.strip()] = float(v.strip())
+
+    storage_path = Path(storage) if storage else Path.home() / ".firecloud" / "storage"
+
+    async def _run():
+        net = Network.load(Path.home() / ".firecloud" / "network.key", passphrase)
+        node = Node(network=net, storage_path=storage_path, port=port, enable_discovery=False)
+        await node.start()
+        try:
+            meta = await save_artifact(
+                node, Path(path), name, version, artifact_type, metrics, []
+            )
+            click.echo(click.style("✓ Artifact saved.", fg="green"))
+            click.echo(f"  Name      : {meta.name}")
+            click.echo(f"  Version   : {meta.version}")
+            click.echo(f"  File ID   : {meta.firecloud_file_id}")
+            click.echo(f"  Size      : {meta.file_size_bytes} bytes")
+        finally:
+            await node.stop()
+
+    asyncio.run(_run())
+
+
+@cli.command()
+@click.argument("name")
+@click.option("--version", "-v", required=True, help="Artifact version.")
+@click.option("--dest", "-d", required=True, type=click.Path(), help="Destination path.")
+@click.option("--passphrase", prompt=True, hide_input=True, help="Network passphrase.")
+@click.option("--port", default=7474, type=int)
+@click.option("--storage", default=None, type=click.Path())
+def load(
+    name: str,
+    version: str,
+    dest: str,
+    passphrase: str,
+    port: int,
+    storage: str | None,
+):
+    """Load an artifact from the FireCloud network."""
+    import asyncio
+    from firecloud import Network, Node
+    from fc_mlops.artifact_store import load_artifact
+
+    storage_path = Path(storage) if storage else Path.home() / ".firecloud" / "storage"
+
+    async def _run():
+        net = Network.load(Path.home() / ".firecloud" / "network.key", passphrase)
+        node = Node(network=net, storage_path=storage_path, port=port, enable_discovery=False)
+        await node.start()
+        try:
+            result_path = await load_artifact(node, name, version, Path(dest))
+            click.echo(click.style(f"✓ Artifact downloaded to {result_path}", fg="green"))
+        finally:
+            await node.stop()
+
+    asyncio.run(_run())
+
+
+@cli.command("list")
+@click.option(
+    "--type", "artifact_type",
+    type=click.Choice(["model", "dataset", "checkpoint"]),
+    default=None,
+    help="Filter by artifact type.",
+)
+def list_artifacts(artifact_type: str | None):
+    """List tracked ML artifacts."""
+    from fc_mlops.artifact_store import list_artifacts as _list
+
+    artifacts = _list(artifact_type)
+    if not artifacts:
+        click.echo("No artifacts found.")
+        return
+
+    click.echo(
+        click.style(
+            f"{'Name':<20} {'Version':<10} {'Type':<12} {'Size':<12} {'File ID':<20}",
+            bold=True,
+        )
+    )
+    click.echo("─" * 75)
+    for a in artifacts:
+        size = f"{a.file_size_bytes:,} B"
+        click.echo(
+            f"{a.name:<20} {a.version:<10} {a.artifact_type:<12} "
+            f"{size:<12} {a.firecloud_file_id[:20]}"
+        )
+
+
+# --- Telemetry ---
+
+@cli.group()
+def telemetry():
+    """Telemetry server commands."""
+    pass
+
+@telemetry.command("start")
+def telemetry_start():
+    """Start the telemetry metrics server on localhost:7475."""
+    from fc_mlops.telemetry import start_server
+    click.echo(click.style("Starting telemetry server on http://127.0.0.1:7475", fg="cyan"))
+    start_server()
+
+
+# --- Anomaly detection ---
+
+@cli.group()
+def anomaly():
+    """Anomaly detection commands."""
+    pass
+
+@anomaly.command("check")
+def anomaly_check():
+    """Run anomaly detection on recent telemetry data."""
+    from fc_mlops.anomaly import check_anomaly
+
+    result = check_anomaly()
+
+    if isinstance(result, dict):
+        click.echo(f"Insufficient data: {result.get('readings', 0)} readings (need ≥ 50)")
+        return
+
+    click.echo(click.style("Anomaly Detection Results", bold=True))
+    click.echo(f"  Anomaly detected  : {'Yes' if result.is_anomaly else 'No'}")
+    click.echo(f"  Anomaly score     : {result.anomaly_score}")
+    click.echo(f"  Flagged metrics   : {', '.join(result.flagged_metrics) or 'None'}")
+    click.echo(f"  Recommendation    : {result.recommendation}")
+
+
+@cli.command("simulate-failure")
+def simulate_failure():
+    """Run the failure simulation demo."""
+    from fc_mlops.simulate_failure import main
+    main()
+
+
+if __name__ == "__main__":
+    cli()

fc_mlops/simulate_failure.py

@@ -0,0 +1,100 @@
+"""Standalone failure simulation demo.
+
+Generates synthetic telemetry, injects anomalies, and runs detection.
+Run via: python -m fc_mlops.simulate_failure
+"""
+
+import json
+import random
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+from fc_mlops.anomaly import check_anomaly
+
+console = Console()
+
+
+def _write_reading(log_path: Path, reading: dict) -> None:
+    with open(log_path, "a", encoding="utf-8") as f:
+        f.write(json.dumps(reading, default=str) + "\n")
+
+
+def _normal_reading() -> dict:
+    return {
+        "node_id": "sim-node",
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "disk_io_read_mbps": round(random.uniform(50, 150), 2),
+        "disk_io_write_mbps": round(random.uniform(30, 100), 2),
+        "chunk_upload_latency_ms": round(random.uniform(20, 50), 2),
+        "active_connections": random.randint(1, 5),
+        "storage_used_percent": round(random.uniform(30, 60), 2),
+        "cpu_percent": round(random.uniform(10, 30), 2),
+        "memory_percent": round(random.uniform(40, 60), 2),
+    }
+
+
+def _anomalous_reading() -> dict:
+    return {
+        "node_id": "sim-node",
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "disk_io_read_mbps": round(random.uniform(5, 15), 2),
+        "disk_io_write_mbps": round(random.uniform(1, 5), 2),
+        "chunk_upload_latency_ms": round(random.uniform(400, 600), 2),
+        "active_connections": random.randint(0, 1),
+        "storage_used_percent": round(random.uniform(85, 98), 2),
+        "cpu_percent": round(random.uniform(85, 95), 2),
+        "memory_percent": round(random.uniform(80, 95), 2),
+    }
+
+
+def main() -> None:
+    tmp_dir = Path(tempfile.mkdtemp(prefix="fc_mlops_sim_"))
+    log_path = tmp_dir / "telemetry_log.jsonl"
+
+    # baseline
+    console.print("[bold cyan][Phase 1][/bold cyan] Generating 60 baseline readings...")
+    for _ in range(60):
+        _write_reading(log_path, _normal_reading())
+
+    # inject failures
+    console.print("[bold yellow][Phase 2][/bold yellow] Injecting failure signatures...")
+    for _ in range(10):
+        _write_reading(log_path, _anomalous_reading())
+
+    # detect
+    console.print("[bold magenta][Phase 3][/bold magenta] Running anomaly detection...")
+    result = check_anomaly(log_path=log_path)
+
+    if isinstance(result, dict):
+        console.print(f"[red]Insufficient data: {result}[/red]")
+        console.print("[bold red]✗ FAIL: Not enough readings for detection[/bold red]")
+        return
+
+    table = Table(title="Anomaly Detection Results", show_header=True)
+    table.add_column("Metric", style="cyan", width=25)
+    table.add_column("Value", style="white", width=50)
+
+    table.add_row("Anomaly detected", "[red]Yes[/red]" if result.is_anomaly else "[green]No[/green]")
+    table.add_row("Anomaly score", str(round(result.anomaly_score, 4)))
+    table.add_row("Flagged metrics", ", ".join(result.flagged_metrics) if result.flagged_metrics else "None")
+    table.add_row("Recommendation", result.recommendation)
+
+    console.print()
+    console.print(table)
+    console.print()
+
+    if result.is_anomaly:
+        console.print("[bold green]✓ PASS: Anomaly correctly detected[/bold green]")
+    else:
+        console.print(
+            "[bold red]✗ FAIL: Anomaly not detected — "
+            "check contamination parameter[/bold red]"
+        )
+
+
+if __name__ == "__main__":
+    main()

fc_mlops/telemetry.py

@@ -0,0 +1,72 @@
+"""FastAPI metrics endpoint with psutil system monitoring."""
+
+import json
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+import psutil
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+_LOG_PATH = Path.home() / ".fc_mlops" / "telemetry_log.jsonl"
+
+app = FastAPI(title="FireCloud Telemetry", version="0.1.0")
+
+
+class NodeMetrics(BaseModel):
+    """Snapshot of system and node health metrics."""
+    node_id: str
+    timestamp: datetime
+    disk_io_read_mbps: float
+    disk_io_write_mbps: float
+    chunk_upload_latency_ms: float
+    active_connections: int
+    storage_used_percent: float
+    cpu_percent: float
+    memory_percent: float
+
+
+def _collect_metrics() -> NodeMetrics:
+    # disk I/O — sample over a short window
+    disk1 = psutil.disk_io_counters()
+    if disk1:
+        time.sleep(0.1)
+        disk2 = psutil.disk_io_counters()
+        read_mbps = (disk2.read_bytes - disk1.read_bytes) / 0.1 / (1024 * 1024)
+        write_mbps = (disk2.write_bytes - disk1.write_bytes) / 0.1 / (1024 * 1024)
+    else:
+        read_mbps = write_mbps = 0.0
+
+    disk_usage = psutil.disk_usage("/")
+
+    return NodeMetrics(
+        node_id="local",
+        timestamp=datetime.now(timezone.utc),
+        disk_io_read_mbps=round(read_mbps, 2),
+        disk_io_write_mbps=round(write_mbps, 2),
+        chunk_upload_latency_ms=0.0,
+        active_connections=0,
+        storage_used_percent=round(disk_usage.percent, 2),
+        cpu_percent=round(psutil.cpu_percent(interval=None), 2),
+        memory_percent=round(psutil.virtual_memory().percent, 2),
+    )
+
+
+@app.get("/metrics", response_model=NodeMetrics)
+def get_metrics() -> NodeMetrics:
+    """Collect and return current system metrics."""
+    metrics = _collect_metrics()
+
+    # append to JSONL log
+    _LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with open(_LOG_PATH, "a", encoding="utf-8") as fh:
+        fh.write(json.dumps(metrics.model_dump(), default=str) + "\n")
+
+    return metrics
+
+
+def start_server() -> None:
+    """Start the telemetry server on localhost:7475."""
+    import uvicorn
+    uvicorn.run(app, host="127.0.0.1", port=7475)

fc_rag/__init__.py

@@ -0,0 +1,3 @@
+"""Private RAG pipeline for FireCloud — all processing runs locally."""
+
+__version__ = "0.1.0"

fc_rag/cli.py

@@ -0,0 +1,51 @@
+"""fc-rag CLI — index files and query the local RAG pipeline."""
+
+from pathlib import Path
+import click
+
+
+@click.group()
+def cli():
+    """fc-rag — Private RAG pipeline for FireCloud docs."""
+    pass
+
+
+@cli.command()
+@click.argument("path", type=click.Path(exists=True))
+def index(path: str):
+    """Index files at PATH into the local vector store."""
+    from fc_rag.indexer import index_path
+
+    target = Path(path)
+    total_chunks = index_path(target)
+
+    if target.is_file():
+        file_count = 1
+    else:
+        supported = {".txt", ".md", ".py", ".json"}
+        file_count = sum(
+            1 for f in target.rglob("*")
+            if f.is_file() and f.suffix in supported
+        )
+
+    click.echo(f"Indexed {total_chunks} chunks from {file_count} files")
+
+
+@cli.command()
+@click.argument("question")
+def query(question: str):
+    """Query the local RAG pipeline with a natural-language question."""
+    from fc_rag.query_engine import query as run_query
+    from fc_rag.retriever import retrieve
+
+    answer = run_query(question)
+    click.echo(answer)
+
+    results = retrieve(question)
+    if results:
+        sources = sorted(set(r.filename for r in results))
+        click.echo(f"\nSources: {', '.join(sources)}")
+
+
+if __name__ == "__main__":
+    cli()

fc_rag/config.py

@@ -0,0 +1,24 @@
+"""Pydantic settings for the fc_rag pipeline."""
+
+from functools import lru_cache
+from pathlib import Path
+from pydantic import BaseModel, ConfigDict
+
+
+class Settings(BaseModel):
+    """All paths default to ~/.fc_rag/ so it works out of the box."""
+
+    model_config = ConfigDict(frozen=True)
+
+    ollama_model: str = "llama3.2:3b"
+    embedding_model: str = "BAAI/bge-small-en-v1.5"
+    qdrant_path: Path = Path.home() / ".fc_rag" / "vectors"
+    collection_name: str = "firecloud_docs"
+    top_k: int = 5
+    max_retries: int = 3
+    log_path: Path = Path.home() / ".fc_rag" / "query_log.jsonl"
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings()