quark-trace 0.1.0__py3-none-any.whl

quark_trace/__init__.py

@@ -0,0 +1,24 @@
+from quark_trace.exceptions import (BackendReadError, BackendWriteError,
+                                    FactSheetAlreadyExistsError,
+                                    FactSheetNotFoundError,
+                                    ImmutableFieldError, InvalidAmendmentError,
+                                    InvalidStageError, QuarkLensError,
+                                    RecordSerializationError)
+from quark_trace.fact_sheet.fact_sheet import FactSheet
+from quark_trace.project import Project
+from quark_trace.trace.backends.json_backend import JsonBackend
+
+__all__ = [
+    "Project",
+    "JsonBackend",
+    "FactSheet",
+    "QuarkLensError",
+    "FactSheetAlreadyExistsError",
+    "FactSheetNotFoundError",
+    "ImmutableFieldError",
+    "InvalidAmendmentError",
+    "InvalidStageError",
+    "RecordSerializationError",
+    "BackendReadError",
+    "BackendWriteError",
+]

quark_trace/exceptions.py

@@ -0,0 +1,122 @@
+class QuarkLensError(Exception):
+    """Base exception for all quark_trace errors."""
+    pass
+
+
+# --- Fact Sheet ---
+
+class FactSheetError(QuarkLensError):
+    """Base exception for fact sheet errors."""
+    pass
+
+
+class FactSheetAlreadyExistsError(FactSheetError):
+    """
+    Raised when attempting to save a fact sheet for a project
+    that already has one persisted in the backend.
+    """
+    def __init__(self, project_id: str) -> None:
+        super().__init__(
+            f"A fact sheet for project '{project_id}' already exists. "
+            f"Use amend() to modify it."
+        )
+        self.project_id = project_id
+
+
+class FactSheetNotFoundError(FactSheetError):
+    """
+    Raised when a fact sheet cannot be found for the given project ID.
+    """
+    def __init__(self, project_id: str) -> None:
+        super().__init__(
+            f"No fact sheet found for project '{project_id}'."
+        )
+        self.project_id = project_id
+
+
+class ImmutableFieldError(FactSheetError):
+    """
+    Raised when amend() attempts to modify a field that is
+    declared immutable on the FactSheet.
+    """
+    def __init__(self, field: str) -> None:
+        super().__init__(
+            f"Field '{field}' is immutable and cannot be amended."
+        )
+        self.field = field
+
+
+class InvalidAmendmentError(FactSheetError):
+    """
+    Raised when amend() is called with no valid fields to update.
+    """
+    def __init__(self) -> None:
+        super().__init__(
+            "Amendment contains no valid fields. "
+            "Ensure field names match FactSheet attributes."
+        )
+
+
+# --- Trace ---
+
+class TraceError(QuarkLensError):
+    """Base exception for trace errors."""
+    pass
+
+
+class InvalidStageError(TraceError):
+    """
+    Raised when log() is called with an empty or invalid stage value.
+    """
+    def __init__(self, stage: str) -> None:
+        super().__init__(
+            f"Invalid stage value: '{stage}'. Stage must be a non-empty string."
+        )
+        self.stage = stage
+
+
+class RecordSerializationError(TraceError):
+    """
+    Raised when a TraceRecord cannot be serialized to or
+    deserialized from JSON.
+    """
+    def __init__(self, record_id: str, reason: str) -> None:
+        super().__init__(
+            f"Failed to serialize record '{record_id}': {reason}"
+        )
+        self.record_id = record_id
+
+
+# --- Backend ---
+
+class BackendError(QuarkLensError):
+    """Base exception for storage backend errors."""
+    pass
+
+
+class BackendReadError(BackendError):
+    """
+    Raised when a backend read operation fails.
+    """
+    def __init__(self, reason: str) -> None:
+        super().__init__(f"Backend read failed: {reason}")
+
+
+class BackendWriteError(BackendError):
+    """
+    Raised when a backend write operation fails.
+    """
+    def __init__(self, reason: str) -> None:
+        super().__init__(f"Backend write failed: {reason}")
+
+class NodeVerificationError(QuarkLensError):
+    """Raised when the node cannot be verified against the registry."""
+    pass
+
+class NodeAuthenticationError(QuarkLensError):
+    """Raised when the server rejects the node's API key."""
+    pass
+
+class NodeScopeError(QuarkLensError):
+    """Raised when the node is not authorized for the target institution."""
+    pass

quark_trace/fact_sheet/__init__.py

@@ -0,0 +1,7 @@
+from quark_trace.fact_sheet.fact_sheet import FactSheet
+from quark_trace.fact_sheet.loader import load_fact_sheet
+
+__all__ = [
+    "FactSheet",
+    "load_fact_sheet",
+]

quark_trace/fact_sheet/fact_sheet.py

