quark-trace 0.1.0

Quark Trace — ML traceability and audit trail library. Part of the Quark suite.

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.

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:

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

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:

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: "[e-mail]"

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

• FactSheet class with amendment trail
• Pydantic validation schema
• YAML loader
• TraceRecord — immutable trace entry
• TraceLog — append-only log
• StorageBackend abstract interface
• JsonBackend — file system implementation
• Project — unified entry point
• SqlBackend
• IpfsBackend
• BlockchainBackend
• Stage schema validation layer
• Query and filtering API for trace history

---

License

To be defined.