pmprov 0.1.0__py3-none-any.whl

models/__init__.py

@@ -0,0 +1,78 @@
+"""
+Pydantic data model for Analytic Provenance in Exploratory Process Mining.
+
+Derived from: "A Conceptual Model to Enhance Process Mining Analysis with Provenance"
+(ER 2026, blinded for review)
+
+Package layout
+--------------
+agents      – Agent, AgentType, RuntimeEnvironment
+artifacts   – Artifact, ArtifactType, ArtifactState, Delta, DataFrameDelta, ModificationType
+parameters  – Parameter, ParameterValueType, and all ParameterValue subclasses / union
+operations  – OperationType, StepCategory, Operation, Version
+analysis    – AnalysisStep, AnalysisState, StateAbstraction
+history     – AnalysisBranch, AnalysisHistory
+pipelines   – PipelineFragment, Pipeline
+"""
+
+from .agents import Agent, AgentType, RuntimeEnvironment
+from .analysis import AnalysisState, AnalysisStep, StateAbstraction
+from .artifacts import (
+    Artifact,
+    ArtifactState,
+    ArtifactType,
+    DataFrameDelta,
+    Delta,
+    ModificationType,
+)
+from .history import AnalysisBranch, AnalysisHistory
+from .operations import Operation, OperationType, StepCategory, Version
+from .parameters import (
+    ArtifactStateParameterValue,
+    DictParameterValue,
+    LambdaParameterValue,
+    ListParameterValue,
+    Parameter,
+    ParameterValue,
+    ParameterValueType,
+    ScalarParameterValue,
+)
+from .pipelines import Pipeline, PipelineFragment
+
+__all__ = [
+    # agents
+    "AgentType",
+    "Agent",
+    "RuntimeEnvironment",
+    # artifacts
+    "ArtifactType",
+    "ModificationType",
+    "Artifact",
+    "ArtifactState",
+    "Delta",
+    "DataFrameDelta",
+    # parameters
+    "ParameterValueType",
+    "Parameter",
+    "ScalarParameterValue",
+    "ArtifactStateParameterValue",
+    "LambdaParameterValue",
+    "ListParameterValue",
+    "DictParameterValue",
+    "ParameterValue",
+    # operations
+    "OperationType",
+    "StepCategory",
+    "Operation",
+    "Version",
+    # analysis
+    "StateAbstraction",
+    "AnalysisState",
+    "AnalysisStep",
+    # history
+    "AnalysisBranch",
+    "AnalysisHistory",
+    # pipelines
+    "PipelineFragment",
+    "Pipeline",
+]

models/agents.py