@@ -0,0 +1,108 @@
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from quark_trace.exceptions import ImmutableFieldError, InvalidAmendmentError
+
+
+class FactSheet:
+
+    def __init__(self,
+                 project_id: str,
+                 purpose: str,
+                 domain: str,
+                 ml_type: str,
+                 algorithm: List[Dict],
+                 input: List[Dict],
+                 output: List[Dict],
+                 performance_metrics: List[str],
+                 bias: Dict,
+                 stakeholders: List[Dict],
+                 institution_id: Optional[str] = None) -> None:
+        self.project_id = project_id
+        self.institution_id = institution_id
+        self.version: int = 1
+        self.created_at: str = datetime.now(timezone.utc).isoformat()
+        self.amended_at: Optional[str] = None
+        self.amendment_log: List[Dict] = []
+        self.purpose = purpose
+        self.domain = domain
+        self.ml_type = ml_type
+        self.algorithm = algorithm
+        self.input = input
+        self.output = output
+        self.performance_metrics = performance_metrics
+        self.bias = bias
+        self.stakeholders = stakeholders
+
+    @property
+    def sheet_id(self) -> str:
+        return f"{self.project_id}-v{self.version}"
+
+    def amend(self, fields: Dict[str, Any], amended_by: str, reason: str) -> None:
+        changed = []
+        for key, value in fields.items():
+            if key in self._immutable_fields():
+                raise ImmutableFieldError(key)
+            if hasattr(self, key):
+                setattr(self, key, value)
+                changed.append(key)
+
+        if not changed:
+            raise InvalidAmendmentError()
+
+        self.amendment_log.append({
+            "version": self.version + 1,
+            "amended_at": datetime.now(timezone.utc).isoformat(),
+            "amended_by": amended_by,
+            "fields_changed": changed,
+            "reason": reason
+        })
+        self.version += 1
+        self.amended_at = datetime.now(timezone.utc).isoformat()
+
+    def to_json(self) -> Dict[str, Any]:
+        return {
+            "sheet_id": self.sheet_id,
+            "project_id": self.project_id,
+            "version": self.version,
+            "created_at": self.created_at,
+            "amended_at": self.amended_at,
+            "amendment_log": self.amendment_log,
+            "purpose": self.purpose,
+            "domain": self.domain,
+            "ml_type": self.ml_type,
+            "algorithm": self.algorithm,
+            "input": self.input,
+            "output": self.output,
+            "performance_metrics": self.performance_metrics,
+            "bias": self.bias,
+            "stakeholders": self.stakeholders
+        }
+
+    @classmethod
+    def from_json(cls, data: Dict[str, Any]) -> 'FactSheet':
+        fact_sheet = cls(
+            project_id=str(data["project_id"]),
+            purpose=str(data["purpose"]),
+            domain=str(data["domain"]),
+            ml_type=str(data["ml_type"]),
+            algorithm=data.get("algorithm", []),
+            input=data.get("input", []),
+            output=data.get("output", []),
+            performance_metrics=data.get("performance_metrics", []),
+            bias=data.get("bias", {}),
+            stakeholders=data.get("stakeholders", [])
+        )
+        fact_sheet.version = int(data.get("version", 1))
+        fact_sheet.created_at = str(data["created_at"])
+        fact_sheet.amended_at = data.get("amended_at")
+        fact_sheet.amendment_log = data.get("amendment_log", [])
+        return fact_sheet
+
+    def _immutable_fields(self) -> List[str]:
+        return ["sheet_id", "project_id", "created_at", "version"]
+
+    def __str__(self):
+        return (f"FactSheet(sheet_id={self.sheet_id}, "
+                f"project_id={self.project_id}, "
+                f"version={self.version})")

quark_trace/fact_sheet/loader.py

@@ -0,0 +1,30 @@
+import yaml
+
+from .fact_sheet import FactSheet
+from .schema import FactSheetSchema
+
+
+def load_fact_sheet(yaml_path: str) -> FactSheet:
+    """
+    Load a fact sheet from a YAML file.
+
+    :param yaml_path: Path to the YAML file containing the fact sheet data.
+    :return: A FactSheet instance populated with the data from the YAML file.
+    """
+    with open(yaml_path, 'r') as file:
+        raw = yaml.safe_load(file)
+
+    validated = FactSheetSchema.model_validate(raw)
+
+    return FactSheet(
+        project_id=validated.project_id,
+        purpose=validated.purpose,
+        domain=validated.domain,
+        ml_type=validated.ml_type.value,
+        algorithm=[a.model_dump() for a in validated.algorithm],
+        input=[i.model_dump() for i in validated.input],
+        output=[o.model_dump() for o in validated.output],
+        performance_metrics=validated.performance_metrics,
+        bias=validated.bias.model_dump(),
+        stakeholders=[s.model_dump() for s in validated.stakeholders],
+    )

quark_trace/fact_sheet/schema.py

