flameiq.schema — Data Models

FlameIQ Performance Schema — Version 1.

This module defines the canonical, versioned data contract for all FlameIQ performance snapshots. Schema v1 is stable and immutable — fields will never be removed or renamed. New optional fields may appear in minor patch releases.

All classes use standard-library dataclasses only. Zero external runtime dependencies in this module.

Schema version: 1 Stability: Production / Stable

class flameiq.schema.v1.models.Environment(*values)[source]

Bases: str, Enum

The execution environment for a benchmark run.

CI = 'ci'

LOCAL = 'local'

STAGING = 'staging'

CUSTOM = 'custom'

class flameiq.schema.v1.models.LatencyMetrics(mean=None, p50=None, p95=None, p99=None)[source]

Bases: object

Latency measurements in milliseconds.

At least one field must be provided. p95 is the primary regression signal used by the comparison engine.

Parameters:

mean (float | None) – Arithmetic mean latency (ms).
p50 (float | None) – Median latency (ms).
p95 (float | None) – 95th-percentile latency (ms). Primary regression signal.
p99 (float | None) – 99th-percentile latency (ms). Tail latency signal.

mean: float | None = None

p50: float | None = None

p95: float | None = None

p99: float | None = None

__post_init__()[source]

Validate that at least one latency metric is provided and all are non-negative.

Return type:: None

class flameiq.schema.v1.models.Metrics(latency=None, throughput=None, memory_mb=None, cpu_percent=None, custom=<factory>)[source]

Bases: object

All performance measurements for a single benchmark run.

At least one metric must be non-null/non-empty.

Parameters:

latency (LatencyMetrics | None) – Latency breakdown in milliseconds.
throughput (float | None) – Operations or requests per second.
memory_mb (float | None) – Peak memory usage in megabytes.
cpu_percent (float | None) – Average CPU utilisation (0–100).
custom (dict[str, float]) – User-defined numeric metrics. Keys are dotted names.

latency: LatencyMetrics | None = None

throughput: float | None = None

memory_mb: float | None = None

cpu_percent: float | None = None

custom: dict[str, float]

__post_init__()[source]

Validate that at least one metric is provided and all numeric values are non-negative.

Return type:: None

flat()[source]

Return a flat {key: value} dict of all non-null metrics.

Keys follow a dotted naming convention: latency.mean, latency.p95, throughput, memory_mb, cpu_percent, custom.<name>.

Returns:: Ordered dict of all non-null metric values.
Return type:: dict[str, float]

class flameiq.schema.v1.models.SnapshotMetadata(run_id=<factory>, commit=None, branch=None, timestamp=<factory>, environment=Environment.CI, tags=<factory>)[source]

Bases: object

Contextual metadata attached to a PerformanceSnapshot.

Parameters:

run_id (str) – UUID4 uniquely identifying this run. Auto-generated.
commit (str | None) – Git commit hash (short or full SHA).
branch (str | None) – Git branch name.
timestamp (datetime) – UTC datetime of the run. Auto-generated if omitted.
environment (Environment) – Execution environment label.
tags (dict[str, str]) – Arbitrary str → str metadata for user context.

run_id: str

commit: str | None = None

branch: str | None = None

timestamp: datetime

environment: Environment = 'ci'

tags: dict[str, str]

class flameiq.schema.v1.models.PerformanceSnapshot(metrics, schema_version=1, metadata=<factory>)[source]

Bases: object

A complete, versioned performance snapshot.

This is the primary data unit in FlameIQ. Every benchmark run produces exactly one PerformanceSnapshot. Snapshots are immutable in intent — do not mutate after construction.

Parameters:

metrics (Metrics) – All performance measurements for this run.
schema_version (int) – Must be 1 for v1 snapshots.
metadata (SnapshotMetadata) – Run context (commit, branch, timestamp, etc.).

Example:

snapshot = PerformanceSnapshot(
    metadata=SnapshotMetadata(commit="abc123", branch="main"),
    metrics=Metrics(
        latency=LatencyMetrics(mean=120.5, p95=180.0, p99=240.0),
        throughput=950.2,
        memory_mb=512.0,
    ),
)