@@ -0,0 +1,59 @@
+"""Agent and execution-environment models."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class AgentType(str, Enum):
+    """Distinguishes human analysts from automated scripts / systems."""
+
+    HUMAN = "human"
+    AUTOMATED = "automated"
+
+
+class Agent(BaseModel):
+    """
+    Represents the entity (human or system) that performs an AnalysisStep.
+
+    UML attributes: agentId, agentType
+    """
+
+    agent_id: str = Field(..., description="Unique identifier for the agent.")
+    agent_type: AgentType = Field(
+        ..., description="Whether the agent is a human analyst or an automated system."
+    )
+    username: Optional[str] = Field(
+        None, description="OS username of the agent, captured at session start."
+    )
+
+
+class RuntimeEnvironment(BaseModel):
+    """
+    Captures the execution environment of an AnalysisStep to enable reproducibility (R2).
+
+    UML attributes: envId, toolVersion, libraryVersions, runtime
+    """
+
+    env_id: str = Field(..., description="Unique identifier for this environment snapshot.")
+    tool_version: str = Field(
+        ..., description="Version of the primary analysis tool (e.g., Python 3.11)."
+    )
+    library_versions: dict[str, str] = Field(
+        default_factory=dict,
+        description="Map of library name → version string (e.g., {'pandas': '2.2.1'}).",
+    )
+    runtime: Optional[str] = Field(
+        None,
+        description="Free-form description of the runtime platform (OS, hardware, etc.).",
+    )
+
+
+__all__ = [
+    "AgentType",
+    "Agent",
+    "RuntimeEnvironment",
+]

models/analysis.py

@@ -0,0 +1,137 @@
+"""AnalysisStep, AnalysisState, and StateAbstraction models."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class StateAbstraction(BaseModel):
+    """
+    A comparable summary or aggregated representation of an AnalysisState,
+    enabling state-level and history-level comparison (R5, R6).
+
+    UML attributes : abstractionId, type, value, function
+    UML relationship:
+        - wasAbstractedBy → AnalysisState (via analysis_state_id)
+    """
+
+    abstraction_id: str = Field(..., description="Unique identifier for this abstraction.")
+    analysis_state_id: str = Field(
+        ...,
+        description="FK → AnalysisState.state_id – the state this abstraction summarises.",
+    )
+    abstraction_type: str = Field(
+        ...,
+        description=(
+            "Category of abstraction (e.g., 'trace_variant_distribution', "
+            "'performance_metric', 'feature_vector')."
+        ),
+    )
+    value: Any = Field(
+        ...,
+        description="The computed abstraction value (scalar, dict, list, …).",
+    )
+    function: str = Field(
+        ...,
+        description=(
+            "Identifier or source-code reference of the function used to compute "
+            "this abstraction (e.g., a qualified Python callable name)."
+        ),
+    )
+
+
+class AnalysisState(BaseModel):
+    """
+    An immutable snapshot of the overall analysis at a specific point in time.
+    Acts as a container for one or more ArtifactStates.
+
+    UML attributes : stateId, createdAt
+    UML relationships:
+        - usedInput        → AnalysisStep    (via produced_by_step_id)
+        - outputProducedBy → AnalysisStep    (via produced_by_step_id)
+        - wasDerivedFrom   → AnalysisState   (via derived_from_state_id)
+        - hasActiveState   → AnalysisBranch  (via branch_id)
+        - includes         → ArtifactState   (1-to-N; represented in ArtifactState.analysis_state_id)
+        - wasAbstractedBy  → StateAbstraction (1-to-N; represented in StateAbstraction.analysis_state_id)
+    """
+
+    state_id: str = Field(..., description="Unique identifier for this analysis state.")
+    history_id: str = Field(
+        ...,
+        description="FK → AnalysisHistory.history_id – the session this state belongs to.",
+    )
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="UTC timestamp at which this state was created.",
+    )
+    branch_id: str = Field(
+        ...,
+        description="FK → AnalysisBranch.branch_id – the branch this state belongs to.",
+    )
+    produced_by_step_id: Optional[str] = Field(
+        None,
+        description=(
+            "FK → AnalysisStep.step_id – the step whose output produced this state. "
+            "None for the initial ROOT state."
+        ),
+    )
+    derived_from_state_id: Optional[str] = Field(
+        None,
+        description=(
+            "FK → AnalysisState.state_id – the predecessor state in the analysis chain. "
+            "None for the ROOT state."
+        ),
+    )
+
+
+class AnalysisStep(BaseModel):
+    """
+    A concrete, immutable execution of an Operation within an AnalysisBranch.
+    Bridges two AnalysisStates (input → output) and records the full execution context.
+
+    UML attributes: stepId, createdAt
+    UML relationships:
+        - usedInput        → AnalysisState      (via input_state_id)
+        - outputProducedBy → AnalysisState      (via output_state_id)
+        - performedBy      → Agent              (via agent_id)
+        - executesIn       → RuntimeEnvironment (via env_id)
+        - executes         → Operation          (via operation_id)
+        - produces         → Delta              (1-to-N; represented in Delta.root/updated refs)
+        - instantiates     → ParameterValue     (1-to-N; represented in ParameterValue.step_id)
+    """
+
+    step_id: str = Field(..., description="Unique identifier for this analysis step.")
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="UTC timestamp at which this step was executed.",
+    )
+    input_state_id: str = Field(
+        ...,
+        description="FK → AnalysisState.state_id – the state consumed as input.",
+    )
+    output_state_id: str = Field(
+        ...,
+        description="FK → AnalysisState.state_id – the state produced as output.",
+    )
+    agent_id: str = Field(
+        ...,
+        description="FK → Agent.agent_id – the agent that performed this step.",
+    )
+    env_id: str = Field(
+        ...,
+        description="FK → RuntimeEnvironment.env_id – the runtime environment used.",
+    )
+    operation_id: str = Field(
+        ...,
+        description="FK → Operation.operation_id – the operation that was executed.",
+    )
+
+
+__all__ = [
+    "StateAbstraction",
+    "AnalysisState",
+    "AnalysisStep",
+]

models/artifacts.py