@@ -0,0 +1,84 @@
+from enum import Enum
+from typing import List, Optional  # Optional retained for sub-schema fields
+
+from pydantic import BaseModel, Field
+
+
+class MLType(str, Enum):
+    SUPERVISED = "supervised"
+    UNSUPERVISED = "unsupervised"
+    SEMI_SUPERVISED = "semi-supervised"
+    REINFORCEMENT = "reinforcement"
+
+
+class BiasSeverity(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class InputType(str, Enum):
+    IMAGE = "image"
+    TEXT = "text"
+    TABULAR = "tabular"
+    TIME_SERIES = "time_series"
+    AUDIO = "audio"
+    OTHER = "other"
+
+
+class OutputType(str, Enum):
+    LABEL = "label"
+    SCORE = "score"
+    EMBEDDING = "embedding"
+    SEQUENCE = "sequence"
+    OTHER = "other"
+
+
+class AlgorithmSchema(BaseModel):
+    name: str
+    variant: Optional[str] = None
+
+
+class InputSchema(BaseModel):
+    name: str
+    type: InputType
+    description: Optional[str] = None
+
+
+class OutputSchema(BaseModel):
+    name: str
+    type: OutputType
+    description: Optional[str] = None
+
+
+class BiasSchema(BaseModel):
+    type: str
+    affected_group: str
+    severity: BiasSeverity
+    notes: Optional[str] = None
+
+
+class StakeholderSchema(BaseModel):
+    name: str
+    role: str
+    contact: Optional[str] = None
+
+
+class FactSheetSchema(BaseModel):
+    project_id: str = Field(
+        description=(
+            "Stable identifier for this project, supplied by the caller. Used as the "
+            "storage key for the fact sheet and the correlation key for all trace "
+            "records. Required — never auto-generated. Immutable once set."
+        ),
+    )
+    purpose: str
+    domain: str
+    ml_type: MLType
+    algorithm: list[AlgorithmSchema]
+    input: list[InputSchema]
+    output: list[OutputSchema]
+    performance_metrics: List[str]
+    bias: BiasSchema
+    stakeholders: list[StakeholderSchema]

quark_trace/project.py

@@ -0,0 +1,96 @@
+from typing import Any, Dict, List
+
+from quark_trace.fact_sheet.fact_sheet import FactSheet
+from quark_trace.fact_sheet.loader import load_fact_sheet
+from quark_trace.trace.backends.base import StorageBackend
+from quark_trace.trace.record import TraceRecord
+from quark_trace.trace.trace_log import TraceLog
+
+
+class Project:
+    """
+    Unified entry point for quark_trace.
+    Binds a Factsheet and a TraceLog under a single object.
+    """
+
+    def __init__(self, fact_sheet: FactSheet, tracer: TraceLog):
+        self.fact_sheet = fact_sheet
+        self._tracer = tracer
+
+
+    @classmethod
+    def load(cls, fact_sheet_path: str, backend: StorageBackend) -> 'Project':
+        """
+        Load a project from a YAML fact sheet and a storage backend.
+        Persists the fact sheet immediately on first load.
+
+        :param fact_sheet_path: path to the YAML fact sheet.
+        :param backend: Storage backend instance.
+
+        :returns project: a project containing the fact sheet and the tracer.
+        """
+        fact_sheet = load_fact_sheet(fact_sheet_path)
+        backend.save_fact_sheet(fact_sheet)
+        tracer = TraceLog(project_id=fact_sheet.project_id, backend=backend)
+        return cls(fact_sheet, tracer)
+    
+    @classmethod
+    def resume(cls, project_id: str, backend: StorageBackend) -> 'Project':
+        """
+        Resume an existing project by loading its fact sheet from the backend.
+        Used when re-attaching to an in-progress or completed experiment.
+
+        :param project_id: The project identifier.
+        :param backend: Storage backend instance.
+
+        :returns project: a project containing the fact sheet and the tracer.
+        """
+        fact_sheet = backend.load_fact_sheet(project_id)
+        tracer = TraceLog(project_id, backend)
+        return cls(fact_sheet, tracer)
+    
+    def log(self, stage: str, **payload: Any) -> TraceRecord:
+        """
+        Append a single trace record.
+
+        :param stage: Lifecycle stage being logged.
+        :param payload: Arbitary key-value data for this record
+
+        :return trace record: The logged event with associated metadata and payload
+        """
+        return self._tracer.log(stage, **payload)
+    
+    def history(self) -> List[TraceRecord]:
+        """
+        Retrieve all trace records for this project.
+
+        :return List[TraceRecord]: All trace records associated with this project.
+        """
+        return self._tracer.load_all()
+    
+    def summary(self) -> Dict[str, Any]:
+        records = self._tracer.load_all()
+
+        stages_recorded: Dict[str, int] = {}
+
+        for record in records:
+            stages_recorded[record.stage] = stages_recorded.get(record.stage, 0) + 1
+
+        return {
+            "project_id": self.fact_sheet.project_id,
+            "fact_sheet_version": self.fact_sheet.version,
+            "created_at": self.fact_sheet.created_at,
+            "amended_at": self.fact_sheet.amended_at,
+            "purpose": self.fact_sheet.purpose,
+            "domain": self.fact_sheet.domain,
+            "ml_type": self.fact_sheet.ml_type,
+            "total_records": len(records),
+            "stages_recorded": stages_recorded,
+            "first_record_at": records[0].timestamp if records else None,
+            "last_record_at": records[-1].timestamp if records else None,
+            "backend": type(self._tracer.backend).__name__
+        }
+    
+    def __str__(self) -> str:
+        return (f"Project(project_id={self.fact_sheet.project_id}, "
+                f"backend={type(self._tracer.backend).__name__})")

quark_trace/trace/__init__.py

@@ -0,0 +1,7 @@
+from quark_trace.trace.record import TraceRecord
+from quark_trace.trace.trace_log import TraceLog
+
+__all__ = [
+    "TraceRecord",
+    "TraceLog",
+]

quark_trace/trace/backends/__init__.py

@@ -0,0 +1,7 @@
+from quark_trace.trace.backends.base import StorageBackend
+from quark_trace.trace.backends.json_backend import JsonBackend
+
+__all__ = [
+    "StorageBackend",
+    "JsonBackend",
+]

quark_trace/trace/backends/base.py

@@ -0,0 +1,44 @@
+
+from abc import ABC, abstractmethod
+from typing import List
+
+from quark_trace.fact_sheet.fact_sheet import FactSheet
+from quark_trace.trace.record import TraceRecord
+
+
+class StorageBackend(ABC):
+    """
+    Abstract base class for storage backends that handle saving and loading trace records.
+    Everybackend must implement save() and load_all().
+    """
+
+    @abstractmethod
+    def save(self, record: TraceRecord) -> None:
+        """
+        Persist a TraceRecord to the storage backend.
+        """
+        ...
+
+    @abstractmethod
+    def load_all(self, project_id:str) -> List[TraceRecord]:
+        """
+        Retrieve all trace records for a given project ID.
+        """
+        ...
+
+    def save_fact_sheet(self, fact_sheet: FactSheet) -> None:
+        """
+        Persist the fact sheet for a project as a JSON file.
+
+        :param fact_sheet: The FactSheet instance to be saved.
+        """
+        ...
+
+    def load_fact_sheet(self, project_id: str) -> FactSheet:
+        """
+        Retrieve the fact sheet for a given project.
+
+        :param project_id: The ID of the project for which to retrieve the fact sheet.
+        :return: The FactSheet instance for the specified project.
+        """
+        ...

quark_trace/trace/backends/http_backend.py

@@ -0,0 +1,161 @@
+import os
+from typing import List, Optional
+
+import requests
+from dotenv import load_dotenv
+
+from quark_trace.exceptions import (BackendReadError, BackendWriteError,
+                                    FactSheetAlreadyExistsError,
+                                    FactSheetNotFoundError,
+                                    NodeAuthenticationError,
+                                    NodeScopeError,
+                                    NodeVerificationError)
+from quark_trace.fact_sheet.fact_sheet import FactSheet
+from quark_trace.trace.backends.base import StorageBackend
+from quark_trace.trace.record import TraceRecord
+
+load_dotenv()
+
+class HttpBackend(StorageBackend):
+    """
+    Storage backend that saves trace records in a persistent database.
+     - Each trace record is stored in a SQL database.
+    """
+
+    def __init__(self, base_url: Optional[str] = None, node_id: Optional[str] = None, api_key: Optional[str] = None) -> None:
+        if base_url:
+            self.server_url = base_url.rstrip("/")
+        else:
+            self.server_url = os.environ.get("QUARK_TRACE_SERVER_URL")
+
+        self.node_id = node_id or os.environ.get("QUARK_TRACE_NODE_ID")
+        self.api_key = api_key or os.environ.get("QUARK_TRACE_API_KEY")
+
+        if not all([self.server_url, self.node_id, self.api_key]):
+            raise ValueError("server_url, node_id, and api_key must be provided "
+                "either as arguments or via environment variables "
+                "QUARK_TRACE_SERVER_URL, QUARK_TRACE_NODE_ID, QUARK_TRACE_API_KEY")
+
+        self.institution_id: str = ""
+
+        self._verify_node()
+
+    @property
+    def _auth_headers(self) -> dict:
+        return {"X-API-Key": self.api_key}
+
+    def _check_scope(self, resource_institution_id: Optional[str] = None) -> None:
+        """Raise NodeScopeError if this node is not authorised to write the resource."""
+        if not self.institution_id:
+            raise NodeScopeError("Node has no institution scope — pre-flight verification may not have completed.")
+        if resource_institution_id is not None and resource_institution_id != self.institution_id:
+            raise NodeScopeError(
+                f"Node is scoped to institution '{self.institution_id}' "
+                f"but resource belongs to '{resource_institution_id}'."
+            )
+
+    def save(self, record: TraceRecord) -> None:
+        self._check_scope()
+        try:
+            response = requests.post(
+                f"{self.server_url}/projects/{record.project_id}/records",
+                json=record.to_json(),
+                headers=self._auth_headers,
+            )
+
+            if not response.ok:
+                print(response.json())
+                response.raise_for_status()
+
+        except requests.RequestException as e:
+            raise BackendWriteError(str(e))
+        
+
+    def load_all(self, project_id: str) -> List[TraceRecord]:
+        try:
+            response = requests.get(f"{self.server_url}/projects/{project_id}/records")
+
+            if not response.ok:
+                print(response.json())
+                response.raise_for_status()
+
+            return [TraceRecord.from_json(r) for r in response.json()]
+        except requests.RequestException as e:
+            raise BackendReadError(str(e))
+        
+    def _fact_sheet_payload(self, fact_sheet: FactSheet) -> dict:
+        """Map our FactSheet onto the server's FactSheet schema."""
+        return {
+            "project_id": fact_sheet.project_id,
+            "sheet_id": fact_sheet.sheet_id,
+            "institution": self.institution_id,
+            "purpose": fact_sheet.purpose,
+            "domain": fact_sheet.domain,
+            "ml_type": fact_sheet.ml_type,
+            "algorithm": fact_sheet.algorithm,
+            "input": fact_sheet.input,
+            "output": fact_sheet.output,
+            "bias": fact_sheet.bias,
+            "stakeholders": fact_sheet.stakeholders,
+            "performance_metrics": fact_sheet.performance_metrics,
+        }
+
+    def save_fact_sheet(self, fact_sheet: FactSheet) -> None:
+        self._check_scope(fact_sheet.institution_id)
+        try:
+            response = requests.post(
+                f"{self.server_url}/projects/",
+                json=self._fact_sheet_payload(fact_sheet),
+                headers=self._auth_headers,
+            )
+            if response.status_code == 409:
+                raise FactSheetAlreadyExistsError(fact_sheet.project_id)
+            
+            if not response.ok:
+                print(response.json())
+                response.raise_for_status()
+
+        except FactSheetAlreadyExistsError:
+            raise
+        except requests.RequestException as e:
+            raise BackendWriteError(str(e))
+
+    def load_fact_sheet(self, project_id: str) -> FactSheet:
+        try:
+            response = requests.get(
+                f"{self.server_url}/projects/{project_id}"
+            )
+            if response.status_code == 404:
+                raise FactSheetNotFoundError(project_id)
+            response.raise_for_status()
+            return FactSheet.from_json(response.json())
+        except FactSheetNotFoundError:
+            raise
+        except requests.RequestException as e:
+            raise BackendReadError(str(e))    
+
+    def _verify_node(self) -> None:
+        try:
+            if self.api_key is not None:
+                response = requests.get(f"{self.server_url}/registry/nodes/{self.node_id}", headers={"X-API-Key": self.api_key})
+
+        except requests.exceptions.ConnectionError:
+            raise NodeVerificationError(
+            f"Could not connect to server at {self.server_url}"
+        )
+
+        if response.status_code == 401:
+            raise NodeAuthenticationError("Invalid or inactive node credentials")
+        
+        if response.status_code == 404:
+            raise NodeVerificationError(f"Node '{self.node_id}' not found in registry")
+        
+        if response.status_code != 200:
+            raise NodeVerificationError(f"Unexpected response from registry: {response.status_code}")
+        
+        data = response.json()
+
+        if data.get("status") != "active":
+            raise NodeVerificationError(f"Node '{self.node_id}' is registered but inactive")
+
+        self.institution_id = data["institution_id"]

quark_trace/trace/backends/json_backend.py

@@ -0,0 +1,68 @@
+import json
+import os
+from pathlib import Path
+from typing import List
+
+from quark_trace.exceptions import (
+    FactSheetAlreadyExistsError,
+    FactSheetNotFoundError,
+    BackendReadError,
+    BackendWriteError,
+)
+from quark_trace.fact_sheet.fact_sheet import FactSheet
+from quark_trace.trace.backends.base import StorageBackend
+from quark_trace.trace.record import TraceRecord
+
+
+class JsonBackend(StorageBackend):
+    """
+    Storage backend that saves trace records as JSON lines in a file.
+     - Each trace record is stored as a separate line in the file.
+    """
+    def __init__(self, path: str, file_type: str = "jsonl") -> None:
+        self.path = Path(path).resolve()
+        os.makedirs(self.path, exist_ok=True)
+        self.file_type = file_type
+
+    def _trace_path(self, project_id: str) -> str:
+        return os.path.join(self.path, f"{project_id}_trace_log.{self.file_type}")
+
+    def _fact_sheet_path(self, project_id: str) -> str:
+        return os.path.join(self.path, f"{project_id}_fact_sheet.json")
+
+    def save(self, record: TraceRecord) -> None:
+        try:
+            with open(self._trace_path(record.project_id), "a") as f:
+                f.write(json.dumps(record.to_json()) + "\n")
+        except IOError as e:
+            raise BackendWriteError(str(e))
+
+    def load_all(self, project_id: str) -> List[TraceRecord]:
+        path = self._trace_path(project_id)
+        if not os.path.exists(path):
+            return []
+        try:
+            with open(path, "r") as f:
+                return [TraceRecord.from_json(json.loads(line)) for line in f if line.strip()]
+        except IOError as e:
+            raise BackendReadError(str(e))
+
+    def save_fact_sheet(self, fact_sheet: FactSheet) -> None:
+        path = self._fact_sheet_path(fact_sheet.project_id)
+        if os.path.exists(path):
+            raise FactSheetAlreadyExistsError(fact_sheet.project_id)
+        try:
+            with open(path, "w") as f:
+                json.dump(fact_sheet.to_json(), f, indent=2)
+        except IOError as e:
+            raise BackendWriteError(str(e))
+
+    def load_fact_sheet(self, project_id: str) -> FactSheet:
+        path = self._fact_sheet_path(project_id)
+        if not os.path.exists(path):
+            raise FactSheetNotFoundError(project_id)
+        try:
+            with open(path, "r") as f:
+                return FactSheet.from_json(json.load(f))
+        except IOError as e:
+            raise BackendReadError(str(e))

quark_trace/trace/record.py

@@ -0,0 +1,68 @@
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict
+from uuid import uuid4
+
+
+@dataclass(frozen=True)
+class TraceRecord:
+	"""
+	A trace record of the ML lifecycle, representing a single logged event with associated metadata and payload.
+	"""
+	record_id: str
+	project_id: str
+	stage: str
+	timestamp: str
+	payload: Dict[str, Any]
+
+	@classmethod
+	def create(cls, project_id: str, stage: str, payload: Dict[str, Any]) -> 'TraceRecord':
+		"""
+		Create a new TraceRecord with a unique record_id and current timestamp.
+
+		:param project_id: The ID of the project this trace record belongs to.
+		:param stage: The stage of the ML lifecycle this record represents (e.g., "experiment_start", "client_round", etc.).
+		:param payload: A dictionary containing any additional data relevant to this trace record.
+		:return: A new instance of TraceRecord with the provided data and generated metadata.
+		"""
+		return cls(
+			record_id=str(uuid4()),
+			project_id=project_id,
+			stage=stage,
+			timestamp=datetime.now(timezone.utc).isoformat(),
+			payload=payload
+		)
+
+	def to_json(self) -> Dict[str, Any]:
+		"""
+		Convert the TraceRecord instance into a JSON-serializable dictionary format.
+
+		:return: A dictionary representation of the TraceRecord suitable for JSON serialization.
+		"""
+		return {
+			"record_id": self.record_id,
+			"project_id": self.project_id,
+			"stage": self.stage,
+			"timestamp": self.timestamp,
+			"payload": self.payload
+		}
+
+	@classmethod
+	def from_json(cls, data: Dict[str, Any]) -> 'TraceRecord':
+		"""
+		Create a new TraceRecord instance from a JSON-serializable dictionary.
+
+		:param data: A dictionary containing the trace record data.
+		:return: A new instance of TraceRecord initialized with the data from the dictionary.
+		"""
+		return cls(
+			record_id=str(data["record_id"]),
+			project_id=str(data["project_id"]),
+			stage=str(data["stage"]),
+			timestamp=str(data["timestamp"]),
+			payload=data.get("payload", {})
+		)
+	
+	def __str__(self) -> str:
+		return f"TraceRecord(record_id={self.record_id}, project_id={self.project_id}, stage={self.stage}, timestamp={self.timestamp}, payload={self.payload})"

quark_trace/trace/trace_log.py

@@ -0,0 +1,41 @@
+from typing import Any
+
+from quark_trace.exceptions import InvalidStageError
+from quark_trace.trace.backends.base import StorageBackend
+from quark_trace.trace.record import TraceRecord
+
+
+class TraceLog:
+    """
+    Append-only trace log for a specific project.
+    Delegates persistence to an injected StorageBackend implementation.
+    """
+    def __init__(self, project_id: str, backend: StorageBackend) -> None:
+        self.project_id = project_id
+        self.backend = backend
+
+    def log(self, stage: str, **payload: Any) -> TraceRecord:
+        """
+        Create a persistent trace record for a specific stage of the ML lifecycle.
+
+        :param stage: The lifecycle data being logged.
+        :param payload: Arbitrary key-value pairs representing the data to be logged.
+        """
+        if not stage or not stage.strip():
+            raise InvalidStageError(stage)
+        record = TraceRecord.create(
+            project_id=self.project_id,
+            stage=stage,
+            payload=dict(payload)
+        )
+        self.backend.save(record)
+        return record
+
+    def load_all(self) -> list[TraceRecord]:
+        """"
+        Retrieve all trace records for the project from the backend.
+        """
+        return self.backend.load_all(self.project_id)
+
+    def __str__(self) -> str:
+        return f"TraceLog(project_id={self.project_id}, backend={type(self.backend).__name__})"

quark_trace-0.1.0.dist-info/METADATA

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: quark-trace
+Version: 0.1.0
+Summary: Quark Trace — ML traceability and audit trail library. Part of the Quark suite.
+Author-email: Mohammed <mohammed.alwedaei@outlook.com>
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests
+Requires-Dist: python-dotenv
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+
+# Quark Trace
+
+A Python library for ML traceability. Provides structured logging of machine learning project metadata, experiment history, and audit trails across interchangeable storage backends.
+
+Designed to integrate with federated learning frameworks and other distributed ML pipelines.
+
+---
+
+## Status
+
+Active development. Core modules — `FactSheet`, `TraceLog`, `Project`, and the JSON storage backend — are implemented.
+
+---
+
+## Architecture
+
+```
+user-defined YAML file
+        |
+        v
+Pydantic schema (validation)
+        |
+        v
+FactSheet (identity + amendment trail)
+        |
+        v
+Project (unified entry point)
+        |
+        v
+TraceLog (append-only trace records)
+        |
+        v
+StorageBackend (interchangeable: JSON, SQL, IPFS, Blockchain)
+```
+
+The library is organized around three layers:
+
+- **Identity layer** — `FactSheet` defines the static project identity, loaded from YAML and validated by Pydantic. Supports controlled amendments with a full version trail.
+- **Trace layer** — `TraceLog` maintains an append-only log of discrete lifecycle events. Each call to `project.log()` produces one immutable `TraceRecord`.
+- **Storage layer** — `StorageBackend` is an abstract interface. All persistence is delegated to a backend. No component is coupled to a specific storage mechanism.
+
+---
+
+## Module Structure
+
+```
+quark_trace/
+    project.py                  # Unified entry point
+    fact_sheet/
+        __init__.py
+        schema.py               # Pydantic validation models
+        fact_sheet.py           # FactSheet class
+        loader.py               # YAML -> Pydantic -> FactSheet
+    trace/
+        __init__.py
+        record.py               # TraceRecord — single immutable entry
+        trace_log.py            # TraceLog — append-only log
+        backends/
+            __init__.py
+            base.py             # Abstract StorageBackend
+            json_backend.py     # File system backend (JSONL + JSON)
+```
+
+---
+
+## Components
+
+### Project
+
+The single object the consuming framework interacts with. Binds a `FactSheet` and a `TraceLog` under one interface.
+
+```python
+from quark_trace.project import Project
+from quark_trace.trace.backends.json_backend import JsonBackend
+
+# First run — loads YAML, persists fact sheet, starts trace log
+project = Project.load(
+    fact_sheet_path="fact_sheet.yaml",
+    backend=JsonBackend(path="logs/")
+)
+
+# Resume an existing project without re-loading the YAML
+project = Project.resume(
+    project_id="fl-project-001",
+    backend=JsonBackend(path="logs/")
+)
+```
+
+### Logging
+
+All trace logging goes through a single method on `Project`:
+
+```python
+project.log(stage="experiment_start", rounds=10, clients=5)
+project.log(stage="client_round", round=1, client_id="client_03", loss=0.21)
+project.log(stage="aggregation_round", round=1, aggregated_loss=0.19)
+project.log(stage="experiment_end", final_loss=0.11, duration_seconds=342)
+```
+
+### Retrieving History
+
+```python
+records = project.history()
+```
+
+---
+
+### FactSheet
+
+Defines and tracks the static identity of an ML project. Loaded from a user-defined YAML file. Supports controlled amendments with a full version trail.
+
+**YAML template:**
+
+```yaml
+project_id: "my-project-001"   # optional — auto-assigned if omitted
+
+purpose: "Detect fraudulent transactions in real-time"
+domain: "Financial Services"
+ml_type: "supervised"
+
+algorithm:
+  - name: "XGBoost"
+    variant: "XGBClassifier"
+
+input:
+  - name: "transaction_features"
+    type: "tabular"
+    description: "Normalized transaction records"
+
+output:
+  - name: "fraud_label"
+    type: "label"
+    description: "Binary fraud classification"
+
+performance_metrics:
+  - "accuracy"
+  - "precision"
+  - "recall"
+  - "f1"
+
+bias:
+  type: "historical"
+  affected_group: "low-income demographics"
+  severity: "medium"
+  notes: "Training data reflects prior biased approval patterns"
+
+stakeholders:
+  - name: "Jane Doe"
+    role: "ML Engineer"
+    contact: "jane@example.com"
+```
+
+**Schema:**
+
+| Field | Type | Description |
+|---|---|---|
+| `sheet_id` | `str` | Unique identifier for the fact sheet |
+| `project_id` | `str` | Parent project identifier |
+| `version` | `int` | Increments on each amendment |
+| `created_at` | `str` | ISO-8601 timestamp of initial creation |
+| `amended_at` | `str` | ISO-8601 timestamp of last amendment |
+| `amendment_log` | `list` | Full history of all amendments |
+| `purpose` | `str` | Description of the project's objective |
+| `domain` | `str` | Application domain |
+| `ml_type` | `str` | supervised, unsupervised, semi-supervised, self-supervised, reinforcement |
+| `algorithm` | `list[dict]` | Algorithm name and optional variant |
+| `input` | `list[dict]` | Input modalities and types |
+| `output` | `list[dict]` | Output types and descriptions |
+| `performance_metrics` | `list[str]` | Metric names tracked in this project |
+| `bias` | `dict` | Structured bias declaration with type, affected group, severity, and notes |
+| `stakeholders` | `list[dict]` | Named stakeholders, roles, and contacts |
+
+---
+
+### TraceRecord
+
+A single immutable trace entry. Frozen at the object level — no field can be modified after creation.
+
+| Field | Type | Description |
+|---|---|---|
+| `record_id` | `str` | Unique identifier for this record |
+| `project_id` | `str` | Parent project identifier |
+| `stage` | `str` | Lifecycle stage label |
+| `timestamp` | `str` | ISO-8601 UTC timestamp |
+| `payload` | `dict` | Arbitrary stage-specific data |
+
+---
+
+### Storage Backends
+
+All backends implement the `StorageBackend` abstract interface:
+
+| Method | Description |
+|---|---|
+| `save(record)` | Persist a single trace record |
+| `load_all(project_id)` | Retrieve all trace records for a project |
+| `save_fact_sheet(fact_sheet)` | Persist the fact sheet for a project |
+| `load_fact_sheet(project_id)` | Retrieve the fact sheet for a project |
+
+**JSON Backend** stores data as two files per project:
+
+| File | Format | Description |
+|---|---|---|
+| `{project_id}.jsonl` | Newline-delimited JSON | Append-only trace records |
+| `{project_id}.fact.json` | JSON | Fact sheet |
+
+---
+
+## Design Principles
+
+- The `Project` object is the single interface for consuming frameworks. Internal components are not exposed.
+- Storage backends are interchangeable. Switching from JSON to SQL or IPFS requires no changes to `Project`, `FactSheet`, or `TraceLog`.
+- The fact sheet is written once and amended with a version trail — never silently overwritten.
+- Trace records are strictly append-only and immutable at the object level.
+- All structures are JSON-serializable by design.
+- YAML is the primary interface for fact sheet definition. Direct construction is not the intended path.
+
+---
+
+## Roadmap
+
+- [x] `FactSheet` class with amendment trail
+- [x] Pydantic validation schema
+- [x] YAML loader
+- [x] `TraceRecord` — immutable trace entry
+- [x] `TraceLog` — append-only log
+- [x] `StorageBackend` abstract interface
+- [x] `JsonBackend` — file system implementation
+- [x] `Project` — unified entry point
+- [ ] `SqlBackend`
+- [ ] `IpfsBackend`
+- [ ] `BlockchainBackend`
+- [ ] Stage schema validation layer
+- [ ] Query and filtering API for trace history
+
+---
+
+## License
+
+To be defined.

quark_trace-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+quark_trace/__init__.py,sha256=ivyJNZvwcQckoyqSZs8gUI7454twWDfDVhOOeQqxDfE,886
+quark_trace/exceptions.py,sha256=Cojh2L-MYrbTcadbh-Gw_8wdbbDoE48RS9rzAWkXcZc,3265
+quark_trace/project.py,sha256=11ypzRnFypekFbSd5nnSXWQoh76Um1-lhHKAzBb0JtE,3569
+quark_trace/fact_sheet/__init__.py,sha256=gqOQpGw_BiYBKv2Rlk_UNH5PcNxnxNJskLkkuoG-_e0,169
+quark_trace/fact_sheet/fact_sheet.py,sha256=Lg8PaYYgUSha8uBH7vm34XokiLGl_gbMkiLxI3NEHe0,3886
+quark_trace/fact_sheet/loader.py,sha256=1bCmoRGGRqfXX52XbseGXbWSwR6ZRoVzTY3mW4vQ2yQ,1005
+quark_trace/fact_sheet/schema.py,sha256=oCNAKn1yZn7blNo63CHOqS1vMDPoWs5l5P4NzvSczfU,1852
+quark_trace/trace/__init__.py,sha256=5GPsr1CHAAzZpEKXpoPw249OeIp6hXX1p198lGpigvM,148
+quark_trace/trace/record.py,sha256=ap6a0Aodbfiyc7FplRlglmFuPFVh9FJgtPTHyPNt7MY,2175
+quark_trace/trace/trace_log.py,sha256=HhteQ_5nLsm956qbG2smGvUn0JYL6GHRfvm4sxOCXxw,1403
+quark_trace/trace/backends/__init__.py,sha256=A8GjUU9M9dAhrdx9RhcL4jtDmjjWOh79wqD-iqCa31o,179
+quark_trace/trace/backends/base.py,sha256=LHuZztd_597JN3ejqf-d3onsTvhyCM3CEO0-SzKWSVU,1224
+quark_trace/trace/backends/http_backend.py,sha256=pqBdQrd_bzX4AS0I75J_Uu44dPzxsNQB50rQpZqcNLg,6309
+quark_trace/trace/backends/json_backend.py,sha256=1aDEOqB1A9EhCGt84ezv1RYpKUwjK0mpV5ydzbWEEg0,2471
+quark_trace-0.1.0.dist-info/METADATA,sha256=Av0wTSpxp4VMUnoo7yZnudv89FuM2BsDD9IKhaStW2s,7804
+quark_trace-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+quark_trace-0.1.0.dist-info/top_level.txt,sha256=Ip-hCoq51zV2gv1R3FGLr1dsaSsZKxmbhiMFD0739_c,12
+quark_trace-0.1.0.dist-info/RECORD,,

quark_trace-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

quark_trace-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+quark_trace