@@ -0,0 +1,134 @@
+"""Artifact, ArtifactState, and Delta models."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class ArtifactType(str, Enum):
+    EVENT_LOG = "event_log"
+    PROCESS_MODEL = "process_model"
+    KPI_REPORT = "kpi_report"
+    OTHER = "other"
+
+
+class ModificationType(str, Enum):
+    """Analyst-facing classification of what a Delta describes."""
+    ADDITION = "addition"          # new rows or columns added
+    REMOVAL = "removal"            # rows or columns removed
+    RENAMING = "renaming"          # columns renamed
+    CASTING = "casting"            # column dtype changed
+    NORMALIZATION = "normalization"  # values scaled or standardised (e.g. min-max, z-score)
+    ENRICHMENT = "enrichment"      # new information derived from external or computed sources
+    OBFUSCATION = "obfuscation"    # values masked, hashed, or anonymised
+    RECALCULATION = "recalculation"  # existing values recomputed (e.g. updated formula or parameter)
+    OTHER = "other"
+
+
+class Artifact(BaseModel):
+    """
+    Conceptual data object (e.g., an event log or process model) that persists
+    across the analysis.  ArtifactStates are its versioned snapshots.
+
+    UML attributes: artifactId, name, artifactType
+    """
+
+    artifact_id: str = Field(..., description="Unique identifier for the artifact.")
+    name: str = Field(..., description="Human-readable name (e.g., 'RTFM event log').")
+    artifact_type: ArtifactType = Field(..., description="Category of the artifact.")
+
+
+class ArtifactState(BaseModel):
+    """
+    An immutable snapshot of an Artifact at a specific point in the analysis.
+    Multiple ArtifactStates may be *included* in a single AnalysisState.
+
+    UML attributes : artifactStateId, mimeType, checksum, contentRef, sizeBytes
+    UML relationships:
+        - includes  → AnalysisState  (via analysis_state_id)
+        - roots     → Delta          (an ArtifactState is the root of a Delta chain)
+        - updates   → Delta          (an ArtifactState is the updated end of a Delta)
+        - snapshots → Artifact       (via artifact_id)
+    """
+
+    artifact_state_id: str = Field(..., description="Unique identifier for this snapshot.")
+    artifact_id: str = Field(
+        ..., description="FK → Artifact.artifact_id – the artifact being snapshotted."
+    )
+    analysis_state_id: str = Field(
+        ...,
+        description="FK → AnalysisState.state_id – the analysis state that includes this snapshot.",
+    )
+    mime_type: str = Field(
+        ..., description="MIME type of the stored content (e.g., 'text/csv')."
+    )
+    checksum: str = Field(
+        ..., description="Hash of the content for integrity verification (e.g., SHA-256)."
+    )
+    content_ref: str = Field(
+        ...,
+        description="Pointer to the actual stored content (file path, URI, object-store key, …).",
+    )
+    size_bytes: int = Field(..., description="Size of the stored content in bytes.")
+
+
+class Delta(BaseModel):
+    """
+    Abstract base class that records the incremental structural change between
+    two ArtifactStates, supporting Data Evolution Transparency (R7).
+
+    UML attributes : deltaId, modificationType
+    UML relationships:
+        - roots   → ArtifactState  (via root_artifact_state_id)
+        - updates → ArtifactState  (via updated_artifact_state_id)
+    """
+
+    delta_id: str = Field(..., description="Unique identifier for this delta.")
+    modification_type: ModificationType = Field(
+        ..., description="High-level classification of the change."
+    )
+    root_artifact_state_id: str = Field(
+        ...,
+        description="FK → ArtifactState.artifact_state_id – the state *before* the change.",
+    )
+    updated_artifact_state_id: str = Field(
+        ...,
+        description="FK → ArtifactState.artifact_state_id – the state *after* the change.",
+    )
+
+
+class DataFrameDelta(Delta):
+    """
+    Concrete Delta subclass for pandas DataFrame transformations.
+
+    Extends Delta with DataFrame-specific change attributes used in the
+    evaluation scenario (Sect. 6 of the paper).
+    """
+
+    columns_added: list[str] = Field(
+        default_factory=list, description="Column names added in this step."
+    )
+    columns_removed: list[str] = Field(
+        default_factory=list, description="Column names removed in this step."
+    )
+    dtype_changes: dict[str, str] = Field(
+        default_factory=dict,
+        description="Map of column name → new dtype string for columns whose type changed.",
+    )
+    rows_delta: Optional[int] = Field(
+        None,
+        description="Net row count change (positive = rows added, negative = rows removed).",
+    )
+
+
+__all__ = [
+    "ArtifactType",
+    "ModificationType",
+    "Artifact",
+    "ArtifactState",
+    "Delta",
+    "DataFrameDelta",
+]

models/history.py

@@ -0,0 +1,72 @@
+"""AnalysisBranch and AnalysisHistory models."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class AnalysisBranch(BaseModel):
+    """
+    An independent analysis path within an AnalysisHistory.  Multiple branches
+    may share a common ancestor state (R3 – Branching Capability).
+
+    UML attributes: branchId
+    UML relationships:
+        - belongs to     → AnalysisHistory (via history_id)
+        - startsAt       → AnalysisState   (via starts_at_state_id – divergence point)
+        - hasActiveState → AnalysisState   (via active_state_id – current tip of the branch)
+    """
+
+    branch_id: str = Field(..., description="Unique identifier for this branch.")
+    history_id: str = Field(
+        ...,
+        description="FK → AnalysisHistory.history_id – the history this branch belongs to.",
+    )
+    name: str = Field(
+        "main",
+        description="Human-readable branch label (e.g., 'main', 'experiment-1'). Defaults to 'main'.",
+    )
+    starts_at_state_id: str = Field(
+        ...,
+        description=(
+            "FK → AnalysisState.state_id – the state at which this branch diverges "
+            "(i.e., its common origin with the parent branch)."
+        ),
+    )
+
+
+class AnalysisHistory(BaseModel):
+    """
+    Root container that encapsulates the entire lifecycle of an analytical process,
+    including all of its branches.
+
+    UML attributes: historyId
+    UML relationships:
+        - aggregates → AnalysisBranch (1-to-N; represented in AnalysisBranch.history_id)
+    """
+
+    history_id: str = Field(..., description="Unique identifier for this analysis history.")
+    name: Optional[str] = Field(
+        None, description="Optional human-readable title for the analysis session."
+    )
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="UTC timestamp at which this history was initiated.",
+    )
+    active_state_id: Optional[str] = Field(
+        None,
+        description=(
+            "FK → AnalysisState.state_id – the most recently produced state in this "
+            "history, regardless of branch.  Updated after every step so it always "
+            "reflects where the analyst currently is."
+        ),
+    )
+
+
+__all__ = [
+    "AnalysisBranch",
+    "AnalysisHistory",
+]

models/operations.py

@@ -0,0 +1,99 @@
+"""Operation definitions, their classification types, and versioning."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class OperationType(BaseModel):
+    """
+    Fine-grained classification of an operation (e.g., 'attribute_derivation',
+    'case_filter', 'conformance_check').
+
+    UML attributes: typeId, name
+    """
+
+    type_id: str = Field(..., description="Unique identifier for this operation type.")
+    name: str = Field(..., description="Human-readable label (e.g., 'attribute_derivation').")
+
+
+class StepCategory(BaseModel):
+    """
+    Broad grouping of analysis steps (e.g., 'log_enrichment', 'process_discovery',
+    'conformance_checking').
+
+    UML attributes: categoryId, name
+    """
+
+    category_id: str = Field(..., description="Unique identifier for this step category.")
+    name: str = Field(..., description="Human-readable label (e.g., 'log_enrichment').")
+
+
+class Operation(BaseModel):
+    """
+    The abstract, reusable definition of an analysis task (e.g., 'filter by threshold',
+    'derive case-centric view').  Concrete executions are recorded as AnalysisSteps.
+
+    UML attributes: operationId, name
+    UML relationships:
+        - hasType   → OperationType (via operation_type_id)
+        - belongsTo → StepCategory  (via step_category_id)
+        - aggregates → Parameter    (1-to-N; represented in Parameter.operation_id)
+    """
+
+    operation_id: str = Field(..., description="Unique identifier for this operation definition.")
+    name: str = Field(..., description="Human-readable operation name (e.g., 'add_attribute').")
+    operation_type_id: str = Field(
+        ...,
+        description="FK → OperationType.type_id – the fine-grained type of this operation.",
+    )
+    step_category_id: Optional[str] = Field(
+        None,
+        description=(
+            "FK → StepCategory.category_id – the broad category this operation belongs to. "
+            "Optional if not yet categorised."
+        ),
+    )
+
+
+class Version(BaseModel):
+    """
+    Governs individual operations within a Pipeline, capturing creation timestamps
+    and hierarchical lineage to maintain the integrity of reusable components.
+
+    UML attributes: versionId, number, createdAt
+    UML relationship:
+        - originatedFrom → Version    (via originated_from_version_id – parent version)
+        - references     → Operation  (via operation_id)
+    """
+
+    version_id: str = Field(..., description="Unique identifier for this version record.")
+    operation_id: str = Field(
+        ...,
+        description="FK → Operation.operation_id – the operation this version tracks.",
+    )
+    number: str = Field(
+        ..., description="Semantic version string (e.g., '1.0.0', '2.1.3')."
+    )
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="UTC timestamp at which this version was created.",
+    )
+    originated_from_version_id: Optional[str] = Field(
+        None,
+        description=(
+            "FK → Version.version_id – the parent version from which this one was derived. "
+            "None for the initial version."
+        ),
+    )
+
+
+__all__ = [
+    "OperationType",
+    "StepCategory",
+    "Operation",
+    "Version",
+]